Homologação

O ambiente de homologação serve para testar sua integração antes de ir para produção. Com uma chave de homologação, a API responde com dados fictícios e previsíveis: a consulta nunca vai à fonte e nunca desconta créditos.

Criar a chave

1. No Dashboard, abra Chave API e vá até a seção Homologação.
2. Clique em Criar chave de homologação e dê um nome a ela.
3. Copie a chave. Ela começa com fapi_test_ e aparece uma única vez, na criação.

• Não é preciso ter plano ativo.
• Cada conta pode ter até 2 chaves de homologação ativas. Acima disso, a criação responde 409 com o código LIMITE_DE_CHAVES. Revogue uma para criar outra.
• A chave de homologação nunca é a principal: gerar uma nova chave principal não a afeta.

O que muda e o que não muda

• Mesmos parâmetros e mesmo formato. As duas rotas recebem os mesmos parâmetros e respondem no mesmo formato da produção, inclusive nos erros. A exceção é secundarias=true: em homologação o parâmetro é aceito e ignorado, e cnaes_secundarios vem sempre null.
• Ambiente identificado. Toda resposta de /api/consultar e /api/consultar-ie-todos, em produção e em homologação, traz o header X-FiscalAPI-Ambiente (producao ou homologacao). As respostas 200 também trazem o campo ambiente no topo do JSON; as respostas de erro trazem só o header.
• Limite próprio. Acima de 30 requisições por minuto na mesma chave, a API responde 429.
• Só as rotas de IE, por enquanto. Qualquer outra rota da API chamada com chave de homologação responde 403 com o código ROTA_SEM_HOMOLOGACAO.
• Ambiente indisponível. Se a homologação estiver temporariamente desligada, a chave de teste recebe 403 com o código API_KEY_ERROR e a mensagem "Ambiente de homologação indisponível". A chave de produção não é afetada.
• Histórico. As chamadas aparecem no histórico de consultas do Dashboard e no CSV marcadas como homologação, sem custo. Recusas (403) e o cenário de saldo insuficiente (402) não entram no histórico.

Massa de teste

Cada documento abaixo devolve sempre o mesmo resultado. O CNPJ pode ir com ou sem pontuação.

Como cada rota responde aos cenários de erro, como na produção:

Qualquer outro CPF ou CNPJ válido devolve uma IE habilitada fictícia, com razão social EMPRESA DE HOMOLOGACAO NNNN LTDA (os 4 últimos dígitos do documento). Em /api/consultar, ela vem em qualquer UF pedida, com uma IE diferente para cada UF e sempre a mesma para cada combinação de documento e UF. Em /api/consultar-ie-todos, ela aparece em uma UF só.

• Em /api/consultar?uf=XX, voltam só as IEs da UF pedida. Exemplo: 99.999.999/0001-91 com uf=MG responde results: [].
• Os cenários 0005, 0006, 0007 e 0008 valem em qualquer UF.
• A consulta por ie= funciona com as IEs da tabela, na UF de cada uma, e devolve o mesmo cenário. Outras IEs respondem results: [].

Exemplo

curl -i "https://api.fiscalapi.com.br/api/consultar?uf=SP&cnpj=99999999000191" \
  -H "X-API-Key: fapi_test_sua_chave_aqui"

Resposta, com o header X-FiscalAPI-Ambiente: homologacao (o request_id e a data_atualizacao mudam a cada chamada):

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "ambiente": "homologacao",
  "document": "99999999000191",
  "document_type": "cnpj",
  "uf": "SP",
  "cached": false,
  "data_atualizacao": "2026-10-23T14:05:12-03:00",
  "demo": false,
  "results": [
    {
      "inscricao_estadual": "999990015005",
      "razao_social": "EMPRESA DE HOMOLOGACAO 0191 LTDA",
      "nome_fantasia": "",
      "situacao_ie": "Habilitado",
      "uf_ie": "SP",
      "tipo_ie": "IE Normal",
      "logradouro": "RUA DE HOMOLOGACAO",
      "complemento": "",
      "bairro": "CENTRO",
      "numero": "100",
      "municipio": "SAO PAULO",
      "municipio_ibge": "3550308",
      "cep": "01000000",
      "regime_pagamento": "",
      "data_situacao": "01/03/2020",
      "situacao_contribuinte": "Sem restrição",
      "data_inicio_atividade": "01/03/2020",
      "cnae_codigo": "0151201",
      "cnae_descricao": "CRIAÇÃO DE BOVINOS PARA CORTE",
      "regime_apuracao_icms": "NORMAL",
      "situacao_nfe": "NFe",
      "cpf_cnpj": "99.999.999/0001-91",
      "situacao_cadastral": "",
      "cnaes_secundarios": null,
      "data_situacao_iso": "2020-03-01",
      "data_inicio_atividade_iso": "2020-03-01"
    }
  ]
}

O significado de cada campo está em Consultar IE por UF.

Salesforce (Apex)

• Trocar de ambiente é trocar a chave. Se a chave fica num Named Credential, mude só a chave para alternar entre homologação e produção: a URL é a mesma.
• Teste o timeout do callout com o CNPJ 99.999.999/0007-87, que responde em cerca de 20 segundos. No Apex, o timeout padrão do callout é de 10 segundos; em produção, a consulta pode ir até a fonte oficial e a API encerra a requisição em 90 segundos, então configure o callout entre 100 e 120 segundos com setTimeout.

Planos e preços