Emisión de NFS-e

Emite NFS-e con el mismo motor de la hoja de cálculo y del panel: misma validación, misma cola, misma recuperación de fallas técnicas. La nota emitida por la API aparece en el panel, con el origen "API".

Siempre envías el mismo JSON, sea cual sea el municipio. Lo que cambia por municipio o por escenario tributario (completar, omitir, exigir un campo) lo decidimos nosotros, y la respuesta cuenta lo que se hizo en ajustes:

{
  "campo": "/prestador/inscricao_municipal",
  "acao": "omitido",
  "motivo": "O município não aceita a inscrição municipal do prestador nesta DPS (E0120). A nota foi reenviada sem ela.",
  "regra": "correcao.E0120"
}

acao es preenchido, omitido, derivado o exigido; regra es el identificador estable de la regla en nuestro catálogo (por ejemplo dps.pAliq.exigido.simples_retido, param.aliquota_iss, correcao.E0120). regras_versao trae la versión de los dos catálogos que decidieron la nota, corrección automática y reglas de campo, en ese orden (2026-09-30.1+2026-10-02.1).

Cuando la alícuota del ISS es obligatoria y no envías ninguna (ni la empresa tiene una por defecto), usamos la alícuota OFICIAL que el municipio registró en el Sistema Nacional para el servicio, si es única en el período de competencia. Aparece como ajuste preenchido con la regla param.aliquota_iss.

Estados

El ciclo completo, con qué hacer en cada uno y el webhook correspondiente, está en Estados de la NFS-e.

Estado	Qué significa
transmitindo	Nos estamos encargando: en la cola, enviando, o recuperando una falla técnica del Sistema Nacional. No reenvíes.
autorizada	NFS-e emitida. numero y chave_acesso completos.
rejeitada	El Sistema Nacional la rechazó. Motivo en rejeicao. Corrige y emite una nota nueva.
cancelada	Cancelada después de autorizada. Protocolo en cancelamento. Si fue por sustitución, substituida_por indica qué nota la sustituyó.
falha_transmissao	Final. No se pudo concluir ni confirmar la transmisión, y no se intentará nada más automáticamente. Mira falha: con dps_enviada: "desconhecido", verifica en el Emissor Nacional antes de emitir de nuevo.
descartada	La nota volvió sin éxito y se descartó en el panel.
aguardando_confirmacao	El período de competencia de la nota terminó antes de un reintento automático. No se transmite nada hasta que confirmes en POST /v1/nfse/{id}/confirmacao (puedes cambiar el período de competencia).

Si la nota pasa 30 minutos en transmitindo, la respuesta incluye aviso: {"codigo": "processamento_prolongado"} y se envía el webhook NFSE_PROCESSAMENTO_PROLONGADO, una vez. Es solo un aviso: seguimos encargándonos de la nota y el estado no cambia.

Sustituir una NFS-e

Para corregir una nota autorizada sin cancelar y emitir otra, emite la nota correcta en POST /v1/nfse con el bloque substituicao:

{
  "empresa_id": "…",
  "tomador": { "documento": "11222333000181" },
  "valor": "1500.00",
  "servico": { "descricao": "Consultoria de setembro, valor corrigido" },
  "substituicao": { "nfse_id": "id-da-nota-original", "codigo_motivo": "99", "motivo": "Valor do serviço informado errado na nota original." }
}

La nota nueva sigue el camino de siempre. Cuando se autoriza, el Sistema Nacional cancela la original por sí solo (cancelación por sustitución): la original pasa a cancelada, con substituida_por, y se envía su webhook NFSE_CANCELADA. Si la nueva es rechazada, la original sigue autorizada y nada cambia en ella.

Antes de transmitir, rechazamos con 422 lo que ya se sabe que no pasa: nota cancelada o ya sustituida (E0046), nota de otro entorno (E0065), otra sustitución de la misma nota en curso, y codigo_motivo 99 sin motivo (E0078). El plazo de sustitución del municipio (E0050) y la manifestación del tomador (E0070) solo los conoce el Sistema Nacional; vuelven como rechazo, con rejeicao.explicacao.

Para una NFS-e emitida fuera de Sudrel, usa chave_acesso en lugar de nfse_id. La sustitución no existe por lote.

Construcción civil: datos de la obra

En los códigos de construcción civil (07.02.01, 07.02.02, 07.04.01, 07.05.01, 07.05.02, 07.06.01, 07.06.02, 07.07.01, 07.08.01, 07.17.01, 07.19.01, 14.14.03 y 14.14.04) el Sistema Nacional exige los datos de la obra, y en los demás los rechaza. Envía servico.obra con el CNO, el CIB o el CEP y número de la dirección de la obra, y el municipio, cuando no viene del CEP:

{ "servico": { "codigo_nacional": "070201", "obra": { "cno": "90.012.34567/89", "municipio": "Lauro de Freitas - BA" } } }

El municipio de la obra pasa a ser el lugar de prestación de la nota. En los códigos en que el ISS se debe donde está la obra, el convenio de ese municipio decide si se exige la alícuota del ISS. En la hoja de cálculo, son las columnas "CNO da obra", "CEP da obra" etc., en el layout Completo.

Probar la integración (sandbox)

Usa una clave sdr_test_ en las MISMAS rutas y con el MISMO JSON. La nota se transmite de verdad al entorno de pruebas del Sistema Nacional (producción restringida), con el certificado real de la empresa, y vuelve autorizada o rechazada por las mismas reglas. No tiene valor fiscal, no cuenta en la franquicia, no depende del plan y no aparece en el panel. ambiente viene como sandbox en la respuesta y en los webhooks.

Los dos entornos nunca se cruzan: la clave de prueba solo ve notas de prueba, la de producción solo las de producción, y la misma referencia o Idempotency-Key se puede usar en los dos. Una empresa que emite por el sistema del propio municipio no tiene entorno de pruebas: la preparación trae el elemento sandbox_municipio_proprio en bloqueio, y la emisión se rechaza con 412 empresa_nao_pronta.

Una falla técnica del Sistema Nacional no es una respuesta para ti: la nota sigue en transmitindo mientras la recuperación automática trabaja (consulta la DPS antes de cualquier reenvío, así que la nota nunca se emite dos veces).

Emisión mínima

curl https://api.sudrel.com.br/api/v1/nfse \
  -H "Authorization: Bearer sdr_live_..." \
  -H "Idempotency-Key: 7f1c0d9a-4a51-4e0e-9b1f-2b6f0d3c5a10" \
  -H "Prefer: wait=15" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":"0b7e6a52-3c1d-4f8e-9a20-5d4c3b2a1f00","referencia":"PED-1001","tomador":{"documento":"11222333000181"},"valor":"1500.00","servico":{"descricao":"Consultoria em sistemas"}}'

Los valores monetarios y las alícuotas van como TEXTO con punto decimal ("1500.00"). Un número JSON se rechaza, para que ningún valor de nota fiscal dependa del redondeo de punto flotante.