NFSe: Nota Fiscal de Serviços Eletrônica

A NFSe é o documento fiscal para prestação de serviços. Diferente da NFe, é autorizada pela prefeitura municipal (ABRASF) ou pela SEFIN/ADN (Padrão Nacional). Cada padrão tem seu próprio contrato.

Endpoint base: https://api.engineapi.com.br/v1/nfse

Diferenças NFSe vs NFe

Emitir NFSe

servico.itemListaServico é obrigatório no fluxo manual, só pode ficar de fora com resolverTributacao: true.

curl -X POST https://api.engineapi.com.br/v1/nfse \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issuerId": "ISSUER_ID",
    "tomador": {
      "cnpjCpf": "99888777000100",
      "razaoSocial": "Cliente Exemplo SA",
      "email": "financeiro@cliente.com.br",
      "telefone": "11999998888",
      "endereco": {
        "logradouro": "Av Paulista",
        "numero": "1000",
        "bairro": "Bela Vista",
        "codigoMunicipio": "3550308",
        "uf": "SP",
        "cep": "01310100"
      }
    },
    "servico": {
      "codigoMunicipio": "3550308",
      "itemListaServico": "01.01",
      "discriminacao": "Desenvolvimento de software sob encomenda",
      "valorServicos": 5000.00,
      "aliquotaIss": 2.00
    },
    "dpsNacional": {
      "opSimpNac": 1,
      "cTribNac": "010701",
      "tribISSQN": 1
    },
    "competencia": "2026-04-01",
    "informacoesComplementares": "Referente ao projeto engineAPI, Fase 1"
  }'

Campos de Referência

Emissão assistida (Cérebro Fiscal)

Com "resolverTributacao": true, campos ausentes da DPS (dpsNacional.cTribNac, opSimpNac, tribISSQN, tpRetISSQN, servico.itemListaServico, servico.codigoNBS) são preenchidos a partir do cadastro do emissor (cTribNacPadrao/servicoPadraoLc116 em Issuer). Requer feature de plano + Issuer.fiscalBrainEnabled (403 sem isso). Campo obrigatório sem fonte cadastrada → 422 com camposNaoResolvidos e nada é emitido. aliquotaIss nunca é opinada pelo Cérebro: se o payload mandar um valor mesmo assim, ele é ignorado (ecoar um valor divergente do cálculo da SEFIN causa rejeição E1235), e esse descarte aparece na resposta, em avisos[] (string), além do log do servidor. Sem a flag, o comportamento é o de sempre (passthrough manual, sem avisos).

Códigos de Serviço LC116

Os códigos (servico.itemListaServico) são definidos pela Lei Complementar 116/2003:

Response de Sucesso

Envelopado em { data, meta }:

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "numero": 1234,
    "codigoVerificacao": "ABC12345",
    "chaveAcesso": "35260211222333...",
    "protocol": "135260000001234",
    "status": "AUTHORIZED",
    "dataEmissao": "2026-04-27T02:00:00.000Z",
    "valorServicos": "5000",
    "downloads": {
      "xml": "/v1/nfse/xml/3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "pdf": "/v1/nfse/pdf/3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-07-06T12:00:00.000Z"
  }
}

Cancelar NFSe

curl -X POST https://api.engineapi.com.br/v1/nfse/{id}/cancelar \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "motivo": "Serviço não prestado, contrato cancelado", "codigoMotivo": "2" }'

{id} é o id (UUID) retornado na emissão. Diferente de NFe/NFCe (campo justificativa), o corpo do cancelamento de NFSe usa motivo.

Se a SEFIN rejeitar o cancelamento, a resposta 400 traz erros[] estruturado (codigo/descricao/complemento verbatim do Padrão Nacional), nunca vazio, pra sua aplicação ramificar por código.

Consultar NFSe na SEFIN

curl https://api.engineapi.com.br/v1/nfse/{id}/consultar \
  -H "x-api-key: SUA_API_KEY"

{id} é o id (UUID) retornado na emissão. Consulta a NFS-e diretamente na SEFIN/ADN pela chave de acesso e atualiza o xmlContent local quando a SEFIN devolve um XML.

Próximos passos