POST /v1/orders — отправка заказа в Италии
Идемпотентная отправка с X-Idempotency-Key. Возвращает 201 с order_id или 409 при дубликате. IVA 22% рассчитывается на сервере.
Схема запроса
POST /v1/orders с JSON-телом: { idempotency_key, buyer:{vat_id, billing_address}, ship_to:{name, address (с почтовым индексом Милан), contact}, lines:[{sku, qty, unit_price_cents, currency:'EUR'}], promised_date, po_number, tax_mode:'incl_iva' }. VAT ID валидируется через VIES в реальном времени. Макс. 250 строк на заказ.
Ответ и поток состояний
201 Created → { order_id, status:'accepted', estimated_iva_amount_cents, currency, fulfilment_hub:'Милан', invoice_channel:'SdI' }. Переходы как webhook: accepted → confirmed → in_production → shipped → delivered. Каждый переход пишется в GET /v1/orders/{id}/events.
Ошибки валидации
400 с RFC 7807 problem+json: invalid_vat (VIES mismatch), invalid_sku (нет в каталоге страны), min_qty_violation (ниже MOQ), invalid_iva_rate (mismatch c 22%), idempotency_conflict. Все ошибки содержат человекочитаемый detail и стабильный type URI.
FAQ
Endpoint идемпотентный?
Да — передавайте X-Idempotency-Key (рекомендуется UUID v4). Тот же ключ + то же тело возвращает существующий заказ; тот же ключ + другое тело возвращает 409 conflict.
Какие валюты принимаются?
EUR для Италия. Цены в минимальных единицах (центы). Строки со смешанной валютой отклоняются с 400 invalid_currency_mix.
Что с частичным выполнением?
Отключено по умолчанию. Установите partial_ok:true для разрешения раздельных отгрузок. Каждая отгрузка получает отдельный счёт через SdI.
Как рассчитываются налоги?
На стороне сервера, исходя из VAT-статуса покупателя, страны доставки и налогового класса SKU. IVA 22% для внутренних; reverse-charge для валидного B2B EU (VIES OK).
Можно отменить заказ через API?
DELETE /v1/orders/{id} допустим в состояниях accepted и confirmed. После in_production координируем по email — свяжитесь с вашим AE.