> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invo.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Ambiente de testes determinístico para NF-e e NFS-e — sem certificado real e sem tocar a SEFAZ/prefeitura.

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](/autenticacao) exatamente como as de produção:

```bash theme={null}
curl https://invo.work/api/nfe/v1/notas \
  -u "$INVO_SANDBOX_API_KEY:$INVO_SANDBOX_API_SECRET" \
  -H "X-Empresa-CNPJ: 12345678000190"
```

<Note>
  **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.
</Note>

### 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_operacao` | Resultado                                  |
| ------------------------------- | ------------------------------------------ |
| *(nenhum)*                      | `autorizada`                               |
| `REJEITAR`                      | `rejeitada`                                |
| `DENEGAR`                       | `denegada`                                 |
| `DUPLICAR`                      | `duplicidade`                              |
| `PROCESSAR`                     | lote 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ço | Resultado                 |
| -------------------------------- | ------------------------- |
| *(nenhum)*                       | `emitida`                 |
| `REJEITAR`                       | RPS `processado_com_erro` |

<Note>
  Cancelamento e inutilização no sandbox são sempre homologados com sucesso.
</Note>

## 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](/ciclo-de-vida).

<CardGroup cols={2}>
  <Card title="Webhooks (NF-e)" icon="webhook">
    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](/webhooks).
  </Card>

  <Card title="Polling" icon="rotate">
    Consulte `GET /notas/{id}` até a situação atingir um estado terminal — o mesmo loop da produção.
  </Card>
</CardGroup>

<Note>
  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.
</Note>

## 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

<Warning>
  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.
</Warning>