Guía
Pedidos observados y pedidos a preparar
La API mantiene dos vistas deliberadamente distintas: lo que informó un canal y el trabajo de fulfillment que debe ejecutar el vendedor.
| Recurso | Ruta | Propósito |
|---|---|---|
| Pedido externo | /connections/{id}/external-orders | Observación versionada del sistema fuente. El cuerpo comercial queda inmutable tras la primera importación. |
| Pedido del vendedor | /orders | Proyección pagada para preparación, envío y entrega; contiene información personal. |
Importar desde WooCommerce
Usa external_order_id como identidad estable, source_version para deduplicar y source_updated_at para ordenar observaciones. PUT responde 200 tanto al crear como al actualizar.
PUT /vendors/{vendor_id}/connections/{connection_id}/external-orders/{external_order_id}
Idempotency-Key: woo-order-1842-v5Estado e inventario
pendingreserva inventario Moku cuando Moku es autoridad.paidconsume la reserva y crea la proyección de fulfillment.- Si el canal controla inventario, Moku registra el efecto como
channel_managed. - Una reserva vencida marca el pedido para reconciliación manual; no inventes una transición pagada.
Fulfillment
Los estados avanzan de pending a processing, shipped y delivered. Incluye expected_version, una clave idempotente y datos de despacho al enviar. Un pedido de fulfillment del canal requiere su authority_connection_id.
Cancelación después del pago
Una observación cancelled o failed posterior al pago queda en revisión manual. Resuélvela con terminal-resolution:
cancel_without_restock: cancela fulfillment y libera cercos sin cambiar stock.cancel_and_restock: repone unidades consumidas por Moku. Se rechaza si un canal controla actualmente el inventario.
La resolución preserva el historial de pago y marca la proyección como cancelled.