Tipos e enums — NFS-e Inbound
Os valores canônicos vêm da referência gerada da API. O resumo abaixo cobre os mais usados.
Tipo de documento
Enum interno: None, Dps, EventRegistrationRequest, Nfse, Event, Cnc, Unknown. No payload (wire), Nfse serializa como serviceInvoice, Event como serviceInvoiceEvent (v2), e Unknown como unknown.
No filtro de listagem o tipo da NFS-e é Nfse; na resposta o campo aparece como serviceInvoice. Atente a essa assimetria ao montar filtros.
Status do documento
Received, Processed, Failed, PdfPending, PdfFailed, Reprocessed.
Status de webhook
Pending, Delivered, Retrying, DefinitivelyFailed, Skipped.
| Valor | Significado |
|---|---|
Pending | Entrega ainda devida |
Delivered | Seu endpoint respondeu 2xx. Exceção: documentos obtidos por captura sob demanda nascem Delivered sem que nenhum POST tenha sido feito — os dados já foram devolvidos na resposta da chamada. O webhook desse documento sai quando o lote trouxer a mesma nota |
Retrying | Em backoff, ainda tentando |
DefinitivelyFailed | Esgotou as tentativas |
Skipped | Nenhum webhook será entregue — não por falha, mas por regra de negócio: o documento é anterior à data de corte da empresa (histórico retido). Não confunda com Pending (ainda devida) nem com DefinitivelyFailed (tentou e desistiu). Se o histórico for liberado, esses documentos passam a ser entregues |
Manifestação (tomador)
- Códigos de evento:
203202(Confirmação) e203206(Rejeição). - Status:
Pending→Accepted/Rejected/Failed.
NSU
O nsu do documento é o Número Sequencial Único atribuído pelo ambiente nacional na distribuição em lote.
Ele vem null em documentos obtidos por captura sob demanda pela chave de acesso, que não passam pela distribuição em lote. Quando o lote trouxer a mesma NFS-e depois, o nsu é preenchido. Trate nsu: null como estado válido — não como erro de integração.
Ambiente
environment (na empresa e no documento): três valores distintos, case-insensitive — Production, Development e Homologation. A normalização retorna o valor canônico exato (não há mapeamento de Homologation para Development). Quando omitido, o padrão é Production. Verificado no código.
Motivo de desativação (deactivationReason)
Preenchido quando a empresa fica com isActive: false. Valores que o serviço grava hoje:
| Valor | Quem grava | Quando |
|---|---|---|
CertificateRejected | Automático (circuit breaker) | A SEFIN rejeitou o certificado em falhas consecutivas até atingir o limite. É o único motivo automático que ainda desativa |
ManualDeactivation | Ação do operador ou do cliente | DELETE .../details, ou PUT .../details com isActive: false |
Antes, certificado não cadastrado ou fora da validade desativava a captura. Hoje a empresa permanece ativa e a captura é apenas espaçada (o campo rateLimitedUntil é preenchido com um cooldown) até o certificado ser regularizado — assim a captura retoma sozinha, sem precisar de reativação manual. Veja Troubleshooting.
Os valores CertificateNotFound e CompanyNotAuthorized continuam existindo para leitura de registros antigos: uma empresa desativada no passado pode ainda exibi-los. Nenhum fluxo atual os grava. O valor CertificateExpired foi retirado do conjunto.
Campos do documento (detalhe REST)
O GET .../inbound/nfse/{id} retorna metadados — accessKey, nsu, provider/borrower (cada um com federalTaxNumber, name, cityCode), servicesAmount, serviceCode, issueCityCode, accrualOn, generatedOn, status, type, webhookStatus, hasPdf, xmlSizeBytes, failureReason, reprocessCount, webhookAttempts. O nsu pode vir null — veja NSU.
O detalhe REST não traz os grupos de tributos (taxes/amounts) — esses só aparecem no payload do webhook (incluindo IBS/CBS). Veja Reforma Tributária (RTC).
Notificações de manutenção
- Severidade:
Info,Warning,Critical. - Tipo: falhas definitivas de documento/lote/webhook e desativação automática de empresa.
Detalhes finos de alguns enums (ex.: estados intermediários de status) estão sendo confirmados — ver issue #210. Em caso de dúvida, a fonte de verdade é a referência gerada.