NFS-e · TF Fiscal API

Nota

NFS-e - Nota Fiscal de Servicos Eletronica

A API de NFS-e permite emitir, cancelar e consultar Notas Fiscais de Servico Eletronicas. O sistema detecta automaticamente o municipio da empresa e roteia para a API correta:

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

O integrador nao precisa se preocupar com qual API usar - basta enviar os dados e o sistema faz o roteamento automaticamente pelo codigo IBGE do municipio cadastrado na empresa.

Endpoint	Metodo	Descricao
`/api/nfse/create`	POST	Emitir NFS-e
`/api/nfse/cancel`	POST	Cancelar NFS-e
`/api/nfse/get_danfse`	POST	Obter DANFSE (PDF)
`/api/nfse/get_xml`	POST	Download do XML

POST/api/nfs/company/create

Cadastrar empresa NFS-e

Cadastra (ou atualiza) uma empresa para emissão de NFS-e. Se o CNPJ já existir para o usuário, apenas os campos NFS-e e o certificado são atualizados; caso contrário, uma nova empresa é criada e um token dedicado é retornado. Atenção ao path: /api/nfs/... (sem o "e"), diferente dos demais endpoints NFS-e.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token B2B do integrador
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
cnpj *	string	CNPJ da empresa (apenas dígitos)
name *	string	Razão social
cep *	string	CEP (apenas dígitos)
address *	string	Logradouro
house_number *	string	Número do endereço
town *	string	Bairro
city *	string	Cidade
state *	string	UF (2 dígitos, ex.: "SP")
cert_content *	string	Conteúdo do arquivo do certificado A1 (.pfx/.p12) em Base64
cert_file	string	Descontinuado — rejeitado a partir de 2026-09-01. URL HTTPS do certificado
cert_pwd *	string	Senha do certificado digital
im *	string	Inscrição Municipal
codigo_municipio_nfse *	string	Código IBGE do município emissor
codigo_servico_nfse *	string	Código do serviço padrão (LC 116)
alias	string	Nome fantasia
ie	string	Inscrição estadual
invoice_type	string	Regime tributário
unit	string	Unidade / filial
email	string	E-mail de contato
telefone	string	Telefone
complemento	string	Complemento do endereço
cnae_nfse	string	CNAE da atividade padrão
serie_nfse	int	Série inicial da NFS-e
number_nfse	int	Número inicial da NFS-e
regime_especial_tributacao	int	Código do regime especial de tributação
optante_simples_nacional	bool	Optante pelo Simples Nacional

* Campo obrigatório.

Nota: O token retornado deve ser usado nas demais chamadas NFS-e (/api/nfse/create, /cancel, /get_danfse, /get_xml). Se a empresa já existir, a mensagem será "Empresa atualizada para NFS-e" e o token retornado é o token existente.

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

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

Campos Principais

Campo	Tipo	Descricao
ambiente	string	`"1"` = Producao, `"2"` = Homologacao
id	string	ID de referencia externa (opcional)
descricao_servico	string	Descricao do servico prestado (obrigatorio)
valor_servico	decimal	Valor total do servico em R$ (obrigatorio)
aliquota_iss	decimal	Aliquota ISS em % (ex: 2.90)
iss_retido	boolean	`false` = Nao retido, `true` = Retido pelo tomador
valor_iss	decimal	Override do valor do ISS. Se maior que 0, sobrepoe o calculo automatico (base_calculo x aliquota_iss div 100). Default: calculado automaticamente
codigo_servico	string	Codigo do servico. Se vazio, usa o padrao da empresa
cnae	string	CNAE. Se vazio, usa o padrao da empresa
tomador	object	Dados do tomador do servico (obrigatorio)

Tomador - Campos

Campo	Tipo	Descricao
cnpj	string	CNPJ do tomador (somente numeros)
cpf	string	CPF do tomador (usar cnpj OU cpf)
name	string	Nome/Razao Social (obrigatorio)
email	string	Email do tomador
telefone	string	Telefone
cep	string	CEP (obrigatorio)
endereco	string	Logradouro (obrigatorio)
numero	string	Numero (obrigatorio)
complemento	string	Complemento
bairro	string	Bairro (obrigatorio)
city	string	Cidade
uf	string	UF (2 digitos)
codigo_municipio	string	Codigo IBGE do municipio

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

Header	Tipo	Descricao
token	string	Token da empresa
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Campos

Campo	Tipo	Descricao
chave	string	Codigo de verificacao da NFS-e (obrigatorio)
motivo	string	Motivo do cancelamento (obrigatório; no padrão Nacional deve ter de 15 a 255 caracteres)
c_motivo	string	Código de justificativa do cancelamento (opcional, padrão Nacional): "1" = Erro na emissão (padrão), "2" = Serviço não prestado, "9" = Outros

POST/api/nfse/get_danfse

Obter PDF da NFS-e

Headers obrigatorios

Header	Tipo	Descricao
token	string	Token da empresa
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Campos

Campo	Tipo	Descricao
chave	string	Codigo de verificacao da NFS-e (obrigatorio)

Nota: Para Paulistana (SP), retorna a URL direta do PDF da prefeitura. Para API Nacional, retorna o PDF em base64.

POST/api/nfse/get_xml

Download XML da NFS-e

Headers obrigatorios

Header	Tipo	Descricao
token	string	Token da empresa
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Campos

Campo	Tipo	Descricao
chave	string	Codigo de verificacao da NFS-e (obrigatorio)

dpsXml: Link (URL no OSS) do XML enviado para a prefeitura/ADN. nfseXml: Link do XML de retorno com o resultado da emissao. Os XMLs sobem ao OSS na primeira consulta e a URL fica em cache.

GET/api/nfse/get_list

Listar NFS-e (com paginação)

Lista as NFS-e da empresa com paginação. Parâmetros passados via query string (não no body). O filtro de tempo é opcional, mas se enviado exige ambos start_create_time e end_create_time.

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)
start_create_time	long	Unix timestamp em milissegundos — início (exige `end_create_time`)
end_create_time	long	Unix timestamp em milissegundos — fim
status	string	Filtrar por status. Valores: `"autorizada"`, `"cancelada"`, `"pendente"`, `"rejeitada"`

* 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/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
          }
        }