Documentação da API

Uma chamada HTTP devolve o cadastro completo de um produto pelo código de barras. Se você usa Delphi ou C#, os exemplos abaixo são coláveis.

A primeira chamada

Autenticação é um cabeçalho Authorization: Bearer com o seu token. Não há OAuth, não há renovação de sessão, não há segredo na URL.

copiarcurl -H "Authorization: Bearer sc_SEU_TOKEN_AQUI" \
  https://catalogo.wxdev.com.br/v1/produtos/7894900011517

O código pode ir com ou sem o dígito verificador à esquerda: internamente tudo vira GTIN-14, então 7894900011517 e 07894900011517 são o mesmo produto.

Delphi e C#

Os dois trechos são completos — cabeçalho, chamada e leitura do JSON.

uses System.Net.HttpClient, System.Net.URLClient, System.JSON;

function ConsultarProduto(const Gtin: string): TJSONObject;
var
  Http: THTTPClient;
  Resposta: IHTTPResponse;
begin
  Http := THTTPClient.Create;
  try
    Http.CustomHeaders['Authorization'] := 'Bearer sc_SEU_TOKEN_AQUI';
    Resposta := Http.Get('https://catalogo.wxdev.com.br/v1/produtos/' + Gtin);

    if Resposta.StatusCode = 200 then
      Result := TJSONObject.ParseJSONValue(Resposta.ContentAsString) as TJSONObject
    else
      Result := nil;   // ver a tabela de erros mais abaixo
  finally
    Http.Free;
  end;
end;

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "sc_SEU_TOKEN_AQUI");

var resposta = await http.GetAsync("https://catalogo.wxdev.com.br/v1/produtos/7894900011517");

if (resposta.IsSuccessStatusCode)
{
    var json = await resposta.Content.ReadAsStringAsync();
    using var doc = JsonDocument.Parse(json);
    var produto = doc.RootElement.GetProperty("produto");
    Console.WriteLine(produto.GetProperty("descricao").GetString());
}

Os campos da resposta

{
  "gtin": "07894900011517",
  "origem": "cache",
  "encontrado": true,
  "produto": {
    "descricao": "Coca-Cola Original 350ml",
    "marca": "Coca-Cola",
    "categoria": "Bebidas",
    "ncm": "22021000",
    "cest": "0300700",
    "unidade": "UN",
    "peso_liquido": 0.35,
    "fonte": "cadastroproduto",
    "confianca": 90,
    "imagem": {
      "thumb":  "https://.../thumb.webp",
      "media":  "https://.../media.webp",
      "grande": "https://.../grande.webp",
      "licenca": "CC BY-SA 3.0",
      "atribuicao": "Foto: Open Food Facts, sob licença CC BY-SA"
    }
  }
}

Sincronização incremental

É o endpoint que serve melhor a um ERP desktop: o cliente manda a lista de códigos que tem, recebe tudo de uma vez, grava no próprio banco e passa a ler do disco. No dia a dia o caixa bipa e o ERP responde sem tocar a rede — o que também significa que continua funcionando com a internet caída.

POST https://catalogo.wxdev.com.br/v1/sincronizar
Authorization: Bearer sc_SEU_TOKEN_AQUI
Content-Type: application/json

{ "gtins": ["7894900011517", "7891000100103"], "desde": "2026-09-01T00:00:00Z" }

Sem desde, vem o catálogo inteiro. Com desde, só o que mudou desde aquela data — guarde o sincronizado_em da resposta e mande de volta na próxima vez. Até 5.000 códigos por chamada.

A resposta separa quatro situações, e a diferença entre elas importa:

Revisão antes de importar no ERP

Comece mantendo os valores atuais. Mostre lado a lado as sugestões e peça confirmação por campo, inclusive para marca vazia e foto ausente. Não substitua descrição apenas por estar diferente. Compare marca, NCM e CEST; normalize a pontuação de NCM/CEST.

unidade_tipo informa comercial, apresentacao ou nao_classificada. Somente unidade comercial comprovada pode ser comparada a UNIDADE do ERP. Campos históricos sem origem comprovada ficam não classificados. “AM” e “910 ml” não são equivalentes.

A marca completa é preservada na API. O ERP adapta ao limite do DBF e mostra o texto abreviado/truncado e a codificação antes de gravar. Busca por descrição requer confirmar identidade, GTIN, marca e embalagem; semelhança não é confirmação.

Licença da foto

Licença ausente não comprova autorização para redistribuir. Preserve os créditos, a origem e as condições recebidas; veja as condições por fonte.

Códigos de erro

Como a cota funciona

A conta é de produtos distintos, não de consultas. O caixa bipar o mesmo refrigerante mil vezes por dia não custa nada e nunca é recusado — o que consome a faixa é conhecer um produto novo.

Duas consequências práticas:

• Estourar a faixa não derruba a loja. Tudo que você já cadastrou continua respondendo normalmente; o que para é aprender produto novo.
• Código interno e produto que não temos não consomem nada. Você só paga pelo que a gente de fato entrega.

Toda resposta traz o seu consumo nos cabeçalhos:

X-Produtos-Usados:     1842
X-Produtos-Limite:     2000
X-Produtos-Restantes:   158
X-Quota-Restante:     19873   (requisições restantes hoje)

Estabilidade do contrato

ERP instalado em loja física quase nunca é atualizado. Por isso a v1 é tratada como permanente: campo novo entra sempre opcional, e campo em uso nunca é removido nem renomeado. Você pode integrar hoje e não mexer mais.

Existe também um openapi.json, se a sua ferramenta gerar cliente a partir dele.

Planilha assistida e catálogo privado

Na área do cliente, envie um CSV padrão de até500 linhas, acompanhe o processamento e escolha o valor atual ou sugerido por campo antes de exportar. O processamento usa somente a base existente e o cadastro privado da loja selecionada, sem consultas externas. Produtos da base compartilhada seguem a cota do plano; cadastros próprios não consomem suas posições.

O resultado CSV e o relatório de lacunas são arquivos para mapear no importador do ERP. Não foi comprovado um leiaute de importação automática específico do SysLoja. Cabeçalhos do resultado: codigo,gtin,descricao,marca,unidade,ncm,cest,foto_url,foto_licenca,foto_atribuicao,foto_privada_path,origem,unidade_tipo,foto_licenca_url,foto_origem_url,foto_alteracoes. Respeite a licença e mantenha a atribuição das fotos compartilhadas. Códigos devem ser importados como texto para preservar zeros. A coluna foto_privada_path exige download autenticado; não é um link público.

Cadastro privado: código, descrição e uma foto da loja, consultáveis por uma rota separada. A credencial de loja fixa seu CNPJ; a credencial principal pode escolher uma loja previamente vinculada por X-Cliente-CNPJ. Sem esse cabeçalho, usa o catálogo da conta principal. Isso evita misturar o código123 de duas lojas.

GET https://catalogo.wxdev.com.br/v1/privados/123
Authorization: Bearer sc_...
X-Cliente-CNPJ: CNPJ_DA_LOJA_VINCULADA

A resposta traz descricao,versao,tem_foto e foto_path. Baixe foto_path usando a mesma credencial e o mesmo CNPJ. Fotos são WebP, servidas com autenticação e no-store; o ERP pode guardar a cópia na instalação daquela loja. Não use o caminho para expor fotos de outra loja.

Limites iniciais por conta:200 produtos privados,50 tarefas preservadas e2.000 requisições diárias nas ferramentas de conta. Foto original até3MB, normalizada em até800px e256KB. Tarefas processam25 linhas por etapa, são salvas no banco e podem ser retomadas. Revisões registram usuário, horário e escolhas; a base compartilhada não é alterada. Grade, cor/tamanho estruturados, novas fontes e publicação global de correções não fazem parte desta versão.

GET /v1/autopecas?montadora=Fiat&modelo=Uno&motor=1.0%20Fire&ano=2012
GET /v1/autopecas/{id}
POST /v1/autopecas/sincronizar
{ "ids": ["IDENTIFICADOR_DA_PECA"], "desde": "2026-10-10T00:00:00Z" }
GET /v1/autopecas/{id}/exportar/aplicacoes.csv