#Прикрепление чека к заявке

Если вы принимаете оплату на своей странице (берёте у нас только реквизиты), чек об оплате можно приложить к заявке по API. Мы сохраняем PDF, привязываем его к транзакции и автоматически передаём получателю - трейдеру или провайдеру.

#Содержание секции

POST /merchant/orders/{id}/receipt - загрузить чек
GET /merchant/receipts/{file_id} - скачать чек
Требования к файлу и коды ошибок

#POST /merchant/orders/{id}/receipt

POST https://api.nimbo.me/merchant/orders/{id}/receipt
Authorization: Bearer <ваш API-ключ>
Content-Type: multipart/form-data

{id} - идентификатор заявки: наш id (тот, что вернулся при создании) или ваш merchant_transaction_id. Заявка должна принадлежать вам - чужая или несуществующая → 404 NOT_FOUND.

Тело - multipart/form-data. Значение берётся только из поля file, остальные части формы игнорируются.

Поле	Тип	Обяз.	Описание
`file`	`file`	✅	PDF-файл чека. Имя файла сохраняется как есть и отдаётся при скачивании.

// REQ

curl -X POST https://api.nimbo.me/merchant/orders/ВАШ_ID/receipt \
  -H "Authorization: Bearer <ваш API-ключ>" \
  -F "file=@receipt.pdf"

// RES 200

{
  "file_id": "e6a2fe2c-f967-4af2-b50f-fd6643182991",
  "order_id": "ВАШ_ID",
  "download_url": "https://api.nimbo.me/merchant/receipts/e6a2fe2c-f967-4af2-b50f-fd6643182991",
  "status": "received"
}

file_id - UUID чека: по нему чек скачивается, и он же приходит в массиве receipts[] в GET /merchant/status.

#Требования к файлу

Только PDF - проверяем и content-type части, и сигнатуру файла %PDF
Максимум 100 MB
Один файл за запрос - поле формы file, непустое

ℹ️

JPG/PNG сюда не проходят - конвертируйте в PDF. Скриншоты как доказательства по спору прикладываются отдельно, через POST /merchant/dispute (там до 5 файлов, до 10 MB, картинки и видео разрешены).

#Ошибки загрузки

HTTP	Code	`message`	Когда
400	`INVALID_INPUT`	`file is required`	Нет поля `file` или файл пустой
400	`INVALID_INPUT`	`receipt must be a PDF (%PDF)`	Файл не PDF
400	`INVALID_INPUT`	`file too large (max 100MB)`	Файл больше 100 MB
401	`UNAUTHORIZED`	-	Нет / невалидный Bearer
404	`NOT_FOUND`	`order not found`	Заявка чужая или не существует

#GET /merchant/receipts/{file_id}

GET https://api.nimbo.me/merchant/receipts/{file_id}
Authorization: Bearer <ваш API-ключ>

Отдаёт байты PDF потоком: Content-Type: application/pdf и Content-Disposition: attachment; filename="…". Ссылка на само хранилище наружу не раскрывается - скачивание всегда идёт через эту ручку с вашим ключом.

curl https://api.nimbo.me/merchant/receipts/e6a2fe2c-f967-4af2-b50f-fd6643182991 \
  -H "Authorization: Bearer <ваш API-ключ>" \
  -o receipt.pdf

Доступны только чеки ваших заявок - и загруженные вами, и присланные трейдером. Чужой или несуществующий file_id → 404 NOT_FOUND (receipt not found).

#Где взять file_id

Из ответа на загрузку либо из receipts[] в GET /merchant/status:

{
  "receipts": [
    {
      "id": "e6a2fe2c-f967-4af2-b50f-fd6643182991",
      "file_name": "receipt.pdf",
      "multimedia_type": "client_receipt",
      "content_type": "application/pdf",
      "url": "https://api.nimbo.me/merchant/receipts/e6a2fe2c-f967-4af2-b50f-fd6643182991"
    }
  ]
}

id - это и есть file_id
multimedia_type: client_receipt - чек от клиента или загруженный вами, trader_receipt - чек от трейдера
url ведёт на защищённую ручку выше - открывается с тем же Bearer