DiscordStatus
Guias / Guides

FAQ de Notas Fiscais

Encontre respostas para dúvidas recorrentes sobre configuração, emissão e acompanhamento de Notas Fiscais de Serviço (NFS-e) pela API.

O que preciso configurar antes de emitir uma NFS-e?

Configure primeiro as informações fiscais da conta conforme as exigências do município.

Antes de salvar a configuração, consulte:

GET /v3/fiscalInfo/municipalOptions

A resposta informa dados exigidos pela prefeitura, como método de autenticação e regras específicas do município.

Configure as informações fiscais.

Como verifico se a conta já possui configuração fiscal?

Consulte:

GET /v3/fiscalInfo

A resposta retorna a configuração fiscal atual da conta.

Se ainda não houver uma configuração cadastrada, a API retorna HTTP 404.

Consulte o endpoint Recuperar informações fiscais.

A NFS-e precisa estar vinculada a uma cobrança?

Não.

Ao agendar uma nota fiscal, informe pelo menos uma das seguintes origens:

CampoUtilize quando
paymentA NFS-e estiver vinculada a uma cobrança
installmentA NFS-e estiver vinculada a um parcelamento
customerA NFS-e for avulsa

Consulte o endpoint Agendar nota fiscal.

Devo utilizar municipalServiceId ou municipalServiceCode?

Depende do município.

Quando a prefeitura disponibilizar a lista de serviços pela API, consulte:

GET /v3/fiscalInfo/services

Utilize o id retornado em municipalServiceId.

Se a prefeitura não disponibilizar a listagem, obtenha o código do serviço e informe-o em municipalServiceCode.

Consulte o endpoint Listar serviços municipais.

Como informo o serviço quando a conta utiliza o Portal Nacional?

O Portal Nacional não disponibiliza a lista de serviços municipais pelo endpoint GET /v3/fiscalInfo/services.

Nesse cenário:

  • obtenha o código correspondente ao serviço;
  • informe-o em municipalServiceCode;
  • não utilize municipalServiceId.

Consulte como emitir notas fiscais de serviço.

Uma nota agendada já pode ser considerada emitida?

Não.

O agendamento cria a nota e inicia o fluxo de processamento conforme effectiveDate. Considere a NFS-e emitida quando ela atingir o status AUTHORIZED.

Utilize Webhooks para acompanhar essa mudança.

O evento:

INVOICE_AUTHORIZED

confirma a autorização da nota.

Em caso de falha, trate:

INVOICE_ERROR

Consulte os eventos para notas fiscais.

Preciso consultar a API continuamente para saber se a nota foi emitida?

Não.

Use Webhooks como mecanismo principal para acompanhar emissão, cancelamento e falhas.

Utilize consultas GET para recuperação pontual, conciliação ou quando precisar confirmar o estado atual de uma nota.

Consulte os eventos para notas fiscais.

Posso alterar uma nota fiscal depois de agendá-la?

Sim, desde que ela ainda não tenha sido emitida.

O endpoint de atualização aceita notas nos status:

  • SCHEDULED;
  • ERROR.

Utilize:

PUT /v3/invoices/{id}

Depois da emissão definitiva, os dados da nota não podem mais ser alterados por esse endpoint.

Consulte o endpoint Atualizar nota fiscal.

Posso antecipar a emissão de uma nota agendada?

Sim.

Se a nota já existe e possui uma effectiveDate futura, utilize:

POST /v3/invoices/{id}/authorize

Esse endpoint não cria uma nova nota. Ele antecipa o processamento de uma nota já agendada.

Consulte o endpoint Emitir uma nota fiscal.

Como funciona o cancelamento de uma NFS-e?

Solicite o cancelamento por:

POST /v3/invoices/{id}/cancel

O resultado depende das regras da prefeitura e do estado atual da nota. Nem todos os municípios permitem cancelamento automático pela integração.

Após a solicitação, acompanhe principalmente:

  • INVOICE_PROCESSING_CANCELLATION;
  • INVOICE_CANCELED;
  • INVOICE_CANCELLATION_DENIED.

Prefira Webhooks para acompanhar o resultado.

Consulte o endpoint Cancelar uma nota fiscal.

Posso emitir notas fiscais automaticamente para assinaturas?

Sim.

A emissão automática é configurada por assinatura e permite definir quando as notas das cobranças recorrentes devem ser emitidas.

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

Quando preciso me preocupar com PIS/COFINS?

As regras dependem do regime tributário e do modelo de emissão utilizado pela conta.

Para cenários impactados pela NT-007, consulte o guia específico antes de definir pisCofinsTaxStatus, operationPis, operationCofins e retenções.

Configure retenção e situação tributária de PIS/COFINS.

O que muda com a Reforma Tributária?

A Reforma Tributária adiciona informações de IBS/CBS à integração de NFS-e em cenários sujeitos às novas regras fiscais.

Quando sua operação estiver abrangida, prepare a integração para enviar o objeto ibsCbs com as classificações aplicáveis.

Adequar sua integração à Reforma Tributária.

Onde encontro exemplos completos de requisição?

Utilize os Recipes para executar exemplos de configuração fiscal, identificação de serviços e emissão de NFS-e.

Consulte os Recipes.

Para contratos completos de campos, respostas e parâmetros, utilize a API Reference.

Próximos passos

Updated 1 day ago

Did this page help you?