API de pedidos2026-11Vista previa

Pedidos

Una venta tuya que compramos al vendedor, revisamos y fotografiamos en nuestro almacén, empacamos en tu caja y enviamos a tu cliente.

Sigue un pedido con webhooks en lugar de consultarlo periódicamente: los eventos de pedido se disparan con cada paso. El paquete en sí es una orden de preparación y luego un envío.

Endpoints

POST/v1/ordersCrear un pedido
GET/v1/ordersListar pedidos
GET/v1/orders/{id}Obtener un pedido
POST/v1/orders/{id}/cancelCancelar un pedido

El objeto Order

idstring: Empieza por ord_.
external_idstring: El número de pedido de tu tienda. Único en tu cuenta.
sourcestring: api, o shopify para pedidos que nos envió tu tienda de Shopify.
statusstring: El estado de la línea menos avanzada; consulta Estados más abajo.
payment_statusstring: awaiting_payment, paid, partially_refunded o refunded.
lanestring: saver o fast.
lines[]array: Variante, cantidad, unidades compradas por artículo, estado, las fotos del almacén una vez revisada, y reason si se rechazó.
ship_toobject: El nombre, la dirección, el teléfono y el correo de tu cliente.
packagingstring|null: Tu caja o sobre con marca; el tuyo por defecto si es null.
chargesobject: Lo que cuesta, en CN¥: la compra (mercancía, tarifa de recepción, impuesto) y el paquete (envío, tarifa de manipulación, impuesto). El paquete es una estimación según tus pesos hasta que lo pesemos.
amount_duemoney|null: Lo que tu saldo aún tiene que cubrir, mientras está en awaiting_payment.
fulfillment_orders[]array: Los paquetes en que sale.

order

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Envíanos uno de los pedidos de tu tienda. Cada línea es una variante que guardaste, o un enlace de publicación y un SKU que compramos tal cual. El pedido se paga de inmediato desde tu saldo; uno que tu saldo no cubre se crea igualmente, como awaiting_payment con amount_due, y continúa solo cuando recargas.

Los pedidos de tu tienda de Shopify nos llegan sin esta llamada. Úsala para WooCommerce, Wix, tu propio sitio o cualquier otra cosa que venda.

Alcanceorders:write

Cuerpo

external_idstringobligatorio: Tu número de pedido. Un segundo pedido con él se rechaza.
lines[]arrayobligatorio: variant y quantity, o url, sku y quantity. units (opcional) compra esa cantidad por artículo, para paquetes.
ship_toobjectobligatorio: name, line1, line2, city, region, postal_code, country (dos letras), phone, email.
lanestring: saver o fast. saver si se omite.
packagingstring: Opcional. Un id de empaque; el tuyo por defecto si se omite.
notestring: Opcional. Para el equipo de nuestro almacén, hasta 500 caracteres.

Errores

Estado	Tipo	Cuándo
400	bad-body	Falta un campo o es incorrecto; errors[] lo señala.
409	duplicate-order	external_id ya es un pedido; order lo indica.
422	unprocessable	La variante de una línea está agotada o su enlace no se puede leer.
422	not-shippable	Ninguna tarifa publicada llega a ship_to.country en esa línea.

curl -X POST "https://www.ninjabuy.com/api/v1/orders" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1012",
    "lines": [{ "variant": "var_41hz", "quantity": 1 }],
    "ship_to": {
      "name": "Sam Rivera",
      "line1": "500 Congress Ave",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "country": "US",
      "phone": "+15125550142",
      "email": "sam@example.com"
    },
    "lane": "saver"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "api",
  "status": "buying",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "buying",
      "photos": [],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": [],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Listar pedidos

GET/v1/orders

Lo más reciente primero.

Alcanceorders:read

Parámetros de consulta

statusstring: Opcional. Uno de los estados siguientes.
sourcestring: Opcional. api o shopify.
external_idstring: Opcional. Busca uno por tu propio número de pedido.
created_sincestring: Opcional. Una hora.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/orders?status=checked" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "ord_3n7q",
      "external_id": "1012",
      "status": "checked",
      "payment_status": "paid"
    }
  ],
  "has_more": false,
  "cursor": null
}

Obtener un pedido

GET/v1/orders/{id}

El estado de cada línea, sus fotos del almacén una vez revisada, lo que costó y sus paquetes.

Alcanceorders:read

Parámetros de ruta

idstringobligatorio: El id del pedido.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe ese pedido en esta cuenta.

curl "https://www.ninjabuy.com/api/v1/orders/ord_3n7q" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Cancelar un pedido

POST/v1/orders/{id}/cancel

Antes de que compremos, se reembolsa todo el pedido a tu saldo. Una vez comprado, se reembolsan las líneas que el vendedor acepta de vuelta y el resto queda en tu estante como stock en almacén. Un pedido enviado no se puede cancelar.

Alcanceorders:write

Parámetros de ruta

idstringobligatorio: El id del pedido.

Cuerpo

reasonstring: Opcional. Se guarda en el pedido.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe ese pedido en esta cuenta.
409	invalid-state	Se ha enviado.

curl -X POST "https://www.ninjabuy.com/api/v1/orders/ord_3n7q/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer changed their mind" }'

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "status": "cancelled",
  "payment_status": "refunded",
  "refunded": { "amount": "191.52", "currency": "CNY" }
}

Estados

Cada línea tiene su propio estado; el de un pedido es el de su línea menos avanzada. En orden:

Estado	Significado
awaiting_payment	Tu saldo no lo cubrió. Recarga y continúa solo.
buying	Pagado; se lo estamos comprando al vendedor.
with_seller	Comprado; el vendedor aún no lo ha enviado a nuestro almacén.
checked	En nuestro almacén, revisado y fotografiado, esperando a empacarse.
shipped	En camino, con seguimiento.
delivered	El transportista indica que llegó.
rejected	No pudimos comprarlo (agotado, enlace inexistente); reason indica por qué, y se reembolsa.
cancelled	Lo cancelaste.

Dinero

En los ejemplos, comprar una unidad cuesta 57,00 CNY y enviarla 134,52 CNY, descontados de tu saldo. Qué es cada línea: Tarifas.

El objeto Order

Crear un pedido

Cuerpo

Errores

Listar pedidos

Parámetros de consulta

Obtener un pedido

Parámetros de ruta

Errores

Cancelar un pedido

Parámetros de ruta

Cuerpo

Errores

Estados

Dinero