Sandbox (Homologação)

A engineAPI 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.

Todo emissor nasce em homologação

Ao cadastrar uma empresa (POST /v1/companies), o ambienteFiscal do emissor nasce com o valor 2 (homologação) por padrão. O payload de cadastro não tem um campo environment (nem ambienteFiscal) que você possa enviar:

curl -X POST https://api.engineapi.com.br/v1/companies \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "11222333000181",
    "name": "Empresa Teste Ltda"
  }'

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:

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. O upload segue o mesmo contrato de produção: POST /v1/companies/{id}/certificate, campo multipart file, ver Certificados Digitais.

Promovendo um emissor para produção

Trocar ambienteFiscal é self-service, via um endpoint dedicado, separado do PATCH /v1/companies/{id} genérico (que ignora o campo, ver aviso acima). Não existe aprovação do suporte no caminho: quem chama a rota com o valor certo promove o emissor.

curl -X PATCH https://api.engineapi.com.br/v1/companies/ISSUER_ID/ambiente \
  -H "x-api-key: ek_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ambienteFiscal": 1
  }'

Resposta de sucesso (200):

{
  "data": {
    "id": "5f2c1e40-6b3a-4e1a-9b2c-8f0a1d2e3f4a",
    "cnpj": "11222333000181",
    "ambienteFiscal": 1
  },
  "meta": { "requestId": "req_a1b2c3d4e5", "timestamp": "2026-07-16T12:00:00.000Z" }
}

Corpo inválido (400, ex. { "ambienteFiscal": 3 }):

{
  "error": {
    "type": "https://engineapi.com.br/errors/VALIDATION_ERROR",
    "title": "Bad Request",
    "status": 400,
    "detail": "Os dados enviados são inválidos",
    "errors": [
      {
        "field": "ambienteFiscal",
        "message": "ambienteFiscal deve ser exatamente 1 (Produção) ou 2 (Homologação)"
      }
    ],
    "instance": "/v1/companies/5f2c1e40-6b3a-4e1a-9b2c-8f0a1d2e3f4a/ambiente",
    "requestId": "req_a1b2c3d4e5",
    "timestamp": "2026-07-16T12:00:00.000Z"
  }
}

Testando Rejeições

Para testar o tratamento de erros no seu código, você pode provocar rejeições específicas (todas voltam como 400 com error.erros[], nunca 422, ver Erros e Rejeições):

Comparação: Sandbox vs Produção

O DANFE em homologação

GET /v1/nfe/pdf/{accessKey} e GET /v1/nfce/pdf/{accessKey} funcionam normalmente em homologação: o documento é gerado a partir do XML autorizado pela SEFAZ de homologação, e a própria SEFAZ manda imprimir a tarja NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL. Ambiente, CST/CSOSN e informações complementares saem do XML: o PDF é o documento, não uma remontagem.

A resposta só é 409 (DANFE_INDISPONIVEL) quando não existe XML autorizado para aquele documento neste ambiente:

Checklist: Estou pronto para produção?

Próximos passos