- Guias de NFS-e
- Emissão de NFS-e
Guias de NFS-e
Emissão de NFS-e
Emita a NFS-e no padrão nacional enviando só o serviço e o valor.
POST /nfse emite uma NFS-e de forma síncrona para a empresa dona da x-api-key. A Treeunfe monta a DPS com os dados da empresa, aplica a regra de tributação do serviço, assina com o certificado A1 e transmite à SefIN Nacional.
Antes da primeira emissão
Confira o certificado
A empresa precisa de um certificado A1 válido. Veja Consultar certificado atual.
Confira as configurações de NFS-e
Regime (CRT), inscrição municipal, série, numeração e ambiente (tpAmb) ficam nas configurações de NFS-e. A configuração inicial é feita no emissor; pela API você consulta e ajusta.
Escolha o código do serviço
Consulte os códigos de serviço com escopo=organizacao_cnae para ver só os compatíveis com os CNAEs da empresa.
Payload
{
"tomadorCnpj": "12345678000195",
"cTribNac": "010501",
"cNbs": "115011000",
"cTribMun": "001",
"descricao": "Licenciamento de software - mensalidade",
"vServ": 230
}
| Campo | Obrigatório | Descrição |
|---|---|---|
cTribNac | Sim | Código nacional do serviço (6 dígitos). |
vServ | Sim | Valor do serviço, como número. |
cNbs | Para regime normal | Código NBS (9 dígitos). Obrigatório quando o CRT da empresa é NORMAL. |
tomadorCnpj | Não | CNPJ ou CPF do tomador, só com números. |
cTribMun | Não | Código de tributação municipal. |
descricao | Não | Descrição do serviço. |
Os dados do prestador (CNPJ, inscrição municipal, regime) vêm do cadastro e das configurações da empresa. Não é preciso enviá-los.
Como a tributação é definida
A Treeunfe usa a regra de tributação configurada no emissor para o cTribNac (e o cNbs, quando houver). A regra define ISSQN, local da prestação, retenções, PIS/COFINS, INSS e IBS/CBS.
Resposta
Quando a nota é autorizada:
{
"success": true,
"nfseId": "123e4567-e89b-12d3-a456-426614174000",
"status": "AUTHORIZED"
}
Guarde o nfseId. Ele é o ID usado para baixar o PDF, enviar por e-mail e, como idDps, no cancelamento.
O resultado do processamento vem em outcome:
outcome | Significado | O que fazer |
|---|---|---|
SUCCESS | Nota emitida. | Nada. |
FAILED_PERMANENT | Nota recusada. | Corrija o payload ou a configuração antes de reenviar. |
TRANSIENT_ERROR | Falha temporária. | Tente de novo mais tarde. |
VALIDATION_ERROR | Payload inválido (400). | Veja a lista errors em Erros. |
Depois da emissão
| Para | Use |
|---|---|
| Baixar o PDF (DANFSE) | GET /nfse/{id}/danfse |
| Obter só o link do PDF | GET /nfse/{id}/danfe |
| Enviar XML e PDF ao tomador | POST /nfse/{id}/send-email |
| Ser avisado da autorização | Webhooks, evento NFSE_AUTHORIZED |
Status de resposta
| Status | Significado |
|---|---|
200 | Nota processada. Confira outcome. |
400 | Payload inválido ou erro na emissão. Veja errors. |
401 | x-api-key ausente ou inválida. |
429 | Limite de requisições excedido. |