ПерфектПак · API v1.1
openapi.yaml ↗
Справочник методов / Подписки на события

Журнал доставок

GET /webhooks/{id}/deliveries
Адрес
GET https://api.perfektpak.ru/v1/webhooks/{id}/deliveries

Тот же адрес и в песочнице — режим выбирает ключ: pp_live_… отвечает боевыми данными, pp_test_… — данными песочницы.

Описание метода

Каждая доставка — одно событие для одной подписки: попытки, код ответа вашего адреса, причина неудачи по-русски, время следующей попытки. Ответ на «мы ничего не получали» — здесь, а не в переписке.

Авторизация

Authorization: Bearer <ключ> Ключ выдаёт менеджер (боевой) или песочница (тестовый).

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

id обязательный в пути
строка
status в строке запроса
строка
Значения: PENDING DELIVERED FAILED
limit в строке запроса
целое число1…200; по умолчанию 50
Размер страницы. Значение вне диапазона молча округляется до ближайшей границы (0 и меньше — до значения по умолчанию, больше максимума — до максимума); ошибка 400 bad_request — только если значение вообще не целое число.
Пример: 50
cursor в строке запроса
строка
Непрозрачный курсор страницы из next_cursor предыдущего ответа. Не передавайте для первой страницы. Курсор, который мы не выдавали сами, — это 400 bad_cursor, а не тихий возврат к первой странице.

Ответы

200 Доставки, новые первыми.
  • items массив
    поля элемента — Delivery
    • id строка
    • webhook_id строка
    • event_id строка
    • event_type строка
    • status строка
      Значения: PENDING DELIVERED FAILED
    • attempts целое число
    • last_attempt_at строка или null
    • last_status_code целое число
      Код ответа вашего адреса; 0 — ответа не было.
    • last_error строка
      Причина по-русски, например «Адрес не ответил за 10 секунд».
    • next_attempt_at строка или null
    • created_at строка
    • payload объект Event
      Только в ответе по одной доставке — событие, как оно было отправлено.
      поля Event
      • id строка
      • type строка
        Значения: receipt.created receipt.confirmed receipt.status_changed receipt.completed shipment.status_changed order.status_changed webhook.ping
      • occurred_at строка
      • data любой
  • total целое число
  • next_cursor строка или null
404 Ресурса с таким идентификатором нет — в том числе если он существует, но принадлежит не вашему client_id. API намеренно не различает эти два случая (подробнее — в /docs), поэтому чужой объект тоже отвечает 404, а не 403.

Схема: ErrorResponse

  • error объект Error обязательно
    поля Error
    • code строка ErrorCode обязательно
      Машинный, стабильный код ошибки — ветвитесь в коде по нему, а не по тексту message (он на русском и может измениться). unauthorized — ключ не передан или не существует; key_revoked — ключ существует, но отозван; bad_request — параметры запроса не прошли валидацию; bad_cursor — курсор не наш или испорчен (в отличие от обычного bad_request, здесь нужно перезапросить страницу заново, а не повторять тот же курсор); not_found — ресурса нет либо он принадлежит не вашему client_id (специально неразличимо); rate_limited — превышен лимит запросов; internal — ошибка на нашей стороне. С v1.1: validation_error — поле тела запроса не прошло проверку (поле названо в message); cabinet_required — у вас несколько кабинетов, укажите cabinet_id; mixed_marking — в одной заявке позиции и с маркировкой, и без, разделите на две; write_disabled — заявки через API ещё не включены для вашего ключа; warehouse_unavailable — склад временно не принял заявку, повторите через минуту (заявка не создана); webhook_url_unverified — адрес не ответил 2xx на проверочное событие; webhook_limit — больше 10 подписок; webhooks_unavailable — вебхуки временно выключены; sandbox_only — операция только для тестового ключа.
      Значения: unauthorized key_revoked rate_limited not_found bad_request bad_cursor internal validation_error cabinet_required mixed_marking write_disabled warehouse_unavailable webhook_url_unverified webhook_limit webhooks_unavailable sandbox_only
    • message строка обязательно
      Текст ошибки на русском для лога и для человека — не для ветвления в коде.
    • request_id строка обязательно
      Тот же идентификатор, что и в заголовке X-Request-Id. Присылайте его в поддержку, чтобы нашли конкретный вызов.