POST /v1/orders — inviare un ordine in Italia
Invio idempotente con X-Idempotency-Key. Restituisce 201 con order_id, o 409 in caso di duplicato. IVA 22% calcolato lato server.
Schema della richiesta
POST /v1/orders con body JSON: { idempotency_key, buyer:{vat_id, billing_address}, ship_to:{name, address (con CAP Milano), contact}, lines:[{sku, qty, unit_price_cents, currency:'EUR'}], promised_date, po_number, tax_mode:'incl_iva' }. Partita IVA validata su VIES in tempo reale. Max 250 righe per ordine.
Risposta e flusso di stati
201 Created → { order_id, status:'accepted', estimated_iva_amount_cents, currency, fulfilment_hub:'Milano', invoice_channel:'SdI' }. Transizioni emesse come eventi webhook: accepted → confirmed → in_production → shipped → delivered. Ogni transizione è registrata in GET /v1/orders/{id}/events.
Errori di validazione
400 con problem+json RFC 7807: invalid_vat (mismatch VIES), invalid_sku (non in catalogo paese), min_qty_violation (sotto MOQ), invalid_iva_rate (mismatch con 22%), idempotency_conflict. Tutti gli errori includono detail leggibile e URI di tipo stabile.
FAQ
L'endpoint è idempotente?
Sì — passa X-Idempotency-Key (UUID v4 consigliato). Stessa key + stesso body restituisce l'ordine esistente; stessa key + body diverso restituisce 409.
Quali valute sono accettate?
EUR per l'Italia. Prezzi unitari in unità minime (centesimi). Righe a valuta mista rifiutate con 400 invalid_currency_mix.
Come gestite il fulfilment parziale?
Disattivato di default. Imposta partial_ok:true per consentire spedizioni multiple. Ogni spedizione riceve una fattura separata via SdI.
Come sono calcolate le tasse?
Lato server in base a stato partita IVA del buyer, paese di consegna e classe fiscale SKU. IVA 22% applicata domestico; reverse-charge per B2B EU valido (VIES OK).
Posso annullare un ordine via API?
DELETE /v1/orders/{id} permesso negli stati accepted e confirmed. Dopo in_production coordiniamo via email — contatta il tuo AE.