Pular para o conteúdo principal

Sandbox

O Sandbox é onde você testa sua integração com a Notare sem gerar nota fiscal real e sem depender dos webservices das prefeituras. É a forma recomendada de validar seu código antes de ir para produção.

Como ativar​

Use uma chave de teste (nnt_test_) no lugar da de produção (nnt_live_). Mesma URL, mesmo JSON — só a chave muda.

Authorization: Bearer nnt_test_xxxxxxxxxxxxxxxxxxxxxxxxxx

O que é validado de verdade​

O Sandbox roda as mesmas validações que a produção — não é um mock que sempre diz "ok". Se o seu request tem um problema, você recebe exatamente a mesma rejeição que produção daria:

  • Schema — campos obrigatórios, formatos, enums, CPF/CNPJ, CEP.
  • Regras do município — limites de tamanho, códigos aceitos, particularidades de cada prefeitura (ex.: "a descrição do serviço aceita no máximo 2000 caracteres neste município").
  • Pré-validação — valores, deduções, regras de negócio.

Ou seja: se passou no Sandbox, vai passar em produção (na parte de validação).

O que é simulado​

Quando o request é válido, o Sandbox devolve um retorno simulado:

  • status: "autorizada"
  • numero, chaveAcesso e numeroRps com prefixo SANDBOX-
  • meta.sandbox: true

Nada disso toca a prefeitura nem gera documento fiscal. A numeração de RPS de produção não é consumida.

Exemplo de resposta (Sandbox)​

{
  "id": "a1b2c3d4-...",
  "status": "autorizada",
  "numero": "SANDBOX-123456",
  "chaveAcesso": "SANDBOX5208707...",
  "meta": {
    "trilho": "municipal",
    "municipio": { "ibge": "5208707", "nome": "Goiânia/GO", "padrao": "Nacional-1.01" },
    "sandbox": true,
    "tempoProcessamento": "12ms"
  }
}

Exemplo de rejeição (idêntica à produção)​

{
  "status": "rejeitada_regras_municipais",
  "erros": [
    {
      "codigo": "CENTI-001",
      "campo": "servico[0].discriminacao",
      "mensagem": "Discriminação do serviço aceita no máximo 2000 caracteres."
    }
  ],
  "meta": { "sandbox": true }
}

Webhooks no Sandbox​

Se você configurar opcoes.webhookUrl no request, o Sandbox dispara o mesmo webhook que produção dispararia (assinado com HMAC, igual). Assim você testa o seu endpoint de webhook ponta a ponta — recebe o 202, e depois o webhook chega. Veja Webhooks.

Diferenças resumidas​

Sandbox (nnt_test_)Produção (nnt_live_)
Validações✅ reais (todas)✅ reais
Toca a prefeitura❌ não✅ sim
Gera documento fiscal❌ não✅ sim
Consome RPS de produção❌ não✅ sim
Webhook✅ simulado✅ real
meta.sandboxtrueausente

Quando estiver pronto​

Troque a chave nnt_test_ pela nnt_live_ e os mesmos requests passam a emitir notas reais. Não há mais nada a mudar no seu código.