TF FISCAL - Brazilian Invoice API

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

The TF FISCAL API allows integration with the Brazilian electronic invoice (NF-e) system. Currently supports issuing invoices for products throughout Brazil.

System Flow

Input Data

Customer Information (buyer)
Product Information
Tax Information
Transport Information

Processing

Data validation
Tax calculation
NF-e XML generation
SEFAZ authorization

Output

Invoice XML
Invoice PDF
DANFE (Auxiliary Document)
Authorization status

Authentication

All requests must include the following headers:

Parameter	Type	Required	Description
Content-Type	string	Yes	application/json;charset=utf-8
sign	string	Yes	Digital signature of the request
timestamp	string	Yes	UTC timestamp of the request
token	string	Yes	Authentication token

Note: To create a company and get company list, use the distributor token (b2b_token).

Signature Algorithm (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();
    }
}

Available Endpoints

Endpoint	Method	Functionality
`/api/company/create`	POST	Create company
`/api/company/get_detail`	GET	Consult company
`/api/company/edit`	POST	Edit company
`/api/company/get_list`	GET	List companies
`/api/category/get_list`	GET	List categories
`/api/invoice/create`	POST	Create invoice
`/api/invoice/get_list`	GET	List invoices
`/api/invoice/get_detail`	GET	Consult invoice
`/api/invoice/refresh`	POST	Update invoice status
`/api/invoice/cancel`	POST	Cancel invoice
`/api/invoice/invalid`	POST	Invalidate invoice

Tax Parameters

Tax parameters are essential for the correct fiscal classification of operations.

ICMS Parameters

11.1 Taxation Scenario

padrao Standard (applicable to all scenarios, except ICMS)

saida_fora_estado Sale outside the state (interstate)

saida_dentro_estado Sale within the state (intrastate)

entrada_fora_estado Purchase from outside the state

entrada_dentro_estado Purchase within the state

11.2 Tax Situation

Value	Description
00	Entry with credit recovery
01	Entry taxed at zero rate
02	Exempt entry
03	Non-taxed entry
04	Immune entry
05	Entry with suspension
49	Other entries
01	Taxable Operation - Tax Base = Operation Value Normal Rate
02	Taxable Operation - Tax Base = Operation Value (Differentiated rate)
03	Taxable Operation - Tax Base = Quantity Sold X Rate per Product Unit
04	Taxable Operation - Monophasic Taxation - (Zero Rate)
05	Taxable Operation - (Tax Substitution)
06	Taxable Operation (Zero Rate)
07	Contribution Exempt Operation

11.3 Person Type

fisica Individual

juridica Legal Entity

PIS/COFINS Parameters

12.1 Taxation Scenario

padrao Standard (applicable to all scenarios)

saida_fora_estado Sale outside the state

saida_dentro_estado Sale within the state

entrada_fora_estado Purchase from outside the state

entrada_dentro_estado Purchase within the state

12.2 Tax Situation - PIS/COFINS

Value	Description
71	Acquisition Operation with Exemption
72	Acquisition Operation with Suspension
73	Acquisition Operation at Zero Rate
74	Acquisition Operation without Contribution Incidence
75	Acquisition Operation by Tax Substitution
98	Other Entry Operations
99	Other Operations

12.3 Person Type

fisica Individual

juridica Legal Entity

Payment Parameters

Configuration of payment methods and card information for the invoice.

13. Payment Indicator

Value	Description
0	Cash
1	Installment

14. Payment Method

Value	Description
01	Cash
02	Check
03	Credit Card
04	Debit Card
05	Store Card
10	Food Voucher
11	Meal Voucher
12	Gift Voucher

15. Card Information

Note: Fill only when payment_method is 03 (Credit Card) or 04 (Debit Card).

15.1 Integration Type

Value	Description	Explanation
1	Payment integrated with company automation system	Like TEF or integrated payment gateway
2	Payment not integrated with company automation system	Independent POS, without automatic synchronization

15.2 Brand Code

Value	Brand
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	Others

XML Troubleshooting

Rejection 225 - XML Schema Failure

Scenario: When you try to cancel, download XML, inutilize number, or make recipient manifestation of an NF-e that was not successfully registered in SEFAZ database.

1

Check NF-e Status

Confirm if the NF-e was successfully authorized (status "Authorized") using the status query functionality.

2

Reissue the NF-e

If not authorized, try to reissue the NF-e (re-do the issuance).

3

Inutilize Number

If the invoice number was not used and subsequent invoices were already authorized, consider inutilizing the invoice number.

How to Identify the Specific Error

When the error is "schema failure", it means some information in the XML is not in accordance with SEFAZ valid layout. In the path indicated in red, it will always indicate which XML TAG is invalid.

Error Example

Schema and Business Rules Validation Result:
- XML Opinion: No errors found
- Message Type: NF-e Document
- XML Schema: 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
  Path: NF-e[1]/infNFe[1]/det[1]/prod[1]/NCM

Validation Tools

SEFAZ Online Validation

Use SEFAZ official validator to identify XML problems:

URL: https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx

1

Copy XML Content

Access the system and copy all XML file content.

2

Paste in Validator

Paste XML content in validator appropriate field.

3

Analyze Results

Check specific errors pointed by validator.

Common Problems

Recipient address incomplete or with abnormal data (special symbols)
Incorrect product tax information (invalid NCM, wrong tax classifications)
Incorrect value formatting (points, commas, decimal places)
Missing mandatory fields

Certificate Information

Certificate Remaining Days

It's essential to monitor digital certificate validity. Expired certificates cause NF-e rejection.

Recommendations

Renew certificate at least 30 days before expiration
Keep certificate and password backup in safe place
Test new certificate before current expiration
Configure alerts for certificate expiration

Validity Verification

To verify certificate remaining days:

Windows

1. Open Internet Explorer
2. Go to Tools → Internet Options → Content → Certificates
3. Select your certificate and click "View"
4. Check validity date in "General" tab

Select Language