TF FISCAL - API de Nota Fiscal Brasileira

URL Base: https://api.tffiscal.com

A API TF FISCAL permite a integração com o sistema de notas fiscais eletrônicas (NF-e) do Brasil. Atualmente suporta emissão de notas fiscais para produtos em todo o território brasileiro.

Fluxo do Sistema

Dados de Entrada
  • Informações do Cliente (comprador)
  • Informações dos Produtos
  • Informações Fiscais (impostos)
  • Informações de Transporte
Processamento
  • Validação dos dados
  • Cálculo de impostos
  • Geração do XML da NF-e
  • Autorização na SEFAZ
Saída
  • XML da nota fiscal
  • PDF da nota fiscal
  • DANFE (Documento Auxiliar)
  • Status de autorização

Autenticação

Todas as requisições devem incluir os seguintes cabeçalhos:

Parâmetro Tipo Obrigatório Descrição
Content-Type string Sim application/json;charset=utf-8
sign string Sim Assinatura digital da requisição
timestamp string Sim Timestamp UTC da requisição
token string Sim Token de autenticação

Observação: Para criar empresa e obter lista de empresas, use o token do distribuidor (b2b_token).

Algoritmo de Assinatura (SIGN) 

static string GetSign(string AppKey, string Path, string bodyString, string timestamp)
{
    string input = AppKey + Path + bodyString + timestamp;
    using (MD5 md5 = MD5.Create())
    {
        byte[] inputBytes = Encoding.UTF8.GetBytes(input);
        byte[] hashBytes = md5.ComputeHash(inputBytes);
        
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < hashBytes.Length; i++)
        {
            sb.Append(hashBytes[i].ToString("x2"));
        }
        return sb.ToString();
    }
}

Endpoints Disponíveis

Endpoint Método Funcionalidade
/api/company/create POST Criar empresa
/api/company/get_detail GET Consultar empresa
/api/company/edit POST Editar empresa
/api/company/get_list GET Listar empresas
/api/category/get_list GET Listar categorias
/api/invoice/create POST Criar nota fiscal
/api/invoice/get_list GET Listar notas fiscais
/api/invoice/get_detail GET Consultar nota fiscal
/api/invoice/refresh POST Atualizar status da nota
/api/invoice/cancel POST Cancelar nota fiscal
/api/invoice/invalid POST Invalidar nota fiscal

Parâmetros Tributários

Os parâmetros tributários são essenciais para a correta classificação fiscal das operações.

Parâmetros ICMS

11.1 Cenário de Tributação

padrao Padrão (aplicável a todos os cenários, exceto ICMS)
saida_fora_estado Venda para fora do estado (interestadual)
saida_dentro_estado Venda dentro do estado (intraestadual)
entrada_fora_estado Compra de fora do estado
entrada_dentro_estado Compra dentro do estado

11.2 Situação Tributária

Valor Descrição
00 Entrada com recuperação de crédito
01 Entrada tributada com alíquota zero
02 Entrada isenta
03 Entrada não-tributada
04 Entrada imune
05 Entrada com suspensão
49 Outras entradas
01 Operação Tributável - Base de Cálculo = Valor da Operação Alíquota Normal
02 Operação Tributável - Base de Cálculo = Valor da Operação (Alíquota diferenciada)
03 Operação Tributável - Base de Cálculo = Quantidade Vendida X Alíquota por Unidade de Produto
04 Operação Tributável - Tributação Monofásica - (Alíquota Zero)
05 Operação Tributável - (Substituição Tributária)
06 Operação Tributável (Alíquota Zero)
07 Operação Isenta de Contribuição

11.3 Tipo de Pessoa

fisica Pessoa Física
juridica Pessoa Jurídica

Parâmetros PIS/COFINS

12.1 Cenário de Tributação

padrao Padrão (aplicável a todos os cenários)
saida_fora_estado Venda para fora do estado
saida_dentro_estado Venda dentro do estado
entrada_fora_estado Compra de fora do estado
entrada_dentro_estado Compra dentro do estado

12.2 Situação Tributária - PIS/COFINS

Valor Descrição
71 Operação de Aquisição com Isenção
72 Operação de Aquisição com Suspensão
73 Operação de Aquisição a Alíquota Zero
74 Operação de Aquisição sem Incidência da Contribuição
75 Operação de Aquisição por Substituição Tributária
98 Outras Operações de Entrada
99 Outras Operações

12.3 Tipo de Pessoa

fisica Pessoa Física
juridica Pessoa Jurídica

Parâmetros de Pagamento

Configuração dos métodos de pagamento e informações de cartão para a nota fiscal.

13. Indicador de Pagamento

Valor Descrição
0 À vista
1 À prazo

14. Método de Pagamento

Valor Descrição
01 Dinheiro
02 Cheque
03 Cartão de Crédito
04 Cartão de Débito
05 Cartão da Loja
10 Vale Alimentação
11 Vale Refeição
12 Vale Presente

15. Informações do Cartão

Nota: Preencher apenas quando payment_method for 03 (Cartão de Crédito) ou 04 (Cartão de Débito).

15.1 Tipo de Integração

Valor Descrição Explicação
1 Pagamento integrado com o sistema de automação da empresa Como TEF ou gateway de pagamento integrado
2 Pagamento não integrado com o sistema de automação da empresa POS independente, sem sincronização automática

15.2 Código da Bandeira

Valor Bandeira
01 Visa
02 Mastercard
03 American Express
04 Sorocred
05 Diners Club
06 Elo
07 Hipercard
08 Aura
09 Cabal
10 Alelo
11 Banes Card
12 CalCard
13 Credz
14 Discover
15 GoodCard
16 GreenCard
17 Hiper
18 JCB
19 Mais
20 MaxVan
21 Policard
22 RedeCompras
23 Sodexo
24 ValeCard
25 Vercoheque
26 VR
27 Ticket
99 Outros

Solução de Problemas com XML

Rejeição 225 - Falha no Schema XML

Cenário: Quando você tenta cancelar, baixar XML, inutilizar número, ou fazer manifestação do destinatário de uma NF-e que não foi registrada com sucesso na base de dados da SEFAZ.

1
Verificar Status da NF-e

Confirme se a NF-e foi autorizada com sucesso (status "Autorizada") usando a funcionalidade de consulta de status.

2
Reemitir a NF-e

Se não foi autorizada, tente reemitir a NF-e (refazer a emissão).

3
Inutilizar Número

Se o número da nota não foi utilizado e notas subsequentes já foram autorizadas, considere inutilizar o número da nota.

Como Identificar o Erro Específico

Quando o erro é "falha no schema", significa que algumas informações no XML não estão de acordo com o layout válido da SEFAZ. No caminho indicado em vermelho, ele sempre indicará qual XML TAG é inválida.

Exemplo de Erro 
Resultado da Validação do Schema e de Regras de Negócio:
- Parecer XML: Nenhum erro encontrado
- Tipo de Mensagem: Documento de NF-e
- Schema XML: The http://www.portalfiscal.inf.br/nfe element is invalid
  The value '$86.300' is invalid according to its datatype 'String'
  The Pattern constraint failed
  Caminho: NF-e[1]/infNFe[1]/det[1]/prod[1]/NCM

Ferramentas de Validação

Validação Online da SEFAZ

Use o validador oficial da SEFAZ para identificar problemas no XML:

URL: https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx
1
Copiar Conteúdo do XML

Acesse o sistema e copie todo o conteúdo do arquivo XML.

2
Colar no Validador

Cole o conteúdo XML no campo apropriado do validador.

3
Analisar Resultados

Verifique os erros específicos apontados pelo validador.

Problemas Comuns

  • Endereço do destinatário incompleto ou com dados anormais (símbolos especiais)
  • Informações fiscais do produto incorretas (NCM inválido, classificações tributárias erradas)
  • Formatação de valores incorreta (pontos, vírgulas, casas decimais)
  • Campos obrigatórios ausentes

Informações do Certificado

Dias Restantes do Certificado

É essencial monitorar a validade do certificado digital. Certificados expirados causam rejeição das NF-e.

Recomendações

  • Renove o certificado pelo menos 30 dias antes da expiração
  • Mantenha backup do certificado e senha em local seguro
  • Teste o novo certificado antes da expiração do atual
  • Configure alertas para expiração do certificado

Verificação da Validade

Para verificar os dias restantes do certificado:

Windows 
1. Abra o Internet Explorer
2. Vá em Ferramentas → Opções da Internet → Conteúdo → Certificados
3. Selecione seu certificado e clique em "Exibir"
4. Verifique a data de validade na aba "Geral"