Consultas auxiliares de CEP e CNPJ com autenticação, cache e franquia por plano.

Status atual

Consultar CEP

curl \
  -H "Authorization: Bearer {token}" \
  https://fiscal.contora.com.br/api/v1/utils/cep/30140071

{
  "ok": true,
  "message": "Consulta de CEP concluida com sucesso.",
  "data": {
    "source": "fiscal_contora",
    "cached": false,
    "requested_at": "2026-07-03T12:00:00-03:00",
    "payload": {
      "cep": "30140071",
      "street": "Rua dos Aimorés",
      "district": "Boa Viagem",
      "city_name": "Belo Horizonte",
      "state_code": "MG"
    }
  }
}

Consultar CNPJ

curl \
  -H "Authorization: Bearer {token}" \
  https://fiscal.contora.com.br/api/v1/utils/cnpj/44295808000119

{
  "ok": true,
  "message": "Consulta de CNPJ concluida com sucesso.",
  "data": {
    "source": "fiscal_contora",
    "cached": false,
    "requested_at": "2026-07-03T12:00:00-03:00",
    "payload": {
      "cnpj": "44295808000119",
      "legal_name": "EMPRESA EXEMPLO LTDA",
      "trade_name": "EMPRESA EXEMPLO"
    }
  }
}

Consultar Cobertura de NFS-e (Por Código IBGE)

Verifica se um município de 7 dígitos emite pelo Padrão Nacional (Sefin Nacional / ADN) ou por provedor municipal próprio (ex: Sigem, Conam, ISSNet, Giss, Tinus, IPM, Coplan).

curl \
  -H "Authorization: Bearer {token}" \
  https://fiscal.contora.com.br/api/v1/utils/nfse-coverage/3550308

{
  "ok": true,
  "message": "Cobertura de NFS-e consultada.",
  "data": {
    "city_code": "3550308",
    "standard": "municipal",
    "provider": "ISSSaoPaulo",
    "verified": true
  }
}

Busca de Municípios e Cobertura Nacional

Busca rápida na base dos 5.571 municípios brasileiros por nome, código IBGE ou UF. Retorna o padrão fiscal, o provedor homologado e o status de disponibilidade.

curl \
  https://fiscal.contora.com.br/api/v1/utils/nfse-cities?q=Salvador&uf=BA

{
  "ok": true,
  "message": "Consulta de municípios concluída. 1 resultado(s) encontrado(s).",
  "total_found": 1,
  "expansion_sla": {
    "commitment": "Homologação e inclusão de nova cidade em até 3 dias úteis.",
    "on_error": "Até 3 dias úteis após a detecção do erro de emissão reportado pela software house.",
    "on_demand_request": "Até 3 dias úteis após a leitura da solicitação no suporte.",
    "support_url": "https://fiscal.contora.com.br/suporte"
  },
  "data": [
    {
      "ibge": "2927408",
      "nome": "Salvador",
      "uf": "BA",
      "provedor": "Sigem / Nota Salvador",
      "padrao": "municipal",
      "status": "homologado"
    }
  ]
}

Regras da primeira versão

• As consultas usam o mesmo Bearer token da API fiscal (a busca de municípios também está disponível publicamente na página de cobertura).
• GET /utils/nfse-coverage/{city_code} e GET /utils/nfse-cities são isentas de franquia auxiliar.
• cache hit de CEP e CNPJ não consome a franquia auxiliar no modelo atual.
• cache miss com sucesso consome uma unidade da franquia de CEP ou CNPJ.
• Nos planos pagos, se a assinatura ativa estiver vencida, suspensa ou cancelada, a API responde 402 subscription_overdue. O plano Gratuito continua sujeito às próprias franquias.
• Se a franquia auxiliar do plano for excedida, a API responde 402 quota_exceeded.
• Se o plano não incluir franquia para o recurso, a API responde 402 plan_upgrade_required.

Validação de entrada