NFS-e · TF Fiscal API

Nota

NFS-e - Factura Electronica de Servicios

La API de NFS-e permite emitir, cancelar y consultar Facturas Electronicas de Servicio. El sistema detecta automaticamente el municipio de la empresa y enruta a la API correcta:

Sao Paulo (SP) - Emision via Nota Fiscal Paulistana (SOAP)
Otros municipios - Emision via API Nacional (ADN/SEFIN)

El integrador no necesita preocuparse por cual API usar - solo envie los datos y el sistema enruta automaticamente por el codigo IBGE del municipio registrado en la empresa.

Endpoint	Metodo	Descripcion
`/api/nfse/create`	POST	Emitir NFS-e
`/api/nfse/cancel`	POST	Cancelar NFS-e
`/api/nfse/get_danfse`	POST	Obtener DANFSE (PDF)
`/api/nfse/get_xml`	POST	Descargar XML

POST/api/nfs/company/create

Registrar empresa NFS-e

Registra (o actualiza) una empresa para emisión de NFS-e. Si el CNPJ ya existe para el usuario, solo los campos NFS-e y el certificado se actualizan; de lo contrario, se crea una nueva empresa y se devuelve un token dedicado. Atención al path: /api/nfs/... (sin la "e"), distinto de los demás endpoints NFS-e.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token B2B del integrador
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
cnpj *	string	CNPJ de la empresa (solo dígitos)
name *	string	Razón social
cep *	string	Código postal (solo dígitos)
address *	string	Dirección
house_number *	string	Número del domicilio
town *	string	Barrio
city *	string	Ciudad
state *	string	UF (2 dígitos, ej.: "SP")
cert_content *	string	Contenido del archivo del certificado A1 (.pfx/.p12) en Base64
cert_file	string	Obsoleto — rechazado a partir del 2026-09-01. URL HTTPS del certificado
cert_pwd *	string	Contraseña del certificado digital
im *	string	Inscripción Municipal
codigo_municipio_nfse *	string	Código IBGE del municipio emisor
codigo_servico_nfse *	string	Código de servicio por defecto (LC 116)
alias	string	Nombre comercial
ie	string	Inscripción estatal
invoice_type	string	Régimen tributario
unit	string	Unidad / sucursal
email	string	E-mail de contacto
telefone	string	Teléfono
complemento	string	Complemento del domicilio
cnae_nfse	string	CNAE de la actividad por defecto
serie_nfse	int	Serie inicial de la NFS-e
number_nfse	int	Número inicial de la NFS-e
regime_especial_tributacao	int	Código del régimen especial de tributación
optante_simples_nacional	bool	Optante por Simples Nacional

* Campo obligatorio.

Nota: El token devuelto debe usarse en las demás llamadas NFS-e (/api/nfse/create, /cancel, /get_danfse, /get_xml). Si la empresa ya existe, el mensaje será "Empresa atualizada para NFS-e" y el token devuelto es el existente.

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

        {
          "cnpj": "43649380000100",
          "name": "EMPRESA EXEMPLO LTDA",
          "alias": "Exemplo",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contato@empresa.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "Rua Exemplo",
          "house_number": "86",
          "complemento": "Andar 2",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_content": "MIIOkAIBAzCC...(Base64)",
          "cert_pwd": "senha-do-certificado",
          "im": "12345678",
          "codigo_municipio_nfse": "3550308",
          "codigo_servico_nfse": "07498",
          "cnae_nfse": "6201501",
          "serie_nfse": 1,
          "number_nfse": 1,
          "regime_especial_tributacao": 0,
          "optante_simples_nacional": true
        }

        {
          "success": true,
          "message": "Empresa cadastrada para NFS-e",
          "data": {
            "company_id": 12345,
            "token": "token-dedicado-da-empresa"
          }
        }

POST/api/nfse/create

Emitir NFS-e

Headers obligatorios

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

Campos Principales

Campo	Tipo	Descripcion
ambiente	string	`"1"` = Produccion, `"2"` = Homologacion
id	string	ID de referencia externa (opcional)
descricao_servico	string	Descripcion del servicio prestado (obligatorio)
valor_servico	decimal	Valor total del servicio en R$ (obligatorio)
aliquota_iss	decimal	Alicuota ISS en % (ej: 2.90)
iss_retido	boolean	`false` = No retenido, `true` = Retenido por el tomador
valor_iss	decimal	Override del valor del ISS. Si mayor que 0, sustituye el calculo automatico (base_calculo x aliquota_iss div 100). Default: calculado automaticamente
codigo_servico	string	Codigo del servicio. Si vacio, usa el predeterminado de la empresa
cnae	string	CNAE. Si vacio, usa el predeterminado de la empresa
tomador	object	Datos del tomador del servicio (obligatorio)

Tomador - Campos

Campo	Tipo	Descripcion
cnpj	string	CNPJ del tomador (solo numeros)
cpf	string	CPF del tomador (usar cnpj O cpf)
name	string	Nombre/Razon Social (obligatorio)
email	string	Email del tomador
telefone	string	Telefono
cep	string	Codigo postal (obligatorio)
endereco	string	Direccion (obligatorio)
numero	string	Numero (obligatorio)
complemento	string	Complemento
bairro	string	Barrio (obligatorio)
city	string	Ciudad
uf	string	Estado (2 digitos)
codigo_municipio	string	Codigo IBGE del municipio

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

        {
          "ambiente": "1",
          "id": "REF-001",
          "descricao_servico": "Desenvolvimento de sistemas",
          "valor_servico": 10000.00,
          "aliquota_iss": 2.90,
          "iss_retido": false,
          "codigo_servico": "",
          "cnae": "",
          "valor_deducoes": 0,
          "desconto_incondicionado": 0,
          "desconto_condicionado": 0,
          "valor_iss": 0,
          "valor_pis": 0,
          "valor_cofins": 0,
          "valor_inss": 0,
          "valor_ir": 0,
          "valor_csll": 0,
          "tomador": {
            "cnpj": "43649380000100",
            "cpf": "",
            "name": "EMPRESA TOMADORA LTDA",
            "email": "contato@empresa.com",
            "telefone": "11999999999",
            "inscricao_municipal": "",
            "cep": "03027020",
            "endereco": "Rua Exemplo",
            "numero": "86",
            "complemento": "Andar 2",
            "bairro": "Centro",
            "city": "Sao Paulo",
            "uf": "SP",
            "codigo_municipio": "3550308"
          }
        }

        {
          "success": true,
          "data": {
            "_id": "661234abcdef...",
            "uuid": "guid-unico",
            "status": "autorizada",
            "nfse": "48",
            "serie": 1,
            "chave": "Z685RI9C",
            "codigoVerificacao": "Z685RI9C",
            "modelo": "nfse",
            "tipoEmissao": "paulistana",
            "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
          }
        }

POST/api/nfse/cancel

Cancelar NFS-e

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Campos

Campo	Tipo	Descripcion
chave	string	Codigo de verificacion de la NFS-e (obligatorio)
motivo	string	Motivo de la cancelación (obligatorio; en el estándar Nacional debe tener de 15 a 255 caracteres)
c_motivo	string	Código de justificación de la cancelación (opcional, estándar Nacional): "1" = Error en la emisión (predeterminado), "2" = Servicio no prestado, "9" = Otros

POST/api/nfse/get_danfse

Obtener PDF de la NFS-e

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Campos

Campo	Tipo	Descripcion
chave	string	Codigo de verificacion de la NFS-e (obligatorio)

Nota: Para Paulistana (SP), retorna la URL directa del PDF de la prefectura. Para API Nacional, retorna el PDF en base64.

POST/api/nfse/get_xml

Descargar XML de NFS-e

Headers obligatorios

Header	Tipo	Descripcion
token	string	Token de la empresa
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Campos

Campo	Tipo	Descripcion
chave	string	Codigo de verificacion de la NFS-e (obligatorio)

dpsXml: Enlace (URL en OSS) al XML enviado a la prefectura/ADN. nfseXml: Enlace al XML de retorno con el resultado de la emision. Los XML se suben al OSS en la primera consulta y la URL queda en cache.

GET/api/nfse/get_list

Listar NFS-e (paginado)

Lista las NFS-e de la empresa con paginación. Los parámetros se pasan por query string (no en el body). El filtro de tiempo es opcional, pero si se envía requiere tanto start_create_time como end_create_time.

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)
start_create_time	long	Unix timestamp en milisegundos — inicio (requiere `end_create_time`)
end_create_time	long	Unix timestamp en milisegundos — fin
status	string	Filtrar por estado. Valores: `"autorizada"`, `"cancelada"`, `"pendente"`, `"rejeitada"`

* Campo obligatorio.

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

GET /api/nfse/get_list?page=1&page_size=20&status=autorizada

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "31250112345678000190000000000012345678901234",
                "codigo_verificacao": "ABCD-1234",
                "serie": 1,
                "number": 1,
                "status": "autorizada",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }