Mock da BrasilAPI para testes
Troque a URL base e seus testes de CEP, CNPJ e bancos param de depender da API real. O formato das respostas é o mesmo, os dados são fictícios e a mesma entrada devolve sempre a mesma resposta.
Funciona sem cadastro, até 50 chamadas por dia.
curl https://fakeforge.com.br/api/mock/brasilapi/cnpj/v1/47960351000108Como trocar a URL
Deixe a URL base numa variável de ambiente e aponte para o mock só nos testes:
# .env.test
BRASILAPI_URL=https://fakeforge.com.br/api/mock/brasilapi
# .env.production
BRASILAPI_URL=https://brasilapi.com.br/apiconst base = process.env.BRASILAPI_URL;
const resposta = await fetch(`${base}/cnpj/v1/${cnpj}`);
const empresa = await resposta.json();
empresa.razao_social; // sempre a mesma para este CNPJ
empresa.descricao_situacao_cadastral; // "ATIVA"Rotas disponíveis
| /cep/v1/{cep} | Endereço fictício, com cidade pelo prefixo do CEP e código IBGE |
| /cep/v2/{cep} | O mesmo, com fuso e coordenadas da cidade |
| /cnpj/v1/{cnpj} | Empresa fictícia com todos os campos da resposta real, inclusive sócios. Aceita CNPJ alfanumérico |
| /banks/v1 | Lista pública de instituições do Banco Central |
| /banks/v1/{codigo} | Uma instituição pelo código |
Valores para testar cada caso
Estes valores têm resposta fixa. Use-os para cobrir os caminhos de erro do seu código:
| Consulta | Resposta |
|---|---|
| /cep/v1/00000000 | 404, CEP não encontrado |
| /cep/v1/123 | 400, CEP com tamanho errado |
| /cnpj/v1/99999999000191 | 404, CNPJ não encontrado |
| /cnpj/v1/11111111111111 | 400, CNPJ inválido |
| /cnpj/v1/66666666000191 | 200, empresa SUSPENSA |
| /cnpj/v1/77777777000191 | 200, empresa INAPTA |
| /cnpj/v1/88888888000191 | 200, empresa BAIXADA |
| /banks/v1/9999 | 404, código bancário não encontrado |
Simular limite de uso, erro e lentidão
O que quebra em produção raramente é a resposta certa. É o 429 no meio do cadastro, o 503 na madrugada, a API que demora e estoura o timeout. Com chave do plano Dev ou Team, peça a falha:
# A API de CNPJ devolve 429
curl https://fakeforge.com.br/api/mock/brasilapi/cnpj/v1/88888888000191 \
-H "X-API-Key: $FAKEFORGE_API_KEY" \
-H "X-Mock-Status: 429"
# Resposta certa, depois de 5 segundos
curl https://fakeforge.com.br/api/mock/brasilapi/cep/v2/01310100 \
-H "X-API-Key: $FAKEFORGE_API_KEY" \
-H "X-Mock-Delay: 5000"Status aceitos: 429, 500, 502, 503, 504. Atraso de até 8.000 ms. Também valem os parâmetros mock_status e mock_delay na URL. A resposta simulada traz o cabeçalho X-Mock-Simulated: true.
O que cada plano libera
| Grátis | Dev (R$29/mês) | Team (R$79/mês) | |
|---|---|---|---|
| Chamadas por dia | 50 | 10.000 | 100.000 |
| CEP, CNPJ e bancos | Sim | Sim | Sim |
| Valores fixos para 400 e 404 | Sim | Sim | Sim |
| Erro e atraso sob demanda | Não | Sim | Sim |
O limite diário é o mesmo da API do FakeForge: chamadas ao mock e aos geradores contam juntas. Ver planos.
Perguntas frequentes
Para que serve um mock da BrasilAPI?+
Para rodar testes sem depender da API real. Testes que chamam a BrasilAPI ficam sujeitos a rede, limite de uso e dados que mudam. Com o mock, a mesma entrada devolve sempre a mesma resposta e o CI não para por causa de um serviço externo.
Os dados são reais?+
CEP e CNPJ não. Mesmo que você informe o CNPJ de uma empresa real, a resposta traz uma empresa fictícia, com sócio fictício e e-mail em domínio .example. A lista de bancos é pública e vem do Banco Central.
A mesma entrada sempre devolve a mesma resposta?+
Sim. O CNPJ e o CEP são a semente da resposta, então a asserção do seu teste continua valendo em toda rodada.
Como simular limite de uso, erro ou lentidão?+
Com chave de plano pago, envie o cabeçalho X-Mock-Status com 429, 500, 502, 503, 504 ou X-Mock-Delay com até 8.000 ms. Assim você testa retentativa, timeout e mensagem de erro sem esperar a falha acontecer de verdade.
O que é diferente da BrasilAPI?+
O mock cobre só CEP, CNPJ e bancos. Em bancos, traz código, ISPB e nomes, sem endereço nem logo. O campo service do CEP vem como fakeforge-mock. O resto dos campos de CEP e CNPJ segue a resposta real, conferida em novembro de 2026.
Posso usar em produção?+
Não. As respostas são fictícias e servem só para desenvolvimento e testes. Em produção, use a própria BrasilAPI.
O FakeForge é parte da BrasilAPI?+
Não. A BrasilAPI é um projeto independente de código aberto. O FakeForge só reproduz o formato de algumas rotas para testes e não tem vínculo com o projeto.