HTTP та RPC-запити

01

Виклик публічного методу

Один endpoint, точні імена методів і UTF-8 JSON.

Приклад пошуку товару

POST /v1/rpc HTTP/1.1
Host: api13.arm20.com
Authorization: Bearer Ваш ключ API
Content-Type: application/json

{
  "method": "products.find_code",
  "params": {
    "code": "1001"
  },
  "id": "product-lookup-42"
}

Поле id — необов’язковий ідентифікатор клієнта. Відповідь також містить серверний request_id і заголовок X-Request-Id.

Основні endpoint-и

POST /v1/rpc: виконання методу
POST /v1/operations: методи поточного ключа
POST /v1/auth/introspect: дані поточного principal
POST /v1/auth/api-key: видача ключа з Windows Складу
POST /v1/auth/revoke: відкликання короткого токена a13s1
GET /v1/openapi.json: машинна схема OpenAPI 3.1

Максимальний розмір JSON: 2 097 152 байт. Не надсилайте tenant, DB-реквізити, URL, SQL або внутрішні action/op.

Лише для операцій запису

Як сформувати `Idempotency-Key`

API13 не видає цей ключ. Його створює ваша інтеграція перед першим відправленням окремої бізнес-операції. Найпростіший варіант — згенерувати UUID v4 або UUID v7 стандартною бібліотекою вашої мови. Для читабельності можна додати префікс методу.

Idempotency-Key: nakl-add-lines-0195d2d7-2a68-7d31-8f3a-7b6c5d4e3210

Значення example-nakl-add-lines-0001 у картці методу — лише демонстрація формату. Не копіюйте його як постійний ключ у робочу програму.

Коли створювати новий, а коли повторювати старий

новий записСтворіть новий ключ і збережіть його разом із локальною операцією до відправлення.

timeout / обривПовторіть той самий method і ті самі params із тим самим ключем.

інша діяНавіть для тієї самої накладної або товару створіть інший ключ.

читанняДля методів із позначкою «читання» заголовок не потрібний.

Ключ має містити 8–255 дозволених ASCII-символів. Не генеруйте його заново під час автоматичного retry: інакше API13 сприйме повтор як нову операцію. RPC-поле id — лише кореляція відповіді й не замінює Idempotency-Key. Докладніше про журнал і невизначений результат.

02

Формат результату

Картка методу містить точну схему успішної відповіді.

rowsІменовані рядки з точним переліком columns.

rows_uncountedІменовані рядки без окремого лічильника.

statusРезультат дії без таблиці; додаткові значення наведено у fields.

scalarОдне рядкове значення у status.value.

tagged_rowsРядки з відомим тегом і окремою схемою для кожного тегу.

variable_rowsПеревірений неоднорідний контракт із явно описаними формами рядків.

03

Єдина пагінація для читання

Для методів, що повертають колекції рядків, можна використати окремий endpoint.

Надішліть той самий method і params до POST /v1/rpc/page, додавши limit від 1 до 500 та отриманий cursor. Відповідь містить page.returned, page.total і page.next_cursor.

Щоб отримати весь товарний каталог по 500 рядків, викликайте pos.search_products із порожнім search, задавайте limit: 500 на верхньому рівні та не додавайте params.limit. У кожний наступний запит переносіть data.page.next_cursor; завершіть цикл, коли він дорівнює null.

{
  "method": "pos.search_products",
  "params": {"search": ""},
  "cursor": "500",
  "limit": 500,
  "id": "sync-page-2"
}

Endpoint приймає лише операції читання з рядковим результатом. Записи, scalar/status-методи та довільний upstream cursor через нього не виконуються. Cursor є зміщенням у поточному результаті, а не snapshot: якщо дані між сторінками змінюються, почніть вибірку заново.