Emitindo notas fiscais de serviço

Depois de configurar as informações fiscais da conta, identifique o serviço prestado e agende a Nota Fiscal de Serviço (NFS-e).

A nota pode ser vinculada a uma cobrança, a um parcelamento ou emitida de forma avulsa para um cliente.

Antes de começar

Confirme que as informações fiscais da conta já foram configuradas conforme as exigências do município.

Configure as informações fiscais.

Como funciona

O preenchimento do serviço depende da disponibilidade da lista municipal.

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Listar serviços municipais"] --> B{"A prefeitura retorna serviços?"}

    B --> Sim(("Sim"))
    B --> Nao(("Não"))

    Sim --> C["Usar municipalServiceId"]
    Nao --> D["Usar municipalServiceCode"]

    C --> E["Agendar a NFS-e"]
    D --> E

    E --> F["Receber Webhook"]
    F --> G["Atualizar o resultado"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B decisao
    class C,D,E,F validacao
    class G sucesso

    class Sim respostaSim
    class Nao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

1. Identifique o serviço municipal

Consulte os serviços disponíveis para o município:

GET /v3/fiscalInfo/services

Consulte o endpoint Listar serviços municipais.

A consulta aceita:

• offset, para definir o início da listagem;
• limit, com máximo de 100 registros por requisição;
• description, para localizar um serviço pelo nome ou descrição.

Quando encontrar o serviço, utilize o id retornado como municipalServiceId.

Quando houver lista de serviços

Se a listagem retornar, por exemplo, o serviço de código 1.01 com ID 203561, envie:

{
  "...": "...",
  "municipalServiceId": "203561",
  "municipalServiceCode": null,
  "municipalServiceName": "1.01 - Análise e desenvolvimento de sistemas"
}

Não repita o código em municipalServiceCode quando utilizar municipalServiceId.

Quando não houver lista de serviços

Obtenha o código do serviço junto à prefeitura ou à contabilidade e envie-o manualmente:

{
  "...": "...",
  "municipalServiceId": null,
  "municipalServiceCode": "1.01",
  "municipalServiceName": "Análise e desenvolvimento de sistemas"
}

No agendamento, informe municipalServiceId ou municipalServiceCode, conforme a disponibilidade da prefeitura.

2. Agende a nota fiscal

Envie:

POST /v3/invoices

Consulte o endpoint Agendar nota fiscal.

Exemplo:

{
  "payment": "pay_637959110194",
  "serviceDescription": "Nota fiscal da Fatura 101940. \nDescrição dos Serviços: ANÁLISE E DESENVOLVIMENTO DE SISTEMAS",
  "observations": "Mensal referente aos trabalhos de Junho.",
  "value": 300,
  "deductions": 0,
  "effectiveDate": "2023-07-03",
  "municipalServiceId": "21234",
  "municipalServiceName": "Análise e desenvolvimento de sistemas",
  "taxes": {
    "retainIss": false,
    "iss": 3,
    "cofins": 3,
    "csll": 1,
    "inss": 0,
    "ir": 1.5,
    "pis": 0.65
  }
}

Preencha o objeto taxes conforme o regime e a situação tributária da conta.

Para contas de Regime Normal que emitem pelo Portal Nacional, consulte também Configurações de retenção e situação tributária de PIS/COFINS.

Defina a origem da nota

Informe pelo menos um dos campos:

A data prevista para emissão é definida por effectiveDate.

Resultado esperado

Após o agendamento, a API cria a nota e inicia o fluxo de emissão conforme effectiveDate.

Não considere o agendamento como confirmação de emissão. Aguarde a atualização do processamento.

3. Acompanhe a emissão por Webhooks

Use Webhooks para acompanhar mudanças de estado da nota, em vez de consultar repetidamente o recurso pela API.

Para o fluxo de emissão, trate principalmente:

• INVOICE_CREATED;
• INVOICE_SYNCHRONIZED;
• INVOICE_AUTHORIZED;
• INVOICE_ERROR.

INVOICE_AUTHORIZED confirma a emissão da NFS-e. Em caso de falha, INVOICE_ERROR permite tratar a causa antes de uma nova tentativa.

Antecipe uma nota fiscal agendada

Se a nota possui effectiveDate futura e precisa ser emitida antes dessa data, utilize:

POST /v3/invoices/{id}/authorize

Consulte o endpoint Emitir uma nota fiscal.

Essa chamada não cria uma nova nota. Ela apenas antecipa o processamento de uma nota já agendada.

Emissão pelo Portal Nacional

Contas que utilizam o Portal Nacional não recebem a lista de serviços municipais pela API.

Ao consultar os serviços, o fluxo atual pode retornar:

{
  "errors": [
    {
      "code": "error",
      "description": "O código de serviços municipais não está habilitado para esta conta."
    }
  ]
}

Nesse cenário:

1. obtenha o código do serviço no Portal Nacional ou com a contabilidade;
2. informe esse valor em municipalServiceCode;
3. não utilize municipalServiceId.

Exemplo:

{
  "...": "...",
  "municipalServiceId": null,
  "municipalServiceCode": "1.01",
  "municipalServiceName": "Análise e desenvolvimento de sistemas"
}

Notas fiscais em assinaturas

Para emitir NFS-e automaticamente para as cobranças geradas por uma assinatura, configure a regra de emissão na própria assinatura.

Configure a emissão automática de notas fiscais para assinaturas.

Exemplos práticos

• Liste os serviços municipais antes de emitir uma Nota Fiscal
• Agende uma Nota Fiscal vinculada a uma cobrança
• Execute o fluxo completo para emissão de Nota Fiscal via API

Próximos passos

• Acompanhe os eventos de notas fiscais
• Configure a emissão automática para assinaturas
• Configure retenção e situação tributária de PIS/COFINS
• Adequar sua integração à Reforma Tributária