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

Servidor MCP

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.