Guia rápido

Em cinco minutos você cria uma credencial, guarda o segredo no servidor e confirma a conexão com GET /v1/conta. A URL base é sempre https://api.cotejar.com.br: não existe ambiente de testes separado.

Antes de começar: acesso ao painel como proprietário ou administrador da empresa, e um servidor ou terminal onde a chave possa ficar fora do navegador.

1. Abra Integrações › API

   No painel do Cotejar, entre em Integrações e escolha Gerenciar credenciais no cartão API.

   app.cotejar.com.br › Integrações

   

   Na página da API, use Criar credencial. Crie uma credencial por sistema integrado: assim você revoga um ERP sem derrubar os outros.

   app.cotejar.com.br › Integrações › API

   

2. Marque só as permissões necessárias

   Dê um nome que identifique o sistema, como ERP principal. A validade é de 90 dias.

   Para seguir o tutorial completo, marque:

   No painel	Escopo
   Consultar conta	conta:ler
   Consultar catálogo	catalogo:ler
   Enviar produtos	catalogo:escrever
   Aplicar lotes	catalogo:aplicar
   Executar análises	analise:executar
   Gerenciar webhooks	webhook:gerenciar

   As dependências entram juntas: marcar Aplicar lotes inclui Enviar produtos, que inclui Consultar catálogo.

   Uma credencial não ganha permissões depois de emitida. Se faltar alguma, crie outra e revogue a anterior. A tabela completa está em Autenticação e permissões.

   

3. Copie o segredo, que aparece uma única vez

   Depois de criada, a credencial é exibida uma vez, no formato ctj_api_<id>.<segredo>. Copie direto para o gerenciador de segredos do servidor.

   

   O painel guarda só o prefixo, a validade e o último uso. Se o valor se perder, crie outra credencial.

4. Guarde a chave no servidor

   A chave autoriza a empresa inteira dentro das permissões marcadas. Ela não vai para o navegador, o aplicativo móvel, o repositório nem os logs.

   .env do servidor (fora do Git)

   COTEJAR_API_BASE_URL=https://api.cotejar.com.br
   COTEJAR_API_KEY=ctj_api_...   # valor copiado no passo anterior

5. Faça a primeira chamada

   GET/v1/contaconta:lerReferência →

   A rota devolve o contexto que a própria chave autoriza. Não altera nada.

   cURL

   curl --fail-with-body \
     --header "Authorization: Bearer $COTEJAR_API_KEY" \
     "$COTEJAR_API_BASE_URL/v1/conta"

   Node.js

   conta.mjs

   // Node.js 20 ou mais recente; fetch nativo, sem dependência.
   const base = process.env.COTEJAR_API_BASE_URL
   const chave = process.env.COTEJAR_API_KEY
   if (!base || !chave) throw new Error('Configure COTEJAR_API_BASE_URL e COTEJAR_API_KEY.')
   
   const resposta = await fetch(new URL('/v1/conta', base), {
     headers: { authorization: `Bearer ${chave}` },
     redirect: 'error',
     signal: AbortSignal.timeout(15_000),
   })
   if (!resposta.ok) {
     const referencia = resposta.headers.get('x-request-id') ?? 'ausente'
     throw new Error(`HTTP ${resposta.status}; referência ${referencia}: ${await resposta.text()}`)
   }
   console.log(await resposta.json())

   Python

   conta.py

   # Python 3.10 ou mais recente, com requests instalado.
   import os
   import requests
   
   base = os.environ["COTEJAR_API_BASE_URL"]
   chave = os.environ["COTEJAR_API_KEY"]
   
   resposta = requests.get(
       f"{base}/v1/conta",
       headers={"Authorization": f"Bearer {chave}"},
       allow_redirects=False,
       timeout=15,
   )
   if resposta.status_code != 200:
       referencia = resposta.headers.get("X-Request-Id", "ausente")
       raise RuntimeError(f"HTTP {resposta.status_code}; referência {referencia}: {resposta.text}")
   print(resposta.json())

6. Confira a resposta

   200 OK

   {
     "credencial_id": "196086a4-821c-4a7b-b4e4-0dd696046a4b",
     "cnpj_raiz": "12345678",
     "escopos": ["conta:ler", "catalogo:ler", "catalogo:escrever", "catalogo:aplicar", "analise:executar", "webhook:gerenciar"],
     "expira_em": "2027-01-11T16:26:02.032Z"
   }

   • cnpj_raiz precisa ser a raiz da sua empresa. Se não for, a chave foi emitida em outra empresa.
   • escopos lista exatamente o que foi marcado no painel.
   • expira_em é o fim da validade. Agende a troca antes dessa data: veja rotação sem interrupção.
   • credencial_id serve de referência para o suporte e não substitui a chave.

Se a chamada falhar

Toda recusa vem em JSON, com um código estável e o request_id para suporte:

401 Unauthorized

{
  "erro": {
    "codigo": "CREDENCIAL_INVALIDA",
    "mensagem": "credencial ausente, inválida, expirada ou revogada",
    "request_id": "b0b071f7-f965-443d-a0a4-4ad20a9219c2"
  }
}

Status	O que conferir
401	O cabeçalho é Authorization: Bearer <chave>, sem aspas extras nem quebra de linha. A credencial pode ter expirado ou sido revogada.
403	A credencial não tem a permissão da rota. Crie outra com o escopo necessário.
429	Muitas chamadas no minuto. Aguarde o tempo de Retry-After.
Erro de TLS ou redirecionamento	A URL precisa ser exatamente https://api.cotejar.com.br. Nunca siga redirecionamentos com a chave no cabeçalho.

A lista completa está em Erros e repetição segura.

Próximos passos

Testar com segurançaValide a integração em produção sem alterar o catálogo.

Do ERP à primeira análiseO fluxo completo, com as respostas reais de cada etapa.