NFS-e Service Invoices · TF Fiscal API

Note

NFS-e - Electronic Service Invoice

The NFS-e API allows issuing, canceling and querying Electronic Service Invoices. The system automatically detects the company's municipality and routes to the correct API:

Sao Paulo (SP) - Issuance via Nota Fiscal Paulistana (SOAP)
Other municipalities - Issuance via National API (ADN/SEFIN)

The integrator does not need to worry about which API to use - just send the data and the system routes automatically by the IBGE code of the municipality registered in the company.

Endpoint	Method	Description
`/api/nfse/create`	POST	Issue NFS-e
`/api/nfse/cancel`	POST	Cancel NFS-e
`/api/nfse/get_danfse`	POST	Get DANFSE (PDF)
`/api/nfse/get_xml`	POST	Download XML

POST/api/nfs/company/create

Register NFS-e company

Registers (or updates) a company for NFS-e issuance. If the CNPJ already exists for the user, only the NFS-e fields and certificate are updated; otherwise a new company is created and a dedicated token is returned. Note the path: /api/nfs/... (no "e"), different from the other NFS-e endpoints.

Required headers

Header	Type	Description
token	string	Integrator B2B token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
cnpj *	string	Company CNPJ (digits only)
name *	string	Corporate name
cep *	string	Postal code (digits only)
address *	string	Street
house_number *	string	Address number
town *	string	Neighborhood
city *	string	City
state *	string	State (2 digits, e.g. "SP")
cert_content *	string	Contents of the A1 certificate file (.pfx/.p12), Base64-encoded
cert_file	string	Deprecated — rejected from 2026-09-01. Certificate HTTPS URL
cert_pwd *	string	Digital certificate password
im *	string	Municipal registration (Inscrição Municipal)
codigo_municipio_nfse *	string	IBGE code of the issuing municipality
codigo_servico_nfse *	string	Default service code (LC 116)
alias	string	Trade name
ie	string	State registration
invoice_type	string	Tax regime
unit	string	Unit / branch
email	string	Contact email
telefone	string	Phone
complemento	string	Address complement
cnae_nfse	string	Default activity CNAE
serie_nfse	int	Initial NFS-e series
number_nfse	int	Initial NFS-e number
regime_especial_tributacao	int	Special tax regime code
optante_simples_nacional	bool	Opting in to Simples Nacional

* Required field.

Note: The returned token must be used in the other NFS-e calls (/api/nfse/create, /cancel, /get_danfse, /get_xml). If the company already exists, the message will be "Empresa atualizada para NFS-e" and the returned token is the existing token.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

Issue NFS-e

Required Headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Main Fields

Field	Type	Description
ambiente	string	`"1"` = Production, `"2"` = Staging
id	string	External reference ID (optional)
descricao_servico	string	Service description (required)
valor_servico	decimal	Total service value in R$ (required)
aliquota_iss	decimal	ISS tax rate in % (e.g.: 2.90)
iss_retido	boolean	`false` = Not withheld, `true` = Withheld by payer
valor_iss	decimal	ISS value override. If greater than 0, overrides the automatic calculation (base_calculo x aliquota_iss div 100). Default: calculated automatically
codigo_servico	string	Service code. If empty, uses company default
cnae	string	CNAE. If empty, uses company default
tomador	object	Service payer data (required)

Payer Fields

Field	Type	Description
cnpj	string	Payer CNPJ (numbers only)
cpf	string	Payer CPF (use cnpj OR cpf)
name	string	Name/Company name (required)
email	string	Payer email
telefone	string	Phone
cep	string	Zip code (required)
endereco	string	Street address (required)
numero	string	Number (required)
complemento	string	Address complement
bairro	string	Neighborhood (required)
city	string	City
uf	string	State (2 digits)
codigo_municipio	string	IBGE municipality code

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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

Cancel NFS-e

Required Headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Fields

Field	Type	Description
chave	string	NFS-e verification code (required)
motivo	string	Cancellation reason (required; for the National standard it must be 15 to 255 characters long)
c_motivo	string	Cancellation justification code (optional, National standard): "1" = Issuance error (default), "2" = Service not provided, "9" = Other

POST/api/nfse/get_danfse

Get NFS-e PDF

Required Headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Fields

Field	Type	Description
chave	string	NFS-e verification code (required)

Note: For Paulistana (SP), returns the direct PDF URL from the city hall. For National API, returns the PDF in base64.

POST/api/nfse/get_xml

Download NFS-e XML

Required Headers

Header	Type	Description
token	string	Company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Fields

Field	Type	Description
chave	string	NFS-e verification code (required)

dpsXml: Link (OSS URL) to the XML sent to the city hall/ADN. nfseXml: Link to the return XML with the issuance result. The XMLs are uploaded to OSS on the first request and the URL is cached.

GET/api/nfse/get_list

List NFS-e (paginated)

Lists the company's NFS-e with pagination. Parameters are passed via query string (not in the body). The time filter is optional, but if used, both start_create_time and end_create_time are required.

Required headers

Header	Type	Description
token	string	Issuing company token
sign	string	MD5 signature (path includes the query string)
timestamp	string	Unix timestamp in seconds

Query string

Parameter	Type	Description
page *	int	Page number (≥ 1)
page_size *	int	Page size (1–50)
start_create_time	long	Unix timestamp in milliseconds — start (requires `end_create_time`)
end_create_time	long	Unix timestamp in milliseconds — end
status	string	Filter by status. Values: `"autorizada"`, `"cancelada"`, `"pendente"`, `"rejeitada"`

* Required field.

# sign = md5(token + path + body + timestamp)
# Template generated from the endpoint path; replace the 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
          }
        }