Endpoint utilizado para criar uma nota fiscal e agendar sua emissão para a data informada em effectiveDate.

Essa é a principal chamada de criação de notas fiscais na API.

A nota pode ser criada em três contextos:

• vinculada a uma cobrança, utilizando payment
• vinculada a um parcelamento, utilizando installment
• emitida de forma avulsa para um cliente, utilizando customer

Guia de notas fiscais

Confira o guia de notas fiscais para mais informações

Essa chamada possui os atributos payment, installment e customer.

Apesar de eles não constarem individualmente como required, é obrigatório enviar pelo menos um deles para definir a origem da nota fiscal:

• payment - Nota vinculada a uma cobrança
• installment - Nota vinculada a um parcelamento
• customer - Nota fiscal avulsa vinculada apenas ao cliente

🚧

Importante

Pelo menos um dos atributos payment, installment ou customer deve ser enviado na requisição.

• O não envio desses campos impede a identificação da origem da nota fiscal.
• Cada cenário define o vínculo da nota dentro da plataforma.

Parâmetros principais da requisição

• payment - Identificador da cobrança vinculada à nota.
• installment - Identificador do parcelamento vinculado à nota.
• customer - Identificador do cliente, quando a nota for avulsa.
• serviceDescription - Descrição dos serviços da nota fiscal.
• observations - Observações adicionais da nota fiscal.
• externalReference - Identificador da nota fiscal no seu sistema.
• value - Valor total da nota fiscal.
• deductions - Valor das deduções aplicadas à nota. Esse campo não altera o valor total da nota, mas altera a base de cálculo do ISS.
• effectiveDate - Data em que a nota deve ser emitida.
• municipalServiceId - Identificador do serviço municipal retornado pela listagem de serviços.
• municipalServiceCode - Código do serviço municipal informado manualmente.
• municipalServiceName - Nome do serviço municipal. Se não for informado, o sistema pode utilizar municipalServiceCode como identificação.
• updatePayment - Indica se o valor da cobrança vinculada deve ser atualizado com os impostos da nota descontados.
• taxes - Objeto com os impostos da nota fiscal.

Regra importante sobre o serviço municipal

É obrigatório enviar um ou outro:

• municipalServiceId
• municipalServiceCode

🚧

Importante

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

• Quando existir listagem de serviços municipais, o recomendado é utilizar municipalServiceId.
• Quando não existir listagem disponível, o preenchimento deve ser realizado manualmente utilizando municipalServiceCode.

Quando a prefeitura disponibiliza lista de serviços, o recomendado é utilizar municipalServiceId.

Exemplo:

• a listagem retorna o serviço com id = 203561
• esse serviço representa o código 1.01 - Análise e desenvolvimento de sistemas

Nesse cenário, o preenchimento recomendado é:

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

Quando a prefeitura não disponibiliza lista de serviços, o preenchimento deve ser manual:

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

Portal Nacional

Quando a conta utiliza o Portal Nacional, a API não retorna a lista de serviços municipais.

🚧

Importante

Nesse cenário, o serviço deve ser informado manualmente através de municipalServiceCode.

• O campo municipalServiceId deixa de estar disponível para utilização.
• Recomenda-se validar previamente o código do serviço junto à prefeitura ou contabilidade.

Status possíveis da nota fiscal

• SCHEDULED - Nota fiscal agendada.
• SYNCHRONIZED - Nota fiscal enviada para a prefeitura.
• AUTHORIZED - Nota fiscal emitida com sucesso.
• PROCESSING_CANCELLATION - Cancelamento em processamento.
• CANCELED - Nota fiscal cancelada.
• CANCELLATION_DENIED - Cancelamento negado.
• ERROR - Erro na emissão.

Objeto taxes

O objeto taxes concentra os impostos aplicados à nota fiscal.

📘

Retenção e situações tributárias

Os atributos taxes.pisCofinsRetentionType e taxes.pisCofinsTaxStatus são obrigatórios apenas para clientes não optantes pelo Simples Nacional que emitem via Portal Nacional.

• Para mais detalhes sobre os tipos de retenção e situações tributárias aceitas, acesse a documentação de Configurações de retenção e situação tributária.

⚠️

Breaking Change: Novas regras de PIS/COFINS a partir de 30/06/2026 (NT-007)

A partir de 30/06/2026, as novas regras de PIS/COFINS serão aplicadas automaticamente nas emissões de NFS-e para clientes do Regime Normal (Simples Nacional não é impactado).
Para antecipar a mudança, utilize useTaxSystemReformNT007: true.

Veja o comunicado completo aqui.