RoboFiscalVendas e integrações
Tenho um sistema próprio. Como emitir NFS-e por API?
A API do RoboFiscal recebe requisições autenticadas para cadastrar tomadores, emitir NFS-e e acompanhar documentos. Use a base https://robofiscal.com.br/app/api/v1 e a chave da empresa no cabeçalho Authorization: Bearer. Antes de emitir, configure ambiente, dados fiscais e certificado A1 autorizado. Envie uma referenciaExterna estável para cada operação e consulte o status após a solicitação.
Fatos e fontes
- A API nacional de NFS-e possui operações de emissão, consulta e eventos.Fonte: Portal NFS-e: manual da API, v1.2.
- A RFC 6750 descreve o envio de Bearer token no cabeçalho Authorization e exige proteção da credencial.Fonte: IETF: RFC 6750, proteção de Bearer tokens.
- Pela semântica HTTP, um POST não é idempotente por definição; esse comportamento depende do contrato da aplicação.Fonte: IETF: RFC 9110, semântica HTTP.
- O Portal Nacional distingue endpoints de produção e produção restrita.Fonte: Portal NFS-e: APIs de produção e produção restrita.
- O contrato do RoboFiscal publica rotas de clientes, notas, lotes, documentos e webhooks.Fonte: RoboFiscal: contrato OpenAPI público.
Nesta página
Qual é o fluxo mínimo de integração?
Associe sua empresa à chave de API e confirme o ambiente configurado. Cadastre ou localize o tomador e guarde o identificador retornado. Prepare clienteId, discriminacao e valorServico, com os demais dados exigidos pela operação. A configuração fiscal da empresa também participa da emissão; um corpo JSON mínimo não dispensa essa revisão.
Como associar a nota ao meu pedido?
Envie referenciaExterna com uma identificação estável do serviço ou pedido. Guarde a relação entre essa referência, o identificador da nota e sua chave. Se a conexão falhar, consulte a operação antes de reenviar. Para volumes maiores, use lotes e acompanhe cada item.
Quais resultados meu sistema deve distinguir?
Diferencie autorização, rejeição e processamento pendente. Trate autenticação inválida, dados incompletos e limites de uso conforme a resposta. A obtenção do PDF é uma etapa adicional: uma falha nesse arquivo não é motivo para emitir outra nota. Use webhooks e consultas para manter o estado local atualizado.
| Etapa | Rota relativa à base da API |
|---|---|
| Cadastrar tomador | POST /clientes |
| Solicitar emissão | POST /notas |
| Consultar nota | GET /notas/{id} |
| Obter XML | GET /notas/{id}/xml |
| Obter PDF | GET /notas/{id}/pdf |
{
"clienteId": 123,
"discriminacao": "Serviço de manutenção — exemplo de teste",
"valorServico": 100.00,
"referenciaExterna": "teste-manutencao-001"
}Passo a passo
- Cadastre a empresa, configure o ambiente e conclua o A1 autorizado.
- Gere a chave por CNPJ e armazene-a no servidor.
- Cadastre o cliente e revise o corpo da emissão.
- Envie a operação com referenciaExterna única e estável.
- Concilie status, XML, PDF e eventos antes de concluir o pedido.
Erros comuns
- Expor a chave no JavaScript do navegador.
- Criar uma referência nova a cada tentativa da mesma operação.
Como o RoboFiscal ajuda
O RoboFiscal oferece contrato OpenAPI público e documentação interativa. Para experimentar o fluxo, configure um ambiente de testes antes de executar chamadas de emissão.
Leia o contrato e os requisitos do ambiente antes de criar a conta para configurar uma integração.
Perguntas relacionadas
Tenho que montar e assinar o XML nacional no meu sistema?
A integração com o RoboFiscal envia os dados pelo contrato JSON; o serviço executa o fluxo fiscal a partir da configuração da empresa.
Posso usar uma chave para todos os meus CNPJs?
A chave identifica uma empresa. Mantenha o vínculo correto entre CNPJ e credencial.
Continue lendo
Revisado em · Equipe RoboFiscal. Versão em texto