go-moysklad
SDK находится в стадии разработки!
Некоторые методы могут отсутствовать или работать неправильно!
Подробная документация в процессе написания.
Установка
Требуемая версия go >= 1.21
go get -u gitverse.ru/arcsub/go-moysklad@HEAD
Особенности
Возвращаемые аргументы
Каждый запрос на создание/изменение/удаление возвращает 3 аргумента. Рассмотрим объявление функции
func (s *endpointCreate[T]) Create(ctx context.Context, entity *T, params ...*Params) (*T, *resty.Response, error)
В примере выше нас интересуют возвращаемые аргументы: (*T, *resty.Response, error)
*T
– указатель на сущность/документ, например *Product при вызовеCreate()
(возвращаетbool
при вызове методаDelete()
).*resty.Response
– ответ на запрос, содержащий *http.Response и некоторую другую информацию.error
– ошибки, если они были. При возникновении ошибок от API МойСклад в качестве ошибки будет заполненная структураApiErrors
Указатели
Поля структур сущностей и документов являются указателями.
- Чтобы получить значение по указателю необходимо вызвать метод структуры
GetFieldName()
.FieldName
- наименование поля.
Например:
name := product.GetName()id := product.GetID()
- Чтобы установить значение необходимо передать значение в соответствующий метод
SetFieldName(value)
FieldName
- наименование поляvalue
- передаваемое значение.
[!NOTE] Методы
SetFieldName()
возвращают указатель на объект, что позволяет вызывать методы по цепочке.
Например:
product := new(moysklad.Product)product.SetName("iPhone 15 Pro Max").SetCode("APPL15PM")
Для безопасного разыменовывания указателя необходимо передать указатель в методDeref()
Чтобы установить указатель на примитивное значение поля также существуют вспомогательные методы:Bool()
возвращает *boolInt()
возвращает *intUint()
возвращает *uint64Float()
возвращает *float64String()
возвращает *string
Использование
Создание экземпляра клиента
client := moysklad.NewClient()
Создание экземпляра клиента со своим http клиентом
httpClient := &http.Client{Timeout: 5 * time.Minute} client := moysklad.NewHTTPClient(httpClient)
Создание экземпляра клиента с resty клиентом
restyClient := resty.New() client := moysklad.NewRestyClient(restyClient)
Аутентификация
Имеется два способа аутентификации.
- С помощью токена. Метод клиента
WithTokenAuth()
client := moysklad.NewClient().WithTokenAuth(os.Getenv("MOYSKLAD_TOKEN"))
- С помощью пары логин/пароль. Метод клиента
WithBasicAuth()
client := moysklad.NewClient().WithBasicAuth(os.Getenv("MOYSKLAD_USERNAME"), os.Getenv("MOYSKLAD_PASSWORD"))
Методы клиента
WithTimeout(timeout)
Установить необходимый таймаут для http клиента.
client := moysklad.NewClient().WithTimeout(5 * time.Minute)
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"))
WithDisabledWebhookContent(value)
Временное отключение уведомлений вебхуков
// отключим уведомления вебхуков на данном клиенте client := moysklad.NewClient().WithDisabledWebhookContent(true)
Параметры запроса
Создать экземпляр для работы с параметрами запроса
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()
Запрос по объекту Meta
Если возникает необходимость точечно запросить информацию о сущности, имея только её Meta
, можно использовать
метод FetchMeta
.
Чтобы использовать данный функционал необходимо точно знать, какой тип данных мы ожидаем получить в ответ.
Метод имеет следующую сигнатуру:
func FetchMeta[T any](ctx context.Context, client *Client, meta Meta, params *Params) (*T, *resty.Response, error)
Пример:
productFromMeta, resp, err := moysklad.FetchMeta[moysklad.Product](ctx, client, product.GetMeta(), nil)
Пример работы
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()
// выполняем запрос на получение списка товаров без дополнительных параметров products, _, err := productService.GetList(context.Background()) if err != nil { panic(err) }
// выводим названия полученных товаров for _, product := range products.Rows { fmt.Println(product.GetName()) }
// создадим новый товар product := new(moysklad.Product) product.SetName("Created Product")
// отправим запрос на создание товара // в качестве аргументов передадим контекст и товар productCreated, _, err := productService.Create(context.Background(), product) if err != nil { panic(err) }
// выведем название созданного товара fmt.Println(productCreated.GetName())
// изменим название товара productCreated.SetName("Updated Product")
// отправим запрос на изменение товара // в качестве аргументов передадим контекст, ID изменяемой сущности и изменённый товар productUpdated, _, err := productService.Update(context.Background(), productCreated.GetID(), productCreated) if err != nil { panic(err) }
// выведем название изменённого товара fmt.Println(productUpdated.GetName())
// отправим запрос на удаление товара // в качестве аргументов передадим контекст и ID удаляемой сущности success, _, err := productService.Delete(context.Background(), productUpdated.GetID()) if err != nil { panic(err) }
// выведем состояние выполненного запроса, где true - успешно удалено, false – не удалено, см ошибки fmt.Println("Deleted", success)}
Обратная связь
Буду рад видеть ваши идеи и предложения в Issues.
Языки
Go