Vendas e integrações
Preciso emitir muitas notas de serviço. Como envio um lote sem perder os erros?
Use POST /notas/lote para enfileirar até 500 notas no RoboFiscal e guarde o loteId retornado. A resposta HTTP 202 significa que o lote foi aceito para processamento. Consulte GET /notas/lote/{id} e acompanhe cada item até seu resultado. Cada operação precisa de referenciaExterna própria; uma falha parcial exige análise dos itens, sem criar novas referências para notas já enviadas.
Fatos e fontes
- A RFC 9110 define HTTP 202 como aceitação para processamento ainda não concluído.Fonte: IETF: RFC 9110, semântica HTTP.
- O envio de DPS à API nacional está sujeito a validações e pode resultar em erros.Fonte: Portal NFS-e: manual da API, v1.2.
- Bearer tokens precisam ser protegidos contra uso por terceiros.Fonte: IETF: RFC 6750, proteção de Bearer tokens.
- O Portal NFS-e mantém ambientes distintos para testes e produção.Fonte: Portal NFS-e: APIs de produção e produção restrita.
- A API do RoboFiscal limita cada lote a 500 itens e oferece consulta de status por lote.Fonte: RoboFiscal: contrato OpenAPI público.
Nesta página
Como preparar os itens?
Monte um item por prestação com cliente, descrição, valor e referência externa. Confira os dados fiscais e a competência antes do envio. Divida volumes acima do teto em lotes identificáveis. O tamanho técnico permitido não substitui a verificação do saldo de notas no plano da empresa.
Como acompanhar sem perder rejeições?
Guarde o identificador do lote e consulte seus contadores e itens. Atualize o status local de cada operação individualmente. Se um lote tiver 100 itens e 3 apresentarem erro, o seu relatório precisa mostrar quais são esses 3 e o motivo, além das notas concluídas. Um total agregado de “enviado” é insuficiente.
Como retomar depois de uma falha?
Concilie referências e resultados antes de qualquer reenvio. Um item já registrado pode aparecer como existente. Se houve rejeição de dados, corrija o problema e verifique qual procedimento de reprocessamento cabe ao estado atual. Preserve o histórico das tentativas e impeça dois processos locais de dispararem a mesma operação ao mesmo tempo.
Passo a passo
- Confira empresa, ambiente, certificado e cota disponível.
- Prepare até 500 itens com referências estáveis e distintas.
- Envie o lote e registre loteId e resposta.
- Consulte o lote e registre resultados por item.
- Trate pendências e rejeições separadamente das autorizações.
Erros comuns
- Marcar todas as notas como autorizadas ao receber HTTP 202.
- Reenviar tudo com identificadores novos depois de uma falha parcial.
Como o RoboFiscal ajuda
O RoboFiscal processa o lote em fila e publica a situação de cada item. Seu sistema deve manter a conciliação entre o pedido original, a referência e o documento resultante.
Confira os endpoints, limites e pré-requisitos de lotes antes de configurar a integração na sua conta.
Perguntas relacionadas
Lote aceito garante que todas as notas serão autorizadas?
Não. Cada emissão ainda depende de processamento, configuração e validação fiscal.
Posso usar o mesmo cliente em vários itens?
Sim, quando representam prestações distintas. Use uma referência própria para identificar cada operação.
Continue lendo
Revisado em · Equipe RoboFiscal. Versão em texto