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

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

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

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

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

Установка

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

go get -u github.com/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)

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 16 Pro Max").SetCode("APPL15PM")

• Для безопасного разыменовывания указателя необходимо передать указатель в метод Deref()
• Чтобы установить указатель на примитивное значение поля также существуют вспомогательные методы:
  • Bool() возвращает *bool
  • Int() возвращает *int
  • Uint() возвращает *uint64
  • Float() возвращает *float64
  • String() возвращает *string

Использование

Создание экземпляра клиента

  client := moysklad.New(
moysklad.WithTokenAuth(os.Getenv("MOYSKLAD_TOKEN")), // с использованием токена
// moysklad.WithBasicAuth(os.Getenv("MOYSKLAD_USERNAME"), os.Getenv("MOYSKLAD_PASSWORD")), // или с использование логина и пароля
)

Создание экземпляра клиента со своим http клиентом

  httpClient := &http.Client{Timeout: 5 * time.Minute}

client := moysklad.New(
moysklad.WithHTTPClient(httpClient),
moysklad.WithTokenAuth(os.Getenv("MOYSKLAD_TOKEN")),
)

Создание экземпляра клиента с resty клиентом

  restyClient := resty.New()

client := moysklad.New(
moysklad.WithRestyClient(httpClient),
moysklad.WithTokenAuth(os.Getenv("MOYSKLAD_TOKEN")),
)

Функциональные параметры

WithTokenAuth(token)

Получить простой клиент с авторизацией через токен.

  client := moysklad.New(
moysklad.WithTokenAuth(os.Getenv("MOYSKLAD_TOKEN")),
)

WithBasicAuth(username, password)

Получить простой клиент с авторизацией через пару логин/пароль.

  client := moysklad.New(
moysklad.WithBasicAuth(os.Getenv("MOYSKLAD_USERNAME"), os.Getenv("MOYSKLAD_PASSWORD")),
)

WithTimeout(timeout)

Установить необходимый таймаут для http клиента.

  client := moysklad.New(
moysklad.WithTimeout(15 * time.Minute), // таймаут 15 минут
)

WithDisabledWebhookContent(value)

Временное отключение уведомлений вебхуков

  client := moysklad.New(
moysklad.WithDisabledWebhookContent(true), // отключим уведомления вебхуков на данном клиенте
)

WithDisabledWebhookByPrefix(urls...)

Позволяет указать набор префиксов url-адресов.

  client := moysklad.New(
moysklad.WithDisabledWebhookByPrefix("https://abc.ru/ms/v1/wh1", "https://abc.ru/ms/v1/wh2"),
)

Параметры запроса

Количество элементов на странице limit=val

Пример:

  moysklad.WithLimit(100)

Смещение от первого элемента offset=val

Пример:

  moysklad.WithOffset(100)

Контекстный поиск search=val

Пример:

  moysklad.WithSearch("iPhone 16 Pro Max")

Замена ссылок объектами

Пример:

  moysklad.WithExpand("positions").WithExpand("group")

Фильтрация по значению key=value

Пример:

  moysklad.WithFilterEquals("name", "Яблоко")

Строго больше key>value

Пример:

  moysklad.WithFilterGreater("sum", "100")

Строго меньше key<value

Пример:

  moysklad.WithFilterLesser("sum", "1000")

Больше или равно key=>value

Пример:

  moysklad.WithFilterGreaterOrEquals("moment", "2023-06-01")

Меньше или равно key<=value

Пример:

  moysklad.WithFilterLesserOrEquals("moment", "2023-06-01")

Не равно key!=value

Пример:

  moysklad.WithFilterNotEquals("name", "0001")

Частичное совпадение (обычное подобие) key~value

Пример:

  moysklad.WithFilterEquivalence("code", "ms")

Полное совпадение в начале значения (левое подобие) key~=value

Пример:

  moysklad.WithFilterEquivalenceLeft("code", "ms")

Полное совпадение в конце значения (правое подобие) key=~value

Пример:

  moysklad.WithFilterEquivalenceRight("code", "ms")

Частичное совпадение не выводится key!~value

Пример:

  moysklad.WithFilterNotEquivalence("code", "ms")

Фильтрация по удалённым документам isDeleted=val

Пример:

  moysklad.WithFilterDeleted(true)

Фильтрация по напечатанным документам printed=val

Пример:

  moysklad.WithFilterPrinted(true)

Фильтрация по опубликованным документам published=val

Пример:

  moysklad.WithFilterPublished(true)

Фильтрация по архивным сущностям archived=val

Пример:

  moysklad.WithFilterArchived(true)

Группировка выдачи groupBy=val

Пример:

  moysklad.WithGroupBy(moysklad.GroupByProduct)

Применение сохранённого фильтра namedFilter=href

Метод принимает указатель на сохранённый фильтр.

Пример:

  moysklad.WithNamedFilter(&NamedFilter{...})

Сортировка по умолчанию order=fieldName

Пример:

  moysklad.WithOrder("name")

Сортировка по возрастанию order=fieldName,asc

Пример:

  moysklad.WithOrderAsc("name")

Сортировка по убыванию order=fieldName,desc

Пример:

  moysklad.WithOrderDesc("name")

Остатки и себестоимость в позициях документов fields=stock

Метод устанавливает лимит позиций в 100 единиц, а также применяет замену ссылок объектами для поля positions

Пример:

  moysklad.WithStockFiled()

Тип остатка stockType=val

Используется в отчёте "Остатки"

Пример:

  moysklad.WithStockType(moysklad.StockDefault)

Интервал, с которым будет построен отчет interval=val

Используется в отчётах

Пример:

  moysklad.WithInterval(moysklad.IntervalMonth)

Начало периода momentFrom=val

Метод принимает time.Time Пример:

  moysklad.WithMomentFrom(time.Now())

Конец периода momentTo=val

Метод принимает time.Time Пример:

  moysklad.WithMomentTo(time.Now())

Пример передачи параметров запроса в метод

  list, _, err := client.Entity().Product().GetList(context.Background(),
moysklad.WithExpand("country"),
moysklad.WithOrder("name"),
moysklad.WithLimit(10),
)

Сервисы

Для перехода к определённому сервису необходимо вызвать цепочку методов, аналогично пути запроса.

Пример: ProductService

Сервис для работы с товарами.

Относительный путь: /entity/product Цепочка вызовов от клиента будет выглядеть следующим образом:

  client := moysklad.New(
moysklad.WithTokenAuth(os.Getenv("MOYSKLAD_TOKEN")),
)

// `/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.New(
    moysklad.WithBasicAuth(os.Getenv("MOYSKLAD_USERNAME"), os.Getenv("MOYSKLAD_PASSWORD")),
    moysklad.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, 
    moysklad.WithExpand("country", "owner", "productFolder"), // пример передачи параметров запроса
  )
  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())

  // отправим запрос на удаление товара
  // в качестве аргументов передадим контекст и удаляемую сущность, в которой содержится идентификатор
  success, _, err := productService.Delete(context.Background(), productUpdated)
  if err != nil {
    panic(err)
  }

  // выведем состояние выполненного запроса, где true - успешно удалено, false – не удалено, см ошибки
  fmt.Println("Deleted", success)
}

Обратная связь

Буду рад видеть ваши идеи и предложения в Issues.