API de pedidos2026-11Prévia

Pedidos

Uma venda sua que compramos do vendedor, verificamos e fotografamos no nosso armazém, embalamos na sua caixa e enviamos ao seu cliente.

Acompanhe um pedido com webhooks em vez de consultas periódicas: os eventos de pedido são disparados a cada etapa. O pacote em si é uma ordem de processamento e depois um envio.

Endpoints

POST/v1/ordersCriar um pedido
GET/v1/ordersListar pedidos
GET/v1/orders/{id}Obter um pedido
POST/v1/orders/{id}/cancelCancelar um pedido

O objeto Order

idstring: Começa com ord_.
external_idstring: O número do pedido da sua loja. Único na sua conta.
sourcestring: api, ou shopify para pedidos que a sua loja Shopify nos enviou.
statusstring: O status da linha menos avançada; veja Status abaixo.
payment_statusstring: awaiting_payment, paid, partially_refunded ou refunded.
lanestring: saver ou fast.
lines[]array: Variante, quantidade, unidades compradas por item, status, as fotos do armazém depois de verificada, e reason quando recusada.
ship_toobject: Nome, endereço, telefone e e-mail do seu cliente.
packagingstring|null: A sua caixa ou envelope com marca; o seu padrão se null.
chargesobject: Quanto custa, em CN¥: a compra (mercadorias, taxa de recebimento, imposto) e o pacote (frete, taxa de manuseio, imposto). O pacote é uma estimativa a partir dos seus pesos até o pesarmos.
amount_duemoney|null: O que o seu saldo ainda precisa cobrir, enquanto em awaiting_payment.
fulfillment_orders[]array: Os pacotes em que sai.

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"
}

Envie um dos pedidos da sua loja para nós. Cada linha é uma variante que você salvou, ou um link de anúncio e um SKU que compramos como estão. O pedido é pago na hora com o seu saldo; um que o saldo não cobre é criado mesmo assim, como awaiting_payment com amount_due, e segue sozinho quando você recarregar.

Os pedidos da sua loja Shopify chegam até nós sem esta chamada. Use-a para WooCommerce, Wix, o seu próprio site ou qualquer outra coisa que venda.

Escopoorders:write

Corpo

external_idstringobrigatório: O seu número de pedido. Um segundo pedido com ele é recusado.
lines[]arrayobrigatório: variant e quantity, ou url, sku e quantity. units (opcional) compra essa quantidade por item, para kits.
ship_toobjectobrigatório: name, line1, line2, city, region, postal_code, country (duas letras), phone, email.
lanestring: saver ou fast. saver se omitido.
packagingstring: Opcional. Um id de embalagem; o seu padrão se omitido.
notestring: Opcional. Para a equipe do nosso armazém, até 500 caracteres.

Erros

Status	Tipo	Quando
400	bad-body	Um campo está faltando ou errado; errors[] aponta para ele.
409	duplicate-order	external_id já é um pedido; order o identifica.
422	unprocessable	A variante de uma linha está esgotada, ou o link dela não pode ser lido.
422	not-shippable	Nenhuma tarifa publicada chega a ship_to.country nessa linha.

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

Mais recentes primeiro.

Escopoorders:read

Parâmetros de consulta

statusstring: Opcional. Um dos status abaixo.
sourcestring: Opcional. api ou shopify.
external_idstring: Opcional. Encontre um pelo seu próprio número de pedido.
created_sincestring: Opcional. Um horário.
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
}

Obter um pedido

GET/v1/orders/{id}

O status de cada linha, as fotos do armazém depois de verificada, quanto custou e os pacotes.

Escopoorders:read

Parâmetros de caminho

idstringobrigatório: O id do pedido.

Erros

Status	Tipo	Quando
404	not-found	Esse pedido não existe nesta conta.

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 um pedido

POST/v1/orders/{id}/cancel

Antes de comprarmos, o pedido inteiro é reembolsado no seu saldo. Depois da compra, as linhas que o vendedor aceita de volta são reembolsadas e o resto fica na sua prateleira como estoque no armazém. Um pedido enviado não pode ser cancelado.

Escopoorders:write

Parâmetros de caminho

idstringobrigatório: O id do pedido.

Corpo

reasonstring: Opcional. Guardado no pedido.

Erros

Status	Tipo	Quando
404	not-found	Esse pedido não existe nesta conta.
409	invalid-state	Foi 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" }
}

Status

Cada linha tem o seu próprio status; o de um pedido é o da linha menos avançada. Em ordem:

Status	Significado
awaiting_payment	O seu saldo não cobriu. Recarregue e ele segue sozinho.
buying	Pago; estamos comprando do vendedor.
with_seller	Comprado; o vendedor ainda não enviou ao nosso armazém.
checked	No nosso armazém, verificado e fotografado, aguardando embalagem.
shipped	A caminho, com rastreio.
delivered	A transportadora diz que chegou.
rejected	Não conseguimos comprar (esgotado, link removido); reason diz o motivo, e o valor é reembolsado.
cancelled	Você cancelou.

Dinheiro

Nos exemplos, comprar uma unidade custa CN¥ 57,00 e enviá-la CN¥ 134,52, descontados do seu saldo. O que é cada linha: Taxas.

O objeto Order

Criar um pedido

Corpo

Erros

Listar pedidos

Parâmetros de consulta

Obter um pedido

Parâmetros de caminho

Erros

Cancelar um pedido

Parâmetros de caminho

Corpo

Erros

Status

Dinheiro