API quickstart

1. Отримати ключ X-Api-Key

Автентифікація — один ключ у заголовку X-Api-Key. Ключ прив'язаний до конкретного підключення (пари ваших ключів Укрпошти), тож усі ТТН поїдуть саме тому відправнику.

2. Скоупи

Кожен ключ має набір скоупів, а кожен ендпоінт вимагає відповідний скоуп через іменовану політику (api:read / api:write / api:manage). Набір зберігається канонічним рядком read,write,manage.

3. Авторизація й OpenAPI

Передавайте ключ у заголовку X-Api-Key на кожному запиті до /api/v1. Інтерактивного UI (Swagger) немає — клієнт генерується з машиночитаної специфікації.

4. Приклад: створити ТТН

POST /api/v1/shipments (скоуп write). Тіло — CreateShipmentRequest: тип доставки, отримувач, масив місць (parcels) і ваш externalId (ключ ідемпотентності — повтор із тим самим значенням повертає вже створену ТТН, а не дубль).

curl -X POST https://ukrposhta.main.fish/api/v1/shipments \
  -H "X-Api-Key: upk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryType": "W2W",
    "recipient": { "clientUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
    "parcels": [
      { "weightGrams": 500, "lengthCm": 10, "widthCm": 10, "heightCm": 10 }
    ],
    "externalId": "order-1001"
  }'

import requests

resp = requests.post(
    "https://ukrposhta.main.fish/api/v1/shipments",
    headers={"X-Api-Key": "upk_ваш_ключ"},
    json={
        "deliveryType": "W2W",
        "recipient": {"clientUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"},
        "parcels": [
            {"weightGrams": 500, "lengthCm": 10, "widthCm": 10, "heightCm": 10}
        ],
        "externalId": "order-1001",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json()["barcode"])

using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Api-Key", "upk_ваш_ключ");

var body = new
{
    deliveryType = "W2W",
    recipient = new { clientUuid = "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
    parcels = new[]
    {
        new { weightGrams = 500, lengthCm = 10, widthCm = 10, heightCm = 10 }
    },
    externalId = "order-1001",
};

var resp = await http.PostAsJsonAsync(
    "https://ukrposhta.main.fish/api/v1/shipments", body);
resp.EnsureSuccessStatusCode();

var view = await resp.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(view.GetProperty("barcode").GetString());

Успіх → 200 з ShipmentView (там є barcode і type — фактичний тарифний клас, що поїхав у Укрпошту). Без явного groupId ТТН лягає у дефолтну групу-реєстр відправника під свій ефективний тип. Створити одразу багато — POST /api/v1/shipments/batch (масив тих самих об'єктів).

5. Ключові ендпоінти

Найчастіші виклики й потрібний скоуп. Повний перелік із усіма формами й параметрами — в GET /openapi/v1.json.

Довідник адрес (/api/v1/address/*) читається з нашої копії довідника Укрпошти — запити до самої Укрпошти тут не йдуть. Кожна відповідь несе відмітку свіжості syncedAt і атрибуцію джерела source; дані походять із довідника Укрпошти. Це неофіційний сервіс — він не є сайтом АТ «Укрпошта» і не афілійований з нею.

6. Вебхуки: push замість опитування

Замість опитувати GET /api/v1/shipments/{id}, підпишіться на вебхук — і отримуйте POST на свій endpoint при кожній зміні семантичного статусу ТТН (trackingGroup).

Перевірка підпису

Рахуйте HMAC над отриманими байтами тіла (до будь-якого парсингу) і звіряйте в постійному часі. Заголовки X-Ukrposhta-Timestamp і X-Ukrposhta-Attempt підпис не покриває — у перевірці їх не використовуйте.

import crypto from 'node:crypto'

function verify(rawBody, signatureHeader, secret) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? '')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

import hashlib
import hmac

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Ретраї та ідемпотентність

• Відповідайте 2xx швидко (таймаут на один POST ~10 с). Важку обробку — асинхронно: прийняли, поставили в чергу, повернули 2xx.
• Невдала спроба ретраїться за розкладом 1m → 5m → 30m → 2h → 6h (усього 6 спроб: перша + 5 ретраїв). Після вичерпання доставка переходить у стан Dead і автоматично більше не надсилається — її можна повторити вручну кнопкою «Повторити» в кабінеті.
• Семантика — at-least-once: одну подію можна отримати кілька разів. Робіть обробник ідемпотентним — дедуплікуйте за X-Ukrposhta-Delivery (ретраї однієї доставки несуть той самий UUID). Рідкісний дубль із різними X-Ukrposhta-Delivery відсівайте за змістом: barcode + trackingGroup + eventDateUtc.

7. Коди помилок

Помилки бувають двох походжень: наші (автентифікація, скоупи, ліміти) і Укрпошти (проксовані як є, коди UPExxxxx).

Наш рівень

Рівень Укрпошти

Це лише найчастіші коди — повний каталог помилок UPExxxxx ведеться на боці Укрпошти; кабінет повертає їх без змін разом із людиночитаним текстом.