go-moysklad (МойСклад)

SDK для работы с МойСклад JSON API 1.2

Warning

SDK находится в стадии разработки!

Некоторые методы могут отсутствовать или работать неправильно!

Подробная документация в процессе написания.

Установка

Требуемая версия go >= 1.21

go get -u github.com/arcsub/go-moysklad

Особенности

Возвращаемые аргументы

Каждый запрос на создание/изменение/удаление возвращает 3 аргумента. Рассмотрим объявление функции

func (s *endpointCreate[T]) Create(ctx context.Context, entity *T, params ...*Params) (*T, *resty.Response, error)

В примере выше нас интересуют возвращаемые аргументы: (*T, *resty.Response, error)

1. *T – указатель на сущность/документ, например *Product при вызове Create() (возвращает bool при вызове метода Delete()).
2. *resty.Response – ответ на запрос, содержащий *http.Response и некоторую другую информацию.
3. 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() возвращает *bool
  • Int() возвращает *int
  • Uint() возвращает *uint64
  • Float() возвращает *float64
  • String() возвращает *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.