Esta loja é operada pela plataforma zankh — o ecossistema de e-commerce que conecta lojas próprias, o marketplace zankh e a API aberta descrita nesta página. A integração descrita aqui é com a zankh, não com uma loja individual: com uma única chave, sua loja passa a vender no marketplace zankh.

API zankh para desenvolvedores

Venda no marketplace zankh direto do seu sistema. A API aberta permite cadastrar sua loja, publicar e atualizar produtos, acompanhar e gerenciar pedidos e enviar códigos de rastreio — tudo por REST + JSON, em qualquer linguagem.

Cadastre sua loja

Uma única chamada cria sua loja no marketplace zankh e devolve sua primeira chave de API — dela em diante, é só publicar produtos. O e-mail e a senha informados também dão acesso ao painel administrativo da loja.

curl -X POST https://api.zankhapi.com.br/v1/stores \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Minha Loja",
    "address": "Av. Paulista, 1000, São Paulo - SP",
    "latitude": -23.5613,
    "longitude": -46.6565,
    "ownerEmail": "[email protected]",
    "ownerPassword": "escolha-uma-senha-forte"
  }'

A resposta traz sua loja e a chave zk_live_... — exibida uma única vez. Guarde-a com segurança.

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

Lojas

POST/v1/storesCadastra sua loja e recebe a primeira chave de API (não requer autenticação)
GET/v1/meIdentifica a loja da chave — teste de autenticação

Produtos

GET/v1/productsLista produtos (busca por nome/SKU, paginação)
POST/v1/productsCadastra um produto
GET/v1/products/{id}Detalha um produto, com imagens e estoque
PATCH/v1/products/{id}Atualiza campos de um produto
DELETE/v1/products/{id}Desativa um produto (soft delete)
PUT/v1/products/{id}/stockDefine o estoque absoluto

Pedidos

GET/v1/ordersLista pedidos (filtro por status, busca, paginação)
GET/v1/orders/{id}Detalha um pedido com itens e endereço de entrega
POST/v1/orders/{id}/cancelCancela um pedido ainda não pago

Rastreio

GET/v1/orders/{id}/trackingConsulta os rastreios do pedido
PUT/v1/orders/{id}/trackingEnvia ou corrige o código de rastreio do envio

Parceiros (chave zk_partner_...)

POST/v1/partnersRegistra um parceiro integrado (não requer autenticação)
GET/v1/partners/meIdentifica o parceiro da chave
PUT/v1/partners/offersSincroniza o catálogo do parceiro (upsert por SKU)
GET/v1/partners/agent-ordersLista os pedidos do agente destinados ao parceiro (?status=pending é a fila de trabalho)
GET/v1/partners/agent-orders/{id}Detalha um pedido do agente
POST/v1/partners/agent-orders/{id}/acceptAceita o atendimento — com código de rastreio opcional (idempotente)
POST/v1/partners/agent-orders/{id}/rejectRecusa com motivo — o cliente é estornado automaticamente (idempotente)

Exemplos

Cadastrar um produto

curl -X POST https://api.zankhapi.com.br/v1/products \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Placa de vídeo RTX 4070",
    "sku": "GPU-4070",
    "regularPriceCents": 349990,
    "stockQuantity": 5
  }'

Enviar código de rastreio

curl -X PUT https://api.zankhapi.com.br/v1/orders/PEDIDO_ID/tracking \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "trackingCode": "BR123456789BR",
    "carrier": "Correios",
    "status": "in_transit"
  }'

Valores monetários são sempre inteiros em centavos (19990 = R$199,90). Respostas de sucesso vêm em data; erros em { "error": { "code", "message" } }, com detalhes campo a campo nos erros de validação (HTTP 422).

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.

Registre-se com POST /v1/partners — a chave zk_partner_... é exibida uma única vez.
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.
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).

Como começar

Cadastre sua loja com POST /v1/stores (ou gere uma chave no painel, se sua loja já existe).
Confirme a chave com GET /v1/me.
Publique seu catálogo com POST /v1/products — os produtos aparecem no marketplace zankh.
Acompanhe as vendas com GET /v1/orders e envie o rastreio de cada envio.

Dúvidas ou precisa de um recurso que ainda não existe na API? Fale com a gente pelo painel da sua loja ou conheça a plataforma em zankh.com.br.