zankh Developers

Referência

Referência da API

Todas as rotas do v1 numa página, mais as convenções que valem para todas elas.

Todas as páginas▾

Comece aqui

Catálogo

Vendas

Inteligência artificial

Parceiros

Referência

Base: https://api.zankhapi.com.br/v1. Em desenvolvimento: http://localhost:8090/v1.

Convenções

  • Dinheiro é sempre inteiro na menor unidade da moeda da loja (centavos, no real): 19990 = R$ 199,90. Não há float no contrato.
  • Sucesso embrulha o conteúdo em data; listagens acrescentam page, pageSize, pageCount e total.
  • Erro é sempre { "error": { "code", "message" } } — inclusive JSON malformado e erro inesperado do servidor.
  • Paginação: ?page=1&pageSize=50, com pageSize máximo de 200.
  • Escritas idempotentes: as rotas PUT (estoque, rastreio, variações, chave externa) definem estado absoluto — retentar é seguro.
  • Limpar um campo: envie null. Chave ausente deixa o campo como está.

Lojas

  • POST/v1/storesCadastra loja + conta do dono, devolve a primeira chave.sem chave
  • GET/v1/meA loja a que a chave pertence.

Produtos

  • GET/v1/productsLista produtos (busca por nome/SKU, filtro active, paginação).
  • POST/v1/productsCria um produto.
  • GET/v1/products/{id}Detalha um produto, com imagens, estoque, categorias e variações.
  • PATCH/v1/products/{id}Atualiza campos de um produto.
  • DELETE/v1/products/{id}Apaga o produto sem pedidos; desativa o já vendido.
  • PUT/v1/products/{id}/stockDefine o estoque absoluto (produto sem variação ativa).
  • PUT/v1/products/external/{source}/{externalId}Cria ou atualiza pelo id do seu sistema.
  • GET/v1/products/external/{source}/{externalId}O produto da sua chave externa.
  • GET/v1/products/{id}/variantsTipos e variações do produto.
  • PUT/v1/products/{id}/variantsSubstitui a lista completa de variações.

Categorias

  • GET/v1/categoriesAs categorias da loja (os slugs de categorySlugs).

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

  • POST/v1/partnersRegistra um parceiro integrado.sem chave
  • 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.
  • GET/v1/partners/agent-orders/{id}Detalha um pedido do agente.
  • POST/v1/partners/agent-orders/{id}/acceptAceita o atendimento (idempotente).
  • POST/v1/partners/agent-orders/{id}/rejectRecusa com motivo — estorna o cliente (idempotente).