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

Revisado em 10 de outubro de 2026 · Equipe RoboFiscal.

## Fatos e fontes

- A API nacional de NFS-e possui operações de emissão, consulta e eventos. [Portal NFS-e: manual da API, v1.2](https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/manual-contribuintes-emissor-publico-api-sistema-nacional-nfs-e-v1-2-out2025.pdf).
- A RFC 6750 descreve o envio de Bearer token no cabeçalho Authorization e exige proteção da credencial. [IETF: RFC 6750, proteção de Bearer tokens](https://www.rfc-editor.org/rfc/rfc6750.html).
- Pela semântica HTTP, um POST não é idempotente por definição; esse comportamento depende do contrato da aplicação. [IETF: RFC 9110, semântica HTTP](https://www.rfc-editor.org/rfc/rfc9110.html).
- O Portal Nacional distingue endpoints de produção e produção restrita. [Portal NFS-e: APIs de produção e produção restrita](https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/apis-prod-restrita-e-producao).
- O contrato do RoboFiscal publica rotas de clientes, notas, lotes, documentos e webhooks. [RoboFiscal: contrato OpenAPI público](https://robofiscal.com.br/app/api/v1/openapi.yaml).

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

Exemplo de corpo, com dados ilustrativos. Execute apenas após configurar o ambiente de testes e um cliente válido.

```
{
  "clienteId": 123,
  "discriminacao": "Serviço de manutenção — exemplo de teste",
  "valorServico": 100.00,
  "referenciaExterna": "teste-manutencao-001"
}
```

## Passo a passo

1. Cadastre a empresa, configure o ambiente e conclua o A1 autorizado.
2. Gere a chave por CNPJ e armazene-a no servidor.
3. Cadastre o cliente e revise o corpo da emissão.
4. Envie a operação com referenciaExterna única e estável.
5. 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. [Criar conta grátis](https://robofiscal.com.br/app/registrar).

[Abrir a documentação da API](https://robofiscal.com.br/app/api/docs).

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

- [Como emitir NFS-e em lote e acompanhar o resultado de cada nota?](https://robofiscal.com.br/docs/emissao-nfse-lote/)
- [Como testar uma integração de NFS-e antes de emitir notas reais?](https://robofiscal.com.br/docs/testar-api-nfse/)
- [Como receber e validar webhooks de NFS-e?](https://robofiscal.com.br/docs/webhooks-nfse/)

Página: https://robofiscal.com.br/api-nfs-e.html