NFCom · TF Fiscal API

Nota

NFCom — Nota Fiscal Fatura de Serviço de Comunicação Eletrônica

A API de NFCom (modelo 62, leiaute 1.00) permite emitir, consultar, cancelar e obter o PDF (DANFE-COM) de Notas Fiscais Fatura de Serviços de Comunicação Eletrônica. A NFCom substitui os antigos modelos 21/22 e documenta a fatura de serviços de telecomunicação — telefonia, internet, TV por assinatura, dados. A autorização é feita no ambiente nacional único (SVRS). Os dados do emitente são preenchidos automaticamente a partir do cadastro da empresa (CNPJ, IE, razão social e endereço); os campos técnicos da chave de acesso (cNF, cDV, cUF, dhEmi, mod) são calculados pelo servidor. O QR-Code de consulta (qrCodNFCom) também é gerado automaticamente.

Endpoint	Método	Descrição
`/api/nfcom/create`	POST	Emitir NFCom
`/api/nfcom/consult`	POST	Consultar situação da NFCom
`/api/nfcom/cancel`	POST	Cancelar NFCom autorizada
`/api/nfcom/pdf`	POST	Obter o DANFE-COM (PDF) da NFCom
`/api/nfcom/get_list`	GET	Listar NFCom (paginado)

Credenciamento obrigatório: a emissão de NFCom exige que o CNPJ emissor esteja credenciado para o modelo 62 junto ao Fisco da sua UF (habilitação restrita a prestadores de serviços de telecomunicação). Sem o credenciamento, o Fisco rejeita a emissão com cStat=203 ("Emissor não habilitado para emissão da NFCom"). O credenciamento em homologação e em produção são etapas separadas.

POST/api/nfcom/create

Emitir NFCom

Emite uma NFCom a partir do corpo enviado. O cliente envia apenas os dados de negócio — o bloco do emitente (emit) é montado automaticamente a partir do cadastro da empresa do token, e os campos técnicos da chave de acesso são calculados pelo servidor. O débito de crédito ocorre somente em produção (tpAmb=1) e quando a NFCom é autorizada. Após a autorização, o XML (nfcomProc) e o DANFE-COM (PDF) são gerados e disponibilizados por URL.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Body — raiz

Campo	Tipo	Descrição
ide	object	Identificação da NFCom (ambiente, série, competência do fato gerador)
dest *	object	Dados do destinatário/tomador
assinante *	object	Dados do assinante do serviço (obrigatório no leiaute da NFCom)
det *	array	Itens faturados — mínimo 1
total	object	Totalizador. Opcional — calculado a partir dos itens quando omitido
gFat	object	Dados da fatura (competência, vencimento, código de barras)
infAdFisco	string	Informações de interesse do Fisco
infCpl	array	Informações complementares (lista de textos)
autXML	array	CNPJs/CPFs autorizados a acessar o XML (lista de strings)

Campos obrigatórios na requisição: dest com xNome, um de CNPJ/CPF/idOutros e enderDest (xLgr, nro, xBairro, cMun, xMun, CEP com 8 dígitos, UF); assinante.iCodAssinante; e pelo menos 1 item em det com xProd, cClass (7 dígitos da tabela de classificação de itens da NFCom), vItem e vProd. Todos os demais campos são opcionais.

ide — Identificação

Campo	Tipo	Descrição
tpAmb	int	Ambiente: `1`=produção, `2`=homologação. Default: `2`
nNF	long	Número sequencial da NFCom. Opcional — auto-incrementado pelo servidor quando omitido ou `0`
dhEmi	string	Data/hora de emissão. Opcional — gerada pelo servidor quando omitida
cMunFG	long	Código IBGE do município do fato gerador (7 dígitos). Opcional — default: município do cadastro da empresa
finNFCom	int	Finalidade: `0`=Normal, `3`=Substituição, `4`=Ajuste. Default: `0`
tpFat	int	Tipo de faturamento: `0`=Normal, `1`=Centralizado, `2`=Cofaturamento. Default: `0`
nSiteAutoriz	int	Site autorizador (1 dígito da chave). Default: `0`
indPrePago	string	Indicador de serviço pré-pago: `"1"` quando aplicável

Preenchidos automaticamente pelo servidor — não é necessário enviá-los: mod (fixo em 62), serie (série de NFCom cadastrada na empresa; configure em /api/company/edit via serie_nfcom), cUF (derivado do cadastro da empresa), cNF (código numérico de 7 dígitos), cDV (dígito verificador da chave), tpEmis (normal) e verProc. O bloco emit completo e o infNFComSupl (QR-Code) também são montados pelo servidor.

dest — Destinatário / Tomador

Campo	Tipo	Descrição
xNome *	string	Nome ou razão social do destinatário
CNPJ ⚠	string	CNPJ do destinatário (14 dígitos)
CPF ⚠	string	CPF do destinatário (11 dígitos)
idOutros ⚠	string	Outro documento de identificação (estrangeiro etc.)
indIEDest	int	Indicador de IE: `1`=contribuinte, `2`=isento, `9`=não contribuinte. Default: `9`
IE	string	Inscrição Estadual do destinatário (quando contribuinte)
enderDest *	object	Endereço do destinatário (ver estrutura abaixo)

enderDest — Endereço

Campo	Tipo	Descrição
xLgr *	string	Logradouro
nro *	string	Número
xCpl	string	Complemento
xBairro *	string	Bairro
cMun *	long	Código IBGE do município (7 dígitos)
xMun *	string	Nome do município
CEP *	string	CEP (8 dígitos)
UF *	string	Sigla da UF (2 letras)
fone	string	Telefone
email	string	E-mail

assinante — Assinante do serviço

Campo	Tipo	Descrição
iCodAssinante *	string	Código único de identificação do assinante (1–30 caracteres)
tpAssinante	int	Tipo de assinante: `1`=Comercial, `2`=Industrial, `3`=Residencial, `4`=Produtor rural, `5`=Órgão público, `6`=Prestador de serviço de telecom, `7`=Missões diplomáticas, `8`=Igrejas e templos, `99`=Outros. Default: `1`
tpServUtil	int	Tipo de serviço utilizado: `1`=Telefonia, `2`=Comunicação de dados, `3`=TV por assinatura, `4`=Acesso à Internet, `5`=Multimídia, `6`=Outros, `7`=Vários. Default: `1`
nContrato	string	Número do contrato do assinante

det[] — Itens faturados

Campo	Tipo	Descrição
cProd	string	Código do item. Opcional — default: número sequencial
xProd *	string	Descrição do serviço/item faturado
cClass *	string	Código de classificação do item (7 dígitos — tabela de classificação de itens da NFCom)
CFOP	string	CFOP da prestação (obrigatório quando o item tem ICMS)
uMed	string	Unidade de medida: `1`=Minuto, `2`=MB, `3`=GB, `4`=UN. Default: `4`
qFaturada	string	Quantidade faturada. Default: `"1"`
vItem *	string	Valor unitário do item
vProd *	string	Valor total do item
vDesc	string	Valor do desconto
infAdProd	string	Informações adicionais do item
icms	object	Tributação de ICMS do item (ver abaixo)
pis	object	PIS do item (ver abaixo)
cofins	object	COFINS do item (mesma estrutura do PIS)
ibscbs	object	IBS/CBS — Reforma Tributária (ver abaixo)

det[].icms — ICMS do item

Campo	Tipo	Descrição
cst	string	CST do ICMS. Default: `"00"` (tributação integral)
vBC	string	Base de cálculo do ICMS
pICMS	string	Alíquota do ICMS (%)
vICMS	string	Valor do ICMS
simplesNacional	bool	`true` = emitente do Simples Nacional (grupo `ICMSSN`)
semCST	bool	`true` = item sem relação com o ICMS (`indSemCST`; não informe CFOP nesse caso)

det[].pis / det[].cofins

Campo	Tipo	Descrição
cst	string	CST do PIS/COFINS (`01`, `02`, `06`, `07`, `08`, `09`, `49`). Default: `"01"`
vBC	string	Base de cálculo
pAliq	string	Alíquota (%)
valor	string	Valor do tributo

det[].ibscbs — IBS/CBS (Reforma Tributária)

Campo	Tipo	Descrição
cst	string	CST do IBS/CBS (3 dígitos)
cClassTrib	string	Código de classificação tributária
vBC	string	Base de cálculo
pIBSUF / vIBSUF	string	Alíquota e valor do IBS estadual
pIBSMun / vIBSMun	string	Alíquota e valor do IBS municipal
vIBS	string	Valor total do IBS
pCBS / vCBS	string	Alíquota e valor da CBS

total — Totalizador (opcional)

Campo	Tipo	Descrição
vProd	string	Somatório dos itens. Calculado quando omitido
vBC	string	Base de cálculo total do ICMS
vICMS	string	Valor total do ICMS
vDesc	string	Total de descontos
vNF	string	Valor total da NFCom. Default: igual a `vProd`

gFat — Dados da fatura

Campo	Tipo	Descrição
CompetFat	string	Competência da fatura no formato `AAAAMM`
dVencFat	string	Data de vencimento no formato `AAAA-MM-DD`
codBarras	string	Código de barras da fatura (somente dígitos, 1–48)

* Campo obrigatório. ⚠ No destinatário, pelo menos um de CNPJ, CPF ou idOutros é obrigatório. Valores monetários e alíquotas são enviados como string com ponto decimal (ex.: "99.90").

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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 situação da NFCom

Consulta a situação atual da NFCom no ambiente nacional (SVRS) a partir da chave de acesso.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
chNFCom *	string	Chave de acesso da NFCom (44 dígitos)

* Campo obrigatório.

POST/api/nfcom/cancel

Cancelar NFCom

Cancela uma NFCom autorizada (evento 110111). Requer que a NFCom tenha sido autorizada (possua protocolo) e ainda não esteja cancelada.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
chNFCom *	string	Chave de acesso da NFCom (44 dígitos)
xJust *	string	Justificativa do cancelamento (mínimo 15 caracteres por exigência Fisco)
nProt *	string	Protocolo de autorização da NFCom (16 dígitos)

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/nfcom/cancel" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "chNFCom": "35260712345678000199620010000000011012345675",
          "xJust": "Cancelamento por erro no faturamento do assinante",
          "nProt": "353260000123456"
        }

        {
          "success": true,
          "message": "NFCom cancelada",
          "data": {
            "cStat": "135",
            "xMotivo": "Evento registrado e vinculado a NFCom",
            "nProt": "353260000123457"
          }
        }

POST/api/nfcom/pdf

Obter PDF da NFCom

Retorna a URL do DANFE-COM — a representação em PDF da NFCom (conta do assinante), conforme o MOC Anexo II. O PDF é gerado automaticamente na autorização; quando ainda não existe no armazenamento, é gerado sob demanda a partir do XML.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
chNFCom *	string	Chave de acesso da NFCom (44 dígitos)

* Campo obrigatório.

GET/api/nfcom/get_list

Listar NFCom (com paginação)

Lista as NFCom da empresa com paginação. Parâmetros passados via query string (não no body).

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5 (path inclui a query string)
timestamp	string	Unix timestamp em segundos

Query string

Parâmetro	Tipo	Descrição
page *	int	Número da página (≥ 1)
page_size *	int	Tamanho da página (1–50)

* Campo obrigatório.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os 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
          }
        }