# Homologação > Teste sua integração com respostas fictícias, sem consultar a fonte e sem gastar créditos. URL: https://docs.fiscalapi.com.br/docs/getting-started/homologacao 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](https://app.fiscalapi.com.br?utm_source=docs\&utm_medium=docs\&utm_campaign=homologacao), 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 | | Produção | Homologação | | --------------------- | ------------------------------ | ------------------------------------------------------- | | Chave | `fapi_...` | `fapi_test_...` | | URL | `https://api.fiscalapi.com.br` | A mesma | | Rotas | Todas as do seu plano | `GET /api/consultar` e `GET /api/consultar-ie-todos` | | Dados | Fonte oficial | Fictícios, conforme a [massa de teste](#massa-de-teste) | | Créditos | Descontados | Nunca | | Limite de requisições | O da conta | 30 por minuto, por chave | * **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. Os dados de homologação são fictícios. Antes de ir para produção, troque a chave `fapi_test_...` pela sua chave de produção. ## ## Massa de teste Cada documento abaixo devolve sempre o mesmo resultado. O CNPJ pode ir com ou sem pontuação. | CNPJ | Resultado | IE devolvida | | -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------ | | `99.999.999/0001-91` | 1 IE habilitada em SP | SP `999990015005` | | `99.999.999/0002-72` | 3 IEs habilitadas: SP, MG e PR | SP `999990024006`, MG `0629990020042`, PR `9999900299` | | `99.999.999/0003-53` | 1 IE em SP com situação `Não habilitado` | SP `999990033007` | | `99.999.999/0004-34` | Nenhuma IE (`results: []`, como na produção) | — | | `99.999.999/0005-15` | Fonte oficial indisponível (ver abaixo) | — | | `99.999.999/0006-04` | Falha de processamento na fonte (ver abaixo) | — | | `99.999.999/0007-87` | Igual ao `0001-91`, mas responde em cerca de 20 segundos (para testar o timeout) | SP `999990070004` | | `99.999.999/0008-68` | `402` com o código `LIMITE_ATINGIDO`, nas duas rotas | — | Como cada rota responde aos cenários de erro, como na produção: | Cenário | `/api/consultar` | `/api/consultar-ie-todos` | | ----------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------ | | `0005-15` | `503` com o código `SITE_INDISPONIVEL` | `200` com `complete: false` e todas as UFs com `source_status.status: "error"` | | `0006-04` | `502` com o código `PROCESSAMENTO_FALHOU` | `200` com `complete: false` e todas as UFs com `source_status.status: "error"` | | Documento com dígito verificador inválido | `400` com o código `DOCUMENTO_INVALIDO` | `200` sem inscrições | **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 ```bash 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): ```json { "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](/docs/consulta-ie/consultar-ie#resposta). ## ## 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`.