Guides

Operações disponíveis na API

A NFS-e (Nota Fiscal de Serviços Eletrônica) registra a prestação de serviços e tem o ISSQN como imposto principal. Diferente dos demais documentos fiscais, ela não tem um padrão único nacional em vigor para todos os municípios: cada prefeitura define seu próprio webservice, regras e campos. Por isso a API da Focus expõe a NFS-e em dois conjuntos de operações independentes, com endpoints distintos.

📘

Qual endpoint usar

Esta é a decisão que precede qualquer integração de NFS-e.

  • NFS-e (municipal) — /v2/nfse — integra os webservices das prefeituras pelo padrão de cada município.
  • NFS-e Nacional — /v2/nfsen — integra o ambiente/padrão nacional (DPS) adotado na transição da Reforma Tributária.

O município define qual padrão você usa. Consulte a lista de municípios integrados para saber qual se aplica ao seu caso. Enviar a nota pelo endpoint errado é causa comum de rejeição.

Modelo de processamento

Em ambos os conjuntos, a emissão tem duas etapas:

  • Pré-validação síncrona: ao enviar, a API valida na hora campos essenciais, formato dos dados e o cadastro do prestador. Se algo falhar aqui, você recebe o erro imediatamente na mesma resposta.
  • Processamento assíncrono: aceita a nota, ela entra em uma fila e é autorizada (ou rejeitada) pela prefeitura/ambiente nacional em segundo plano. Para saber o desfecho, use a Consulta ou configure webhooks.

Isso diferencia a NFS-e da NFC-e (totalmente síncrona): na NFS-e, aceita para processamento ≠ autorizada.

Operações — NFS-e municipal (/v2/nfse)

  • Emitir: POST /v2/nfse?ref=... — envia a nota para processamento. Retorna 201 (aceita, em processamento). Campos principais: data_emissao, natureza_operacao, optante_simples_nacional, e os objetos prestador, tomador, servico.
  • Consultar: GET /v2/nfse/{referencia} — verifica o status atual (processando, autorizada, cancelada ou erro de autorização).
  • Cancelar: DELETE /v2/nfse/{referencia} — cancela uma nota autorizada. Retorno síncrono. Exige justificativa de 15 a 255 caracteres. O cancelamento é definitivo.
  • Reenviar email: POST /v2/nfse/{referencia}/email — envia cópia da nota para uma lista de até 10 emails, mesmo que diferentes dos informados na emissão.
  • Solicitar reenvio de notificação: POST /v2/nfse/{referencia}/hook — reaciona todos os webhooks cadastrados para aquela nota (útil para recuperar notificações perdidas ou em testes).
📘

Cancelamento depende da prefeitura

Algumas prefeituras não permitem cancelamento por webservice. Antes de prometer o recurso ao cliente, confirme como o município dele trata o cancelamento na lista de municípios atendidos.

Operações — NFS-e Nacional (/v2/nfsen)

O ambiente nacional usa o conceito de DPS (Declaração de Prestação de Serviços), que gera a NFS-e. O vocabulário dos campos é diferente do municipal.

  • Emitir: POST /v2/nfsen?ref=... — envia a DPS para processamento. Retorna 202 (aceita, em processamento). Campos principais: data_emissao, numero_dps, serie_dps, codigo_municipio_emissora, cnpj_prestador, codigo_tributacao_nacional_iss, descricao_servico, valor_servico.
  • Consultar: GET /v2/nfsen/{referencia} — verifica o status atual.
  • Cancelar: DELETE /v2/nfsen/{referencia} — cancela uma nota autorizada. Retorno síncrono. A justificativa é obrigatória apenas quando o código de cancelamento for 4.
  • Reenviar email: POST /v2/nfsen/{referencia}/email — envia cópia da nota por email.
  • Solicitar reenvio de notificação: POST /v2/nfsen/{referencia}/hook — reaciona os webhooks cadastrados.
📘

Atendimento ao exterior

O padrão nacional prevê prestador/tomador no exterior: use nif_prestador / nif_tomador (Número de Identificação Fiscal) no lugar de CNPJ/CPF, com motivo_ausencia_nif_tomador quando o NIF não existir.

Documentos recebidos (NFS-e Nacional)

Além da emissão, o ambiente nacional permite consultar notas recebidas contra o seu CNPJ:

  • Consultar / Consultar em JSON / Consultar em XML — a nota recebida em diferentes formatos.
  • DANFSe em PDF e em HTML — o documento visual da nota recebida.
  • Solicitar reenvio de notificação — reaciona os webhooks das notas recebidas.

Resumo das operações

NFS-e municipal — /v2/nfse

OperaçãoMétodo + rotaRetorno
EmitirPOST /v2/nfse?ref=201 (assíncrono)
ConsultarGET /v2/nfse/{ref}200
CancelarDELETE /v2/nfse/{ref}200 (síncrono)
Reenviar emailPOST /v2/nfse/{ref}/email200
Reenviar notificaçãoPOST /v2/nfse/{ref}/hook200

NFS-e Nacional — /v2/nfsen

OperaçãoMétodo + rotaRetorno
Emitir (DPS)POST /v2/nfsen?ref=202 (assíncrono)
ConsultarGET /v2/nfsen/{ref}200
CancelarDELETE /v2/nfsen/{ref}200 (síncrono)
Reenviar emailPOST /v2/nfsen/{ref}/email200
Reenviar notificaçãoPOST /v2/nfsen/{ref}/hook200
📘

Campos completos

A listagem acima traz os campos principais. A relação completa dos campos da NFS-e Nacional está na documentação de campos da DPS (link na página de referência da operação Emitir).

Fonte: documentação da API Focus NFe — /reference/nfse e /reference/nfse-nacional (endpoints, métodos, campos e tipo de retorno conforme publicados).

Updated about 2 hours ago

Did this page help you?