Emitindo notas fiscais de serviço

Para emitir uma nota fiscal você deve chamar o endpoint de "Agendar nota fiscal". Mas, antes, vamos verificar o ID dos serviços municipais.

Listar serviços municipais

GET /v3/invoices/municipalServices
Confira a referência completa deste endpoint.

A lista de serviços municipais pode ser utilizada para consultar informações do serviço que deve ser enviado na geração da nota fiscal.

O campo description além de conter o código e descrição do serviço pode conter também o código CNAE, sendo apresentado no seguinte formato: CNAE | Codigo - Descrição.

A cada requisição são retornados no máximo 500 serviços, caso o serviço desejado não seja retornado, utilize o filtro description na requisição.

📘

• Dependendo da sua prefeitura o código CNAE pode não ser retornado.
• Caso sua prefeitura não disponibilize a lista de serviços nenhum resultado será retornado.

Caso você tenha o ID do serviço municial, basta enviá-lo na requisição.

Agendar uma nota fiscal

POST /v3/invoices
Confira a referência completa deste endpoint.

{
  "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
  }
}

📘

Os status possíveis de uma nota fiscal são os seguintes:

SCHEDULED - Agendada

SYNCHRONIZED - Enviada para prefeitura

AUTHORIZED - Emitida

PROCESSING_CANCELLATION - Processando cancelamento

CANCELED - Cancelada

CANCELLATION_DENIED - Cancelamento negado

ERROR - Erro na emissão

A Nota Fiscal pode estar atrelada a uma cobrança, parcelamento ou pode ser gerada de forma avulsa.

Se a Nota Fiscal for originada de uma cobrança existente, é necessário informar o atributo payment. O mesmo ocorre para parcelamentos, onde neste caso, é necessário informar o atributo installment. Para gerar uma Nota Fiscal avulsa, é necessário informar o atributo customer.

Na chamada de agendar notas, dentre vários atributos, existem três fundamentais para a nota ser emitida com sucesso, são eles: municipalServiceId, municipalServiceCode, municipalServiceName.

E é bastante importante que sejam informados corretamente. O municipalServiceId e o municipalServiceCode, tem por objetivo informarem o código de serviço que está sendo emitida a nota. Como, por exemplo, o serviço 1.01 - Análise e desenvolvimento de sistemas.

Em nossa API trabalhamos com Ids para identificar e os serviços funcionam da mesma forma. Ao listar os serviços do município, voltará uma lista com vários serviços e como o exemplo abaixo:

{  
      "id": "203561",  
      "description": "1.01 - Análise e desenvolvimento de sistemas",  
      "issTax": 2  
}

Pode-se observar que o código 1.01 é representado pelo ID 203561. Nesses casos, o municipalServiceId é esse. E como já se tem o id do código, não há necessidade de dobrar a informação, sob risco de a nota sair errada, colocando novamente o código no municipalServiceCode. Então, o cliente deverá enviar apenas:

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

Porém, nem todas as cidades retornam essas listagens. São poucas, mas há prefeituras que não tem lista de serviços na API e com isso, o cliente precisará verificar qual é o código do seu serviço e inserir manualmente, ficando assim:

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

Podemos concluir que, sempre que houver lista de serviços, enviar municipalServiceId. Caso não tenha, enviar o municipalServiceCode. Nesses casos, sempre se envia um ou outro.

Notas fiscais em assinaturas

Para assinaturas, você pode configurar a emissão de notas fiscais automáticas na seção de assinaturas.

Emitir uma nota fiscal agendada

Caso ocorra sucesso nesta requisição, a Nota Fiscal será agendada para emissão na data informada no atributo effectiveDate. Se a data informada for o dia atual, em até 15 minutos após a requisição a Nota Fiscal será emitida e você receberá a atualização através do webhook (se ativado).

👍

O Webhook para notas fiscais enviará eventos quando os status de notas fiscais mudarem ou elas forem criadas

Confira o Webhook para notas fiscais

Se você tem uma nota fiscal agendada para o futuro e deseja adiantar a emissão da mesma, pode chamar o endpoint "Emitir uma nota fiscal".

POST /v3/invoices/{id}/authorize
Confira a referência completa deste endpoint.

Emitir uma nota fiscal usando o Portal Nacional

Se você utiliza o Portal Nacional para emissão de suas notas fiscais, ao acessar o recurso de listar serviços municipais, a API lhe devolverá a seguinte exceção:

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

Nesse caso, o serviço da nota precisará ser informado manualmente no agendamento da mesma, conforme os código dos serviços disponibilizados no Portal Nacional. Caso tenha dúvidas, acesse o Portal Nacional ou verifique junto ao seu contador quais são os códigos de serviço utilizados em seu negócio.

Com o código de serviço em mãos, basta utilizar a API de agendar nota fiscal enviando o código no campo municipalServiceCode.

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