POST /v1/orders — enviar un pedido en España
Envío idempotente con X-Idempotency-Key. Devuelve 201 con order_id, o 409 en duplicado. IVA 21% calculado en servidor.
Esquema de la solicitud
POST /v1/orders con cuerpo JSON: { idempotency_key, buyer:{vat_id, billing_address}, ship_to:{name, address (CP Madrid), contact}, lines:[{sku, qty, unit_price_cents, currency:'EUR'}], promised_date, po_number, tax_mode:'incl_iva' }. CIF/NIF validado vía VIES en tiempo real. Máx 250 líneas por pedido.
Respuesta y flujo de estados
201 Created → { order_id, status:'accepted', estimated_iva_amount_cents, currency, fulfilment_hub:'Madrid', invoice_channel:'FACe/SII (AEAT)' }. Transiciones emitidas como eventos webhook: accepted → confirmed → in_production → shipped → delivered. Cada transición se registra en GET /v1/orders/{id}/events.
Errores de validación
400 con problem+json RFC 7807: invalid_vat (mismatch VIES), invalid_sku (fuera del catálogo), min_qty_violation (por debajo del MOQ), invalid_iva_rate (mismatch con 21%), idempotency_conflict. Todos los errores incluyen detalle legible y URI de tipo estable.
FAQ
¿El endpoint es idempotente?
Sí — pasa X-Idempotency-Key (recomendado UUID v4). Misma clave + mismo cuerpo devuelve el pedido existente; misma clave + cuerpo diferente devuelve 409.
¿Qué monedas se aceptan?
EUR para España. Precios unitarios en unidades mínimas (céntimos). Líneas con moneda mixta se rechazan con 400 invalid_currency_mix.
¿Soportáis cumplimiento parcial?
Desactivado por defecto. Define partial_ok:true para permitir envíos separados. Cada envío genera una factura separada vía FACe/SII (AEAT).
¿Cómo se calculan los impuestos?
En servidor según estado IVA del comprador, país de envío y clase fiscal del SKU. IVA 21% aplicado a doméstico; inversión del sujeto pasivo para B2B UE válido (VIES OK).
¿Puedo cancelar un pedido vía API?
DELETE /v1/orders/{id} permitido en estados accepted y confirmed. Tras in_production coordinamos por email — contacta a tu AE.