fairplaylojas
0
0

API para desenvolvedores

Venda nos marketplaces da plataforma 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

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).

Como começar

  1. Cadastre sua loja com POST /v1/stores (ou gere uma chave no painel, se sua loja já existe).
  2. Confirme a chave com GET /v1/me.
  3. Publique seu catálogo com POST /v1/products — os produtos aparecem no marketplace zankh.
  4. 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.