go-moysklad

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)

1. *T – указатель на сущность/документ, например *Product при вызове Create() (возвращает bool при вызове метода Delete()).
2. *Response – сырой ответ на запрос, *http.Response, обёрнутый в *Response.
3. error – ошибки, если они были. При возникновении ошибок от API МойСклад в качестве ошибки будет заполненная структура ApiErrors

Указатели

Поля структур сущностей и документов являются указателями.

• Для безопасного разыменовывания указателя необходимо передать указатель в метод Deref()

  name := moysklad.Deref(product.Name)

• Чтобы установить указатель на примитивное значение поля также существуют вспомогательные методы:
  • Bool() возвращает *bool
  • Int() возвращает *int
  • Uint() возвращает *uint64
  • Float() возвращает *float64
  • String() возвращает *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)
}