Pular para o conteúdo
CotejarCotejarCotejar para desenvolvedores

API v1 · produção em api.cotejar.com.br

Integre o Catálogo de Produtos ao seu sistema

Sincronize os produtos do ERP, peça análises completas e receba avisos assinados quando as exigências mudam. Cada operação é autenticada, repetível e verificável.

Começar pelo guia rápidoReferência da API
  • REST e JSON
  • Chave Bearer por empresa
  • Escritas idempotentes
  • Webhooks assinados
  • OpenAPI 3.0
Confirme a chave
curl https://api.cotejar.com.br/v1/conta \
  -H "Authorization: Bearer $COTEJAR_API_KEY"
{
  "credencial_id": "196086a4-821c-4a7b-b4e4-0dd696046a4b",
  "cnpj_raiz": "12345678",
  "escopos": ["conta:ler", "catalogo:ler", "catalogo:escrever"],
  "expira_em": "2027-01-11T16:26:02.032Z"
}

Como a integração funciona

Seção intitulada “Como a integração funciona”

O ERP envia o catálogo em lotes, o Cotejar valida antes de aplicar e a análise compara cada produto com a regra vigente do Portal Único. O resultado chega por webhook e em um CSV com tamanho e hash conferíveis.

  1. CredencialCrie a chave no painel, só com as permissões necessárias.Integrações › API
  2. LotesEnvie os produtos do ERP em lotes de até 200.PUT …/lotes/{n}
  3. PréviaValide, confira as recusas e só então aplique.validar → aplicar
  4. AnálisePeça a análise completa e acompanhe o estado.POST /v1/analises
  5. ResultadoReceba o aviso assinado e baixe o CSV conferido.webhook + CSV

Por onde começar

Seção intitulada “Por onde começar”
Guia rápidoCrie a credencial no painel e faça a primeira chamada autenticada em cinco minutos.
Do ERP à primeira análiseTutorial completo: lotes, prévia, aplicação, análise, webhook e CSV, com as respostas reais.
Testar com segurançaNão existe sandbox. Veja como validar a integração em produção sem alterar o catálogo.
Exemplos de códigoCliente HTTP, receptor de webhook e validação do CSV em Node.js e Python, prontos para adaptar.

Por tarefa

Seção intitulada “Por tarefa”

Analisar e vigiar

Análises comparam todos os produtos ativos com a regra vigente. A vigilância repete a conferência nos produtos selecionados.

Receber avisos

Webhooks assinados avisam aplicação, análise concluída e mudança nas divergências. Veja o receptor pronto.

Quatro contratos que valem em toda rota

Seção intitulada “Quatro contratos que valem em toda rota”
  • Uma chave, uma empresaA credencial pertence a um CNPJ raiz. Nenhum campo do corpo ou da URL troca de empresa.
  • Toda escrita é repetívelIdempotency-Key em cada mutação: repetir após um timeout devolve o recibo original, sem efeito duplicado.
  • Aceite não é conclusão202 confirma que o pedido foi guardado. Acompanhe o recurso em Location até um estado final.
  • Sucesso se comprovaWebhooks trazem assinatura HMAC e o CSV traz tamanho e SHA-256. HTTP 200 sozinho não basta.

A referência navegável é gerada do OpenAPI exportado pela própria API. Para gerar clientes ou validar requisições no seu ambiente, baixe o arquivo OpenAPI.