POST /v1/orders — submeter encomenda em Portugal
Submissão idempotente com X-Idempotency-Key. Devolve 201 com order_id, ou 409 em duplicado. IVA 23% calculado no servidor.
Esquema do pedido
POST /v1/orders com corpo JSON: { idempotency_key, buyer:{vat_id, billing_address}, ship_to:{name, address (com CP Lisboa), contact}, lines:[{sku, qty, unit_price_cents, currency:'EUR'}], promised_date, po_number, tax_mode:'incl_iva' }. NIF validado via VIES em tempo real. Máx. 250 linhas por encomenda.
Resposta e fluxo de estados
201 Created → { order_id, status:'accepted', estimated_iva_amount_cents, currency, fulfilment_hub:'Lisboa', invoice_channel:'Portal das Finanças (AT)' }. Transições emitidas como eventos webhook: accepted → confirmed → in_production → shipped → delivered. Cada transição grava em GET /v1/orders/{id}/events.
Erros de validação
400 com RFC 7807 problem+json: invalid_vat (mismatch VIES), invalid_sku (fora do catálogo), min_qty_violation (abaixo do MOQ), invalid_iva_rate (mismatch com 23%), idempotency_conflict. Todos os erros incluem detalhe legível e URI de tipo estável.
FAQ
O endpoint é idempotente?
Sim — passe X-Idempotency-Key (UUID v4 recomendado). Mesma chave + mesmo corpo devolve a encomenda existente; mesma chave + corpo diferente devolve 409.
Que moedas são aceites?
EUR para Portugal. Preços unitários em unidades mínimas (cêntimos). Linhas em moeda mista rejeitadas com 400 invalid_currency_mix.
Suportam fulfilment parcial?
Desativado por defeito. Defina partial_ok:true para permitir envios separados. Cada envio gera fatura separada via Portal das Finanças (AT).
Como são calculados os impostos?
Servidor-side com base no estado de IVA do comprador, país de entrega e classe fiscal do SKU. IVA 23% aplicado a doméstico; reverse-charge para B2B UE válido (VIES OK).
Posso cancelar uma encomenda via API?
DELETE /v1/orders/{id} permitido nos estados accepted e confirmed. Após in_production coordenamos por email — contacte o seu AE.