NFCom · TF Fiscal API

Nota

NFCom — Nota Fiscal Factura de Servicio de Comunicación Electrónica

La API de NFCom (modelo 62, layout 1.00) permite emitir, consultar, cancelar y obtener el PDF (DANFE-COM) de Notas Fiscales Factura de Servicios de Comunicación Electrónica. La NFCom sustituye a los antiguos modelos 21/22 y documenta la factura de servicios de telecomunicación — telefonía, internet, TV por suscripción, datos. La autorización se realiza en el ambiente nacional único (SVRS). Los datos del emisor se rellenan automáticamente a partir del registro de la empresa (CNPJ, IE, razón social y dirección); los campos técnicos de la clave de acceso (cNF, cDV, cUF, dhEmi, mod) son calculados por el servidor. El QR-Code de consulta (qrCodNFCom) también se genera automáticamente.

Endpoint	Método	Descripción
`/api/nfcom/create`	POST	Emitir NFCom
`/api/nfcom/consult`	POST	Consultar situación de la NFCom
`/api/nfcom/cancel`	POST	Cancelar NFCom autorizada
`/api/nfcom/pdf`	POST	Obtener el DANFE-COM (PDF) de la NFCom
`/api/nfcom/get_list`	GET	Listar NFCom (paginado)

Acreditación obligatoria: la emisión de NFCom exige que el CNPJ emisor esté acreditado para el modelo 62 ante la autoridad fiscal de su UF (habilitación restringida a prestadores de servicios de telecomunicación). Sin la acreditación, la autoridad fiscal rechaza la emisión con cStat=203 ("Emissor não habilitado para emissão da NFCom"). La acreditación en homologación y en producción son etapas separadas.

POST/api/nfcom/create

Emitir NFCom

Emite una NFCom a partir del cuerpo enviado. El cliente envía únicamente los datos de negocio — el bloque del emisor (emit) se monta automáticamente a partir del registro de la empresa del token, y los campos técnicos de la clave de acceso son calculados por el servidor. El débito de crédito ocurre solo en producción (tpAmb=1) y cuando la NFCom es autorizada. Tras la autorización, el XML (nfcomProc) y el DANFE-COM (PDF) se generan y quedan disponibles por URL.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Body — raíz

Campo	Tipo	Descripción
ide	object	Identificación de la NFCom (ambiente, serie, competencia del hecho generador)
dest *	object	Datos del destinatario/tomador
assinante *	object	Datos del suscriptor del servicio (obligatorio en el layout de la NFCom)
det *	array	Ítems facturados — mínimo 1
total	object	Totalizador. Opcional — calculado a partir de los ítems cuando se omite
gFat	object	Datos de la factura (competencia, vencimiento, código de barras)
infAdFisco	string	Información de interés del Fisco
infCpl	array	Información complementaria (lista de textos)
autXML	array	CNPJ/CPF autorizados a acceder al XML (lista de strings)

Campos obligatorios en la solicitud: dest con xNome, uno de CNPJ/CPF/idOutros y enderDest (xLgr, nro, xBairro, cMun, xMun, CEP con 8 dígitos, UF); assinante.iCodAssinante; y al menos 1 ítem en det con xProd, cClass (7 dígitos de la tabla de clasificación de ítems de la NFCom), vItem y vProd. Todos los demás campos son opcionales.

ide — Identificación

Campo	Tipo	Descripción
tpAmb	int	Ambiente: `1`=producción, `2`=homologación. Default: `2`
nNF	long	Número secuencial de la NFCom. Opcional — auto-incrementado por el servidor cuando se omite o es `0`
dhEmi	string	Fecha/hora de emisión. Opcional — generada por el servidor cuando se omite
cMunFG	long	Código IBGE del municipio del hecho generador (7 dígitos). Opcional — default: municipio del registro de la empresa
finNFCom	int	Finalidad: `0`=Normal, `3`=Sustitución, `4`=Ajuste. Default: `0`
tpFat	int	Tipo de facturación: `0`=Normal, `1`=Centralizado, `2`=Cofacturación. Default: `0`
nSiteAutoriz	int	Sitio autorizador (1 dígito de la clave). Default: `0`
indPrePago	string	Indicador de servicio prepago: `"1"` cuando aplica

Rellenados automáticamente por el servidor — no es necesario enviarlos: mod (fijo en 62), serie (serie de NFCom registrada en la empresa; configúrela en /api/company/edit vía serie_nfcom), cUF (derivado del registro de la empresa), cNF (código numérico de 7 dígitos), cDV (dígito verificador de la clave), tpEmis (normal) y verProc. El bloque emit completo y el infNFComSupl (QR-Code) también son montados por el servidor.

dest — Destinatario / Tomador

Campo	Tipo	Descripción
xNome *	string	Nombre o razón social del destinatario
CNPJ ⚠	string	CNPJ del destinatario (14 dígitos)
CPF ⚠	string	CPF del destinatario (11 dígitos)
idOutros ⚠	string	Otro documento de identificación (extranjero, etc.)
indIEDest	int	Indicador de IE: `1`=contribuyente, `2`=exento, `9`=no contribuyente. Default: `9`
IE	string	Inscripción Estatal del destinatario (cuando es contribuyente)
enderDest *	object	Dirección del destinatario (ver estructura abajo)

enderDest — Dirección

Campo	Tipo	Descripción
xLgr *	string	Calle
nro *	string	Número
xCpl	string	Complemento
xBairro *	string	Barrio
cMun *	long	Código IBGE del municipio (7 dígitos)
xMun *	string	Nombre del municipio
CEP *	string	Código postal (8 dígitos)
UF *	string	Sigla de la UF (2 letras)
fone	string	Teléfono
email	string	Correo electrónico

assinante — Suscriptor del servicio

Campo	Tipo	Descripción
iCodAssinante *	string	Código único de identificación del suscriptor (1–30 caracteres)
tpAssinante	int	Tipo de suscriptor: `1`=Comercial, `2`=Industrial, `3`=Residencial, `4`=Productor rural, `5`=Órgano público, `6`=Prestador de servicio de telecom, `7`=Misiones diplomáticas, `8`=Iglesias y templos, `99`=Otros. Default: `1`
tpServUtil	int	Tipo de servicio utilizado: `1`=Telefonía, `2`=Comunicación de datos, `3`=TV por suscripción, `4`=Acceso a Internet, `5`=Multimedia, `6`=Otros, `7`=Varios. Default: `1`
nContrato	string	Número del contrato del suscriptor

det[] — Ítems facturados

Campo	Tipo	Descripción
cProd	string	Código del ítem. Opcional — default: número secuencial
xProd *	string	Descripción del servicio/ítem facturado
cClass *	string	Código de clasificación del ítem (7 dígitos — tabla de clasificación de ítems de la NFCom)
CFOP	string	CFOP de la prestación (obligatorio cuando el ítem tiene ICMS)
uMed	string	Unidad de medida: `1`=Minuto, `2`=MB, `3`=GB, `4`=UN. Default: `4`
qFaturada	string	Cantidad facturada. Default: `"1"`
vItem *	string	Valor unitario del ítem
vProd *	string	Valor total del ítem
vDesc	string	Valor del descuento
infAdProd	string	Información adicional del ítem
icms	object	Tributación de ICMS del ítem (ver abajo)
pis	object	PIS del ítem (ver abajo)
cofins	object	COFINS del ítem (misma estructura del PIS)
ibscbs	object	IBS/CBS — Reforma Tributaria (ver abajo)

det[].icms — ICMS del ítem

Campo	Tipo	Descripción
cst	string	CST del ICMS. Default: `"00"` (tributación integral)
vBC	string	Base de cálculo del ICMS
pICMS	string	Alícuota del ICMS (%)
vICMS	string	Valor del ICMS
simplesNacional	bool	`true` = emisor del Simples Nacional (grupo `ICMSSN`)
semCST	bool	`true` = ítem sin relación con el ICMS (`indSemCST`; no informe CFOP en ese caso)

det[].pis / det[].cofins

Campo	Tipo	Descripción
cst	string	CST del PIS/COFINS (`01`, `02`, `06`, `07`, `08`, `09`, `49`). Default: `"01"`
vBC	string	Base de cálculo
pAliq	string	Alícuota (%)
valor	string	Valor del tributo

det[].ibscbs — IBS/CBS (Reforma Tributaria)

Campo	Tipo	Descripción
cst	string	CST del IBS/CBS (3 dígitos)
cClassTrib	string	Código de clasificación tributaria
vBC	string	Base de cálculo
pIBSUF / vIBSUF	string	Alícuota y valor del IBS estadual
pIBSMun / vIBSMun	string	Alícuota y valor del IBS municipal
vIBS	string	Valor total del IBS
pCBS / vCBS	string	Alícuota y valor de la CBS

total — Totalizador (opcional)

Campo	Tipo	Descripción
vProd	string	Sumatoria de los ítems. Calculado cuando se omite
vBC	string	Base de cálculo total del ICMS
vICMS	string	Valor total del ICMS
vDesc	string	Total de descuentos
vNF	string	Valor total de la NFCom. Default: igual a `vProd`

gFat — Datos de la factura

Campo	Tipo	Descripción
CompetFat	string	Competencia de la factura en formato `AAAAMM`
dVencFat	string	Fecha de vencimiento en formato `AAAA-MM-DD`
codBarras	string	Código de barras de la factura (solo dígitos, 1–48)

* Campo obligatorio. ⚠ En el destinatario, al menos uno de CNPJ, CPF o idOutros es obligatorio. Los valores monetarios y alícuotas se envían como string con punto decimal (ej.: "99.90").

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los placeholders
curl -X POST "https://api.tffiscal.com/api/nfcom/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "ide": {
            "tpAmb": 2
          },
          "dest": {
            "xNome": "CLIENTE EXEMPLO LTDA",
            "CNPJ": "98765432000188",
            "indIEDest": 9,
            "enderDest": {
              "xLgr": "AVENIDA EXEMPLO",
              "nro": "500",
              "xBairro": "CENTRO",
              "cMun": 3550308,
              "xMun": "SAO PAULO",
              "CEP": "01001000",
              "UF": "SP"
            }
          },
          "assinante": {
            "iCodAssinante": "CLI-0001",
            "tpAssinante": 1,
            "tpServUtil": 4,
            "nContrato": "CT-2026-0001"
          },
          "det": [
            {
              "cProd": "1",
              "xProd": "PLANO INTERNET FIBRA 500MB",
              "cClass": "0100101",
              "CFOP": "5307",
              "uMed": "4",
              "qFaturada": "1.00",
              "vItem": "99.90",
              "vProd": "99.90",
              "icms": {
                "cst": "00",
                "vBC": "99.90",
                "pICMS": "25.00",
                "vICMS": "24.98"
              }
            }
          ],
          "total": {
            "vProd": "99.90",
            "vBC": "99.90",
            "vICMS": "24.98",
            "vNF": "99.90"
          },
          "gFat": {
            "CompetFat": "202607",
            "dVencFat": "2026-08-15",
            "codBarras": "12345678901234567890"
          }
        }

        {
          "success": true,
          "message": "NFCom autorizada",
          "data": {
            "chave": "35260712345678000199620010000000011012345675",
            "serie": 1,
            "number": 1,
            "cStat": "100",
            "xMotivo": "Autorizado o uso da NFCom",
            "nProt": "353260000123456",
            "xml": "https://storage.../nfcom/35260712345678000199620010000000011012345675.xml",
            "danfcom": "https://storage.../nfcom/35260712345678000199620010000000011012345675.pdf"
          }
        }

        {
          "success": false,
          "message": "NFCom rejeitada: Rejeição: Emissor não habilitado para emissão da NFCom",
          "data": {
            "chave": "35260712345678000199620010000000011012345675",
            "serie": 1,
            "number": 1,
            "cStat": "203",
            "xMotivo": "Rejeição: Emissor não habilitado para emissão da NFCom",
            "nProt": "",
            "xml": "",
            "danfcom": ""
          }
        }

POST/api/nfcom/consult

Consultar situación de la NFCom

Consulta la situación actual de la NFCom en el ambiente nacional (SVRS) a partir de la clave de acceso.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chNFCom *	string	Clave de acceso de la NFCom (44 dígitos)

* Campo obligatorio.

POST/api/nfcom/cancel

Cancelar NFCom

Cancela una NFCom autorizada (evento 110111). Requiere que la NFCom haya sido autorizada (posea protocolo) y aún no esté cancelada.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chNFCom *	string	Clave de acceso de la NFCom (44 dígitos)
xJust *	string	Justificación de la cancelación (mínimo 15 caracteres por exigencia de la autoridad fiscal)
nProt *	string	Protocolo de autorización de la NFCom (16 dígitos)

* Campo obligatorio.

POST/api/nfcom/pdf

Obtener PDF de la NFCom

Retorna la URL del DANFE-COM — la representación en PDF de la NFCom (cuenta del suscriptor), conforme al MOC Anexo II. El PDF se genera automáticamente en la autorización; cuando aún no existe en el almacenamiento, se genera bajo demanda a partir del XML.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chNFCom *	string	Clave de acceso de la NFCom (44 dígitos)

* Campo obligatorio.

GET/api/nfcom/get_list

Listar NFCom (paginado)

Lista las NFCom de la empresa con paginación. Los parámetros se pasan por query string (no en el body).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
page *	int	Número de página (≥ 1)
page_size *	int	Tamaño de página (1–50)

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los placeholders
curl -X GET "https://api.tffiscal.com/api/nfcom/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

GET /api/nfcom/get_list?page=1&page_size=20

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260712345678000199620010000000011012345675",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-07-10T10:30:00Z",
                "issue_time": "2026-07-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 42,
            "total_pages": 3
          }
        }