NFS-e

Visión general y flujo de integración

La autenticación es idéntica a la de NF-e: cabeceras token / timestamp / sign, vea Autenticación.

Tres diferencias estructurales frente a NF-e

1. La clave de acceso tiene 50 dígitos y la genera el emisor oficial. La clave de 44 dígitos de la NF-e la calcula el contribuyente; la clave de la NFS-e solo existe cuando la autoridad acepta el documento. Un documento fallido, por tanto, no tiene chaveAcesso y solo puede localizarse por identificacaoDps, el identificador de DPS de 45 caracteres que generamos.

2. La factura de servicios la rige el municipio. La plataforma enruta por el municipio del emisor; el canal resultante aparece como padraoMunicipal en la respuesta de la consulta. Hoy se admiten el estándar nacional (Nacional) y el sistema municipal de São Paulo (Paulistana); un municipio no admitido se rechaza en la aceptación (10018010) en vez de aceptarse y fallar de forma asíncrona.

3. La cancelación tiene ventana, y fuera de ella la respuesta no es "no se puede cancelar" sino "pasa a análisis municipal". Vea Cancelar NFS-e.

Requisitos previos

• El emisor debe estar aprobado y con certificado utilizable, de lo contrario la aceptación se rechaza (10018004).
• El emisor debe tener perfil de NFS-e, creado con la sección emissaoNFSe de Registrar empresa o mantenido por operaciones en la consola. El encuadre en el Simples, el cálculo en el Simples, el régimen especial y la serie del DPS vienen siempre del perfil; la solicitud de emisión no los envía ni los sustituye. Sin perfil, la aceptación rechaza (10018005). Código de servicio, CNAE, NBS y los demás campos del servicio no están en el perfil: van en cada nota.
• El ambienteEmissao debe coincidir con el entorno actual del emisor. Tras el registro el emisor queda en el entorno de pruebas (Homologacao); el paso a producción es una acción de operaciones y no se expone por la API.
• Los valores de tributación siguen la solicitud: lo que trae prevalece, y solo lo que falta lo busca la plataforma en los datos de referencia fiscal, como la lista de la LC 116, la clasificación y las alícuotas de retención federal y la carga aproximada del IBPT. Si los datos que necesitan la retención federal, las alícuotas propias de PIS/COFINS o el lugar de incidencia del ISS aún no se importaron, la aceptación rechaza con 10018065, listando los campos de la solicitud que pueden sustituirlos.
• Cuando el receptor es persona jurídica (CNPJ) hay retención federal: envíe los importes en servico.retencoes, donde cero declara que no hay retención, u omítalos junto con pisCofins.tipoRetencao y la plataforma los determina por la clasificación oficial de retención del servicio y por cliente.orgaoPublico y cliente.optanteSimplesNacional; enviar pisCofins.tipoRetencao sin los importes se rechaza (10018001). La información faltante se rechaza explícitamente (10018023) con todo lo que falta listado de una vez, en lugar de tratarse como cero.

Restricciones adicionales del canal Paulistana

Un emisor de São Paulo (padraoMunicipal = Paulistana) necesita su CCM (inscricaoMunicipal): si está en el perfil, se usa tal cual; si falta, la plataforma consulta el sistema municipal por CNPJ en la aceptación y guarda el resultado en el perfil; la aceptación solo se rechaza (10018005) cuando no se encuentra nada.

El canal no admite campos de descuento: incorpore el descuento al importe del servicio o a la deducción. Tampoco admite emisión sustitutiva (el layout municipal de RPS no tiene ese grupo): cancele la original y emita una nueva; enviar el grupo se rechaza en la aceptación (10018001).

También obtiene dos capacidades automáticas que no requieren ningún endpoint nuevo: las facturas paulistanas recibidas se traen directamente del sistema municipal al listado de recibidas (origem=PrefeituraSP, fusionadas automáticamente cuando llega la transcripción de la ADN); una factura emitida y cancelada en el portal municipal se sincroniza a Cancelada y el nfse.canceled se envía con normalidad.

Máquina de estados

                 ┌──────────────► Negada (terminal)
                 │
Pendente ────────┼──────────────► Autorizada ──┬──► Cancelada (terminal)
                 │                             │
                 └──────────────► Falha        ├──► EmProcessoDeCancelamento ──┬──► Cancelada
                   (falló antes de la          │                               └──► Autorizada (análisis denegado)
                    numeración, sin documento) └──► Substituida (sustituida)

Estado de manifestación de una factura recibida

El status de una factura recibida usa Autorizada / Cancelada / Substituida de la tabla anterior; la manifestación de este emisor se guarda aparte en el bloque manifestacao, y cada parte manifiesta como máximo una vez por factura.

(sin manifestación, filtro de la lista Pendente) ──┬──► Confirmada (confirmada por este emisor, terminal)
                                                   ├──► Rejeitada (rechazada por este emisor) ──► RejeicaoAnulada (rechazo anulado por el municipio, terminal)
                                                   └──► ConfirmacaoTacita (confirmación tácita del municipio, terminal)

Callbacks de webhook

Se entregan en la URL que usted registra como carga JSON pura.

Aviso: Semántica de las suscripciones. Una aplicación que nunca registró ninguna fila de suscripción recibe los seis eventos de salida. En cuanto exista cualquier fila de suscripción para la aplicación (por ejemplo un evento de entrada), pasa al modo lista de permitidos y solo se entregan los eventos habilitados explícitamente. Al suscribirse a eventos de entrada, habilite también los eventos de salida que necesite, o las notificaciones de salida quedarán en espera de destinatario.

{
  "tipo": "NFS-e",
  "empresaId": "1001",
  "nfseId": "PED-20260918-001",
  "nfseStatus": "Autorizada",
  "nfseMotivoStatus": null,
  "nfseLinkDanfse": "https://api.v2.tffiscal.com/openapi/files/danfse/…",
  "nfseLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/9001?token=…",
  "nfseNumero": "1287",
  "nfseSerie": "1",
  "nfseChaveAcesso": "3550308…",
  "nfseIdentificacaoDps": "DPS3550308…",
  "nfseDataEmissao": "2026-09-18T13:00:00Z",
  "nfseDataAutorizacao": "2026-09-18T13:00:03Z",
  "nfseNumeroProtocolo": null,
  "nfseAtualizadoEm": "2026-09-18T13:00:03Z"
}

nfseAtualizadoEm es el momento de este cambio de estado. El orden de entrega no está garantizado: los reintentos y las múltiples instancias pueden hacer que un evento antiguo llegue después de uno nuevo. Compárelo con la marca de tiempo que ya tiene y descarte el más antiguo en vez de sobrescribir el estado por orden de llegada.

En un callback de fallo el nfseChaveAcesso puede venir vacío (la autoridad nunca generó la clave); concilie por nfseIdentificacaoDps en ese caso. Un callback de fallo anterior a la numeración no trae ninguno de los dos, y solo el nfseId concilia.

Modelo de errores

Los endpoints públicos devuelven un array puro:

[{"codigo": "10018012", "mensagem": "Codigo de servico fora da lista oficial LC 116: 999999"}]

Los errores de autenticación y autorización (10009xxx) están en Autenticación; la tabla completa está en Códigos de error.

Checklist de integración

1. Registre el emisor (con emissaoNFSe) → vincule el certificado → registre el webhook.
2. Emita una factura mínima en Homologacao (solo los campos obligatorios), confirme que llega el nfse.authorized y que el XML y el DANFSe se descargan.
3. Envíe el mismo id otra vez y confirme que no se emite una segunda factura.
4. Envíe un código de servicio inexistente y confirme el rechazo síncrono 10018012, y no una Negada asíncrona.
5. Cancele una factura autorizada y confirme que llega a Cancelada o EmProcessoDeCancelamento según la ventana.
6. Consulte un documento fallido y confirme que concilia por identificacaoDps, no por chaveAcesso.
7. Manifieste sobre una factura recibida con tipo=Confirmacao y vea que el detalle trae manifestacao.status=Confirmada; envíe tipo=Rejeicao en la misma factura y confirme el 10018042 (cada parte manifiesta una vez).