API de Pedidos

Consulta pedidos, actualiza estados y gestiona envíos.

Endpoints

GET

/orders

orders:read

Obtén una lista paginada de pedidos. Soporta filtrado por estado y rango de fechas.

GET

/orders/:id

orders:read

Obtén un pedido con todos los artículos y detalles de envío.

PUT

/orders/:id/status

orders:write

Actualiza el estado de un pedido (ej. marcar como enviado).

POST

/orders/:id/shipment

orders:write

Adjunta información de seguimiento de envío a un pedido.

Referencia de Campos

Campo	Tipo	Obligatorio	Descripción
id	string	No	Identificador único del pedido (solo lectura)
orderNumber	string	No	Número de pedido legible (solo lectura)
customerId	string	No	ID del cliente (ausente para pedidos de invitados)
status	string	No	PENDING, CONFIRMED, PROCESSING, SHIPPED, DELIVERED, CANCELLED, REFUNDED
paymentStatus	string	No	pending, paid, refunded, failed
paymentMethod	string	No	Método de pago utilizado (ej. stripe, cod)
total	integer	No	Total en centavos (solo lectura)
items	OrderLine[]	No	Array de artículos (solo lectura)
shippingAddress	Address	No	Objeto de dirección de envío
fulfillmentType	string	No	shipping, pickup, delivery o digital
createdAt	datetime	No	Marca de tiempo ISO 8601 (solo lectura)
updatedAt	datetime	No	Marca de tiempo ISO 8601 (solo lectura)

Parámetros de Consulta (Lista)

Campo	Tipo	Obligatorio	Descripción
page	integer	No	Número de página (predeterminado: 1)
limit	integer	No	Elementos por página (predeterminado: 20, máx: 100)

Ejemplo

Listar pedidos recientes

bash

curl "https://api.mercozy.com/api/v1/external/orders?page=1&limit=10" \
  -H "X-API-Key: mk_live_your_key_here"

Actualizar estado del pedido

bash

curl -X PUT "https://api.mercozy.com/api/v1/external/orders/ord_abc123/status" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped"
  }'

Crear seguimiento de envío

bash

curl -X POST "https://api.mercozy.com/api/v1/external/orders/ord_abc123/shipment" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "fedex",
    "trackingNumber": "7489236401",
    "trackingUrl": "https://www.fedex.com/track?id=7489236401"
  }'