Sandbox
Teste sua integração com a SEFAZ de homologação sem emitir documentos fiscais reais.
Sandbox (Homologação)
A Engine API se conecta diretamente ao ambiente de homologação da SEFAZ (o mesmo servidor da Fazenda, mas sem validade fiscal). Você testa com a infraestrutura real sem nenhum risco.
O endpoint da API é o mesmo para homologação e produção. A diferença está no campo environment da empresa emissora. Não no seu código.
Ativando o Sandbox
Ao cadastrar ou atualizar uma empresa, defina environment: 2:
curl -X POST https://api.engineapi.com.br/companies \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"cnpj": "11222333000144",
"name": "Empresa Teste Ltda",
"taxRegime": 3,
"environment": 2
}'
| Valor | Ambiente | Comportamento |
|-------|----------|---------------|
| 1 | Produção | Documentos com validade fiscal real |
| 2 | Homologação | Testes com SEFAZ de teste (sem validade fiscal) |
Notas emitidas em homologação não têm validade fiscal e não precisam ser canceladas. Emita à vontade para testar.
CNPJ para Testes
Você pode usar seu próprio CNPJ em homologação. O SEFAZ de teste aceita qualquer CNPJ válido (com dígitos verificadores corretos).
CNPJs de teste comuns:
| CNPJ | Uso |
|------|-----|
| 11222333000144 | Emissor de testes |
| 99888777000155 | Destinatário de testes |
| 12345678000195 | Empresa genérica de testes |
Esses CNPJs são fictícios com dígitos verificadores válidos. Podem ser usados livremente em homologação.
Certificado para Homologação
Em homologação, você pode usar:
- Seu certificado real (funciona normalmente)
- Certificado de testes (emitido por qualquer AC, mesmo que expirado)
O SEFAZ de homologação aceita certificados com qualquer validade.
Testando Rejeições
Para testar o tratamento de erros no seu código, você pode provocar rejeições específicas:
| Rejeição | Como provocar |
|----------|--------------|
| 539: Duplicidade | Emita a mesma nota duas vezes (mesmo número/série) |
| 225 — NCM inválido | Use NCM com menos de 8 dígitos, ex: "1234" |
| 210: IE inválida | Use uma IE que não bate com a UF do destinatário |
| 204 — CNPJ inválido | Use um CNPJ com dígito verificador errado |
Comparação: Sandbox vs Produção
| | Sandbox (env: 2) | Produção (env: 1) |
|--|-------------------|---------------------|
| Validade fiscal | Não Sem validade | Sim Válida |
| Custo por emissão | Gratuito | Conforme plano |
| SEFAZ utilizado | SEFAZ de homologação | SEFAZ estadual real |
| Cancelamento necessário | Não Não | Sim Sim (até 24h) |
| Webhooks disparados | Sim Sim | Sim Sim |
| XML retornado | Sim Sim (teste) | Sim Sim (válido) |
Checklist: Estou pronto para produção?
Emissão testada
Sua integração emite NFe com sucesso em homologação e recebe status: AUTHORIZED?
Erros tratados
Seu código trata 422 (rejeição SEFAZ) e exibe mensagem amigável ao usuário?
Webhooks configurados
Você tem um endpoint recebendo invoice.authorized e invoice.rejected?
Idempotência implementada
Seu webhook usa o id do evento para evitar processar o mesmo evento duas vezes?
Certificado de produção
Você tem um certificado e-CNPJ A1 válido e fez o upload?
Ambiente atualizado
Você mudou environment para 1 na empresa emissora?
Migrando para Produção
curl -X PATCH https://api.engineapi.com.br/companies/ISSUER_ID \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "environment": 1 }'
Nenhuma alteração no seu código de integração. Apenas o environment muda no cadastro da empresa. O endpoint da API é o mesmo.