Venda no marketplace zankh direto do seu sistema

Autenticação

Envie a chave em toda requisição no cabeçalho Authorization: Bearer zk_live_.... Chaves adicionais podem ser geradas (e revogadas) a qualquer momento no painel administrativo da sua loja, em Chaves de API. Cada chave pertence a uma única loja e dá acesso somente aos dados dela. Nunca exponha a chave em sites ou aplicativos — uso exclusivo servidor-a-servidor.

Endpoints

Conecte sua IA (MCP)

A mesma API acima, falada em MCP — o protocolo que Claude Code, Codex e outras ferramentas de IA usam para descobrir e executar operações sozinhas. Em vez de escrever um script para subir 400 produtos, você conecta a sua ferramenta neste endereço e descreve o catálogo: ela lê as operações disponíveis e executa.

Endereço: https://api.zankhapi.com.br/mcp · autenticação: a mesma chave do REST (Authorization: Bearer zk_live_...). Uma chave é uma loja: toda ferramenta opera dentro dela, e não existe parâmetro de loja para a IA errar.

1. Conectar

Pela linha de comando do Claude Code:

claude mcp add --transport http zankh https://api.zankhapi.com.br/mcp \
  --header "Authorization: Bearer zk_live_SUA_CHAVE"

Ou no arquivo de configuração, para qualquer cliente MCP:

{
  "mcpServers": {
    "zankh": {
      "type": "http",
      "url": "https://api.zankhapi.com.br/mcp",
      "headers": { "Authorization": "Bearer zk_live_SUA_CHAVE" }
    }
  }
}

2. Pedir

Cole este prompt na sua ferramenta. Ele já traz as três regras que evitam os erros comuns — conferir a loja antes de escrever, não duplicar, e preço em centavos:

Você está conectado ao MCP da zankh, onde fica o catálogo da minha loja.

1. Chame dados_da_loja e me diga em qual loja você está. Se não for a que eu espero, pare.
2. Chame listar_produtos para ver o que já existe — não quero duplicar nada.
3. Cadastre os produtos do arquivo em anexo com criar_produto, um por vez.

Regras:
- Preço em CENTAVOS inteiros: R$ 199,90 é 19990, nunca 199.9.
- Se um produto já existir com o mesmo nome, pule e me diga qual.
- Ao terminar, liste o que criou e o que pulou.

Ferramentas disponíveis

• dados_da_loja — confirma em qual loja a chave está
• listar_produtos — o catálogo atual, paginado
• criar_produto — cadastra um produto
• listar_pedidos — os pedidos da loja

Cadastrar loja não é uma ferramenta do MCP de propósito: ela cria uma conta com e-mail e senha do dono, o que é um cadastro e não algo que um agente dispara no meio de uma conversa. Use POST /v1/stores acima — é de lá que sai a chave que o MCP exige.

Parceiros integrados

Grandes fornecedores e marketplaces podem integrar o próprio catálogo à zankh: o nosso agente de compras oferece os itens do parceiro como alternativa quando nenhuma loja da rede zankh atende o pedido — a rede zankh é sempre buscada primeiro, e cada cliente ativa cada parceiro individualmente.

1. Registre-se com POST /v1/partners — a chave zk_partner_... é exibida uma única vez.
2. Sincronize o catálogo com PUT /v1/partners/offers (upsert por SKU, até 500 ofertas por chamada) sempre que preço ou estoque mudarem. O prazo de entrega informado em deliveryDays é o compromisso do parceiro.
3. Verifique a chave com GET /v1/partners/me.

Pedidos do agente — o aperto de mãos de atendimento

Quando um cliente autoriza uma compra do agente que inclui ofertas do parceiro, cada remessa vira um pedido do agente com status pending — o cliente já pagou a zankh (saldo); o acerto com o parceiro segue o acordo comercial. Consulte a fila com GET /v1/partners/agent-orders?status=pending (o pedido traz itens, valores em centavos e o endereço de entrega) e confirme cada um:

• Aceitar — POST .../{id}/accept, com trackingCode e carrier opcionais. Idempotente — repetir a chamada corrige o rastreio.
• Recusar — POST .../{id}/reject com reason obrigatório (mostrado ao cliente). O valor da remessa é estornado automaticamente no saldo do cliente; o estorno é idempotente, então repetir a chamada é seguro.

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

Um pedido já recusado não pode mais ser aceito (409 agent_order_already_rejected) e um já aceito não pode ser recusado pela API (409 agent_order_already_accepted — fale com a zankh para reverter).