zankh Developers

Parceiros

Pedidos do agente

O aperto de mãos de atendimento: o cliente já pagou, e a sua resposta libera ou estorna a remessa.

Todas as páginas▾

Comece aqui

Catálogo

Vendas

Inteligência artificial

Parceiros

Referência

Quando um cliente autoriza uma compra do agente que inclui ofertas suas, cada remessa vira um pedido do agente com status pending. O cliente já pagou a zankh (em Saldo); o acerto com o parceiro segue o acordo comercial.

  • GET/v1/partners/agent-ordersLista, do mais recente para o mais antigo. ?status=pending é a fila de trabalho.
  • GET/v1/partners/agent-orders/{id}Um pedido do agente, com itens, valores e endereço de entrega.
  • POST/v1/partners/agent-orders/{id}/acceptAceita o atendimento, com rastreio opcional. Idempotente.
  • POST/v1/partners/agent-orders/{id}/rejectRecusa com motivo obrigatório — o cliente é estornado automaticamente.

Aceitar

 
curl -X POST https://api.zankhapi.com.br/v1/partners/agent-orders/PEDIDO_ID/accept \
  -H "Authorization: Bearer zk_partner_..." \
  -H "Content-Type: application/json" \
  -d '{
    "trackingCode": "BR123456789BR",
    "carrier": "Correios"
  }'

Idempotente: repetir a chamada corrige o rastreio no lugar, em vez de criar um segundo aceite.

Recusar

reason é obrigatório e é mostrado ao cliente. O valor daquela remessa é estornado automaticamente no saldo dele; o estorno também é idempotente, então retentar é seguro.

O que vem no pedido

 
{
  "id": "6f2a...",
  "status": "pending",
  "amountCents": 6330,
  "items": [
    { "offerId": "0b1c...", "sku": "MLB-123",
      "title": "Overgrip Head Prime x3",
      "quantity": 1, "unitPriceCents": 4490 }
  ],
  "shippingAddress": {
    "name": "Victor Zampieri", "phone": "+5511...",
    "street": "Rua Exemplo", "number": "100", "complement": null,
    "district": "Moema", "city": "São Paulo", "state": "SP",
    "postalCode": "05690-020"
  },
  "trackingCode": null,
  "carrier": null,
  "rejectReason": null,
  "createdAt": "2026-09-18T14:03:00.000Z",
  "acknowledgedAt": null
}

amountCents (mercadoria + o frete do parceiro) é exatamente o que foi debitado do saldo do cliente naquela remessa — e exatamente o que uma recusa devolve.