Vendas

Pedidos

Ler a fila de trabalho, abrir um pedido com endereço e itens, cancelar o que não foi pago.

Todas as páginas▾

Comece aqui

Catálogo

Vendas

Inteligência artificial

Servidor MCP

Parceiros

Referência

GET/v1/ordersLista pedidos, do mais recente para o mais antigo. Filtros: status, search, page, pageSize.
GET/v1/orders/{id}Um pedido, com comprador, endereço estruturado e itens.
POST/v1/orders/{id}/cancelCancela um pedido ainda não pago. Idempotente.
PUT/v1/orders/external/{canal}/{idNoMarketplace}Registra um pedido feito NUM MARKETPLACE em que a loja vende (Mercado Livre, Shopee...) — veja abaixo. 201 criou, 200 já existia.

A fila de trabalho

Enquanto não existem webhooks (veja o que ainda não existe), a integração consulta. O que separar vai para o galpão é status=paid:

curl "https://api.zankhapi.com.br/v1/orders?status=paid&pageSize=50" \
  -H "Authorization: Bearer zk_live_..."

Um intervalo de poucos minutos é suficiente e educado. Guarde o id do último pedido que você já processou — a lista vem ordenada do mais novo para o mais antigo, então basta parar de ler quando reencontrá-lo.

Status

Status	O que significa
`pending`	Criado, aguardando pagamento. O dinheiro ainda não entrou.
`paid`	Pago. É a hora de separar e despachar.
`cancelled`	Cancelado. Um pedido pago que for cancelado já foi estornado no painel.

Cancelar

POST /v1/orders/{id}/cancel cancela um pedido não pago e é idempotente. Um pedido pago responde 409 order_already_paid: cancelar algo com dinheiro dentro exige estorno, e estorno acontece no painel, por Cancelar e estornar — o estorno roda antes do cancelamento e, se falhar, o pedido não é cancelado. Trocar o status nunca move dinheiro.

Pedido feito num marketplace

Se o seu sistema é quem segura a conta do Mercado Livre ou da Shopee da loja (publica lá com o token do vendedor e recebe as notificações de venda), mande cada venda para PUT /v1/orders/external/{canal}/{idNoMarketplace}: o pedido entra em Pedidos do painel, a loja é avisada (push no app, e-mail/WhatsApp, Telegram) e a tela mostra de qual marketplace e de qual conta ele veio. canal é um de mercado_livre, shopee, tiktok_shop, magalu, amazon.

curl -X PUT https://api.zankhapi.com.br/v1/orders/external/mercado_livre/2000012345678 \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paid", "isPaid": true, "isCancelled": false,
    "placedAt": "2026-11-02T14:03:00.000Z",
    "account": { "label": "Pedro" },
    "buyer": { "name": "João Souza", "phone": "11999990000" },
    "shipping": { "address": "Rua B, 22 · Centro · São Paulo - SP · 01000-000",
      "postalCode": "01000-000", "city": "São Paulo", "state": "SP",
      "costCents": 1990, "serviceName": "Mercado Envios" },
    "totalCents": 8980,
    "finance": { "grossCents": 8980, "itemsCents": 6990, "buyerShippingCents": 1990,
      "marketplaceFeeCents": 1188, "sellerShippingCostCents": 0, "netCents": 7792,
      "paymentMethod": "Cartão de crédito", "installments": 3, "estimated": true },
    "items": [{ "name": "Gato articulado", "quantity": 1, "unitPriceCents": 6990,
      "sku": "3DS-985561-M", "product": { "source": "3dstores", "externalId": "sm-985561" },
      "variantLabel": "Montado" }]
  }'

Regra	O que significa
Idempotente no par canal + id	A primeira chamada cria (`201`, `created: true`) e avisa a loja. As seguintes só espelham o `status` atual do marketplace (`200`): cancelado lá cancela aqui um pedido pendente, pago marca pago. Reenvie a cada mudança — nada duplica.
O dinheiro é do marketplace	`totalCents` é o que o comprador pagou lá (itens + frete) e fica como veio. A zankh não cobra, não reparte nem estorna esses pedidos, e não baixa estoque.
`finance` é quanto a loja recebe	O card de pagamento do pedido mostra a conta DO MARKETPLACE: `grossCents` (o comprador pagou), `marketplaceFeeCents` (tarifa + serviços), `sellerShippingCostCents` (frete por conta do vendedor), `otherFeesCents` e `netCents` (o repasse). `estimated: true` quando vem do pedido (tarifa por unidade do Mercado Livre), `false` quando é a liquidação (escrow da Shopee). Reenvie quando liquidar; chamada sem o bloco não apaga o que já foi gravado.
Linhas casam com os seus produtos	Mande `product: { source, externalId }` (a mesma chave do upsert de produtos) e, se houver, `sku` para a variação. Linha sem par fica com o `name` do marketplace — mande todas, o total precisa fechar.
Só pedido recente avisa	`placedAt` com mais de 24 h é gravado em silêncio — uma primeira carga de um mês de vendas não dispara trinta pushes.

O que vem no pedido

Todo pedido traz channel (storefront, marketplace, agent ou o canal do marketplace) e, quando nasceu num marketplace externo, um bloco external com { channel, orderId, status, accountLabel, netCents, finance } — id e status do marketplace como estão lá, a conta de vendedor e quanto a loja recebe. external é null nos pedidos que a zankh vendeu.

Resposta 200 (resumida)

{
  "data": {
    "id": "8c1d...",
    "status": "paid",
    "totalCents": 384980,
    "createdAt": "2026-09-18T12:04:00.000Z",
    "buyer": { "name": "Victor Zampieri", "email": "...", "phone": "+5511..." },
    "shippingAddress": {
      "street": "Rua Exemplo", "number": "100", "complement": null,
      "district": "Moema", "city": "São Paulo", "state": "SP",
      "postalCode": "05690-020"
    },
    "items": [
      { "productId": "1f2e...", "sku": "GPU-4070",
        "name": "Placa de vídeo RTX 4070",
        "quantity": 1, "unitPriceCents": 349990 }
    ]
  }
}