Skip to main content
O sandbox reproduz o ciclo de vida das notas com resultado previsível. Ele não precisa de certificado digital real e não chama a SEFAZ nem a prefeitura. Use o sandbox para construir e testar a sua integração. As notas emitidas nele não têm valor fiscal. Tudo acima do transporte fiscal funciona como em produção: a máquina de estados, a trilha de auditoria, os webhooks e o JSON das respostas. A Invo simula só a chamada SOAP à SEFAZ ou à prefeitura. Assim, o seu código de polling e de webhook se comporta como em produção.

​
Credenciais

Cada conta tem um par de credenciais de sandbox, separado do par de produção: sandbox_api_key e sandbox_api_secret. A chave começa com sandbox_. Use o par no HTTP Basic da mesma forma que o de produção:
Sandbox e produção usam a mesma URL base. O par de credenciais define o ambiente. O cabeçalho X-Empresa-CNPJ funciona da mesma forma nos dois.

​
Isolamento de dados

As notas criadas com a chave de sandbox ficam separadas das notas de produção. A chave de sandbox lista e consulta só notas de sandbox, e a chave de produção, só notas de produção. A numeração também é separada. As notas de teste usam um contador de série próprio e não consomem números da sua série fiscal de produção. O codigo_externo também é separado por ambiente. Você pode usar em sandbox um código que já existe em produção, e o contrário também vale.

​
Empresa apta

O sandbox dispensa o certificado digital: a Invo assina o XML de teste com um certificado interno. A empresa ainda precisa de inscrição estadual e de regime tributário, porque a Invo monta o XML e o valida contra o mesmo XSD da produção. O XML só não é transmitido.

​
Como escolher o resultado

Um marcador no documento define o resultado. A Invo ignora maiúsculas e minúsculas no marcador. Sem marcador, a nota segue o caminho de sucesso.

​
NF-e: marcador em natureza_operacao

Exemplo: "natureza_operacao": "Venda REJEITAR" força uma rejeição.

​
NFS-e: marcador na descrição do serviço

No sandbox, o cancelamento e a inutilização sempre terminam com sucesso.

​
Mesmo comportamento assíncrono

A emissão continua assíncrona, com resposta 201 e situacao: "pendente". Você acompanha o resultado da mesma forma que em produção. O resultado chega em segundos, porque não há espera pela SEFAZ ou pela prefeitura. Veja Ciclo de vida.

Webhooks (NF-e)

Os eventos nfe_* disparam normalmente e vão só para o endpoint de sandbox da conta. Configure esse endpoint na página de sandbox dos webhooks. O payload traz "sandbox": true. Veja Webhooks.

Polling

Consulte GET /notas/{id} até a nota chegar a um estado final, como em produção.
A Invo não envia os e-mails do ciclo de vida (nota criada, autorizada etc.) para notas de sandbox. Esses e-mails são avisos para pessoas e não devem chegar a destinatários reais.

​
Limites de uso

Para proteger a aplicação, a Invo limita o tráfego de sandbox por conta:
  • 60 requisições por minuto, para rajadas.
  • 2.000 requisições por dia, para uso contínuo.
Acima de qualquer limite, a API retorna 429 Too Many Requests. Esses limites não valem para o tráfego de produção.

​
Retenção de dados

Uma limpeza diária apaga as notas de sandbox com mais de 30 dias, junto com os eventos e os anexos. Guarde fora do sandbox qualquer dado de teste que você precise manter.