Primeira requisição

Use https://api.cotejar.com.br como URL base de produção e uma chave emitida no contexto da empresa correta. Guarde a configuração no servidor da integração:

Os exemplos da referência usam valores sintéticos. Substitua a URL base, o token e os UUIDs pelos valores do seu ambiente. Gere uma chave de idempotência para cada pedido novo; repita a mesma chave somente ao reenviar esse pedido.

export COTEJAR_API_BASE_URL='https://api.cotejar.com.br'
export COTEJAR_API_KEY='valor-guardado-no-gerenciador-de-segredos'

Não use uma URL interna, um endereço de loopback do Cotejar ou caminhos sob /internal/mcp.

Confirme a chave

Com o escopo conta:ler, consulte o contexto que a própria chave autoriza:

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

Uma resposta bem-sucedida tem esta forma:

{
  "credencial_id": "a1f1d404-5a14-4f91-9b8d-7f975ef405fd",
  "cnpj_raiz": "12345678",
  "escopos": ["conta:ler", "catalogo:ler"],
  "expira_em": "2026-12-01T15:00:00.000Z"
}

Os valores são sintéticos. credencial_id serve como referência de suporte e não substitui a chave.

Trate a resposta inteira

Leia o status HTTP, o corpo e os cabeçalhos. Guarde X-Request-Id quando uma operação falhar. Em 429 ou 503, respeite Retry-After quando estiver presente. Uma integração não deve converter erro de rede, timeout ou resposta incompleta em sucesso.

const base = process.env.COTEJAR_API_BASE_URL
const chave = process.env.COTEJAR_API_KEY

if (!base || !chave) throw new Error('Configuração da API ausente.')

const url = new URL('v1/conta', `${base.replace(/\/+$/, '')}/`)
if (url.protocol !== 'https:') throw new Error('A integração pública exige HTTPS.')

const resposta = await fetch(url, {
  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(`API recusou a consulta: HTTP ${resposta.status}; referência ${referencia}`)
}

const conta = await resposta.json()
// Encaminhe o resultado ao fluxo privado do integrador; não registre a chave.

Siga para autenticação e permissões antes de liberar escritas.