API-интеграция для собственных систем - Интеграции

API-интеграция для собственных систем - Интеграции | AutoLetter Help Center

С помощью API-интеграции вы можете передавать заказы напрямую из вашей собственной системы в AutoLetter. Это идеально для собственных разработок, индивидуальных систем магазинов или автоматизированных рабочих процессов, которые невозможно реализовать через стандартные интеграции (Billbee, Shopify).

Создайте интеграцию

Перейдите в Интеграции, нажмите Добавить и выберите API как тип интеграции.

Назовите интеграцию

Дайте понятное название, например «API собственного магазина» или «ERP-система».

Получите учётные данные

После сохранения вы получите URL API-эндпоинта и сможете сгенерировать JWT-токен для аутентификации.

JWT-токен для API-аутентификации генерируется в вашем Рабочем пространстве в AutoLetter. Храните этот токен в безопасности и не передавайте его посторонним лицам.

Заказы отправляются в виде JSON-массива POST-запросом на API-эндпоинт. Аутентификация осуществляется через Bearer JWT-токен в заголовке Authorization.

curl -X POST https://api.autoletter.eu/v2/orders \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "OrderNumber": "ORD-2026-001",
      "OrderId": "12345",
      "Date": "2026-02-20T10:30:00Z",
      "Total": 89.99,
      "Address": {
        "FirstName": "Max",
        "LastName": "Mustermann",
        "Street": "Musterstraße",
        "HouseNumber": "42",
        "ZIP": "10115",
        "City": "Berlin",
        "Country": "DE"
      }
    }
  ]'

Каждый заказ должен содержать следующие поля:

Поле	Тип	Описание
`OrderNumber`	String	Номер заказа
`OrderId`	String	Уникальный идентификатор заказа
`Date`	String (ISO 8601)	Дата заказа
`Total`	Number	Общая сумма заказа
`Address`	Object

Объект Address содержит адрес доставки и должен включать как минимум имя, улицу, почтовый индекс, город и страну.

Помимо обязательных полей, вы можете передавать следующие необязательные поля:

Поле	Тип	Описание
`ExternalId`	String	Внешний идентификатор из вашей системы
`ShopId`	String	Идентификатор магазина при работе с несколькими магазинами
`InvoiceAddress`	Object	Альтернативный адрес для выставления счёта
`LetterAddress`	Object	Альтернативный адрес для отправки письма
`Products`

По умолчанию создаются только новые заказы. Если вы хотите обновлять существующие заказы, добавьте параметр allowUpdates к вашему запросу:

{
  "allowUpdates": true,
  "orders": [...]
}

При активированном allowUpdates заказы с совпадающим OrderId будут обновлены, а не отклонены.

В отличие от Billbee и Shopify, при API-интеграции нет задержки синхронизации. Заказы, отправленные через API, мгновенно доступны в AutoLetter и могут сразу использоваться в кампаниях.

API возвращает стандартные HTTP-коды состояния:

200 OK — Заказы успешно обработаны
400 Bad Request — Некорректные данные (подробности в теле ответа)
401 Unauthorized — Недействительный или отсутствующий JWT-токен
429 Too Many Requests — Достигнут лимит запросов

При ошибках ответ содержит подробную информацию о затронутых записях.