Заявка на приёмку из 1С и отслеживание до завершения

Зачем

До v1.1 заявку на привоз товара можно было завести только руками, в личном кабинете. Если учётная система уже знает состав поставки — 1С, МойСклад, своя таблица закупок — этот шаг чистое дублирование. POST /v1/receipts заводит заявку напрямую из вашей системы; она приходит к нам в статусе «Ожидает подтверждения» и невидима сотрудникам склада, пока администратор её не подтвердит — то есть нельзя случайно прислать недооформленную заявку, которую кладовщик тут же начнёт обрабатывать.

Создать заявку

POST https://api.perfektpak.ru/v1/receipts
Authorization: Bearer $PP_KEY
Content-Type: application/json

{
  "cabinet_id": "b4b6b0a1-df3f-4a63-8e11-2a6f6b6e2b10",
  "external_ref": "ПОСТ-000412",
  "comment": "Привезём в четверг до обеда",
  "planned_date": "2026-09-05",
  "items": [
    { "barcode": "4680000000011", "name": "Футболка белая M", "article": "TS-W-M", "qty": 120, "honest_mark": true }
  ]
}

Поле	Обязательно	Что это
`cabinet_id`	только если у клиента больше одного кабинета	Кабинет из `GET /v1/me`. Один кабинет — можно не передавать, иначе `400 cabinet_required`.
`external_ref`	нет, но настоятельно рекомендуется	Номер документа в вашей системе. Вернётся как есть и обеспечивает идемпотентность (см. ниже).
`comment`, `planned_date`	нет	Свободный текст и плановая дата привоза (RFC 3339 или `ГГГГ-ММ-ДД`).
`items`	да, 1–500 позиций	Состав поставки.
`items[].barcode`	да	Штрихкод товара.
`items[].qty`	да, целое 1…100000	Заявленное количество.
`items[].honest_mark`	да, у каждой позиции	Товар маркирован «Честным знаком»? Должно быть одинаковым у всех позиций заявки — см. «Правило mixed_marking».

Ответ — 201, объект заявки в статусе PENDING_CONFIRMATION:

{
  "id": "r_2026_0905_07",
  "number": "ПР-2026-0905-07",
  "status": "PENDING_CONFIRMATION",
  "status_label": "Ожидает подтверждения",
  "source": "api",
  "external_ref": "ПОСТ-000412",
  "comment": "Привезём в четверг до обеда",
  "planned_date": "2026-09-05",
  "expected_qty": 120,
  "accepted_qty": 0,
  "discrepancy_qty": 0,
  "created_at": "2026-09-02T10:15:00+03:00",
  "confirmed_at": null,
  "completed_at": null,
  "items": [
    { "barcode": "4680000000011", "article": "TS-W-M", "name": "Футболка белая M",
      "expected_qty": 120, "accepted_qty": 0, "discrepancy_qty": 0, "honest_mark": true }
  ]
}

Ошибки на этом шаге

400 validation_error — поле не прошло валидацию, имя поля в message; 400 cabinet_required — несколько кабинетов, а cabinet_id не передан; 400 mixed_marking — см. ниже. Полное описание — на странице «Ошибки».

Цепочка статусов

PENDING_CONFIRMATION → EXPECTED → RECEIVING → RECEIVED / RECEIVED_WITH_DISCREPANCY

PENDING_CONFIRMATION — заявка создана через API, невидима сотрудникам склада. Администратор видит её в общем списке заданий с пометкой «требует подтверждения» и именем вашего юрлица.
EXPECTED — администратор нажал «Подтвердить»: заявка стала обычным заданием на приёмку, появляется дата подтверждения confirmed_at.
RECEIVING — кладовщик начал пересчёт на ТСД.
RECEIVED / RECEIVED_WITH_DISCREPANCY — приёмка завершена, количество сошлось или нет; смотрите discrepancy_qty и items[].shortage_reason.

Отследить: опрос или вебхук

Проще всего подписаться на изменения и не опрашивать API вовсе:

{ "url": "https://your-system.example/webhooks/perfektpak", "events": ["receipt.status_changed", "receipt.completed"] }

Подробности регистрации, проверки подписи и формата события — на странице «Вебхуки». Если вебхуки пока не подняты, опрашивайте конкретную заявку по id, который вернул POST:

curl https://api.perfektpak.ru/v1/receipts/r_2026_0905_07 \
  -H "Authorization: Bearer $PP_KEY"

Раз в несколько минут достаточно: статус меняется по факту работы кладовщика, а не мгновенно.

Расхождения по позициям

Когда приёмка завершается с расхождением, у каждой позиции с недостачей заполнено discrepancy_qty и shortage_reason — подробный разбор причин и следующих действий смотрите в гайде «Сверка недостач по приёмке».

Идемпотентность по `external_ref`

Если ваша система повторяет запрос (таймаут, повтор после сбоя связи) — отправляйте тот же external_ref. Пока заявка ещё в статусе PENDING_CONFIRMATION, повторный POST с тем же external_ref вернёт 200 с уже существующей заявкой, а не создаст вторую. После того как администратор подтвердил заявку (статус ушёл из PENDING_CONFIRMATION), тот же external_ref для новой поставки уже допустим — используйте свой сквозной номер документа, он у вас и так уникален на партию привоза.

Правило `mixed_marking`

Склад принимает задание либо целиком по кодам маркировки «Честный знак», либо целиком по штрихкодам — смешанное задание кладовщику на ТСД не сформировать. Поэтому honest_mark обязателен у каждой позиции и обязан быть одинаковым у всех позиций одной заявки. Если в одной поставке реально едет и маркированный, и немаркированный товар — разделите её на две заявки с разными external_ref, иначе POST ответит 400 mixed_marking.

Что дальше

Посмотрите полную схему полей в справочнике методов, подпишитесь на события в разделе «Вебхуки», или попробуйте всё это без боевого ключа — на странице «Песочница».