Skip to main content
O sandbox replica o ciclo de vida completo das notas de forma determinística, sem certificado digital real e sem nenhuma chamada às autoridades fiscais (SEFAZ/prefeitura). Use-o para construir e validar sua integração com segurança — nada emitido aqui tem valor fiscal. Toda a camada acima do transporte fiscal roda idêntica à produção: máquina de estados, trilha de auditoria, webhooks e serialização JSON. Só a chamada SOAP à autoridade é falseada, então você testa seus handlers de polling e webhook exatamente como em produção.

​
Credenciais

Cada conta tem um par de credenciais de sandbox separado das de produção: sandbox_api_key / sandbox_api_secret (a chave começa com o prefixo sandbox_). Use-as no HTTP Basic exatamente como as de produção: 
curl https://invo.work/api/nfe/v1/notas \
  -u "$INVO_SANDBOX_API_KEY:$INVO_SANDBOX_API_SECRET" \
  -H "X-Empresa-CNPJ: 12345678000190"
A mesma URL base atende sandbox e produção — o que muda o ambiente é apenas qual par de credenciais você usa. A resolução de empresa via X-Empresa-CNPJ é idêntica.

​
Isolamento de dados

Notas criadas com a chave de sandbox são completamente isoladas das de produção: uma chave de sandbox só lista/consulta notas de sandbox, e a de produção, só as de produção. Não há risco de uma nota de teste aparecer entre as reais. A numeração também é isolada: notas de teste usam um contador de série próprio e nunca consomem números da sua série fiscal de produção.

​
Empresa apta

O sandbox dispensa o certificado digital (a Invo assina o XML de teste com um certificado interno). A empresa ainda precisa dos dados fiscais — Inscrição Estadual e regime tributário — pois o XML é montado e validado de verdade (mesmo XSD da produção), só não é transmitido.

​
Vereditos determinísticos

Você controla o desfecho com um marcador (case-insensitive) no documento. Sem marcador, a nota segue o caminho feliz.

​
NF-e — marcador em natureza_operacao

Marcador em natureza_operacaoResultado
(nenhum)autorizada
REJEITARrejeitada
DENEGARdenegada
DUPLICARduplicidade
PROCESSARlote em processamento (exercita o polling)
Exemplo: "natureza_operacao": "Venda REJEITAR" força uma rejeição.

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

Marcador na descrição do serviçoResultado
(nenhum)emitida
REJEITARRPS processado_com_erro
Cancelamento e inutilização no sandbox são sempre homologados com sucesso.

​
Mesmo comportamento assíncrono

A emissão continua assíncrona (resposta 201 com situacao: "pendente") e o resultado é acompanhado da mesma forma que em produção — só que o veredito chega em segundos, não no ciclo lento da SEFAZ/prefeitura. Veja Ciclo de vida.

Webhooks (NF-e)

Os eventos nfe_* disparam normalmente. O payload de uma nota de sandbox carrega "sandbox": true, para você distinguir eventos de teste dos de produção no mesmo endpoint. Veja Webhooks.

Polling

Consulte GET /notas/{id} até a situação atingir um estado terminal — o mesmo loop da produção.
Os e-mails do ciclo de vida (nota criada/autorizada/etc.) não são enviados para notas de sandbox — são avisos para pessoas, não parte da integração, e não devem chegar a destinatários reais.

​
Limites de uso

Para proteger a aplicação, o tráfego de sandbox é limitado por conta:
  • 60 requisições por minuto (rajada)
  • 2.000 requisições por dia (sustentado)
Exceder qualquer limite retorna 429 Too Many Requests. O tráfego de produção não é afetado por esses limites.

​
Retenção de dados

Notas de sandbox são descartáveis: são removidas automaticamente após 30 dias da criação (com seus eventos e anexos). Não conte com a persistência de longo prazo de dados de teste.