README ¶
go-moysklad (МойСклад)
SDK для работы с МойСклад JSON API 1.2
Внимание! SDK находится в стадии разработки!
Некоторые методы могут отсутствовать или работать неправильно!
Установка
Требуемая версия go >= 1.9
go get github.com/arcsub/go-moysklad
Особенности
go-retryablehttp
- В данном решении используется go-retryablehttp с корректировкой в необходимом для работы API МойСклад заголовке.
- При получении ошибки 429 запрос будет повторяться N количество раз (по умолчанию 5). Изменить количество попыток можно с помощью метода клиента
WithMaxRetries()
Возвращаемые аргументы
Каждый запрос на создание/изменение/удаление возвращает 3 аргумента. Рассмотрим объявление функции
func (s *endpointCreate[T]) Create(ctx context.Context, entity *T, params *Params) (*T, *Response, error)
В примере выше нас интересуют возвращаемые аргументы: (*T, *Response, error)
*T
– указатель на сущность/документ, например *Product при вызовеCreate()
(возвращаетbool
при вызове методаDelete()
).*Response
– сырой ответ на запрос, *http.Response, обёрнутый в *Response.error
– ошибки, если они были. При возникновении ошибок от API МойСклад в качестве ошибки будет заполненная структураApiErrors
Указатели
Поля структур сущностей и документов являются указателями.
- Для безопасного разыменовывания указателя необходимо передать указатель в метод
Deref()
name := moysklad.Deref(product.Name)
- Чтобы установить указатель на примитивное значение поля также существуют вспомогательные методы:
Bool()
возвращает *boolInt()
возвращает *intUint()
возвращает *uint64Float()
возвращает *float64String()
возвращает *string
Пример:
product := &moysklad.Product{
Name: moysklad.String("Apple iPhone 15"),
Active: moysklad.Bool(false),
}
Использование
Создание экземпляра клиента
client := moysklad.NewClient()
Аутентификация
Имеется два способа аутентификации.
- С помощью токена. Метод клиента
WithTokenAuth()
client := moysklad.NewClient().WithTokenAuth(os.Getenv("MOYSKLAD_TOKEN"))
- С помощью пары логин/пароль. Метод клиента
WithBasicAuth()
client := moysklad.NewClient().WithBasicAuth(os.Getenv("MOYSKLAD_USERNAME"), os.Getenv("MOYSKLAD_PASSWORD"))
Методы клиента
WithTokenAuth(token)
Получить простой клиент с авторизацией через токен.
client := moysklad.NewClient().WithTokenAuth(os.Getenv("MOYSKLAD_TOKEN"))
WithBasicAuth(username, password)
Получить простой клиент с авторизацией через пару логин/пароль.
client := moysklad.NewClient().
WithBasicAuth(os.Getenv("MOYSKLAD_USERNAME"), os.Getenv("MOYSKLAD_PASSWORD"))
WithMaxRetries(retries)
Устанавливает максимальное кол-во попыток для одного запроса и возвращает простой клиент. По умолчанию у запроса 5 попыток.
// установим 10 попыток для каждого запроса
client := moysklad.NewClient().WithMaxRetries(10)
WithDisabledWebhookContent(value)
Временное отключение уведомлений вебхуков
// отключим уведомления вебхуков на данном клиенте
client := moysklad.NewClient().WithDisabledWebhookContent(true)
Async()
Методы для работы с асинхронными задачами.
Относительный путь: /async
asyncService := clientExt.Async
Audit()
Методы для работы с аудитом.
Относительный путь: /audit
auditService := clientExt.Audit
Context()
Методы для работы с контекстом.
Относительный путь: /context
contextService := clientExt.Context
Entity()
Методы для работы с сущностями и документами.
Относительный путь: /entity
entityService := clientExt.Entity
Report()
Методы для работы с отчётами.
Относительный путь: /report
reportService := clientExt.Report
Security()
Относительный путь: /security
Методы для получения токена.
securityService := clientExt.Security
Параметры запроса
Создать экземпляр для работы с параметрами запроса
params := new(moysklad.Params)
Методы для работы с параметрами запроса
Количество элементов на странице limit=val
Пример:
params.WithLimit(100)
Смещение от первого элемента offset=val
Пример:
params.WithOffset(100)
Контекстный поиск search=val
Пример:
params.WithSearch("iPhone 15")
Замена ссылок объектами
Пример:
params.WithExpand("positions").WithExpand("group")
Фильтрация по значению key=value
Пример:
params.WithFilterEquals("name", "Яблоко")
Строго больше key>value
Пример:
params.WithFilterGreater("sum", "100")
Строго меньше key<value
Пример:
params.WithFilterLesser("sum", "1000")
Больше или равно key>=value
Пример:
params.WithFilterGreaterOrEquals("moment", "2023-06-01")
Меньше или равно key<=value
Пример:
params.WithFilterLesserOrEquals("moment", "2023-06-01")
Не равно key!=value
Пример:
params.WithFilterNotEquals("name", "0001")
Частичное совпадение (обычное подобие) key~value
Пример:
params.WithFilterEquivalence("code", "ms")
Полное совпадение в начале значения (левое подобие) key~=value
Пример:
params.WithFilterEquivalenceLeft("code", "ms")
Полное совпадение в конце значения (правое подобие) key=~value
Пример:
params.WithFilterEquivalenceRight("code", "ms")
Частичное совпадение не выводится key!~value
Пример:
params.WithFilterNotEquivalence("code", "ms")
Фильтрация по удалённым документам isDeleted=val
Пример:
params.WithFilterDeleted(true)
Фильтрация по напечатанным документам printed=val
Пример:
params.WithFilterPrinted(true)
Фильтрация по опубликованным документам published=val
Пример:
params.WithFilterPublished(true)
Фильтрация по архивным сущностям archived=val
Пример:
params.WithFilterArchived(true)
Группировка выдачи groupBy=val
Пример:
params.WithGroupBy(moysklad.GroupByProduct)
Применение сохранённого фильтра namedFilter=href
Метод принимает указатель на сохранённый фильтр.
Пример:
params.WithNamedFilter(&NamedFilter{...})
Сортировка по умолчанию order=fieldName
Пример:
params.WithOrder("name")
Сортировка по возрастанию order=fieldName,asc
Пример:
params.WithOrderAsc("name")
Сортировка по убыванию order=fieldName,desc
Пример:
params.WithOrderDesc("name")
Остатки и себестоимость в позициях документов fields=stock
Метод устанавливает лимит позиций в 100 единиц, а также применяет замену ссылок объектами для поля positions
Пример:
params.WithStockFiled()
Тип остатка stockType=val
Используется в отчёте "Остатки"
Пример:
params.WithStockType(moysklad.StockDefault)
Интервал, с которым будет построен отчет interval=val
Используется в отчётах
Пример:
params.WithInterval(moysklad.IntervalMonth)
Начало периода momentFrom=val
Метод принимает time.Time
Пример:
params.WithMomentFrom(time.Now())
Конец периода momentTo=val
Метод принимает time.Time
Пример:
params.WithMomentTo(time.Now())
Сервисы
Для перехода к определённому сервису необходимо вызвать цепочку методов, аналогично пути запроса.
Пример: ProductService
Сервис для работы с товарами.
Относительный путь: /entity/product
Цепочка вызовов от клиента будет выглядеть следующим образом:
client := moysklad.NewClient()
// `/entity/product`
_ = client.Entity().Product()
// `/entity/variant`
_ = client.Entity().Variant()
// `/context/companysettings`
_ = client.Context().CompanySettings()
// `/report/dashboard`
_ = client.Report().Dashboard()
Пример работы
package main
import (
"context"
"fmt"
"github.com/arcsub/go-moysklad/moysklad"
"os"
)
func main() {
// инициализируем простой клиент с аутентификацией по паре логин/пароль
client := moysklad.NewClient().
WithBasicAuth(os.Getenv("MOYSKLAD_USERNAME"), os.Getenv("MOYSKLAD_PASSWORD")).
WithDisabledWebhookContent(true)
// сервис для работы с товарами
productService := client.Entity().Product()
// выполняем запрос на получение списка товаров без дополнительных параметров (nil)
products, _, err := productService.Get(context.Background(), nil)
if err != nil {
panic(err)
}
// выводим названия полученных товаров
for _, product := range products.Rows {
name := moysklad.Deref(product.Name) // Deref безопасно разыменовывает указатель
fmt.Println(name)
}
// создадим новый товар
product := new(moysklad.Product)
// придумаем ему название (обязательное поле)
product.Name = moysklad.String("Created Product")
// отправим запрос на создание товара
// в качестве аргументов передадим контекст, указатель на товар и nil в качестве параметров
productCreated, _, err := productService.Create(context.Background(), product, nil)
if err != nil {
panic(err)
}
// выведем название созданного товара
fmt.Println(moysklad.Deref(productCreated.Name))
// изменим название товара
productCreated.Name = moysklad.String("Updated Product")
// отправим запрос на изменение товара
// в качестве аргументов передадим контекст, указатель на Id изменяемой сущности, указатель на изменённый товар и nil в качестве параметров
productUpdated, _, err := productService.Update(context.Background(), productCreated.Id, productCreated, nil)
if err != nil {
panic(err)
}
// выведем название изменённого товара
fmt.Println(moysklad.Deref(productUpdated.Name))
// отправим запрос на удаление товара
// в качестве аргументов передадим контекст и указатель на Id удаляемой сущности
success, _, err := productService.Delete(context.Background(), productUpdated.Id)
if err != nil {
panic(err)
}
// выведем состояние выполненного запроса, где true - успешно удалено, false – не удалено, см ошибки
fmt.Println("Deleted", success)
}