Consultar e cancelar

Endpoints pra ler estado, baixar artefatos e operar sobre NFS-e emitidas.

Consultar uma NFS-e

GET/v1/nfse/{id}🔒 Bearer Token

Devolve o NfseResponse no estado atual. Idempotente — pode chamar quantas vezes quiser.

cURL

curl https://api.notare.nexosos.com/v1/nfse/5fcb9e1d-... \
  -H "Authorization: Bearer nt_live_xxxxxxxx"

Baixar PDF (DANFSe)

GET/v1/nfse/{id}/pdf🔒 Bearer Token

• Disponível em estados autorizada ou cancelada
• Content-Type: application/pdf
• Content-Disposition: inline; filename="danfse-{numero}.pdf"

Baixar XML autorizado

GET/v1/nfse/{id}/xml🔒 Bearer Token

• Disponível apenas quando autorizada
• Content-Type: application/xml; charset=utf-8
• Este XML é o documento fiscal com valor jurídico — guarde por 5 anos

Listar NFS-e

GET/v1/nfse🔒 Bearer Token

Paginação por offset. Filtros via query string.

Query parameters

empresaIdstring

Filtrar por empresa específica. Default: todas do tenant.

Formato: UUID

statusenum

Filtrar por estado.

municipiostring

Filtrar por município de prestação.

Formato: IBGE 7 dígitos

qstring

Busca textual em numero, idIntegracao, chaveAcesso.

dataIniciostring

Formato: ISO 8601Default: 30 dias atrás

dataFimstring

Formato: ISO 8601Default: agora

limitinteger

Default: 25Tamanho: 0 – 100

offsetinteger

Default: 0

Response

{
  "items": [ /* NfseResponse[] */ ],
  "total": 1247,
  "limit": 25,
  "offset": 0
}

Cancelar uma NFS-e

POST/v1/nfse/{id}/cancelar🔒 Bearer Token

Body

{
  "motivo": "Serviço não foi prestado conforme acordo"
}

Body

motivostringObrigatório

Justificativa do cancelamento. Aparece no histórico fiscal.

Tamanho: 15 – 500

Regras de prazo

Prazo de cancelamento autônomo varia por município (geralmente 24h a 30 dias após emissão). Após o prazo, use solicitar cancelamento abaixo.

Erros comuns

Código	Significado
NFSE_NAO_CANCELAVEL	Estado não permite (rejeitada, processando)
PRAZO_EXPIRADO	Prazo de cancelamento autônomo passou
MOTIVO_INVALIDO	Motivo com menos de 15 chars

Solicitar cancelamento (após prazo)

POST/v1/nfse/{id}/solicitar-cancelamento🔒 Bearer Token

Quando o prazo de cancelamento autônomo expirou. A solicitação fica em análise fiscal até aprovação/rejeição — você é notificado por webhook.

Body

{
  "motivo": "Tomador devolveu o serviço por defeito"
}

Substituir uma NFS-e

POST/v1/nfse/{id}/substituir🔒 Bearer Token

Retifica erro material sem cancelar puramente. A nota original é cancelada e uma nova é emitida com vínculo histórico.

Body

{
  "novaNota": { /* NfseEmitirRequest completo */ },
  "motivo": "Correção da descrição do serviço"
}

A nova NFS-e traz meta.numeroOriginal apontando pra anterior.