REST API v2.5 SYSTEM OPERATIONAL

NFE API Documentation

Welcome to NFE API documentation. Complete API for issuing, consulting, and canceling Electronic Invoices (NF-e) in Brazil. Supports automatic tax calculation (ICMS, IPI, PIS/COFINS), XML generation, SEFAZ authorization, and integration with management systems.

list_alt

Important API Fields

Critical Field Interpretation

This section explains the most important fields of the NFE API that are essential for the correct functioning of invoice issuance.

⚠️ ATTENTION: Correct configuration of these fields is fundamental for valid invoice issuance. Always consult current tax legislation.

Field	Description	Possible Values	Importance
`invoice_type`	Company type (legal entity/individual)	`juridica`, `fisica`	High - Defines tax regime
`nature_of_operation`	Nature of operation (sale, return, etc.)	Ex: `SALE`, `RETURN`	High - Determines CFOP
`transaction_type`	Transaction type (input/output)	`INPUT`, `OUTPUT`	High - Directs fiscal flow
`model`	Invoice model	`nfe`, `nfce`	High - Document model
`issuance_type`	Issuance type (normal, contingency)	`NORMAL`, `CONTINGENCY`	Medium - Issuance mode
`ambiente`	Processing environment	`PRODUCTION`, `HOMOLOGATION`	High - Defines destination SEFAZ
`cliente`	Customer/buyer type	`CONSUMER`, `TAXPAYER`	High - Impacts taxes
`products.origem`	Product origin (national/imported)	`0` to `8`	High - Determines taxation
`products.indicador_total`	Whether product enters invoice total	`true`, `false`	Medium - For sample items

💡 TIP: For products, the origem field is critical: 0-National, 1-Foreign direct import, 2-Foreign acquired in domestic market, etc. Consult the complete table of merchandise origin.

sync_alt

Invoice Issuance Process Flow

Complete NF-e issuance diagram

Complete flow of electronic invoice issuance in Brazil, from company creation to final file generation.

business

1. Create Company

Create local company fiscal information in Brazil

send

2. Information Push

Order data (user, address, product taxes)

receipt

3. Issue Invoice

Process and send to SEFAZ authorization

assignment_returned

4. Return Result

Issuance status and NF-e data

description

5. Generate Files

XML and PDF of invoice

published_with_changes

Fiscal Verification

Validation with SEFAZ

check_circle

Success

error

Failure

Initial Setup

Data Processing

Fiscal Issuance

Positive Results

📊 Detailed Flow: The process follows a logical sequence: (1) Company configuration → (2) Receiving order data → (3) Processing and NF-e issuance → (4) Status return → (5) File generation. The decision point (Fiscal Verification) determines whether the issuance was authorized by SEFAZ.

flash_on

Endpoint Quick Reference

All NFE API endpoints

Complete overview of all available API endpoints. Use this table as a quick reference to navigate the documentation.

Base URL

https://api.tffiscal.com

Path	HTTP Method	Function
business Company Management
`/api/company/create`	POST	Create company
`/api/company/get_detail`	GET	Query company
`/api/company/edit`	POST	Modify company
`/api/company/get_list`	GET	List companies
`/api/company/v2/create`	POST	Create company (simplified)
`/api/company/get_cep_detail`	GET	CEP Lookup
`/api/company/get_export_invoice_month_files`	GET	Monthly exported files
category Category/Tax Management
`/api/category/get_list`	GET	List tax categories
`/api/category/create`	POST	Create tax category
`/api/category/get_detail`	GET	Query category details
`/api/category/edit`	POST	Edit tax category
`/api/category/delete`	POST	Delete tax category
receipt Invoice Management
`/api/invoice/create`	POST	Issue invoice
`/api/invoice/get_list`	GET	List invoices
`/api/invoice/get_detail`	GET	Query invoice details
`/api/invoice/refresh`	POST	Update invoice status
`/api/invoice/cancel`	POST	Cancel invoice
`/api/invoice/invalid`	POST	Invalidate invoice number
`/api/invoice/return`	POST	Invoice return
`/api/invoice/get_xml`	POST	Export invoice XML
receipt NFC-e (Consumer Invoice)
`/api/nfce/company/create`	POST	Register NFC-e company
`/api/nfce/company/update`	POST	Update NFC-e company
`/api/nfce/company/get`	POST	Query NFC-e company
`/api/nfce/create`	POST	Issue NFC-e
`/api/nfce/cancel`	POST	Cancel NFC-e
`/api/nfce/get_detail`	POST	Query NFC-e
`/api/nfce/get_danfe`	POST	Get NFC-e DANFE
`/api/nfce/get_list`	GET	List NFC-e (paginated)
description NFS-e (Service Invoice)
`/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 NFS-e XML
`/api/nfse/get_list`	GET	List NFS-e (paginated)
`/api/nfs/company/create`	POST	Register company for NFS-e issuance
receipt_long NF-e — Events and Queries
`/api/invoice/get_danfe`	POST	Get DANFE (PDF) of the NF-e
`/api/invoice/consultar_status`	POST	Consult NF-e/NFC-e status at SEFAZ
`/api/invoice/validar_cpf_cnpj`	POST	Validate CPF/CNPJ against the Receita Federal database
`/api/invoice/cce/send`	POST	Send Correction Letter (CC-e)
`/api/invoice/cce/get_list`	POST	List CC-e of an NF-e
`/api/invoice/cce/download_pdf`	POST	Download CC-e PDF
`/api/invoice/cce/download_xml`	POST	Download CC-e XML
mark_email_read NF-e — Manifestation and Received Documents
`/api/invoice/manifest`	POST	Send recipient manifestation event
`/api/invoice/manifest/list`	POST	List sent manifestations
`/api/invoice/manifest/get_xml`	POST	Get XML of a manifestation
`/api/invoice/received/sync`	POST	Sync received NF-es/events (DistDFe)
`/api/invoice/received/list`	POST	List received documents
`/api/invoice/received/get_xml`	POST	Get XML of a received document
`/api/invoice/received/get_sync_status`	POST	Check DistDFe sync state
category NFC-e — Fiscal Categories
`/api/nfce/category/create`	POST	Create NFC-e tax category
`/api/nfce/category/edit`	POST	Edit NFC-e tax category
`/api/nfce/category/delete`	POST	Delete NFC-e tax category
`/api/nfce/category/get_detail`	GET	Get NFC-e category details
`/api/nfce/category/get_list`	GET	List NFC-e tax categories
local_shipping MDF-e (Electronic Manifest of Fiscal Documents)
`/api/mdfe/create`	POST	Issue MDF-e
`/api/mdfe/consult`	POST	Consult MDF-e status
`/api/mdfe/cancel`	POST	Cancel MDF-e
`/api/mdfe/close`	POST	Close MDF-e
`/api/mdfe/get_list`	GET	List MDF-e (paginated)
inventory_2 DC-e (Electronic Content Declaration)
`/api/dce/create`	POST	Issue DC-e
`/api/dce/consult`	POST	Consult DC-e status
`/api/dce/cancel`	POST	Cancel DC-e
`/api/dce/pdf`	POST	Get DACE (PDF) of the DC-e
`/api/dce/get_list`	GET	List DC-e (paginated)
local_shipping CT-e (Electronic Bill of Lading)
`/api/cte/create`	POST	Issue CT-e
`/api/cte/cancel`	POST	Cancel CT-e
`/api/cte/cce`	POST	Correction Letter (CC-e)
`/api/cte/desacordo`	POST	Service Disagreement
`/api/cte/consult`	POST	Consult CT-e status
`/api/cte/inutilize`	POST	Void a numbering range
`/api/cte/get_list`	GET	List CT-e (paginated)
vpn_key SSO (Automatic Login)
`/api/sso/create_ticket`	POST	Generate automatic login link
`/api/sso/consume_ticket`	POST	Consume ticket and receive the session JWT
account_balance Accountant Management
`/api/accountant/get_info`	POST	Get information of the accountant linked to the company

📋 Important Notes:

All endpoints require authentication via headers: sign, timestamp, token
For creating company and listing companies, use distributor token (b2b_token)
Content-Type must always be application/json;charset=utf-8
Responses follow JSON standard with fields success, message and data

200

Success

Request processed successfully

400

Client Error

Invalid or missing data

500

Server Error

Internal server error

account_balance

NFE API

Brazilian Electronic Invoice (NF-e)

Complete API for issuing, consulting, and canceling Electronic Invoices (NF-e) in Brazil. Supports automatic tax calculation (ICMS, IPI, PIS/COFINS), XML generation, SEFAZ authorization, and integration with management systems. Currently supports invoice issuance for products throughout Brazilian territory.

Base URL (Production)

https://api.tffiscal.com/v1

Authentication

Headers: sign, timestamp, token

Requirements

Valid A1 Digital Certificate

sync_alt System Flow

input Input Data

Customer Information
Product Data
Fiscal Information
Transport Data

settings Processing

Data validation
Tax calculation
XML generation
SEFAZ authorization

download Output

Invoice XML
Invoice PDF
DANFE (Auxiliary Document)
Authorization status

Main Endpoints

POST /api/company/create

Registers an issuing company under a distributor (b2b) account. Use this endpoint when company data is already available. For automatic extraction from the digital certificate, use /api/company/v2/create.

Required headers

Header	Type	Description
token	string	Distributor token (b2b — the account must have `isb2b=true`)
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
Identification
cnpj *	string	Issuing company CNPJ
name *	string	Company name
ie *	string	State Registration (Inscrição Estadual)
invoice_type *	string	Tax regime (e.g., `"simples_nacional"`, `"normal"`)
unit *	string	Unit type
email	string	Company email
Address
cep *	string	ZIP code
address *	string	Street address
house_number *	string	Address number
town *	string	Neighborhood
city *	string	City
state *	string	UF (state abbreviation)
Digital certificate
cert_file *	string	HTTPS URL of the A1 digital certificate (.pfx or .p12)
cert_pwd *	string	Certificate password
Numbering and settings
serie *	int	NF-e series
number *	int	Initial number for numbering
Transport (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e series
number_mdfe	int	MDF-e starting number (where numbering begins)
serie_cte	int	CT-e series
number_cte	int	CT-e starting number (where numbering begins)
serie_dce	int	DC-e series
number_dce	int	DC-e starting number (where numbering begins)
is_create_category_template	boolean	Auto-create default tax categories. Default: `true`

* Required field.

Payload example

        {
          "cnpj": "12345678000199",
          "name": "Empresa Exemplo LTDA",
          "ie": "123456789",
          "invoice_type": "simples_nacional",
          "unit": "UN",
          "email": "contato@empresa.com",
          "cep": "01001000",
          "address": "Rua Exemplo",
          "house_number": "100",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://exemplo.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 1,
          "serie_mdfe": 2,
          "number_mdfe": 1,
          "serie_cte": 3,
          "number_cte": 1,
          "serie_dce": 4,
          "number_dce": 1
        }

Response

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/v2/create

Simplified version of /api/company/create: the API validates the digital certificate and automatically extracts company name, IE, address and other data via internal lookup. Only cnpj, cert_file and cert_pwd are required.

Required headers

Header	Type	Description
token	string	Distributor token (b2b — the account must have `isb2b=true`)
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
cnpj *	string	Issuing company CNPJ
cert_file *	string	HTTPS URL of the A1 digital certificate (.pfx or .p12)
cert_pwd *	string	Certificate password
is_create_category_template	boolean	Auto-create default tax categories. Default: `true`

* Required field.

Payload example

        {
          "cnpj": "12345678000199",
          "cert_file": "https://exemplo.com/cert.pfx",
          "cert_pwd": "senha_do_certificado"
        }

Response

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/edit

Edit company data

Updates issuing company data. Send only the fields you want to change — all except company_id are optional. CNPJ is immutable: sending it returns an error. When cep is updated, the system automatically resolves stateCode and ibge. When cert_file and cert_pwd come together, the certificate is validated before being saved.

The company is created with the NF-e configuration (via /api/company/create). To enable the other documents, complete the setup here: this endpoint also accepts the NFC-e, NFS-e, MDF-e, CT-e and DC-e fields (see the sections below). Send only the fields for the document(s) the company will issue.

Required headers

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

Body

Field	Type	Description
company_id *	string	ID of the company to edit
name	string	Company name
invoice_type	string	Tax regime
ie	string	State Registration
unit	string	Unit type
email	string	Email
cep	string	ZIP code (auto-updates `stateCode` and `ibge`)
address	string	Street address
house_number	string	Number
town	string	Neighborhood
city	string	City
state	string	UF
cert_file	string	HTTPS URL of the new certificate (.pfx or .p12). When sent with `cert_pwd`, it is validated before saving
cert_pwd	string	New certificate password
serie	int	New NF-e series
number	int	New initial number
alias	string	Trade name
telefone	string	Phone
complemento	string	Address complement
NFC-e
csc_id	string	CSC (Taxpayer Security Code) ID at SEFAZ
csc	string	CSC token (shared secret with SEFAZ)
serie_nfce	int	NFC-e series
number_nfce	int	Initial NFC-e number
NFS-e
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)
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
Transport (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e series
number_mdfe	int	MDF-e starting number (where numbering begins)
serie_cte	int	CT-e series
number_cte	int	CT-e starting number (where numbering begins)
serie_dce	int	DC-e series
number_dce	int	DC-e starting number (where numbering begins)

* Required field. Sending cnpj returns an error. All other fields are optional — send only the ones you want to change.

Payload example

        {
          "company_id": "comp_789012",
          "name": "Nova Razão Social LTDA",
          "email": "novo@empresa.com",
          "cep": "01310100"
        }

Example — enable NFC-e and CT-e for the company

        {
          "company_id": "comp_789012",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "serie_cte": 1,
          "number_cte": 1
        }

Response

        {
          "success": true
        }

GET /api/company/get_list

List distributor companies

Lists issuing companies tied to the distributor (b2b) account, with pagination. Parameters via query string.

Required headers

Header	Type	Description
token	string	Distributor token (b2b — the account must have `isb2b=true`)
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–20)

* Required field.

Call example

GET /api/company/get_list?page=1&page_size=10

Response

        {
          "success": true,
          "data": {
            "companys": [
              {
                "company_id": "comp_789012",
                "invoice_type": "simples_nacional",
                "token": "eyJhbGciOiJIUzI1NiIs...",
                "cnpj": "12345678000199",
                "name": "Empresa Exemplo LTDA",
                "ie": "123456789",
                "unit": "UN",
                "email": "contato@empresa.com",
                "cep": "01001000",
                "address": "Rua Exemplo",
                "house_number": "100",
                "town": "Centro",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://exemplo.com/cert.pfx",
                "cert_pwd": "***",
                "serie": 1,
                "number": 142
              }
            ],
            "page": 1,
            "total": 8,
            "total_pages": 1
          }
        }

GET /api/company/get_detail

Details of the authenticated company

Returns the complete data of the company identified by the token header, including the list of registered tax categories. Accepts no body or query string.

Required headers

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

Call example

GET /api/company/get_detail

Response

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "name": "Empresa Exemplo LTDA",
            "token": "eyJhbGciOiJIUzI1NiIs...",
            "invoice_type": "simples_nacional",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "unit": "UN",
            "email": "contato@empresa.com",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://exemplo.com/cert.pfx",
            "cert_pwd": "***",
            "serie": 1,
            "number": 142,
            "categorys": [
              {
                "category_id": "cat_001",
                "descricao": "Venda de mercadoria",
                "disable_difal": false,
                "desconta_icms_pis_cofins": false
              }
            ]
          }
        }

GET /api/company/get_cep_detail

Look up address by CEP

Resolves a Brazilian CEP (ZIP code) returning UF, IBGE municipality code and address data. Useful for filling in company and customer addresses. Requires a distributor (b2b) account.

Required headers

Header	Type	Description
token	string	Distributor token (b2b — the account must have `isb2b=true`)
sign	string	MD5 signature (path includes the query string)
timestamp	string	Unix timestamp in seconds

Query string

Parameter	Type	Description
cep *	string	Brazilian CEP (8 digits, with or without dash)

* Required field.

Call example

GET /api/company/get_cep_detail?cep=01001000

Response

        {
          "success": true,
          "data": {
            "cep": "01001-000",
            "uf": "SP",
            "ibge": 3550308,
            "logradouro": "Praça da Sé",
            "bairro": "Sé",
            "localidade": "São Paulo",
            "ddd": "11"
          }
        }

GET /api/company/get_export_invoice_month_files

List already-generated monthly export files

Returns the list of monthly export files that have already been generated for the company in the current year (timezone America/Sao_Paulo). Each month can have up to 4 files: 1 Excel spreadsheet (status Success only) + 3 XMLs (one per status Success, Canceled and Voided). Only files actually exported appear in the response — use /api/invoice/get_xml to generate new ones.

Required headers

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

Call example

GET /api/company/get_export_invoice_month_files

Response

Field	Type	Description
files[]	array	List of available files
files[].url	string	File URL on OSS
files[].year	int	Period year
files[].month	string	Month (1–12)
files[].type	string	File type: `"xlsx"` or `"xml"`
files[].status	string	Status of the invoices in the file: `"Success"`, `"Canceled"` or `"Voided"`
files[].create	datetime	When the file was generated

Response example

        {
          "success": true,
          "data": {
            "files": [
              {
                "url": "https://oss.example.com/.../2024_01_success.xlsx",
                "year": 2024,
                "month": "1",
                "type": "xlsx",
                "status": "Success",
                "create": "2024-02-01T03:15:00Z"
              },
              {
                "url": "https://oss.example.com/.../2024_01_success.zip",
                "year": 2024,
                "month": "1",
                "type": "xml",
                "status": "Success",
                "create": "2024-02-01T03:15:30Z"
              }
            ]
          }
        }

GET /api/category/get_list

List product categories

Returns all available categories for fiscal classification.

POST /api/invoice/create

Issue a new invoice

Issues an NF-e (model 55). The issuing company is identified by the token header; do not send company_id in the body.

Required headers

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

Body — top-level fields

Field	Type	Description
Identification and operation
id	string	Unique client-supplied ID for idempotency (composes the dedup key)
nature_of_operation *	string	Operation nature (e.g., "Sale of goods")
transaction_type *	string	Type: `"0"`=inbound, `"1"`=outbound, `"2"`=import, `"3"`=export
model *	string	Document model: `"55"`=NF-e
issuance_type *	string	Issuance type (`"1"`=normal, `"9"`=contingency, etc.)
ambiente *	string	`"1"`=production, `"2"`=homologation
finalidade	string	Purpose: `"1"`=normal, `"2"`=complementary, `"3"`=adjustment, `"4"`=return
ref_nfe_chave	string	44-digit access key of the referenced NF-e (complementary/adjustment/return)
is_reopen	boolean	Reopen/overwrite a previously issued NF-e
dh_sai_ent	string	Exit or entry datetime (ISO 8601). Default: current timestamp
Amounts and discounts
total_discount_amount	decimal	Total invoice discount
troco	decimal	Change amount (typical for NFC-e)
seguro	decimal	Insurance amount (apportioned across products as XML `vSeg`)
outras_despesas	decimal	Other expenses (apportioned across products as XML `vOutro`)
Indicators and additional info
ind_final	string	End consumer: `"0"`=B2B, `"1"`=B2C
ind_pres	string	Presence indicator: `"1"`=in-person, `"2"`=internet, `"3"`=tele-service, etc.
informacoes_complementares	string	Complementary info (written to `infAdic.infCpl`)
informacoes_fisco	string	Information for the tax authority (written to `infAdic.infAdFisco`)

Body — `cliente` (object, required)

For domestic operations (transaction_type 0 or 1): cpf or cnpj, name, endereco, bairro (min. 2 chars), city, uf, and cep are required. For import/export (transaction_type 2 or 3): only name is required.

Field	Type	Description
cpf	string	Customer CPF (alternative to cnpj)
cnpj	string	Customer CNPJ (alternative to cpf)
ie	string	State Registration (Inscrição Estadual)
name *	string	Company / customer name
endereco	string	Street address
complemento	string	Address complement
numero	string	Address number
bairro	string	Neighborhood (minimum 2 characters for domestic operations)
city	string	City
uf	string	State (UF) — overwritten by the UF resolved from the CEP
cep	string	ZIP code (validates UF and city)
telefone	string	Phone
email	string	Email
id_estrangeiro	string	Foreign ID (used for import/export)
c_pais	int	BACEN country code. Default: `1058` (Brazil)
x_pais	string	Country name. Default: `"BRASIL"`

Body — `products[]` (array, at least 1 item)

Each product requires taxation: either category_id (reference to a pre-registered tax category), or the impostos/tax_info object with inline configuration.

Field	Type	Description
codigo	string	Internal product code
name *	string	Product description (CJK characters are stripped)
ncm *	string	NCM with 8 digits
cest	string	CEST code (required when ICMS-ST applies)
gtin	string	GTIN / barcode
gtin_tributavel	string	Taxable-unit GTIN
count *	decimal	Quantity
unit *	string	Commercial unit (e.g., "UN", "KG", "MT")
unit_price *	decimal	Unit price
total_price *	decimal	Total item value
discount_price	decimal	Discount applied to the item
origem *	int	Goods origin (`0`=Domestic, `1`=Foreign — direct import, etc.)
indicador_total *	int	Composes the NF-e total: `0`=no, `1`=yes
category_id	string	ID of a pre-registered tax category (required if `impostos`/`tax_info` is not provided)
impostos	object	Inline tax configuration (alternative to `category_id`). Structure below
tax_info	object	Alias for `impostos` (same structure)
disable_difal	boolean	Disables DIFAL calculation for this item
desconta_icms_pis_cofins	boolean	Deducts ICMS from the PIS/COFINS base for this item only (overrides the category)
ii	object	Import Tax — required for CFOP 3.xxx. Structure below
import_declarations	array	Import Declarations (DI) — required when `transaction_type="2"`. Structure below
nItemPed	int	Purchase Order Item (I61). Sequential item number within the order referenced by `xPed` (which comes from root `id`). Valid range: 1–999999. Default: omitted.

Body — `products[].impostos` / `products[].tax_info`

Field	Type	Description
industria	string	Base industry/rate (alias: `aliquota`)
icms
icms.codigo_cfop	string	CFOP
icms.situacao_tributaria	string	ICMS CST/CSOSN
icms.industria	string	ICMS industry
icms.tipo_pessoa	string	Person type (PF/PJ)
icms.codigo_beneficio_fiscal	string	cBenef (tax-benefit code)
ipi
ipi.codigo_enquadramento	string	IPI legal framework code
ipi.situacao_tributaria	string	IPI CST
ipi.aliquota	string	IPI rate
ipi.tipo_pessoa	string	Person type
pis
pis.situacao_tributaria	string	PIS CST
pis.aliquota	string	PIS rate
pis.tipo_pessoa	string	Person type
cofins
cofins.situacao_tributaria	string	COFINS CST
cofins.aliquota	string	COFINS rate
cofins.tipo_pessoa	string	Person type
is (Selective Tax)
is.cenario	string	IS scenario
is.situacao_tributaria	string	IS CST
is.aliquota	string	IS rate
is.tipo_pessoa	string	Person type
ibs_cbs (Tax Reform)
ibs_cbs.situacao_tributaria	string	IBS/CBS CST
ibs_cbs.tipo_pessoa	string	Person type
ibs_cbs.classificacao_tributaria	string	IBS/CBS tax classification
difal
difal.disable_difal	boolean	Disables DIFAL for the item (alternative to `disable_difal` at the product level)

Body — `products[].ii` (Import Tax)

Field	Type	Description
vBC	decimal	II calculation base
vDespAdu	decimal	Customs expenses
vII	decimal	II amount
vIOF	decimal	IOF amount

Body — `products[].import_declarations[]`

Field	Type	Description
nDI	string	DI number
dDI	string (date)	DI date
xLocDesemb	string	Customs clearance location
UFDesemb	string	Customs clearance state
dDesemb	string (date)	Customs clearance date
cExportador	string	Exporter code
tpViaTransp	int	International transport mode
tpIntermedio	int	Intermediation type
vAFRMM	decimal	AFRMM amount
additions	array	DI additions (fields: `nAdicao`, `nSeqAdic`, `cFabricante`, `vDescDI`, `nDraw`)

Body — `shipping_address` / `delivery_address` (objects, optional)

shipping_address is the pickup location (physical origin, if different from the issuer). delivery_address is the delivery location (physical destination, if different from the customer). When present, both require: cpf or cnpj, name, endereco, bairro (min. 2 chars), city, uf, and cep. Both objects share the same structure.

Field	Type	Description
cpf	string	CPF (alternative to cnpj)
cnpj	string	CNPJ (alternative to cpf)
ie	string	State Registration
name *	string	Company / name
endereco *	string	Street address
complemento	string	Complement
number	string	Number (note: the field is `number`, not `numero`)
bairro *	string	Neighborhood
city *	string	City
uf *	string	State
cep *	string	ZIP code
telefone	string	Phone
email	string	Email

Body — `transportation` (object, optional)

If transportation is omitted, the system assumes transport_mode="9" (no freight).

Field	Type	Description
transport_mode	string	Freight modality: `"0"`=by issuer, `"1"`=by recipient, `"2"`=by third party, `"3"`=sender's own transport, `"4"`=recipient's own transport, `"9"`=no freight
freight_amount	decimal	Total freight amount
carrier_info — carrier
carrier_info.cpf	string	Carrier CPF (alternative to cnpj)
carrier_info.cnpj	string	Carrier CNPJ (alternative to cpf)
carrier_info.ie	string	State Registration
carrier_info.name	string	Company name
carrier_info.endereco	string	Street address
carrier_info.city	string	City
carrier_info.uf	string	State
carrier_info.cep	string	ZIP code
vehicle_info — vehicle
vehicle_info.plate	string	License plate
vehicle_info.uf	string	Plate state
vehicle_info.rntc	string	RNTC (National Cargo Carrier Registration)
trailer_info — trailer (same structure as vehicle_info)
trailer_info.plate	string	Trailer plate
trailer_info.uf	string	State
trailer_info.rntc	string	RNTC
packages[] — volumes
packages[].qty	int	Quantity
packages[].gross_weight	decimal	Gross weight
packages[].net_weight	decimal	Net weight
packages[].packaging_type	string	Packaging type
packages[].number	string	Numbering
packages[].mark	string	Mark
packages[].seals	array<string>	Seals
transport_tax_retention_info — ICMS retention on freight
transport_tax_retention_info.freight_service_amount	decimal	Transport service amount
transport_tax_retention_info.tax_base	decimal	Retention calculation base
transport_tax_retention_info.tax_rate	decimal	Retention rate
transport_tax_retention_info.cfop	string	CFOP
transport_tax_retention_info.cep	string	ZIP code

Body — `pag_info[]` (array, optional)

If omitted, the system assumes [{ "payment_method": "01", "payment_indicator": "0" }] (cash, in cash).

Field	Type	Description
payment_method *	string	Payment method: `"01"`=cash, `"02"`=check, `"03"`=credit card, `"04"`=debit card, `"05"`=store credit, `"10"`=meal voucher, `"11"`=food voucher, `"15"`=bank slip, `"17"`=PIX, `"90"`=no payment, `"99"`=others
payment_indicator *	string	Indicator: `"0"`=in cash, `"1"`=on credit
payment_value	decimal	Amount paid
card_info — card details (for payment_method 03/04)
card_info.integration_type *	string	Card-machine integration type (required if `card_info` is present)
card_info.brand_code *	string	Card brand (required if `card_info` is present)
card_info.acquirer_cnpj	string	Acquirer CNPJ
card_info.authorization_code	string	Authorization code

* Required field.

Simplified example

        {
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "cliente": {
            "cpf": "12345678909",
            "name": "Cliente Exemplo",
            "endereco": "Rua Exemplo",
            "numero": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000",
            "email": "cliente@exemplo.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Produto Exemplo",
              "ncm": "85176277",
              "count": 2,
              "unit": "UN",
              "unit_price": 150.00,
              "total_price": 300.00,
              "category_id": "SEU_CATEGORY_ID",
              "origem": 0,
              "indicador_total": 1
            }
          ],
          "pag_info": [
            { "payment_method": "01", "payment_indicator": "0", "payment_value": 300.00 }
          ]
        }

Complete example (all fields)

        {
          "id": "PEDIDO-2026-0001",
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "finalidade": "1",
          "ref_nfe_chave": "",
          "is_reopen": false,
          "dh_sai_ent": "",
          "total_discount_amount": 0.00,
          "troco": 0.00,
          "seguro": 0.00,
          "outras_despesas": 0.00,
          "ind_final": "1",
          "ind_pres": "9",
          "informacoes_complementares": "Entrega via transportadora",
          "informacoes_fisco": "ICMS recolhido conforme legislação",
          "cliente": {
            "cpf": "",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "name": "Cliente Exemplo LTDA",
            "endereco": "Av. Paulista",
            "numero": "1000",
            "complemento": "Sala 200",
            "bairro": "Bela Vista",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "telefone": "11999998888",
            "email": "cliente@exemplo.com",
            "id_estrangeiro": "",
            "c_pais": 1058,
            "x_pais": "BRASIL"
          },
          "shipping_address": {
            "cnpj": "98765432000111",
            "name": "Depósito Origem LTDA",
            "ie": "987654321",
            "endereco": "Rua do Depósito",
            "number": "50",
            "complemento": "Galpão 3",
            "bairro": "Industrial",
            "city": "Guarulhos",
            "uf": "SP",
            "cep": "07000000",
            "telefone": "11988887777",
            "email": "deposito@exemplo.com"
          },
          "delivery_address": {
            "cnpj": "12345678000199",
            "name": "Cliente Exemplo LTDA",
            "ie": "123456789",
            "endereco": "Rua de Entrega",
            "number": "25",
            "complemento": "Loja 2",
            "bairro": "Centro",
            "city": "Campinas",
            "uf": "SP",
            "cep": "13010000",
            "telefone": "11977776666",
            "email": "entrega@exemplo.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Notebook Dell",
              "ncm": "84713012",
              "cest": "",
              "gtin": "7891234567890",
              "gtin_tributavel": "7891234567890",
              "count": 2,
              "unit": "UN",
              "unit_price": 3500.00,
              "total_price": 7000.00,
              "discount_price": 0.00,
              "origem": 0,
              "indicador_total": 1,
              "category_id": "TF00001",
              "nItemPed": 1
            },
            {
              "codigo": "PROD002",
              "name": "Mouse sem fio",
              "ncm": "84716053",
              "count": 5,
              "unit": "UN",
              "unit_price": 80.00,
              "total_price": 400.00,
              "origem": 0,
              "indicador_total": 1,
              "nItemPed": 2,
              "impostos": {
                "icms": {
                  "codigo_cfop": "5102",
                  "situacao_tributaria": "00",
                  "industria": "",
                  "tipo_pessoa": "juridica",
                  "codigo_beneficio_fiscal": ""
                },
                "ipi": {
                  "codigo_enquadramento": "999",
                  "situacao_tributaria": "99",
                  "aliquota": "0.00",
                  "tipo_pessoa": "juridica"
                },
                "pis": {
                  "situacao_tributaria": "01",
                  "aliquota": "0.65",
                  "tipo_pessoa": "juridica"
                },
                "cofins": {
                  "situacao_tributaria": "01",
                  "aliquota": "3.00",
                  "tipo_pessoa": "juridica"
                },
                "ibs_cbs": {
                  "situacao_tributaria": "000",
                  "tipo_pessoa": "juridica",
                  "classificacao_tributaria": "000001"
                }
              }
            }
          ],
          "transportation": {
            "transport_mode": "1",
            "freight_amount": 150.00,
            "carrier_info": {
              "cnpj": "11222333000144",
              "ie": "112223334",
              "name": "Transportadora Exemplo LTDA",
              "endereco": "Rod. BR-101, km 50",
              "city": "Santos",
              "uf": "SP",
              "cep": "11000000"
            },
            "vehicle_info": {
              "plate": "ABC1D23",
              "uf": "SP",
              "rntc": "12345"
            },
            "trailer_info": {
              "plate": "DEF4G56",
              "uf": "SP",
              "rntc": "67890"
            },
            "packages": [
              {
                "qty": 3,
                "gross_weight": 12.500,
                "net_weight": 11.000,
                "packaging_type": "CAIXA",
                "number": "001-003",
                "mark": "FRAGIL",
                "seals": ["LACRE001", "LACRE002"]
              }
            ],
            "transport_tax_retention_info": {
              "freight_service_amount": 150.00,
              "tax_base": 150.00,
              "tax_rate": 12.00,
              "cfop": "5932",
              "cep": "11000000"
            }
          },
          "pag_info": [
            {
              "payment_indicator": "1",
              "payment_method": "03",
              "payment_value": 7400.00,
              "card_info": {
                "integration_type": "1",
                "brand_code": "01",
                "acquirer_cnpj": "01234567000189",
                "authorization_code": "AUTH987654"
              }
            }
          ]
        }

GET /api/invoice/get_list

List NF-e (paginated)

Lists the company's NF-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: `"Success"` (authorized), `"Canceled"` (canceled), `"Voided"` (voided), `"Processing"` (processing), `"InvoicingFailed"` (invoicing failed), `"Failed"` (failed), `"Contingencia"` (offline contingency), `"Unknown"` (unknown)

* Required field.

Call example

GET /api/invoice/get_list?page=1&page_size=20&status=Success

Response

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Success",
                "create": "2024-01-10T10:30:00Z",
                "issue_time": "2024-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

GET /api/invoice/get_detail

Get NF-e details

Returns the details of a specific NF-e by UUID or by access key. Includes XML URL, DANFE URLs (full, simplified, and label) and metadata.

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
uuid	string	NF-e UUID
chave	string	NF-e access key (44 digits)

Provide uuid or chave (at least one). If both are sent, uuid takes precedence.

Call example

GET /api/invoice/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9
GET /api/invoice/get_detail?chave=35210112345678901234567890123456789012345678

Response

        {
          "success": true,
          "data": {
            "id": "pedido-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Success",
            "total_price": 300.00,
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave.pdf",
            "danfe_simples": "https://oss.example.com/.../chave_simplie.pdf",
            "danfe_etiqueta": "https://oss.example.com/.../chave_etiqueta.pdf",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/invoice/refresh

Refresh invoice status

Queries the current NF-e status at SEFAZ and updates the local record. Useful when issuance remained in processing or contingency.

Required headers

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

Body

Field	Type	Description
uuid *	string	UUID of the NF-e to query

* Required field.

Payload example

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/cancel

Cancel invoice

Cancels an authorized NF-e. The justification sent to SEFAZ is fixed: "Erro no preenchimento da nota fiscal." — it cannot be configured via payload.

Required headers

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

Body

Field	Type	Description
uuid *	string	UUID of the NF-e to cancel (internal identifier returned by `/api/invoice/create`)

* Required field.

Payload example

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/invalid

Invalidate numbering range

Invalidates a contiguous range of NF-e numbers that were never authorized (not to be confused with cancellation — cancellation applies to already-authorized invoices). The operation is registered at SEFAZ and is irreversible.

Required headers

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

Body

Field	Type	Description
modelo *	string	Document model: `"55"`=NF-e, `"65"`=NFC-e. (Note: the field is `modelo`, not `model`)
ambiente *	string	`"1"`=production, `"2"`=homologation
serie *	int	Series of the numbering to invalidate
start_number *	int	Starting number of the range
end_number *	int	Ending number of the range
motivo *	string	Justification for the invalidation (minimum 15 characters, SEFAZ requirement)

* Required field.

Payload example

        {
          "modelo": "55",
          "ambiente": "2",
          "serie": 1,
          "start_number": 100,
          "end_number": 105,
          "motivo": "Falha no sistema durante a emissao do lote"
        }

POST /api/invoice/get_danfe

Get DANFE (PDF) of the NF-e

Returns three URLs for an NF-e DANFE: the full DANFE (PDF), the simplified DANFE PDF (receipt format) and the simplified DANFE as a PNG (label image). PDFs are generated on demand from the authorized XML and cached in OSS. On subsequent calls, if the invoice status has not changed, the existing cache is returned; if the status has changed (e.g. the invoice was cancelled), PDFs are regenerated.

Required headers

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

Body

Field	Type	Description
uuid ⚠	string	Internal NF-e UUID (returned by `/api/invoice/create`)
chave ⚠	string	NF-e access key (44 digits)

⚠ Either uuid or chave is required.

Payload example

        {
          "uuid": "abc123-def456-..."
        }

Response

                                                                {
                                                                  "success": true,
                                                                  "data": {
                                                                    "danfe": "https://storage.../uid/dd-MM-yyyy/companyId/.pdf",
                                                                    "danfe_simples": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.pdf",
                                                                    "danfe_simples_png": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.png"
                                                                  }
                                                                }

Response fields

Field	Type	Description
danfe	string	URL of the full DANFE PDF (A4 format)
danfe_simples	string	URL of the simplified DANFE PDF (receipt format)
danfe_simples_png	string	URL of the simplified DANFE PNG (label image)

Error responses

Message	Cause
uuid/chave不能为空	Neither `uuid` nor `chave` was provided
发票不存在	Invoice not found for the token user, or authorized XML missing
发票详情不存在	Invoice detail (with protocol) not found
获取PDF失败:<reason>	Failure generating the PDF from XML

POST /api/invoice/get_xml

Bulk XML/Excel export (asynchronous)

Starts an asynchronous bulk export task for the user's invoices, filtering by period and status. Can generate an Excel spreadsheet (metadata only) or a ZIP package with the XMLs. The first call creates the task and returns status: "Processing"; subsequent calls with the same parameters return the progress until status: "Success", when the url field contains the download link.

Required headers

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

Body

Field	Type	Description
type *	string	Output format: `"excel"` (metadata spreadsheet) or any other value (e.g. `"xml"`) for ZIP with XMLs
status	string	Filter by invoice status (e.g. `"Success"`, `"Canceled"`, `"Voided"`). For `type=excel`, lowercased internally
month	int	Month (1–12). When provided, overrides `start_create_time`/`end_create_time`; uses `America/Sao_Paulo` timezone and the current year (or previous year if the month is in the future)
start_create_time	long	Period start (Unix timestamp in milliseconds)
end_create_time	long	Period end (Unix timestamp in milliseconds)

* Required field.

Payload example

        {
          "type": "xml",
          "status": "Success",
          "month": 5
        }

Response — processing

        {
          "success": true,
          "data": {
            "status": "Processing",
            "progress_count": 120,
            "total_count": 543,
            "url": ""
          }
        }

Response — finished

                                                                {
                                                                  "success": true,
                                                                  "data": {
                                                                    "status": "Success",
                                                                    "progress_count": 543,
                                                                    "total_count": 543,
                                                                    "url": "https://storage.../exports/uid/.zip"
                                                                  }
                                                                }

Response fields

Field	Type	Description
status	string	`"Processing"` while the task runs, `"Success"` when the file is ready
progress_count	int	Number of invoices processed so far
total_count	int	Total invoices to process
url	string	Download URL of the final file (empty while `status = Processing`)

Idempotency: tasks are deduplicated by a hash of the parameters (uid + token + period + status + type). Repeated calls with the same parameters return the same task's progress, without triggering new executions.

Error responses

Message	Cause
发票类型字段不能为空	`type` missing

POST /api/invoice/consultar_status

Consult NF-e/NFC-e status at SEFAZ

Consults the current status of an NF-e or NFC-e directly at SEFAZ using the access key (44 digits), via the NfeConsultaProtocolo4 service. Works for both own invoices (issued by the token company) and third-party invoices (e.g. captured via DistDFe). The model (NF-e/NFC-e) is detected automatically from positions 20-21 of the key.

Required headers

Header	Type	Description
token	string	Company token (whose certificate will be used in the consultation)
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Body

Field	Type	Description
chave *	string	Access key (44 numeric digits). Issuer UF is extracted from positions 0-1; model from positions 20-21 (`55`=NF-e, `65`=NFC-e).

* Required field.

Payload example

        {
          "chave": "35260512345678000199550010000000011000000018"
        }

Response

        {
          "success": true,
          "message": "Sucesso",
          "data": {
            "chave": "35260512345678000199550010000000011000000018",
            "status": "autorizada",
            "cstat": 100,
            "motivo": "Autorizado o uso da NF-e"
          }
        }

Response fields

Field	Type	Description
chave	string	Access key queried
status	string	Normalized status (see table below)
cstat	int	Raw SEFAZ `cStat` code
motivo	string	Raw SEFAZ `xMotivo` message

Status mapping

`status`	SEFAZ cStat	Meaning
autorizada	`100`, `150`	NF-e authorized for use
cancelada	`101`, `151`	Cancelled (also returned if there is a linked cancellation event, even with `cStat=100`)
denegada	`110`, `301`, `302`	Use denied by SEFAZ
inutilizada	`102`	Number invalidated (numbering range)
nao_encontrada	`217`	NF-e not present in SEFAZ database
desconhecido	others	Unmapped cStat — check raw `cstat` and `motivo`

Error responses

Message	Cause
chave inválida: deve ter 44 dígitos	Key missing, with size other than 44, or containing non-numeric characters
empresa não possui certificado configurado	The token company has no `cert_file` registered
SEFAZ retornou resposta vazia	SEFAZ returned no response (timeout, offline)
erro ao consultar SEFAZ: <detail>	Exception while calling the service (invalid XML, timeout, expired certificate, etc.)

POST /api/category/create

Create tax category

Creates a new tax category (tax template) bound to the authenticated company. Each category aggregates scenarios of ICMS, IPI, PIS, COFINS, and optionally IBS/CBS and IS. To edit an existing one, use /api/category/edit.

Required headers

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

Body — top-level

Field	Type	Description
descricao *	string	Category description
category_id	string	Custom ID. When omitted, auto-generated as `"TF"` + incremental number
disable_difal	boolean	Disables DIFAL calculation for this category. Default: `false`
desconta_icms_pis_cofins	boolean	Deducts ICMS from the PIS/COFINS calculation base (base = vProd − vICMS). Default: `false`
icms[] *	array	ICMS scenarios (structure below)
ipi[] *	array	IPI scenarios (structure below)
pis[] *	array	PIS scenarios (structure below)
cofins[] *	array	COFINS scenarios (structure below)
ibs_cbs[]	array	IBS/CBS scenarios — tax reform (structure below)
is[]	array	IS scenarios — Selective Tax (structure below)

Body — `icms[]`

Field	Type	Description
tipo_tributacao *	string	ICMS tax type
cenario *	string	Scenario (e.g., `"saida_dentro_estado"`, `"saida_fora_estado"`, `"padrao"`)
tipo_pessoa *	string	`"fisica"` or `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	ICMS CST/CSOSN
nao_contribuinte	boolean	Non-contributor customer
aliquota_importacao	string	Import rate
aliquota_credito	decimal	Credit rate (% for Simples Nacional)
aliquota_diferimento	decimal	Deferral percentage
aliquota_diferimentoFcp	string	FCP deferral (note: field uses camelCase `diferimentoFcp`)
aliquota_reducao	decimal	ICMS base reduction percentage
aliquota_reducaoSt	decimal	ICMS-ST base reduction percentage (note: `reducaoSt` camelCase)
motivo_desoneracao	string	ICMS exemption reason code
motivo_desoneracaoSt	string	ICMS-ST exemption reason code (note: camelCase)
Per-state rates — optional
aliquota_mva[]	array	MVA per UF — items: `{ estado, aliquota }`
aliquota_icms[]	array	ICMS rate per UF — items: `{ estado, aliquota }`
aliquota_icms_st[]	array	ICMS-ST rate per UF — items: `{ estado, aliquota }`
aliquota_fcp[]	array	FCP rate per UF — items: `{ estado, aliquota }`
aliquota_fcp_st[]	array	FCP-ST rate per UF — items: `{ estado, aliquota }`
beneficio_fiscal[]	array	Tax benefit code per UF — items: `{ estado, codigo }`

Body — `ipi[]`

Field	Type	Description
cenario *	string	Scenario
tipo_pessoa *	string	`"fisica"` or `"juridica"`
situacao_tributaria *	string	IPI CST
codigo_enquadramento *	string	Legal framework code
aliquota *	string	IPI rate

Body — `pis[]` and `cofins[]` (same structure)

Field	Type	Description
cenario *	string	Scenario
tipo_pessoa *	string	`"fisica"` or `"juridica"`
situacao_tributaria *	string	PIS/COFINS CST
aliquota *	string	Rate

Body — `ibs_cbs[]` (Tax Reform)

Field	Type	Description
cenario *	string	Scenario
tipo_pessoa *	string	`"fisica"` or `"juridica"`
situacao_tributaria *	string	IBS/CBS CST
classificacao_tributaria *	string	Tax classification

Body — `is[]` (Selective Tax)

Field	Type	Description
cenario *	string	Scenario
tipo_pessoa *	string	`"fisica"` or `"juridica"`
situacao_tributaria *	string	IS CST
aliquota *	string	IS rate

* Required field.

Minimal example

        {
          "descricao": "Venda de mercadoria padrão",
          "icms": [{
            "tipo_tributacao": "normal",
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "codigo_cfop": "5102",
            "situacao_tributaria": "00"
          }],
          "ipi":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "99", "codigo_enquadramento": "999", "aliquota": "0" }],
          "pis":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "0.65" }],
          "cofins":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "3" }],
          "ibs_cbs":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "000", "classificacao_tributaria": "000001" }]
        }

Response

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

GET /api/category/get_detail

Tax category details

Returns the complete configuration of a tax category: all ICMS, IPI, PIS, COFINS, IBS/CBS scenarios, including per-UF arrays (MVA, rates, tax benefits).

Required headers

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

Query string

Parameter	Type	Description
category_id *	string	Tax category ID

* Required field.

Call example

GET /api/category/get_detail?category_id=TF123

Response

        {
          "success": true,
          "data": {
            "category_id": "TF123",
            "descricao": "Venda de mercadoria padrão",
            "disable_difal": false,
            "desconta_icms_pis_cofins": false,
            "icms": [{
              "tipo_tributacao": "normal",
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "nao_contribuinte": false,
              "codigo_cfop": "5102",
              "situacao_tributaria": "00",
              "aliquota_importacao": "",
              "aliquota_credito": 0,
              "aliquota_reducao": 0,
              "aliquota_reducao_st": 0,
              "motivo_desoneracao": "",
              "motivo_desoneracao_st": "",
              "aliquota_icms": [{"estado":"SP","aliquota":18}]
            }],
            "ipi":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"99","codigo_enquadramento":"999","aliquota":"0"}],
            "pis":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"0.65"}],
            "cofins": [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"3"}],
            "ibs_cbs":[]
          }
        }

GET /api/category/get_list

List tax categories

Lists the tax categories of the authenticated company with pagination. Returns only category_id and descricao for each — use /api/category/get_detail for the full configuration.

Required headers

Header	Type	Description
token	string	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)

* Required field.

Call example

GET /api/category/get_list?page=1&page_size=20

Response

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF123", "descricao": "Venda de mercadoria padrão" },
              { "category_id": "TF124", "descricao": "Devolução de venda" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/category/edit

Edit tax category

Edits an existing tax category. The body is identical to /api/category/create, the only difference being that category_id is required and must match an existing category. The upsert fully replaces the icms, ipi, pis, cofins, ibs_cbs, is arrays — send all updated scenarios (there is no per-scenario merge).

Required headers

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

Body

The full body structure is documented in /api/category/create. Only category_id is handled differently here:

Field	Type	Description
category_id *	string	ID of the category to edit (must exist; otherwise returns an error)
descricao *	string	Description
icms[] *	array	ICMS scenarios (fully replaces)
ipi[] *	array	IPI scenarios
pis[] *	array	PIS scenarios
cofins[] *	array	COFINS scenarios
ibs_cbs[]	array	IBS/CBS scenarios (optional)
is[]	array	IS scenarios (optional)
disable_difal	boolean	Default: `false`
desconta_icms_pis_cofins	boolean	Default: `false`

* Required field. For the inner fields of each array (icms[].codigo_cfop etc.), see /api/category/create.

Response

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

POST /api/category/delete

Delete tax category

Removes a tax category from the company. Irreversible operation. Products bound to this category will continue referencing the removed category_id, so NFe issuance will fail — update the products before deleting.

Required headers

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

Body

Field	Type	Description
category_id *	string	ID of the category to delete

* Required field.

Payload example

        {
          "category_id": "TF123"
        }

Response

        {
          "success": true
        }

POST /api/invoice/return

Issue return NF-e

Issues a return NF-e (model 55, purpose 4) from an original NF-e. Two modes are supported: full return (reference the original invoice via uuid or chave — the return is a full clone of the original NF-e) or partial/custom return (send chave + the complete invoice fields in the request body itself, same structure as /api/invoice/create).

Required headers

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

Body — top-level fields

Field	Type	Description
uuid	string	UUID of the original NF-e (full return; required if `chave` is absent). If sent, the return is always a full clone — partial-return fields are ignored
chave	string	44-digit access key of the original NF-e (required for partial return; alternative to `uuid` for full return)
cfop *	string	Return CFOP (e.g., `"1202"`, `"1411"`, `"2202"`, `"5202"`, `"5411"`, `"6202"`)
natureza_operacao	string	Operation nature (e.g., "Devolução de venda"). Alias accepted: `nature_of_operation`
transaction_type	string	Operation type: `"0"`=inbound, `"1"`=outbound (required for partial return). The return NF-e is always issued as inbound (`tpNF=0`)
model	string	Document model: `"55"` (required for partial return)
issuance_type	string	Issuance type: `"1"`=normal (required for partial return)
ambiente	string	Environment: `"1"`=production, `"2"`=homologation (required for partial return)
cliente	object	Recipient data, same structure as `/api/invoice/create` (required for partial return). Quirk: the address number field is `number` (in English), not `numero`. Without `number`, the address goes out with nro "S/N"; IBGE code, city and state are resolved from `cep`
products	array	Returned items, same structure as `/api/invoice/create` (required for partial return). `codigo` is optional — when absent, cProd falls back to `name`

* Required field. uuid OR chave is also required (exactly one).

Automatic on returns: payment goes out as 90 (No Payment) — pag_info is ignored; empty natureza_operacao defaults to "Devolução de Mercadoria"; item taxation (CST/CSOSN, PIS/COFINS, IPI, IBS/CBS) comes from the fiscal category of category_id, matched by person type and scenario.

Example — full return

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "cfop": "5202",
          "natureza_operacao": "Devolução de venda"
        }

Example — partial return (complete fields in the body)

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "Devolução parcial",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "cliente": {
            "cnpj": "12345678000199",
            "name": "Fornecedor",
            "endereco": "...",
            "bairro": "...",
            "city": "...",
            "uf": "SP",
            "cep": "01001000"
          },
          "products": [
            {
              "name": "...",
              "ncm": "...",
              "count": 1,
              "unit": "UN",
              "unit_price": 100,
              "total_price": 100,
              "category_id": "...",
              "origem": 0,
              "indicador_total": 1
            }
          ]
        }

code Complete Invoice Issuance Examples

Complete Example with Transportation

        {
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "ind_final": "0",
          "ind_pres": "1",
          "cliente": {
            "cnpj": "12345678000199",
            "ie": "123456789",
            "name": "Empresa Cliente Ltda",
            "endereco": "Rua Exemplo",
            "number": "123",
            "complemento": "Sala 45",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01234567",
            "telefone": "11999999999",
            "email": "contato@empresa.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Smartphone XYZ",
              "ncm": "85171210",
              "cest": "2804000",
              "count": 2,
              "unit": "UN",
              "unit_price": 1500.00,
              "total_price": 3000.00,
              "category_id": "YOUR_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1"
            }
          ],
          "transportation": {
            "transport_mode": "0",
            "freight_amount": 30.00,
            "carrier_info": {
              "cnpj": "12345678000188",
              "name": "Transportadora Expressa",
              "endereco": "Rua da Transportadora",
              "city": "São Paulo",
              "uf": "SP"
            },
            "vehicle_info": {
              "plate": "ABC1234",
              "uf": "SP",
              "rntc": "123456"
            },
            "packages": [
              {
                "qty": 1,
                "packaging_type": "CX",
                "gross_weight": 2.500,
                "net_weight": 2.000
              }
            ]
          },
          "shipping_address": {
            "cnpj": "12345678000199",
            "name": "Remetente Ltda",
            "endereco": "Rua do Remetente",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000"
          },
          "delivery_address": {
            "cnpj": "98765432000111",
            "name": "Destinatário Ltda",
            "endereco": "Rua do Destinatário",
            "number": "200",
            "bairro": "Centro",
            "city": "Rio de Janeiro",
            "uf": "RJ",
            "cep": "20040020"
          },
          "pag_info": [
            {
              "payment_method": "03",
              "payment_indicator": "0",
              "card_info": {
                "integration_type": "1",
                "brand_code": "01"
              }
            }
          ],
          "informacoes_complementares": "Sem informações adicionais",
          "informacoes_fisco": "ICMS recolhido conforme legislação"
        }

💡 INFORMATION: This example includes all important fields, including transportation, detailed fiscal information, and payment. Adapt values according to your specific needs.

Complete Import Example

        {
          "id": "PED-IMP-001",
          "nature_of_operation": "Importacao para revenda",
          "transaction_type": "2",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "finalidade": "1",
          "ind_final": "0",
          "ind_pres": "9",
          "cliente": {
            "name": "EXPORTADOR EXTERIOR CO LTD",
            "endereco": "Pudong District",
            "numero": "456",
            "city": "Shanghai",
            "id_estrangeiro": "CN-EXP-001",
            "c_pais": 1600,
            "x_pais": "CHINA"
          },
          "products": [
            {
              "name": "Fonte chaveada 12V 2A Quickfitting",
              "codigo": "123450000888",
              "ncm": "85044090",
              "count": 2,
              "unit": "PC",
              "unit_price": 0.25,
              "total_price": 0.50,
              "origem": 1,
              "indicador_total": "1",
              "category_id": "YOUR_CATEGORY_ID",
              "import_declarations": [
                {
                  "nDI": "2312345678",
                  "dDI": "2026-04-12",
                  "xLocDesemb": "PORTO DE SANTOS",
                  "UFDesemb": "SP",
                  "dDesemb": "2026-04-15",
                  "tpViaTransp": 1,
                  "vAFRMM": 0.01,
                  "tpIntermedio": 1,
                  "cExportador": "EXP-CN-001",
                  "additions": [
                    {
                      "nAdicao": 1,
                      "nSeqAdic": 1,
                      "cFabricante": "FAB-CN-001",
                      "vDescDI": 0,
                      "nDraw": ""
                    }
                  ]
                }
              ]
            },
            {
              "name": "Quick fitting MA",
              "codigo": "123450000157",
              "ncm": "85044090",
              "count": 2,
              "unit": "PC",
              "unit_price": 0.25,
              "total_price": 0.50,
              "origem": 1,
              "indicador_total": "1",
              "category_id": "YOUR_CATEGORY_ID",
              "ii": {
                "vBC": 0.50,
                "vDespAdu": 0.00,
                "vII": 0.00,
                "vIOF": 0.00
              },
              "import_declarations": [
                {
                  "nDI": "2312345678",
                  "dDI": "2026-04-12",
                  "xLocDesemb": "PORTO DE SANTOS",
                  "UFDesemb": "SP",
                  "dDesemb": "2026-04-15",
                  "tpViaTransp": 1,
                  "vAFRMM": 1.00,
                  "tpIntermedio": 1,
                  "cExportador": "EXP-CN-001",
                  "additions": [
                    {
                      "nAdicao": 1,
                      "nSeqAdic": 2,
                      "cFabricante": "FAB-CN-001",
                      "vDescDI": 0,
                      "nDraw": ""
                    }
                  ]
                }
              ]
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

💡 INFORMATION: Example for NFe Import (CFOP 3.xxx). Differences from a domestic NFe:

transaction_type: "2" — inbound (import) operation.
cliente without cnpj/cpf/uf/cep; uses id_estrangeiro, c_pais (BACEN table — China = 1600) and x_pais.
category_id must point to a fiscal category with CFOP 3.xxx and CST/CSOSN compatible with import.
Product origem = 1 (foreign — direct import) or 2 (foreign — purchased domestically).
The ii block (Import Tax) is required when CFOP is 3.xxx. Values come from the DI issued by the customs broker (vBC, vDespAdu, vII, vIOF). May be zero for testing.
The import_declarations block (Import Declaration) contains customs clearance data: nDI, dDI, clearance location/state/date, transport mode, intermediary, exporter and additions.
vAFRMM is required when tpViaTransp = 1 (Sea).

percent Detailed Tax Parameters

scale_balance ICMS Parameters

Taxation Scenario

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado entrada_dentro_estado

Tax Situation (CST)

00: Fully taxed

02: Tax exempt

10: Taxed with ICMS collection

20: With reduced calculation base

30: Exempt or not taxed

40: Exempt

41: Not taxed

50: Suspension

51: Deferral

60: ICMS previously collected

70: Reduction and collection

90: Others

pie_chart PIS/COFINS Parameters

Taxation Scenario

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado entrada_dentro_estado

Tax Situation (CST)

01: Taxable Operation (normal rate)

02: Taxable Operation (differentiated rate)

03: Taxable Operation (exempt)

04: Taxable Operation (suspension)

05: Taxable Operation (ST)

06: Taxable Operation (zero rate)

07: Contribution Exempt Operation

08: Operation without Contribution Incidence

09: Operation with Contribution Suspension

49: Other Output Operations

50: Credit right (own operations)

51: Credit right (acquisitions)

52: Credit posting

53: Debit posting

54: Credit posting (extemporaneous)

55: Debit posting (extemporaneous)

56: Presumed Credit

60: Presumed Credit (acquisitions)

61: Presumed Credit (import)

62: Presumed Credit (rural activity)

63: Presumed Credit (others)

64: Presumed Credit (non-generator)

65: Presumed Credit (substitution)

66: Presumed Credit (substitution)

67: Presumed Credit (export)

70: Acquisition Operation without Credit Right

71: Acquisition Operation with Exemption

72: Acquisition Operation with Suspension

73: Acquisition Operation at Zero Rate

74: Acquisition Operation without Incidence

75: Acquisition Operation by Substitution

98: Other Input Operations

99: Other Operations

💡 INFORMATION: The tipo_pessoa fields accept values fisica (individual) or juridica (legal entity). For PIS/COFINS, the aliquota field must be formatted as string with two decimal places (ex: "1.65").

credit_card Payment Parameters

Payment Indicator

`0`	At sight (upfront)
`1`	Deferred (installments)

Payment Methods

`01`	Cash
`02`	Check
`03`	Credit Card
`04`	Debit Card
`05`	Store Credit
`10`	Food Voucher (Vale Alimentação)
`11`	Meal Voucher (Vale Refeição)
`12`	Gift Voucher
`13`	Fuel Voucher
`15`	Bank Slip
`90`	No Payment
`99`	Others

Card Brands

`01`	Visa
`02`	Mastercard
`03`	American Express
`04`	Sorocred
`05`	Diners Club
`06`	Elo
`07`	Hipercard
`08`	Aura
`09`	Cabal
`99`	Others

bug_report XML Troubleshooting

warning Rejection 225 - XML Schema Failure

Occurs when trying to cancel, download XML, invalidate number, or manifest an NF-e that was not successfully registered in SEFAZ database.

Verify if NF-e was authorized (status "Authorized")

Re-issue NF-e if not authorized

Invalidate number if not used

lightbulb SEFAZ Online Validation

Use official validator to identify XML problems:


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

Common problems: Incomplete address, invalid NCM, incorrect value formatting, missing required fields.

error SEFAZ Error Codes

Code	Description	Solution
`217`	Issue date too delayed	Issue in contingency or regularize
`404`	Recipient CNPJ/CPF invalid	Verify customer document
`563`	CFOP not allowed for operation	Review operation CFOP

POST /api/nfce/company/create

Registers (or updates) a company for NFC-e issuance. Company name, IE, address and other data are extracted automatically via SintegraWS from the CNPJ. If the CNPJ already exists for the user, the NFC-e fields are updated and the existing company is returned.

Required headers

Header	Type	Description
token	string	Distributor token (b2b)
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
cnpj *	string	Issuing company CNPJ
cert_file *	string	HTTPS URL of the A1 digital certificate (.pfx or .p12)
cert_pwd *	string	Certificate password
csc_id *	string	CSC (Taxpayer Security Code) ID at SEFAZ
csc *	string	CSC token (shared secret with SEFAZ)
serie_nfce	int	NFC-e series
number_nfce	int	Initial NFC-e number
telefone	string	Company phone

* Required field. Other data (name, IE, address, etc.) are extracted automatically via SintegraWS from the CNPJ.

Payload example

        {
          "cnpj": "12345678000199",
          "cert_file": "https://exemplo.com/cert.pfx",
          "cert_pwd": "senha_certificado",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "telefone": "11999999999"
        }

Response

        {
          "success": true,
          "message": "Empresa cadastrada para NFC-e",
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/nfce/company/update

Update NFC-e company data

Updates the NFC-e company identified by the token header. All body fields are optional — send only those you want to change. When cep is updated, the system automatically resolves stateCode and ibge. When cert_file and cert_pwd come together, the certificate is validated before saving.

Required headers

Header	Type	Description
token	string	NFC-e company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body (all fields optional — send ≥ 1)

Field	Type	Description
Identification
name	string	Company name
alias	string	Trade name
ie	string	State Registration
invoice_type	string	Tax regime
email	string	Email
telefone	string	Phone
Address
cep	string	ZIP code (auto-updates `stateCode` and `ibge`)
address	string	Street address
house_number	string	Number
complemento	string	Complement
town	string	Neighborhood
city	string	City
state	string	UF
NFC-e
csc_id	string	CSC ID
csc	string	CSC token
serie_nfce	int	Series
number_nfce	int	Next number
cert_file	string	HTTPS URL of the new A1 certificate (.pfx or .p12)
cert_pwd	string	Certificate password

At least 1 body field is required. CNPJ is immutable.

Payload example

        {
          "alias": "Loja Centro - Filial 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

Response

        {
          "success": true,
          "message": "Empresa NFC-e atualizada com sucesso"
        }

POST /api/nfce/company/get

Get NFC-e company

Returns the NFC-e company data identified by the token header. Note: method is POST but no body fields are required — the company is resolved only by token.

Required headers

Header	Type	Description
token	string	NFC-e company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Empty. {} may be sent.

Response

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "cnpj": "12345678000199",
            "name": "Empresa Exemplo LTDA",
            "alias": "Loja Centro",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contato@empresa.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "complemento": "Sala 5",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://exemplo.com/cert.pfx",
            "csc_id": "000001",
            "csc": "ABCDEF0123456789",
            "serie_nfce": 1,
            "number_nfce": 42
          }
        }

NFC-e Fiscal Category Management

Fiscal categories define the tax rules applied to products when issuing NFC-e. Unlike NFe, NFC-e only operates with intrastate sales, so the structure is simplified: a single object per tax type, without the need for multiple scenarios.

Note: NFC-e categories are stored separately from NFe categories. Each category includes ICMS, PIS, COFINS, and IBS/CBS settings. All endpoints in this section require the token, sign, and timestamp headers.

POST /api/nfce/category/create

Create NFC-e tax category

Creates an NFC-e tax category. Each category has a single scenario (internal outbound) and uses flat objects for ICMS, PIS, COFINS and IBS/CBS (no array, since NFC-e does not allow multiple scenarios per category). No IPI.

Required headers

Header	Type	Description
token	string	NFC-e company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body (root)

Field	Type	Description
descricao *	string	Category description
codigo_cfop *	string	CFOP code (e.g. 5102, 5405)
icms *	object	ICMS configuration (flat object)
pis *	object	PIS configuration (flat object)
cofins *	object	COFINS configuration (flat object)
ibs_cbs	object	IBS/CBS configuration (Tax Reform, optional)

icms

Field	Type	Description
situacao_tributaria *	string	CST/CSOSN (e.g. 102, 500)
aliquota_reducao	decimal	Base reduction percentage
motivo_desoneracao	string	Exemption reason code
aliquota_icms	array	Rates per state: `[{ "estado": "SP", "aliquota": 18.00 }]`
aliquota_fcp	array	FCP per state: `[{ "estado": "SP", "aliquota": 0.00 }]`
beneficio_fiscal	array	Tax benefit per state: `[{ "estado": "SP", "codigo": "SP800001" }]`

pis / cofins

Field	Type	Description
situacao_tributaria *	string	PIS/COFINS CST
aliquota *	string	Percentage rate (e.g. "0.00", "1.65", "7.60")

ibs_cbs (optional)

Field	Type	Description
situacao_tributaria *	string	IBS/CBS CST
classificacao_tributaria *	string	Tax classification code

* Required field.

Payload example

        {
          "descricao": "Bebidas não alcoólicas",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

Response

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

GET /api/nfce/category/get_detail

Get NFC-e tax category details

Returns full data of an NFC-e tax category (description, CFOP, ICMS, PIS, COFINS and IBS/CBS).

Required headers

Header	Type	Description
token	string	NFC-e company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Query string

Field	Type	Description
category_id *	string	NFC-e category ID

* Required field.

Request example

GET /api/nfce/category/get_detail?category_id=TF00001

Response

        {
          "success": true,
          "data": {
            "category_id": "TF00001",
            "descricao": "Bebidas não alcoólicas",
            "codigo_cfop": "5102",
            "icms": {
              "situacao_tributaria": "102",
              "aliquota_icms": [
                { "estado": "SP", "aliquota": 18.00 }
              ],
              "aliquota_fcp": [
                { "estado": "SP", "aliquota": 0.00 }
              ],
              "beneficio_fiscal": [
                { "estado": "SP", "codigo": "SP800001" }
              ]
            },
            "pis": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "cofins": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "ibs_cbs": {
              "situacao_tributaria": "000",
              "classificacao_tributaria": "000001"
            }
          }
        }

GET /api/nfce/category/get_list

List NFC-e tax categories

Returns a paginated list of NFC-e tax categories registered for the authenticated company.

Required headers

Header	Type	Description
token	string	NFC-e company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Query string

Field	Type	Description
page *	int	Page number (minimum 1)
page_size *	int	Items per page (1 to 50)

* Required field.

Request example

GET /api/nfce/category/get_list?page=1&page_size=20

Response

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF00001", "descricao": "Bebidas não alcoólicas" },
              { "category_id": "TF00002", "descricao": "Alimentos industrializados" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/nfce/category/edit

Edit NFC-e tax category

Note: Same structure as the /api/nfce/category/create endpoint, with the additional required field category_id. The icms, pis, cofins and ibs_cbs fields are fully replaced (no merge).

Required headers

Header	Type	Description
token	string	NFC-e company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Additional field

Field	Type	Description
category_id *	string	ID of the category to edit

* Required field.

Payload example

        {
          "category_id": "TF00001",
          "descricao": "Bebidas não alcoólicas — atualizado",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

Response

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

POST /api/nfce/category/delete

Delete NFC-e tax category

Removes an NFC-e tax category. Irreversible operation. Products bound to this category will continue referencing the removed category_id — update them first.

Required headers

Header	Type	Description
token	string	NFC-e company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
category_id *	string	ID of the NFC-e category to delete

* Required field.

Payload example

        {
          "category_id": "TF123"
        }

Response

        {
          "success": true
        }

POST /api/nfce/create

Issue NFC-e

Issues an NFC-e (model 65, always intrastate outbound, no shipping). Key differences from the NFe endpoint: the consumer object is called client (not cliente); the address number is client.number; the consumer is optional; impostos.ipi, shipping_address, delivery_address and transportation do not exist. The value field in pag_info is named amount.

Required headers

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

Body (root)

Field	Type	Description
nature_of_operation *	string	Operation nature (e.g. "Goods sale")
issuance_type *	string	Issuance type: "1" (normal), "9" (NFC-e offline contingency)
ambiente *	string	"1" production, "2" homologation
products *	array	Product list (see details below)
id	string	External identifier
ind_pres	string	Buyer presence: "1" in-person (default), "4" home delivery, "5" in-person off-premises, "9" not applicable
ind_intermed	string	"0" no intermediary, "1" marketplace. Required when `ind_pres` = 2, 3, or 4
total_discount_amount	decimal	Total invoice discount
troco	decimal	Change value
seguro	decimal	Insurance amount
outras_despesas	decimal	Other ancillary expenses
informacoes_complementares	string	Complementary info for the consumer
informacoes_fisco	string	Info of interest to the tax authority
client	object	Consumer data (optional — see table)
pag_info	array	Payments (default: cash on hand — see table)

client (optional)

Provide only if the consumer is identified. CPF or CNPJ must be sent as digits only.

Field	Type	Description
cpf	string	CPF (sets individual person)
cnpj	string	CNPJ (legal entity)
ie	string	State registration
name	string	Name / corporate name
endereco	string	Street
number	string	Address number (note: different from NFe, which uses `numero`)
complemento	string	Complement
bairro	string	Neighborhood
city	string	City
uf	string	State (validated from CEP, if provided)
cep	string	Postal code (digits only)
telefone	string	Phone
email	string	E-mail

products[] (each item)

Field	Type	Description
name *	string	Product name (CJK characters are stripped)
ncm *	string	NCM (8 digits)
count *	decimal	Quantity
unit *	string	Commercial unit (e.g. "UN", "KG")
unit_price *	decimal	Unit price
total_price *	decimal	Item total value
origem *	int	Merchandise origin (0..8)
indicador_total *	int	1 = composes the invoice total; 0 = does not
category_id ⚠	string	NFC-e tax category ID (required if `impostos` not sent)
impostos ⚠	object	Manual taxes (alternative to `category_id`; no IPI)
tax_info ⚠	object	Alias of `impostos` (same structure). Used only if `impostos` is missing
codigo	string	Internal product code
cest	string	CEST
gtin	string	Commercial GTIN/EAN
gtin_tributavel	string	Taxable GTIN
discount_price	decimal	Item discount
nItemPed	int	Purchase Order Item (I61). Sequential item number within the order referenced by `xPed` (which comes from root `id`). Valid range: 1–999999. Default: omitted.

pag_info[] (each item)

Field	Type	Description
payment_indicator *	string	"0" cash, "1" on credit
payment_method *	string	Payment method (01=cash, 03=credit card, 04=debit card, 17=PIX, 99=other, etc.)
amount	decimal	Amount paid in this method
card_info.integration_type	string	"1" integrated, "2" not integrated (required for card 03/04)
card_info.brand_code	string	Card brand (required for card 03/04)
card_info.acquirer_cnpj	string	Acquirer CNPJ
card_info.authorization_code	string	Authorization code

* Required field. ⚠ category_id, impostos or tax_info, one of them is required.

Simplified example

        {
          "nature_of_operation": "Venda de mercadoria",
          "issuance_type": "1",
          "ambiente": "2",
          "ind_pres": "1",
          "client": {
            "cpf": "12345678909",
            "name": "Consumidor Final"
          },
          "products": [
            {
              "name": "Refrigerante 2L",
              "ncm": "22021000",
              "count": 2,
              "unit": "UN",
              "unit_price": 10.50,
              "total_price": 21.00,
              "origem": 0,
              "indicador_total": 1,
              "category_id": "TF00001"
            }
          ],
          "pag_info": [
            {
              "payment_indicator": "0",
              "payment_method": "17",
              "amount": 21.00
            }
          ]
        }

Complete example (all fields)

        {
          "id": "PEDIDO-2026-0001",
          "nature_of_operation": "Venda de mercadoria",
          "issuance_type": "1",
          "ambiente": "2",
          "ind_pres": "1",
          "ind_intermed": "0",
          "total_discount_amount": 0.00,
          "troco": 0.00,
          "seguro": 0.00,
          "outras_despesas": 0.00,
          "informacoes_complementares": "Pedido entregue na loja",
          "informacoes_fisco": "ICMS recolhido conforme legislação",
          "client": {
            "cpf": "12345678909",
            "cnpj": "",
            "ie": "",
            "name": "Consumidor Final",
            "endereco": "Rua das Flores",
            "number": "100",
            "complemento": "Sala 5",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000",
            "telefone": "11999998888",
            "email": "cliente@exemplo.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Refrigerante 2L",
              "ncm": "22021000",
              "cest": "0300100",
              "gtin": "7891234567890",
              "gtin_tributavel": "7891234567890",
              "count": 2,
              "unit": "UN",
              "unit_price": 10.50,
              "total_price": 21.00,
              "discount_price": 0.00,
              "origem": 0,
              "indicador_total": 1,
              "category_id": "TF00001",
              "nItemPed": 1
            },
            {
              "codigo": "PROD002",
              "name": "Salgadinho 100g",
              "ncm": "19053100",
              "count": 1,
              "unit": "UN",
              "unit_price": 8.00,
              "total_price": 8.00,
              "origem": 0,
              "indicador_total": 1,
              "impostos": {
                "icms": {
                  "codigo_cfop": "5102",
                  "situacao_tributaria": "102",
                  "industria": "",
                  "tipo_pessoa": "juridica"
                },
                "pis": {
                  "situacao_tributaria": "99",
                  "aliquota": "0.00",
                  "tipo_pessoa": "juridica"
                },
                "cofins": {
                  "situacao_tributaria": "99",
                  "aliquota": "0.00",
                  "tipo_pessoa": "juridica"
                },
                "ibs_cbs": {
                  "situacao_tributaria": "000",
                  "tipo_pessoa": "juridica",
                  "classificacao_tributaria": "000001"
                }
              }
            }
          ],
          "pag_info": [
            {
              "payment_indicator": "0",
              "payment_method": "03",
              "amount": 24.00,
              "card_info": {
                "integration_type": "1",
                "brand_code": "01",
                "acquirer_cnpj": "01234567000189",
                "authorization_code": "AUTH123456"
              }
            }
          ]
        }

Response

        {
          "success": true,
          "data": {
            "uuid": "abc123...",
            "chave": "35..."
          }
        }

POST /api/nfce/cancel

Cancel NFC-e

Cancels an authorized NFC-e. Unlike NFe, the cancellation reason here is provided by the client and forwarded to SEFAZ. The SEFAZ cancellation window is short (usually 15-30 minutes after authorization).

Required headers

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

Body

Field	Type	Description
chave *	string	44-digit access key of the NFC-e (note: here it's `chave`, not `uuid` as in other endpoints)
motivo *	string	Cancellation justification (minimum 15 characters, SEFAZ requirement)

* Required field.

Payload example

        {
          "chave": "35210112345678901234650010000000051234567890",
          "motivo": "Cancelamento por erro de operacao do caixa"
        }

GET /api/nfce/get_detail

Get NFC-e details

Returns the details of a specific NFC-e by UUID. Includes XML and DANFE (thermal receipt) URLs, plus customer data when provided.

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
uuid *	string	NFC-e UUID

* Required field.

Call example

GET /api/nfce/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9

Response

        {
          "success": true,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234650010000000051234567890",
            "serie": 1,
            "number": 5,
            "status": "Success",
            "modelo": "nfce",
            "total_price": 145.90,
            "nprot": "135210000123456",
            "motivo": "",
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave_nfce.pdf",
            "client_cpf": "12345678909",
            "client_cnpj": "",
            "client_name": "Cliente",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/nfce/get_danfe

Generate / fetch NFC-e DANFE (thermal receipt)

Returns the NFC-e DANFE URL (electronic fiscal receipt) as PDF, with a QR Code for SEFAZ lookup. Generated on demand and cached by hash (access key + status); repeated calls return the existing URL.

Required headers

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

Body

Field	Type	Description
uuid *	string	NFC-e UUID (note: here it's `uuid`, unlike `cancel` which uses `chave`)

* Required field.

Payload example

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

Response

        {
          "success": true,
          "data": {
            "danfe": "https://oss.example.com/.../chave_nfce.pdf"
          }
        }

GET /api/nfce/get_list

List NFC-e (paginated)

Lists the company's NFC-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: `"Success"` (authorized), `"Canceled"` (canceled), `"Processing"` (processing), `"Failed"` (failed), `"Unknown"` (unknown)

* Required field.

Call example

GET /api/nfce/get_list?page=1&page_size=20&status=Success

Response

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

code NFC-e Complete Examples

Example 1 — In-Person Sale (no recipient)

        {
          "nature_of_operation": "Venda de mercadoria",
          "ambiente": "2",
          "ind_pres": "1",
          "products": [
            {
              "codigo": "001",
              "name": "Refrigerante 350ml",
              "ncm": "22021000",
              "count": 3,
              "unit": "UN",
              "unit_price": 5.50,
              "total_price": 16.50,
              "category_id": "BEBIDAS_PADRAO",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5102"
            }
          ],
          "pag_info": [
            { "payment_indicator": "0", "payment_method": "17" }
          ]
        }

Example 2 — Home Delivery (with recipient)

        {
          "nature_of_operation": "Venda de mercadoria",
          "ambiente": "2",
          "ind_pres": "4",
          "client": {
            "cpf": "12345678900",
            "name": "Maria Silva",
            "endereco": "Rua das Flores",
            "number": "456",
            "bairro": "Jardim Primavera",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "04567000"
          },
          "products": [
            {
              "codigo": "PIZZA01",
              "name": "Pizza Grande Marguerita",
              "ncm": "19059090",
              "count": 1,
              "unit": "UN",
              "unit_price": 45.90,
              "total_price": 45.90,
              "category_id": "ALIMENTOS",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5102"
            }
          ],
          "pag_info": [
            { "payment_indicator": "0", "payment_method": "03" }
          ],
          "frete": 8.00,
          "informacoes_complementares": "Entrega em até 40 minutos"
        }

tune NFe Adjustment / Supplementary

Supplementary NFe and Adjustment NFe are invoices issued to correct tax values of an already authorized invoice. Unlike CC-e, which only corrects registration data, these invoices allow changing tax amounts, quantities, and prices.

Supplementary NFe (finalidade = 2):

Used to add values that were reported lower than correct in the original invoice
Price supplement, quantity, or tax amount
Example: issued invoice with 12% ICMS but the correct rate was 18% — issue supplementary with the difference

Adjustment NFe (finalidade = 3):

Used for various tax adjustments provided by legislation
Inventory adjustment, credit transfer, tax regularization
Example: ICMS adjustment by assessment, credit transfer between branches

Important:

Both are new invoices — they generate a new access key and new number
Must reference the original invoice via the ref_nfe_chave field (44-digit key)
The original invoice must be authorized
Each consumes 1 credit (same as a regular issuance)

Authentication

Uses the same endpoint and authentication as the NFe issuance:

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

description 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

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_file *	string	URL of the A1 digital certificate (.pfx)
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.

Payload example

        {
          "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_file": "https://storage.exemplo.com/cert.pfx",
          "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
        }

Response

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

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.

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)

Payload

        {
          "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"
          }
        }

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

Success Response

        {
          "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

Payload

        {
          "chave": "Z685RI9C",
          "motivo": "Cancelamento da NFS-e por erro na emissao"
        }

Fields

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

Success Response

        {
          "success": true,
          "message": "Nota de servico cancelada com sucesso"
        }

POST /api/nfse/get_danfse

Get DANFSE (PDF)

Required Headers

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

Payload

        {
          "chave": "Z685RI9C"
        }

Fields

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

Response

        {
          "success": true,
          "data": {
            "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
          }
        }

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

Payload

        {
          "chave": "Z685RI9C"
        }

Fields

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

Response

        {
          "success": true,
          "data": {
            "dpsXml": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_dps.xml",
            "nfseXml": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_nfse.xml"
          }
        }

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.

POST /api/invoice/create

Issue Supplementary NFe (finalidade = 2)

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)

Payload

        {
          "finalidade": "2",
          "ref_nfe_chave": "CHAVE_NFE_AQUI",
          "nature_of_operation": "Complemento de preço",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "ind_final": "1",
          "ind_pres": "2",
          "cliente": {
            "cpf": "264.438.800-72",
            "name": "Nome do Destinatário",
            "endereco": "Rua Example",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "indIEDest": "9"
          },
          "products": [
            {
              "codigo": "001",
              "name": "Complemento de valor - Produto X",
              "ncm": "82100090",
              "count": 1,
              "unit": "UN",
              "unit_price": 5.00,
              "total_price": 5.00,
              "category_id": "SEU_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5102"
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

Specific Fields

Field	Type	Description
finalidade	string	`"2"` for Supplementary (required)
ref_nfe_chave	string	Access key of the original invoice — 44 digits (required)

Note: The remaining fields follow the same pattern as the /api/invoice/create endpoint for regular issuance. See the NFe issuance documentation for details on all fields.

Payment: In supplementary invoices, payment is usually "90" (No Payment) since it is only a supplement of tax values.

Success Response

        {
          "success": true,
          "data": {
            "uuid": "a1b2c3d4-e5f6-...",
            "chave": "35260312345678000195550010000004051234567890",
            "status": "Success",
            "motivo": "Autorizado o uso da NF-e",
            "nfe": 405,
            "serie": 1,
            "danfe": "https://storage.../danfe.pdf",
            "xml": "https://storage.../xml.xml"
          }
        }

POST /api/invoice/create

Issue Adjustment NFe (finalidade = 3)

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)

Payload

        {
          "finalidade": "3",
          "ref_nfe_chave": "CHAVE_NFE_AQUI",
          "nature_of_operation": "Ajuste fiscal",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "ind_final": "1",
          "ind_pres": "2",
          "cliente": {
            "cpf": "264.438.800-72",
            "name": "Nome do Destinatário",
            "endereco": "Rua Example",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "indIEDest": "9"
          },
          "products": [
            {
              "codigo": "001",
              "name": "Ajuste fiscal - Regularização",
              "ncm": "82100090",
              "count": 1,
              "unit": "UN",
              "unit_price": 0.01,
              "total_price": 0.01,
              "category_id": "SEU_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5949"
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

Specific Fields

Field	Type	Description
finalidade	string	`"3"` for Adjustment (required)
ref_nfe_chave	string	Access key of the original invoice — 44 digits (required)

Available finalidade values:

Value	Description
1	Normal (default)
2	Supplementary
3	Adjustment
4	Return

Difference between Supplementary and Adjustment:

Supplementary (2): Supplements values from the original invoice (price, tax, quantity reported lower than correct)
Adjustment (3): Tax adjustments provided by legislation (regularization, credit transfer, inventory adjustment)

edit_note CC-e — Electronic Correction Letter

The CC-e (Electronic Correction Letter) is an event linked to the NF-e that allows correcting information in an already authorized invoice, without changing tax values. Regulated by Ajuste SINIEF 01/07.

What can be corrected via CC-e:

Recipient or issuer address
Recipient company name (without changing CNPJ/CPF)
Fiscal operation code (CFOP), as long as it does not change the nature of taxes
Product description
Additional data and supplementary information

What CANNOT be corrected via CC-e:

Tax values (tax base, rate, tax amount)
Product quantity and value
Issuer or recipient CNPJ/CPF
Data that changes tax calculations

Rules:

Only invoices with authorized (Success) status can receive CC-e
Correction text must be between 15 and 1000 characters
Up to 20 CC-e can be issued for the same invoice
Each CC-e consumes 1 credit

Authentication

All CC-e endpoints use the same authentication as the main API:

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

POST /api/invoice/cce/send

Send Correction Letter (CC-e)

Sends a CC-e (event 110110) to SEFAZ to correct data of an already authorized NF-e. The sequence (nSeqEvento) is calculated automatically — do not send it. Only non-fiscal data can be corrected (does not correct values, CNPJ, IE, etc.).

Required headers

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

Body

Field	Type	Description
uuid	string	NF-e UUID (required if `chave` is absent)
chave	string	44-digit access key of the NF-e (required if `uuid` is absent)
correcao *	string	Correction text (SEFAZ limit: 15–1000 characters)

* Required field. At least one of uuid or chave is also required.

Payload example

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "correcao": "Corrigir nome do destinatario para Empresa XYZ LTDA"
        }

Response

        {
          "success": true,
          "data": {
            "nProt": "135210000123456",
            "nSeqEvento": 1,
            "xml": "https://oss.example.com/.../cce.xml"
          }
        }

POST /api/invoice/cce/get_list

List CC-e of an NF-e

Returns all CC-e (Correction Letters) issued for a specific NF-e, ordered from most recent to oldest.

Required headers

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

Body

Field	Type	Description
uuid	string	NF-e UUID (required if `chave` is absent)
chave	string	44-digit access key of the NF-e (required if `uuid` is absent)

At least one of uuid or chave is required.

Payload example

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

Response

        {
          "success": true,
          "data": {
            "items": [
              {
                "id": "65fa1b2c3d4e5f6a7b8c9d0e",
                "detail": "Corrigir nome do destinatario para Empresa XYZ LTDA",
                "nProt": "135210000123456",
                "nSeqEvento": 1,
                "date": "15/01/2024 14:30:00",
                "pdfUrl": "https://oss.example.com/.../cce_seq1.pdf",
                "xmlUrl": "https://oss.example.com/.../cce.xml"
              }
            ],
            "total": 1
          }
        }

POST /api/invoice/cce/download_pdf

Download CC-e PDF

Returns the CC-e PDF URL. The PDF is generated on demand on the first call (rendered from the invoice XML + CC-e XML) and stored in OSS; subsequent calls return the existing URL.

Required headers

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

Body

Field	Type	Description
cce_id *	string	CC-e ID (ObjectId) returned by `/api/invoice/cce/get_list` in the `id` field

* Required field.

Payload example

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

Response

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce_seq1.pdf"
          }
        }

POST /api/invoice/cce/download_xml

Download CC-e XML

Returns the URL of the signed CC-e XML (already stored in OSS after submission to SEFAZ).

Required headers

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

Body

Field	Type	Description
cce_id *	string	CC-e ID (ObjectId) returned by `/api/invoice/cce/get_list` in the `id` field

* Required field.

Payload example

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

Response

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce.xml"
          }
        }

how_to_reg Recipient Manifestation

Recipient Manifestation allows the NF-e recipient to formally position themselves regarding an invoice issued against their CNPJ. There are 4 event types defined by SEFAZ, each with its own legal meaning.

Event Types

Code	Name	Meaning	Justification
210210	Operation Awareness	The recipient acknowledges the NF-e exists but has neither confirmed nor rejected it yet. Usually the first event, and a requirement to download the full XML via DistDFe.	Not required
210200	Operation Confirmation	The recipient confirms the operation took place and the goods/services were received. Final event, proves receipt.	Not required
210220	Operation Unawareness	The recipient declares they do NOT recognize the operation (suspected fraud, misuse of CNPJ, etc.).	Required (15-255 chars)
210240	Operation Not Performed	The recipient acknowledges the operation but declares it did NOT take place (return, refusal of delivery, etc.).	Required (15-255 chars)

Sequence rule: After sending Awareness (210210), you may send Confirmation (210200) OR Unawareness (210220) OR Not Performed (210240). Confirmation/Unawareness/Not Performed are final states — they cannot be overwritten.

Attention: The CNPJ sent in the cnpj field must be the recipient of the NF-e (the one manifesting) and must be registered in the system bound to the token in use. Otherwise SEFAZ returns the rejection "The event author differs from the NF-e recipient".

Return cStat Codes

cStat	Meaning
135	✅ Event successfully registered
573	✅ Event duplicity — already registered (treated as success)
236	❌ Invalid access key
491	❌ Manifestation already registered — cannot overwrite final state
596	❌ Recipient CNPJ differs from informed one
656	❌ Improper consumption (rate limit)

POST /api/invoice/manifest

Send recipient manifestation event

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)

Payload

        {
          "chave": "35260514200166000187550010000000011000000018",
          "cnpj": "14200166000187",
          "tipo_evento": 210210,
          "justificativa": "Operação reconhecida pelo destinatário"
        }

Fields

Field	Type	Required	Description
chave	string	Yes	NF-e access key — 44 digits
cnpj	string	Yes	Recipient CNPJ (the one manifesting) — 14 digits, unformatted. Must be registered in the system
tipo_evento	int	Yes	Event code: `210200`, `210210`, `210220` or `210240`
justificativa	string	Conditional	Required for `210220` and `210240`. Must be 15–255 characters. Ignored for `210200` and `210210`

Sequence (nSeqEvento): calculated automatically. For the same combination (cnpj + chave + tipo_evento) it increments on each call — so duplicates return cStat: 573 and are saved without error.

Success Response

        {
          "success": true,
          "message": "data",
          "data": {
            "id": "67341a8f5d4e1f2a3b4c5d6e",
            "chave": "35260514200166000187550010000000011000000018",
            "cnpj": "14200166000187",
            "tipo_evento": 210210,
            "desc_evento": "Ciencia da Operacao",
            "nProt": "135260000123456",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a NF-e",
            "nSeqEvento": 1,
            "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
          }
        }

Response Fields

Field	Type	Description
id	string	Internal ObjectId of the manifestation record (used in `/get_xml`)
chave	string	Access key of the manifested NF-e
cnpj	string	Recipient CNPJ that manifested
tipo_evento	int	Event code sent (210200/210210/210220/210240)
desc_evento	string	Event textual description (SEFAZ original wording)
nProt	string	SEFAZ protocol number — event receipt
cStat	int	SEFAZ status code. `135` = registered, `573` = duplicity (also accepted)
xMotivo	string	SEFAZ descriptive return message
nSeqEvento	int	Event sequence assigned automatically
xml_url	string	Public URL of the procEvento XML (signed and protocoled) stored in OSS

Example — Unawareness (210220) with justification

        {
          "chave": "35260514200166000187550010000000011000000018",
          "cnpj": "14200166000187",
          "tipo_evento": 210220,
          "justificativa": "Operação desconhecida pelo destinatário, sem pedido vinculado ao fornecedor informado"
        }

POST /api/invoice/manifest/list

List sent manifestations (history)

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)

Payload

        {
          "cnpj": "14200166000187",
          "chave": "",
          "start_create_time": "01/05/2026",
          "end_create_time": "31/05/2026",
          "page": 1,
          "page_size": 20
        }

Fields

Field	Type	Required	Description
cnpj	string	No	Filter by recipient CNPJ. If omitted, lists across all of the user's CNPJs
chave	string	No	Filter by a specific NF-e access key (44 digits)
start_create_time	string/long	No	Start date. Accepts: `"dd/MM/yyyy"`, `"yyyy-MM-dd"`, `"dd/MM/yyyy HH:mm:ss"` or Unix timestamp in seconds. Considers 00:00:00 UTC if date-only
end_create_time	string/long	No	End date. Same formats. If date-only, considers 23:59:59.999 UTC
page	int	No	Page number (default `1`)
page_size	int	No	Items per page (default `20`, max `100`)

Success Response

        {
          "success": true,
          "message": "成功",
          "data": {
            "total": 2,
            "page": 1,
            "page_size": 20,
            "list": [
              {
                "id": "67341a8f5d4e1f2a3b4c5d6e",
                "chave": "35260514200166000187550010000000011000000018",
                "cnpj": "14200166000187",
                "tipo_evento": 210210,
                "desc_evento": "Ciencia da Operacao",
                "justificativa": "Operação reconhecida pelo destinatário",
                "nProt": "135260000123456",
                "nSeqEvento": 1,
                "cStat": 135,
                "xMotivo": "Evento registrado e vinculado a NF-e",
                "xml_url": "https://storage.../...210210_1.xml",
                "create": "2026-05-13 14:25:33"
              }
            ]
          }
        }

Response Fields

Field	Type	Description
total	int	Total records matching the filters (regardless of pagination)
page	int	Current page returned
page_size	int	Page size returned
list[].id	string	Internal ObjectId of the record
list[].chave	string	Access key of the manifested NF-e
list[].cnpj	string	Recipient CNPJ that manifested
list[].tipo_evento	int	Event code (210200/210210/210220/210240)
list[].desc_evento	string	Event textual description
list[].justificativa	string	Sent justification (filled only for 210220/210240)
list[].nProt	string	SEFAZ protocol number for the event
list[].nSeqEvento	int	Event sequence
list[].cStat	int	SEFAZ status code
list[].xMotivo	string	SEFAZ descriptive return message
list[].xml_url	string	Public URL of the procEvento XML in OSS
list[].create	string	UTC creation timestamp (format `yyyy-MM-dd HH:mm:ss`)

Ordering: records are returned from newest to oldest (by create descending).

POST /api/invoice/manifest/get_xml

Get URL of a specific manifestation's XML

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)

Payload

        {
          "id": "67341a8f5d4e1f2a3b4c5d6e"
        }

Fields

Field	Type	Required	Description
id	string	Yes	Manifestation ObjectId — returned by `/manifest` or `/manifest/list`

Success Response

        {
          "success": true,
          "message": "data",
          "data": {
            "id": "67341a8f5d4e1f2a3b4c5d6e",
            "chave": "35260514200166000187550010000000011000000018",
            "tipo_evento": 210210,
            "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
          }
        }

Common Errors

Message	Cause
id inválido	Value is not a valid ObjectId
manifestação não encontrada	ObjectId exists but does not belong to the token's user, or was deleted

cloud_download DistDFe Capture — Received NFes

Allows querying and downloading NFes and events destined to your CNPJ via the NFeDistribuicaoDFe service from SEFAZ (National Environment). Capture is incremental by NSU (Unique Sequential Number) — each call only downloads what has not been captured yet.

Returned Document Types

doc_type	What it is	Content
resNFe	NFe summary	Basic metadata (key, value, issuer, status). Comes BEFORE the Awareness event is sent — does not contain products/taxes
procNFe	Full authorized NFe	Complete NF-e XML (with products, taxes, transport, etc.). Only available AFTER the recipient sends Awareness (210210) for the key
resEvento	Event summary	Event metadata (key, type, sequence, reason)
procEvento	Full event	Complete event XML (CC-e, cancellation, manifestations from other recipients on your invoices)

Recommended flow:

Call /received/sync — downloads all new documents
List with /received/list filtering by doc_type: "resNFe" to see invoices without Awareness
For each key of interest, call /invoice/manifest with tipo_evento: 210210
Call /received/sync again — now SEFAZ returns the procNFe (full XML) of the manifested keys
Use /received/get_xml to fetch the XML URL and process

SEFAZ rate limit: SEFAZ allows at most 1 DistDFe call per hour per CNPJ. Exceeding this returns cStat: 656 (Improper Consumption). In homologation the rule is more permissive.

DistDFe Return cStat Codes

cStat	Meaning
137	✅ No documents found (normal end of loop)
138	✅ Documents found — loop continues
656	❌ Improper consumption — wait 1h and retry
252	❌ Environment differs from informed (production vs homologation)
280	❌ Certificate expired or invalid

POST /api/invoice/received/sync

Sync — download new NFes/events from SEFAZ via DistDFe

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)

Payload

        {
          "cnpj": "26638419000167",
          "max_iterations": 50
        }

Fields

Field	Type	Required	Description
cnpj	string	Yes	Recipient company CNPJ — 14 digits, unformatted. Must be registered in the system bound to the token
max_iterations	int	No	Maximum number of SEFAZ calls per execution. Each call downloads up to 50 documents. Default `50` (≈2,500 docs), max `200`

How it works:

Reads the last ultNSU persisted for that (uid + cnpj)
Loops calling SEFAZ until cStat ≠ 138 or max_iterations is reached
Decompresses the returned XMLs (gzip)
Persists each document in w_invoice_received with XML uploaded to OSS
Updates ultNSU and maxNSU in w_invoice_received_sync
Deduplicates by (uid + cnpj + nsu) — repeated calls don't duplicate

Success Response

        {
          "success": true,
          "message": "data",
          "data": {
            "cnpj": "26638419000167",
            "uf": "SP",
            "initial_nsu": 0,
            "ult_nsu": 2323,
            "max_nsu": 2323,
            "pending": 0,
            "iterations": 8,
            "last_cstat": 137,
            "last_motivo": "Nenhum documento localizado",
            "stats": {
              "resNFe": 3,
              "procNFe": 4,
              "resEvento": 336,
              "procEvento": 5,
              "skipped": 0
            }
          }
        }

Response Fields

Field	Type	Description
cnpj	string	Recipient CNPJ queried
uf	string	Recipient state used in the query
initial_nsu	long	Starting NSU — the last one processed before this run
ult_nsu	long	New last NSU after the sync
max_nsu	long	Largest NSU available in SEFAZ AN at the time of the query
pending	long	Documents still pending (`max_nsu - ult_nsu`). If > 0, call `/sync` again to download the rest
iterations	int	How many SEFAZ calls were made in this run
last_cstat	int	Last cStat returned by SEFAZ. `137` is normal end, `656` is rate limit
last_motivo	string	SEFAZ descriptive return message for the last call
stats.resNFe	int	Number of NFe summaries downloaded in this run
stats.procNFe	int	Number of full NFes downloaded
stats.resEvento	int	Number of event summaries downloaded
stats.procEvento	int	Number of full events downloaded
stats.skipped	int	Documents skipped (duplicates or isolated parse error)

Initial volume: companies that have never synced may have hundreds to thousands of historical documents. The first run may take longer and be interrupted by max_iterations. Check pending in the response — if > 0, call again (respecting the rate limit).

POST /api/invoice/received/list

List captured documents (NFes and events)

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)

Payload

        {
          "cnpj": "26638419000167",
          "doc_type": "resNFe",
          "chave": "",
          "emitente_cnpj": "",
          "start_create_time": "01/05/2026",
          "end_create_time": "31/05/2026",
          "page": 1,
          "page_size": 20
        }

Fields

Field	Type	Required	Description
cnpj	string	No	Filter by recipient CNPJ (your CNPJ). If omitted, lists across all of the user's
doc_type	string	No	Filter by document type: `resNFe`, `procNFe`, `resEvento` or `procEvento`
chave	string	No	Filter by access key (44 digits)
emitente_cnpj	string	No	Filter by NF-e issuer CNPJ (supplier)
start_create_time	string/long	No	Start date. Accepts `"dd/MM/yyyy"`, ISO or Unix timestamp
end_create_time	string/long	No	End date. Same formats
page	int	No	Page number (default `1`)
page_size	int	No	Items per page (default `20`, max `100`)

Success Response

        {
          "success": true,
          "message": "成功",
          "data": {
            "total": 3,
            "page": 1,
            "page_size": 20,
            "list": [
              {
                "id": "6a04a70d3201b5a62f3ac2f8",
                "nsu": 2318,
                "doc_type": "resNFe",
                "schema": "resNFe_v1.01.xsd",
                "chave": "35260563845920000120550020000085471156822656",
                "cnpj_destinatario": "26638419000167",
                "emitente_cnpj": "63845920000120",
                "emitente_nome": "MEGA ONLINE LTDA",
                "valor": 1.00,
                "dh_emi": "2026-05-13 14:05:35",
                "serie": 0,
                "number": 0,
                "tp_nf": 1,
                "c_sit_nfe": 3,
                "tp_evento": 0,
                "desc_evento": "",
                "n_seq_evento": 0,
                "dh_evento": null,
                "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml",
                "create": "2026-05-13 16:30:05"
              }
            ]
          }
        }

Response Fields

Field	Type	Description
total	int	Total records matching the filters
page	int	Current page
page_size	int	Page size
list[].id	string	Internal ObjectId (use in `/received/get_xml`)
list[].nsu	long	NSU assigned by SEFAZ to this document
list[].doc_type	string	Document type: `resNFe`, `procNFe`, `resEvento`, `procEvento`
list[].schema	string	Document schema (e.g. `resNFe_v1.01.xsd`)
list[].chave	string	NF-e access key (44 digits)
list[].cnpj_destinatario	string	Recipient CNPJ (your CNPJ)
list[].emitente_cnpj	string	NF-e issuer CNPJ (supplier)
list[].emitente_nome	string	Issuer company name
list[].valor	decimal	NF-e total value (`vNF`)
list[].dh_emi	string	NF-e issuance date/time
list[].serie	int	NF-e series (filled only for `procNFe`)
list[].number	long	NF-e number (filled only for `procNFe`)
list[].tp_nf	int	Operation type: `0`=Inbound, `1`=Outbound (from the issuer's perspective)
list[].c_sit_nfe	int	NF-e status (filled in `resNFe`): `1`=Authorized, `2`=Denied, `3`=Canceled
list[].tp_evento	int	Event code (filled in `resEvento`/`procEvento`). E.g. `110110`=CC-e, `110111`=Cancellation, `210210`=Awareness
list[].desc_evento	string	Event textual description
list[].n_seq_evento	int	Event sequence
list[].dh_evento	string	Event date/time (events only)
list[].xml_url	string	Public URL of the document XML in OSS
list[].create	string	UTC capture timestamp

Ordering: records are returned by NSU descending (most recent first).

POST /api/invoice/received/get_xml

Get URL of a specific received document's XML

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)

Payload

        {
          "id": "6a04a70d3201b5a62f3ac2f8"
        }

Fields

Field	Type	Required	Description
id	string	Yes	Document ObjectId — returned by `/received/list`

Success Response

        {
          "success": true,
          "message": "data",
          "data": {
            "id": "6a04a70d3201b5a62f3ac2f8",
            "nsu": 2318,
            "doc_type": "resNFe",
            "chave": "35260563845920000120550020000085471156822656",
            "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml"
          }
        }

About the returned XML:

resNFe — XML is the summary only, does NOT contain products/taxes. Use for auditing/triage before sending Awareness
procNFe — Full signed XML, equivalent to the one generated at issuance. Ready to import into the client's ERP
procEvento — Full event XML with signature and protocol

Common Errors

Message	Cause
id inválido	Value is not a valid ObjectId
documento recebido não encontrado	ObjectId exists but does not belong to the token's user

POST /api/invoice/received/get_sync_status

Check current DistDFe sync state (does not call SEFAZ)

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)

Payload

        {
          "cnpj": "26638419000167"
        }

Fields

Field	Type	Required	Description
cnpj	string	Yes	Recipient company CNPJ — 14 digits, unformatted

Response — Company already synced

        {
          "success": true,
          "message": "成功",
          "data": {
            "cnpj": "26638419000167",
            "uf": "SP",
            "ult_nsu": 2323,
            "max_nsu": 2323,
            "pending": 0,
            "last_sync": "2026-05-13 16:30:05"
          }
        }

Response — Company never synced

        {
          "success": true,
          "message": "成功",
          "data": {
            "cnpj": "26638419000167",
            "ult_nsu": 0,
            "max_nsu": 0,
            "pending": 0,
            "last_sync": null
          }
        }

Response Fields

Field	Type	Description
cnpj	string	CNPJ queried
uf	string	Recipient state used in the last sync (absent if never synced)
ult_nsu	long	Last NSU processed. `0` = never synced
max_nsu	long	Largest NSU available in SEFAZ at the last sync
pending	long	Pending documents (`max_nsu - ult_nsu`). If > 0, there are new documents in SEFAZ
last_sync	string	UTC date/time of the last successful sync. `null` if never synced

Typical use: call this endpoint before /received/sync to decide whether to call SEFAZ. This endpoint does not consume the SEFAZ rate limit — it only reads local MongoDB state.

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.

Call example

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

Response

        {
          "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
          }
        }

local_shipping MDF-e — Electronic Manifest of Fiscal Documents

The MDF-e API (model 58, layout PL-MDFe 3.00) allows you to issue, query, cancel and close transport manifests. The MDF-e aggregates NF-es and/or CT-es linked to a transport operation, supporting 4 modes: road, air, waterway and rail. All operational information (driver, vehicle, contracting party, CIOT, toll voucher, payment) goes in the body of the /create — there are no inclusion/amendment events after issuance.

Endpoint	Method	Description
`/api/mdfe/create`	POST	Issue MDF-e
`/api/mdfe/consult`	POST	Query the status of the MDF-e
`/api/mdfe/cancel`	POST	Cancel MDF-e (up to 24h after authorization)
`/api/mdfe/close`	POST	Close MDF-e (after finishing the trip)

POST /api/mdfe/create

Issue MDF-e

Issues an MDF-e from the submitted body. The fields cMDF, cDV, cUF, dhEmi, mod, tpEmis, procEmi, verProc are calculated automatically by the server. The client sends only the business fields. The fields serie and nMDF are optional: they are allocated automatically when omitted (or set to 0), but are honored when sent (useful for skipping the numbering, e.g. after a duplicate at SEFAZ).

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Body — root

Field	Type	Description
ide *	object	Identification of the MDF-e
emit *	object	Issuer data
infModal *	object	Mode information (only ONE of the four: `rodo`, `aereo`, `aquav`, `ferrov`)
infDoc *	object	Linked fiscal documents
tot *	object	Cargo totalizers
prodPred	object	Predominant product of the cargo
seg	array	Insurance information
lacres	array	Seals of the MDF-e
autXML	array	CNPJs/CPFs authorized to access the XML
infAdic	object	Additional information (tax authority and taxpayer)
infRespTec	object	Technical responsible (CNPJ, contact, email, etc.)

ide — Identification

Field	Type	Description
tpAmb *	int	Environment: `1`=production, `2`=homologation
tpEmit *	int	Issuer type: `1`=carrier, `2`=own cargo, `3`=transport service provider
modal *	string	Mode: `"1"`=road, `"2"`=air, `"3"`=waterway, `"4"`=rail
UFIni *	string	State (UF) where the trip starts (2 letters)
UFFim *	string	State (UF) where the trip ends
infMunCarrega[] *	array	Loading municipalities: `[{ cMunCarrega, xMunCarrega }]`
infPercurso[]	array	States (UFs) of the route: `[{ UFPer }]`
tpTransp	string	Carrier type (road)
dhIniViagem	string	Trip start date/time (ISO 8601)
indCanalVerde	string	Green channel indicator
indCarregaPosterior	string	Later loading indicator
serie	int	MDF-e series (3 digits of the access key). Optional — auto-allocated (the company's MDF-e series) when omitted or `0`; respected when sent
nMDF	int	MDF-e number (part of the access key). Optional — auto-incremented by the server when omitted or `0`; respected when sent (useful for skipping numbering, e.g.: after a duplicate)

emit — Issuer

Field	Type	Description
CNPJ ⚠	string	CNPJ of the issuer (14 digits)
CPF ⚠	string	CPF of the issuer (11 digits)
IE	string	State Registration
xNome *	string	Company name
xFant	string	Trade name
enderEmit	object	Address: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email }`

infModal — Road Mode (modal="1")

Field	Type	Description
rodo.veicTracao *	object	Traction vehicle: `{ placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop }`
rodo.veicTracao.condutor[] *	array	Drivers: `[{ xNome, CPF }]` — minimum 1
rodo.veicReboque[]	array	Trailer vehicles (same structure as veicTracao without driver)
rodo.infANTT	object	ANTT information: `{ RNTRC, infCIOT[], valePed, infContratante[], infPag[] }`
rodo.codAgPorto	string	Port scheduling code
rodo.lacRodo[]	array	Seals of the mode: `[{ nLacre }]`

infModal — Air Mode (modal="2")

Field	Type	Description
aereo.nac *	string	Aircraft nationality mark
aereo.matr *	string	Aircraft registration
aereo.nVoo *	string	Flight number
aereo.cAerEmb *	string	IATA code of the boarding airport
aereo.cAerDes *	string	IATA code of the destination airport
aereo.dVoo *	string	Flight date (YYYY-MM-DD)

infModal — Waterway Mode (modal="3")

Field	Type	Description
aquav.irin *	string	IRIN of the vessel
aquav.tpEmb *	string	Vessel type (2 digits). Use values ≥ 10 to avoid truncation of the internal Zeus `byte` (e.g.: `"10"`, `"11"`)
aquav.cEmbar *	string	Vessel code
aquav.xEmbar *	string	Vessel name
aquav.nViag *	string	Trip number. Cannot start with zero (schema validation) — use `"1"`, `"100"`, etc.
aquav.cPrtEmb *	string	Boarding port code
aquav.cPrtDest *	string	Destination port code
aquav.prtTrans	string	Transshipment port
aquav.tpNav	string	Navigation type
aquav.infTermCarreg[]	array	Loading terminals: `[{ cTermCarreg, xTermCarreg }]`
aquav.infTermDescarreg[]	array	Unloading terminals
aquav.infEmbComb[]	array	Convoy vessels: `[{ cEmbComb, xBalsa }]`
aquav.infUnidCargaVazia[]	array	Empty cargo units
aquav.infUnidTranspVazia[]	array	Empty transport units

infModal — Rail Mode (modal="4")

Field	Type	Description
ferrov.trem *	object	Train data: `{ xPref, dhTrem, xOri, xDest, qVag }`
ferrov.vag[] *	array	Wagons: `[{ pesoBC, pesoR, tpVag, serie, nVag, nSeq, TU }]` — minimum 1. Zeus/SEFAZ restrictions: `serie` must have exactly 3 digits (use 100+, e.g.: `"100"`); `nVag` only accepts digits (`long` internally, e.g.: `"100001"`); `nSeq` optional 1-3 digits.

infDoc — Linked documents

Field	Type	Description
infMunDescarga[] *	array	Unloading municipalities — minimum 1
infMunDescarga[].cMunDescarga *	string	IBGE code of the municipality
infMunDescarga[].xMunDescarga *	string	Name of the municipality
infMunDescarga[].infNFe[]	array	Linked NF-es: `[{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }]`
infMunDescarga[].infCTe[]	array	Linked CT-es
infMunDescarga[].infMDFeTransp[]	array	Transport MDF-es (subcontracting)

prodPred — Predominant product

Field	Type	Description
tpCarga *	string	Cargo type: `"01"`=solid bulk, `"02"`=liquid bulk, `"03"`=refrigerated, `"04"`=containerized, `"05"`=general cargo, `"06"`=neobulk, `"07"`=hazardous, `"08"`=pressurized bulk
xProd *	string	Description of the predominant product
cEAN	string	GTIN/EAN
NCM	string	NCM
infLotacao	object	Full load: `{ infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} }`

tot — Totalizers

Field	Type	Description
vCarga *	decimal	Total value of the cargo (> 0)
cUnid *	string	Unit code: `"01"`=KG, `"02"`=TON
qCarga *	decimal	Total quantity of the cargo (> 0)
qCTe	int	Number of linked CT-es
qNFe	int	Number of linked NF-es
qMDFe	int	Number of linked MDF-es

* Required field. ⚠ At least one of CNPJ or CPF is required.

Simplified example — Road Mode

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "veicTracao": {
                "placa": "ABC1D23",
                "tara": 8000,
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" }
                ],
                "tpRod": "01",
                "tpCar": "01"
              }
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          }
        }

Simplified example — Air Mode

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "2",
            "UFIni": "SP",
            "UFFim": "RJ",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA AEREA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV AEROPORTO",
              "nro": "5000",
              "xBairro": "CUMBICA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aereo": {
              "nac": "PT",
              "matr": "ABC1234",
              "nVoo": "AB1234",
              "cAerEmb": "GRU",
              "cAerDes": "GIG",
              "dVoo": "2026-05-21"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3304557",
                "xMunDescarga": "Rio de Janeiro",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 25000.00,
            "cUnid": "01",
            "qCarga": 500.00
          }
        }

Simplified example — Waterway Mode

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "3",
            "UFIni": "SP",
            "UFFim": "PA",
            "infMunCarrega": [
              { "cMunCarrega": "3548500", "xMunCarrega": "SANTOS" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "NAVEGACAO EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV PORTUARIA",
              "nro": "200",
              "xBairro": "PORTO",
              "cMun": "3548500",
              "xMun": "SANTOS",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aquav": {
              "irin": "1234567",
              "tpEmb": "10",
              "cEmbar": "1234",
              "xEmbar": "EMBARCACAO EXEMPLO",
              "nViag": "1",
              "cPrtEmb": "BRSSZ",
              "cPrtDest": "BRBEL"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "1501402",
                "xMunDescarga": "Belém",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "GRAOS DE SOJA"
          },
          "tot": {
            "vCarga": 500000.00,
            "cUnid": "02",
            "qCarga": 50.00
          }
        }

Simplified example — Rail Mode

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "4",
            "UFIni": "MG",
            "UFFim": "SP",
            "infMunCarrega": [
              { "cMunCarrega": "3106200", "xMunCarrega": "BELO HORIZONTE" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "FERROVIA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV FERROVIARIA",
              "nro": "300",
              "xBairro": "INDUSTRIAL",
              "cMun": "3106200",
              "xMun": "BELO HORIZONTE",
              "UF": "MG"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "ferrov": {
              "trem": {
                "xPref": "F123",
                "dhTrem": "2026-05-21T08:00:00-03:00",
                "xOri": "BELO HORIZONTE",
                "xDest": "SANTOS",
                "qVag": 2
              },
              "vag": [
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "100",
                  "nVag": "100001",
                  "nSeq": "1",
                  "TU": 28.000
                },
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "101",
                  "nVag": "100002",
                  "nSeq": "2",
                  "TU": 28.000
                }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3548500",
                "xMunDescarga": "Santos",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "MINERIO DE FERRO"
          },
          "tot": {
            "vCarga": 800000.00,
            "cUnid": "02",
            "qCarga": 56.00
          }
        }

Complete example (all fields) — Road Mode

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "tpTransp": "1",
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ],
            "dhIniViagem": "2026-05-21T08:00:00-03:00",
            "indCanalVerde": "1",
            "indCarregaPosterior": "0"
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "xFant": "Exemplo Transportes",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "GALPAO A",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01001000",
              "UF": "SP",
              "fone": "1133334444",
              "email": "contato@exemplo.com"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "infANTT": {
                "RNTRC": "12345678",
                "infCIOT": [
                  { "CIOT": "1234567890", "CNPJ": "12345678000199" }
                ],
                "valePed": {
                  "categCombVeic": "01",
                  "disp": [
                    {
                      "CNPJForn": "98765432000111",
                      "CNPJPg": "12345678000199",
                      "nCompra": "VP001",
                      "vValePed": 250.00,
                      "tpValePed": "01"
                    }
                  ]
                },
                "infContratante": [
                  {
                    "xNome": "EMPRESA CONTRATANTE LTDA",
                    "CNPJ": "11222333000144"
                  }
                ],
                "infPag": [
                  {
                    "xNome": "João da Silva",
                    "CPF": "12345678909",
                    "Comp": [
                      { "tpComp": "01", "vComp": 5000.00, "xComp": "Frete contratado" }
                    ],
                    "vContrato": 5000.00,
                    "indAltoDesemp": "1",
                    "indPag": "0",
                    "infBanc": {
                      "codBanco": "001",
                      "codAgencia": "1234",
                      "PIX": "12345678909"
                    }
                  }
                ]
              },
              "veicTracao": {
                "cInt": "VT001",
                "placa": "ABC1D23",
                "RENAVAM": "12345678901",
                "tara": 8000,
                "capKG": 25000,
                "capM3": 80,
                "prop": {
                  "CNPJ": "12345678000199",
                  "RNTRC": "12345678",
                  "xNome": "TRANSPORTADORA EXEMPLO LTDA",
                  "IE": "123456789012",
                  "UF": "SP",
                  "tpProp": "0"
                },
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" },
                  { "xNome": "Maria Souza", "CPF": "98765432100" }
                ],
                "tpRod": "01",
                "tpCar": "01",
                "UF": "SP"
              },
              "veicReboque": [
                {
                  "cInt": "VR001",
                  "placa": "DEF4G56",
                  "RENAVAM": "98765432109",
                  "tara": 3500,
                  "capKG": 30000,
                  "capM3": 90,
                  "tpCar": "02",
                  "UF": "SP"
                }
              ],
              "lacRodo": [
                { "nLacre": "LACRE001" },
                { "nLacre": "LACRE002" }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  {
                    "chNFe": "35260512345678000199550010000000011000000018",
                    "SegCodBarras": "",
                    "indReentrega": "0",
                    "infUnidTransp": [
                      {
                        "tpUnidTransp": "1",
                        "idUnidTransp": "UT001",
                        "qtdRat": 100.000,
                        "lacUnidTransp": [{ "nLacre": "LACRE-UT-001" }],
                        "infUnidCarga": [
                          {
                            "tpUnidCarga": "1",
                            "idUnidCarga": "UC001",
                            "qtdRat": 100.000,
                            "lacUnidCarga": [{ "nLacre": "LACRE-UC-001" }]
                          }
                        ]
                      }
                    ],
                    "peri": []
                  }
                ]
              }
            ]
          },
          "seg": [
            {
              "infResp": {
                "respSeg": "1",
                "CNPJ": "12345678000199"
              },
              "infSeg": {
                "xSeg": "SEGURADORA EXEMPLO SA",
                "CNPJ": "55666777000188"
              },
              "nApol": "APOL-2026-001",
              "nAver": ["AV001", "AV002"]
            }
          ],
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL",
            "cEAN": "7891234567890",
            "NCM": "84713012",
            "infLotacao": {
              "infLocalCarrega": {
                "CEP": "01001000",
                "latitude": "-23.5505",
                "longitude": "-46.6333"
              },
              "infLocalDescarrega": {
                "CEP": "29100000",
                "latitude": "-20.3297",
                "longitude": "-40.2925"
              }
            }
          },
          "tot": {
            "qCTe": 0,
            "qNFe": 1,
            "qMDFe": 0,
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          },
          "lacres": [
            { "nLacre": "LACRE-GERAL-001" }
          ],
          "autXML": [
            { "CNPJ": "11222333000144" }
          ],
          "infAdic": {
            "infAdFisco": "Documento emitido em conformidade com a legislação vigente",
            "infCpl": "Transporte com escolta armada"
          },
          "infRespTec": {
            "CNPJ": "12345678000199",
            "xContato": "Suporte Técnico",
            "email": "suporte@exemplo.com",
            "fone": "1133334444"
          }
        }

Success response

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "nMDF": 1,
            "serie": 1,
            "protocolo": "135260000123456",
            "xml": "https://storage.../mdfe/2026-05-21/35260512345678000199580010000000011000000018.xml"
          }
        }

POST /api/mdfe/consult

Query the status of the MDF-e

Queries the status of the MDF-e directly at SEFAZ from the access key.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chMDFe *	string	Access key of the MDF-e (44 digits)

* Required field.

Payload example

        {
          "chMDFe": "35260512345678000199580010000000011000000018"
        }

Response

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 100,
            "xMotivo": "Autorizado o uso do MDF-e",
            "protocolo": "135260000123456",
            "dhRecbto": "2026-05-21T10:30:00-03:00",
            "encerrado": false,
            "cancelado": false
          }
        }

POST /api/mdfe/cancel

Cancel MDF-e

Cancels an authorized MDF-e. Window: up to 24 hours after authorization. Not allowed if the MDF-e has already been closed.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chMDFe *	string	Access key of the MDF-e (44 digits)
xJust *	string	Cancellation justification (minimum 15 characters per SEFAZ requirement)

* Required field.

Payload example

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "xJust": "Cancelamento por erro no preenchimento dos dados do veiculo"
        }

Response

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123457",
            "dhRegEvento": "2026-05-21T11:00:00-03:00"
          }
        }

POST /api/mdfe/close

Close MDF-e

Closes an MDF-e at the end of the trip. After closing, it is no longer possible to cancel. The fields dtEnc, cUF and cMun are optional — when omitted, the system infers them from the original MDF-e (current date, UF and municipality of the issuer).

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chMDFe *	string	Access key of the MDF-e (44 digits)
dtEnc	string	Closing date (YYYY-MM-DD). Default: current date
cUF	int	IBGE code of the UF where the closing occurred. Default: UF of the issuer
cMun	string	IBGE code of the municipality where the closing occurred. Default: municipality of the issuer

* Required field.

Payload example

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "dtEnc": "2026-05-22",
          "cUF": 32,
          "cMun": "3205200"
        }

Response

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123458",
            "dhRegEvento": "2026-05-22T18:00:00-03:00"
          }
        }

GET /api/mdfe/get_list

List MDF-e (paginated)

Lists the company's MDF-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: `"Success"` (authorized), `"Canceled"` (canceled), `"Voided"` (closed), `"Processing"` (processing), `"Failed"` (failed), `"Unknown"` (unknown)

* Required field.

Call example

GET /api/mdfe/get_list?page=1&page_size=20&status=Success

Response

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190580010000000011000000015",
                "serie": 1,
                "number": 1,
                "modal": "1",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

inventory_2 DC-e — Electronic Content Declaration

The DC-e API (model 99, layout 1.00) lets you issue, consult, cancel and obtain the PDF (DACE) of electronic content declarations. The DC-e is the fiscal document that covers the transport of goods or merchandise when there is no obligation to issue an invoice — for example, shipments involving ICMS non-taxpayers. The issuer is always a legal entity (CNPJ); the recipient may be a legal entity (CNPJ) or an individual (CPF). The business data goes in the /create body; the technical access-key fields (cDC, cDV, cUF, dhEmi, mod) are calculated automatically by the server.

Endpoint	Method	Description
`/api/dce/create`	POST	Issue DC-e
`/api/dce/consult`	POST	Consult the status of the DC-e
`/api/dce/cancel`	POST	Cancel an authorized DC-e
`/api/dce/pdf`	POST	Obtain the DACE (PDF) of the DC-e

The DC-e is routed to the authorizer of the issuer's state (UF). The ide.cUF field must be consistent with the UF informed in emit.enderEmit.UF — SEFAZ rejects with cStat=220 when they diverge; if omitted, cUF is derived from that UF.

POST /api/dce/create

Issue DC-e

Issues a DC-e from the submitted body. The client sends only the business data; the technical access-key identification fields are calculated by the server (see the note below the ide table). Credit is debited only in production (tpAmb=1) and when the DC-e is authorized.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Body — root

Field	Type	Description
ide *	object	DC-e identification
emit *	object	Issuer/sender data (CNPJ; or CPF via Marketplace — see below)
dest *	object	Recipient data
det *	array	Declared items/goods — minimum 1
total *	object	Declaration totalizer
transp	object	Transport data
marketplace	object	Marketplace data (only when `ide.tpEmit=1`)
fisco	object	Tax authority body data (only when `ide.tpEmit=0`)
autXML	array	CNPJs/CPFs authorized to access the XML
infAdic	object	Additional information

Required fields in the request: ide.tpAmb; emit.CNPJ (14 digits) or emit.CPF (11 digits, individual sender via Marketplace — see the note under emit), emit.xNome and emit.enderEmit (xLgr, nro, xBairro, cMun, xMun, CEP with 8 digits, UF); dest with CNPJ or CPF, dest.xNome and dest.enderDest (same address fields); at least 1 item in det with xProd, NCM (2 or 8 digits), qCom > 0 and vProd > 0; and total.vDC > 0. All other fields are optional.

ide — Identification

Field	Type	Description
tpAmb *	int	Environment: `1`=production, `2`=staging. The only truly required field of `ide`.
tpEmit	int	Issuer type: `0`=Tax Authority Application, `1`=Marketplace, `2`=Own issuer. Optional — default: `2`
cUF	int	IBGE code of the issuer's UF (2 digits). Optional — derived from `emit.enderEmit.UF` when omitted. If sent, it must be consistent with that UF (SEFAZ rejects with `cStat=220` in case of divergence)
serie	int	Fiscal document series (3 digits of the access key) — identifies the DC-e numbering set. Optional — default: DC-e series registered for the company
nDC	long	Sequential DC-e number (part of the access key). Optional — auto-incremented by the server when omitted or `0`
nSiteAutoriz	int	Identification of the authorizer site that processed the DC-e (1 digit of the access key). Usually `0` (primary site). Optional — default: `0`
tpEmis	int	Issuance method: `1`=Normal, `9`=Contingency. Optional — default: `1`

Filled in automatically by the server — you do not need to send them: mod (fixed at 99) and cDV (key check digit) are always set by the server; cDC (6-digit numeric code), dhEmi (issuance date/time) and verProc (process version) are generated when omitted. The serie, nDC and cUF fields in the table above are also filled in automatically when omitted.

emit — Issuer / Sender

Field	Type	Description
CNPJ ⚠	string	Issuer's CNPJ (14 digits). Filled in with the CNPJ of the token's company when omitted
CPF ⚠	string	CPF of the individual sender (11 digits). Only allowed for issuance via Marketplace — see note below
xNome *	string	Issuer's/sender's name or company name
enderEmit *	object	Issuer's address (see structure below)

Individual sender (CPF): by SEFAZ rules, a CPF cannot be its own issuer (tpEmit=2 requires a CNPJ). To issue with a CPF as the sender, just send emit.CPF (without emit.CNPJ): the server automatically sets tpEmit=1 (Marketplace), uses your company's CNPJ (from the token) as the authorized issuer in the access key, and fills the marketplace block with the company's data. The CPF you provide appears as the sender in emit.

dest — Recipient

Field	Type	Description
CNPJ ⚠	string	Recipient's CNPJ (14 digits)
CPF ⚠	string	Recipient's CPF (11 digits)
xNome *	string	Recipient's name or company name
enderDest *	object	Recipient's address (see structure below)

enderEmit / enderDest — Address

Field	Type	Description
xLgr *	string	Street
nro *	string	Number
xCpl	string	Complement
xBairro *	string	Neighborhood
cMun *	long	IBGE municipality code (7 digits)
xMun *	string	Municipality name
CEP *	string	Postal code (8 digits)
UF *	string	State abbreviation (2 letters)
cPais	int	Country code. Default: `1058` (Brazil)
xPais	string	Country name. Default: `BRASIL`
fone	string	Phone
email	string	E-mail

det[] — Declared items

Field	Type	Description
nItem	int	Sequential item number
xProd *	string	Description of the declared good/merchandise
NCM *	string	NCM code (2 or 8 digits)
qCom *	decimal	Quantity (> 0)
vUnCom	decimal	Unit value
vProd *	decimal	Total item value (> 0)
infAdProd	string	Additional item information

total — Totalizer

Field	Type	Description
vDC *	decimal	Total declared value (> 0)

transp — Transport

Field	Type	Description
modTrans	int	Transport mode: `0`=Postal service, `1`=own, `2`=carrier. Default: `2`
CNPJTransp	string	Carrier's CNPJ

marketplace — Marketplace (only `tpEmit=1`)

Field	Type	Description
CNPJ	string	Marketplace's CNPJ
xNome	string	Marketplace name
Site	string	Marketplace website

fisco — Tax authority body (only `tpEmit=0`)

Field	Type	Description
CNPJ	string	Body's CNPJ
xOrgao	string	Body name
UF	string	Body's UF

autXML[] — Authorized for XML

Field	Type	Description
CNPJ	string	CNPJ authorized to consult/download the XML
CPF	string	CPF authorized to consult/download the XML

infAdic — Additional information

Field	Type	Description
infAdFisco	string	Information of interest to the tax authority
infCpl	string	Supplementary information of interest to the taxpayer
infAdMarketPlace	string	Additional marketplace information

* Required field. ⚠ In the issuer and in the recipient, at least one of CNPJ or CPF is required.

Simplified example (minimum fields)

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR"
            }
          },
          "dest": {
            "CPF": "12345678909",
            "xNome": "JOAO DA SILVA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR"
            }
          },
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00
            }
          ],
          "total": {
            "vDC": 150.00
          }
        }

Complete example (all fields)

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "cUF": 41,
            "serie": 1,
            "nSiteAutoriz": 0
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "SALA 2",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4133334444",
              "email": "contato@exemplo.com"
            }
          },
          "dest": {
            "CNPJ": "98765432000188",
            "xNome": "DESTINATARIO EXEMPLO LTDA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xCpl": "GALPAO 3",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4333335555",
              "email": "destino@exemplo.com"
            }
          },
          "autXML": [
            { "CNPJ": "11222333000144" },
            { "CPF": "98765432100" }
          ],
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00,
              "infAdProd": "Caixa 1 de 2"
            },
            {
              "nItem": 2,
              "xProd": "MATERIAL DE ESCRITORIO",
              "NCM": "48201000",
              "qCom": 10,
              "vUnCom": 8.00,
              "vProd": 80.00,
              "infAdProd": "Caixa 2 de 2"
            }
          ],
          "total": {
            "vDC": 230.00
          },
          "transp": {
            "modTrans": 2,
            "CNPJTransp": "55666777000188"
          },
          "infAdic": {
            "infAdFisco": "Operacao nao sujeita a emissao de nota fiscal",
            "infCpl": "Remessa de bens entre filiais"
          }
        }

Success response

        {
          "success": true,
          "message": "DC-e autorizada",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Rejection response

        {
          "success": false,
          "message": "DC-e rejeitada: Rejeicao: ...",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "225",
            "xMotivo": "Rejeicao: Falha no Schema XML",
            "nProt": "",
            "xml": "",
            "dace": ""
          }
        }

POST /api/dce/consult

Consult the status of the DC-e

Consults the current status of the DC-e at SEFAZ from the access key. When the DC-e is canceled, the response reflects the cancellation data (the local database is the source of truth about cancellation).

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chDCe *	string	DC-e access key (44 digits)

* Required field.

Payload example

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

Response — active DC-e

        {
          "success": true,
          "message": "Autorizado o uso do DC-e",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Success",
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Response — canceled DC-e

        {
          "success": true,
          "message": "DC-e Cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Canceled",
            "cStat": "101",
            "xMotivo": "Cancelamento de DCe homologado",
            "nProt": "141250000123457",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml",
            "dhEventoCancel": "2026-06-11T11:00:00-03:00"
          }
        }

POST /api/dce/cancel

Cancel DC-e

Cancels an authorized DC-e (event 110111). Requires that the DC-e has been authorized (has a protocol) and is not yet canceled. Each DC-e allows a single cancellation.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chDCe *	string	DC-e access key (44 digits)
xJust *	string	Cancellation justification (minimum 15 characters as required by SEFAZ)
nProt	string	Authorization protocol. Optional: when omitted, uses the protocol registered at issuance

* Required field.

Payload example

        {
          "chDCe": "41250612345678000199990010000000011201234564",
          "xJust": "Cancelamento por erro no preenchimento dos dados da declaracao"
        }

Success response

        {
          "success": true,
          "message": "DC-e cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "cStat": "135",
            "xMotivo": "Evento registrado e vinculado a DC-e",
            "nProtCancel": "141250000123457",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml"
          }
        }

In case of rejection, the response returns success=false, the cStat/xMotivo of the refusal and an additional field xmlEnviadoDebug with the XML that was sent, for diagnosis.

POST /api/dce/pdf

Obtain DACE (PDF) of the DC-e

Returns the URL of the DACE — the PDF representation of the DC-e. When the PDF does not yet exist in storage, it is generated on demand and uploaded. If storage is unavailable, the PDF is returned as base64 in the response body itself.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chDCe *	string	DC-e access key (44 digits)

* Required field.

Payload example

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

Response — PDF URL

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Response — base64 fallback (storage unavailable)

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "pdfBase64": "JVBERi0xLjcKJ...",
            "pdfSize": 84213
          }
        }

GET /api/dce/get_list

List DC-e (paginated)

Lists the company's DC-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: `"Success"` (authorized), `"Canceled"` (canceled), `"Processing"` (processing), `"Failed"` (failed), `"Unknown"` (unknown)

* Required field.

Call example

GET /api/dce/get_list?page=1&page_size=20&status=Success

Response

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190990010000000011000000013",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

local_shipping CT-e — Electronic Bill of Lading

The CT-e API (model 57, layout 4.00 + NT2025/001) lets you issue, cancel, correct (CC-e), register service disagreement, consult and void the numbering of Electronic Bills of Lading. The CT-e documents the provision of a cargo transport service. It supports 6 modes (road, air, waterway, rail, pipeline, multimodal) and 4 types of CT-e (Normal, Supplement, Annulment, Replacement). The business data goes in the /create body; the technical access-key fields (cCT, cDV, cUF, dhEmi, mod) are calculated automatically by the server. The fields serie and nCT are optional: they are allocated automatically when omitted (or set to 0), but are honored when sent (useful for skipping the numbering, e.g. after a duplicate at SEFAZ).

Endpoint	Method	Description
`/api/cte/create`	POST	Issue CT-e
`/api/cte/cancel`	POST	Cancel CT-e (event 110111)
`/api/cte/cce`	POST	Correction Letter — CC-e (event 110110)
`/api/cte/desacordo`	POST	Service Disagreement (event 610110, registered by the service taker)
`/api/cte/consult`	POST	Consult the status of the CT-e
`/api/cte/inutilize`	POST	Void a numbering range

The service taker (whoever pays the freight) is defined in ide.toma: 0=Sender, 1=Dispatcher, 2=Receiver, 3=Recipient, 4=Others (in this case fill in ide.toma4).

POST /api/cte/create

Issue CT-e

Issues a CT-e from the submitted body. The client sends only the business data; the technical access-key identification fields are calculated by the server (see the note below the ide table). Credit is debited only in production (tpAmb=1) and when the CT-e is authorized. The examples below cover the most common case: road mode (modal=01) and Normal CT-e (tpCTe=0).

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Required fields in the request: ide (tpAmb, CFOP, natOp, modal, tpCTe, toma, cMunIni, UFIni, cMunFim, UFFim); emit with CNPJ or CPF and xNome; rem with CNPJ or CPF; dest with CNPJ or CPF; vPrest.vTPrest > 0; imp (with one ICMS variant). For tpCTe=0 (Normal): infCTeNorm with infCarga (proPred + at least 1 infQ) and infModal (the mode corresponding to ide.modal; for modal=01, rodo.RNTRC is required). All other fields are optional.

Body — root

Field	Type	Description
ide *	object	CT-e identification
emit *	object	Issuer data (carrier)
rem *	object	Cargo sender
dest *	object	Cargo recipient
vPrest *	object	Service provision values
imp *	object	Taxes (ICMS + tributes)
infCTeNorm *	object	Normal CT-e body — required when `tpCTe=0` (Normal) or `3` (Replacement)
exped	object	Dispatcher (optional)
receb	object	Receiver (optional)
compl	object	Complementary data (observations, flow, delivery)
infCteComp	object	Key of the supplemented CT-e — required when `tpCTe=1` (Supplement): `{ chCTe }`
infCteAnu	object	Key of the annulled CT-e — required when `tpCTe=2` (Annulment): `{ chCte, dEmi }`
autXML	array	CNPJs/CPFs authorized to access the XML: `[{ CNPJ } \| { CPF }]`
infRespTec	object	Technical contact — filled in automatically by the server per UF

ide — Identification

Field	Type	Description
tpAmb *	int	Environment: `1`=production, `2`=staging
CFOP *	int	Fiscal operation code (e.g.: `5353` within the state, `6353` interstate)
natOp *	string	Nature of the operation (e.g.: `"PRESTACAO DE SERVICO DE TRANSPORTE"`)
modal *	string	Mode: `"01"`=road, `"02"`=air, `"03"`=waterway, `"04"`=rail, `"05"`=pipeline, `"06"`=multimodal
tpCTe *	int	CT-e type: `0`=Normal, `1`=Supplement, `2`=Annulment, `3`=Replacement
tpServ *	int	Service type: `0`=Normal, `1`=Subcontracting, `2`=Reshipment, `3`=Intermediate Reshipment, `4`=Service Linked to Multimodal
toma *	int	Service taker: `0`=Sender, `1`=Dispatcher, `2`=Receiver, `3`=Recipient, `4`=Others
toma4	object	Service taker data — required when `toma=4` (see table below)
indIEToma	int	Service taker IE indicator: `1`=ICMS taxpayer, `2`=Exempt, `9`=Non-taxpayer (when `9`, the service taker's IE is omitted automatically)
cMunIni *	long	IBGE code of the service start municipality (7 digits)
xMunIni	string	Name of the start municipality
UFIni *	string	Start UF (2 letters)
cMunFim *	long	IBGE code of the service end municipality (7 digits)
xMunFim	string	Name of the end municipality
UFFim *	string	End UF (2 letters)
cMunEnv	long	IBGE code of the issuance municipality
xMunEnv	string	Name of the issuance municipality
UFEnv	string	Issuance UF
retira	int	Pickup at origin: `0`=Yes, `1`=No. Default: `1`
xDetRetira	string	Pickup details
tpImp	int	DACTE format: `1`=Portrait, `2`=Landscape. Default: `1`
infPercurso	array	Route UFs: `[{ UFPer }]`
dhCont	string	Date/time of entry into contingency (ISO 8601)
xJust	string	Contingency justification
serie	int	CT-e series (3 digits of the access key). Optional — auto-allocated (the company's CT-e series) when omitted or `0`; respected when sent
nCT	long	CT-e number (part of the access key). Optional — auto-incremented by the server when omitted or `0`; respected when sent (useful for skipping numbering, e.g.: after a duplicate)

Filled in automatically by the server — you do not need to send them: mod (fixed at 57), cCT (8-digit numeric code), cDV (check digit), cUF (derived from the issuer's UF), dhEmi (current date/time), tpEmis (default 1=Normal), procEmi and verProc.

toma4 — "Others" service taker (when `ide.toma=4`)

Field	Type	Description
CNPJ ⚠ / CPF ⚠	string	Service taker's document (one of the two)
IE	string	State Registration
xNome	string	Company name/name
xFant, fone, email	string	Trade name, phone, e-mail
enderToma	object	Address: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, cPais, xPais }`

emit — Issuer (carrier)

Field	Type	Description
CNPJ ⚠	string	Issuer's CNPJ (14 digits)
CPF ⚠	string	Issuer's CPF (11 digits)
IE	string	State Registration
IEST	string	State Registration of the tax substitute
xNome *	string	Company name
xFant	string	Trade name
CRT	int	Tax Regime Code: `1`=Simples Nacional, `2`=SN exceeding sublimit, `3`=Normal Regime, `4`=MEI. Default: `3`
enderEmit	object	Address: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone }`

rem — Sender

Field	Type	Description
CNPJ ⚠ / CPF ⚠	string	Sender's document (one of the two)
IE	string	State Registration (or `"ISENTO"`)
xNome	string	Company name/name
xFant, fone, email	string	Trade name, phone, e-mail
enderReme	object	Sender's address (structure below)
locColeta	array	Pickup locations (optional): `[{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }]`

dest — Recipient

Field	Type	Description
CNPJ ⚠ / CPF ⚠	string	Recipient's document (one of the two)
IE	string	State Registration (or `"ISENTO"`)
xNome	string	Company name/name
fone, email, ISUF	string	Phone, e-mail, SUFRAMA Registration
enderDest	object	Recipient's address (structure below)
locEnt	object	Delivery location (optional): `{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }`

exped / receb — Dispatcher / Receiver (optional)

Field	Type	Description
CNPJ / CPF	string	Document (one of the two)
IE, xNome, fone, email	string	State Registration, name, phone, e-mail
enderExped / enderReceb	object	Address (same generic structure below)

Address (enderEmit / enderReme / enderExped / enderReceb / enderDest)

Field	Type	Description
xLgr	string	Street
nro	string	Number
xCpl	string	Complement
xBairro	string	Neighborhood
cMun	string	IBGE municipality code (7 digits)
xMun	string	Municipality name
CEP	string	Postal code (8 digits) — not used in `enderEmit`
UF	string	State abbreviation (2 letters)
cPais	string	Country code (optional, default 1058 Brazil)
xPais	string	Country name (optional)
fone	string	Phone (only in `enderEmit`)

vPrest — Service Provision Values

Field	Type	Description
vTPrest *	decimal	Total value of the service provision (> 0)
vRec	decimal	Amount receivable
Comp	array	Value components: `[{ xNome, vComp }]` — e.g.: `"FRETE PESO"`, `"PEDÁGIO"`, `"GRIS"`

imp — Taxes

Field	Type	Description
ICMS *	object	ICMS taxation — fill in only one of the variants (see below)
vTotTrib	decimal	Approximate total value of tributes
infAdFisco	string	Additional information of interest to the tax authority
ICMSUFFim	object	DIFAL (interstate sharing, optional): `{ vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni }`
infTribFed	object	Federal tributes (optional): `{ vPIS, vCOFINS, vIR, vINSS, vCSLL }`

ICMS — variants (fill in only one)

Variant	When to use	Fields
ICMS00	Normal taxation	`{ vBC, pICMS, vICMS }` (CST 00)
ICMS20	With reduction of calculation base	`{ pRedBC, vBC, pICMS, vICMS }` (CST 20)
ICMS45	Exempt / non-taxed / deferred	`{ CST }` — `"40"`=Exempt, `"41"`=Non-taxed, `"51"`=Deferred
ICMS60	ICMS charged by tax substitution	`{ vBCSTRet, vICMSSTRet, pICMSSTRet, vCred }` (CST 60)
ICMS90	Others (special regime)	`{ pRedBC, vBC, pICMS, vICMS, vCred }` (CST 90)
ICMSOutraUF	ICMS due to another UF	`{ pRedBCOutraUF, vBCOutraUF, pICMSOutraUF, vICMSOutraUF }`
ICMSSN	Simples Nacional issuer	`{ CST: "90", indSN: 1 }`

infCTeNorm — Normal CT-e (required for `tpCTe=0`/`3`)

Field	Type	Description
infCarga *	object	Cargo information (table below)
infDoc	object	Transported documents (table below)
infModal *	object	Mode information (table below)
docAnt	object	Previous documents (subcontracting/reshipment): `{ emiDocAnt[]{ CNPJ\|CPF, IE, UF, xNome, idDocAnt[] } }`
seg	array	Cargo insurance: `[{ respSeg, xSeg, CNPJ, nApol, nAver, vCarga }]` — `respSeg`: 1=Sender…6=Service taker
cobr	object	Billing/invoices: `{ fat{ nFat, vOrig, vDesc, vLiq }, dup[]{ nDup, dVenc, vDup } }`
veicNovos	array	New vehicles transported: `[{ chassi, cCor, xCor, cMod, vUnit, vFrete }]`
infCteSub	object	Replacement — required when `tpCTe=3`: `{ chCte, indAltToma, refNF, tomaICMS, tomaNaoICMS }`

infCTeNorm.infCarga — Cargo

Field	Type	Description
proPred *	string	Predominant product
vCarga	decimal	Total cargo value
xOutCat	string	Other cargo characteristics (e.g.: FRIA, GRANEL, REFRIGERADA)
vCargaAverb	decimal	Cargo value for endorsement purposes
infQ[] *	array	Quantities — minimum 1: `[{ cUnid, tpMed, qCarga }]`
infQ[].cUnid	string	Unit: `"00"`=M³, `"01"`=KG, `"02"`=TON, `"03"`=UNIT, `"04"`=LITERS, `"05"`=MMBTU
infQ[].tpMed	string	Measurement type (e.g.: `"PESO BRUTO"`, `"PESO DECLARADO"`)
infQ[].qCarga	decimal	Quantity

infCTeNorm.infDoc — Transported documents

Field	Type	Description
infNFe	array	NF-es by access key: `[{ chave, PIN, dPrev, infUnidCarga[], infUnidTransp[] }]` — `chave` with 44 digits
infNF	array	Paper invoices (legacy): `[{ mod, serie, nDoc, dEmi, vBC, vICMS, vProd, vNF, nCFOP, nPeso, … }]`
infOutros	array	Other documents: `[{ tpDoc, descOutros, nDoc, dEmi, vDocFisc }]` — `tpDoc`: `"00"`=Declaration, `"10"`=Pipeline, `"99"`=Others

infCTeNorm.infModal — Modes (fill in only the one corresponding to `ide.modal`)

Mode	Object	Fields
01 Road	rodo	`{ RNTRC* }` — RNTRC with 8 digits or `"ISENTO"`. Optional: `occ[]` (pickup orders)
02 Air	aereo	`{ nMinu, nOCA, dPrevAereo, natCarga{ xDime, cInfManu[] }, tarifa{ CL, cTar, vTar }, peri[] }` — `dPrevAereo` AAAA-MM-DD
03 Waterway	aquav	`{ vPrest, vAFRMM, xNavio, nViag, direc, irin, tpNav, balsa[], detCont[] }` — `direc`: N/L/S/O; `tpNav`: 0=Interior, 1=Coastal
04 Rail	ferrov	`{ tpTraf, respFat, ferrEmi, vFrete, chCTeFerroOrigem, ferroEnv[] }` — `tpTraf`: 0=Own, 1=Mutual, 2=Road-rail, 3=Road
05 Pipeline	duto	`{ vTar, dIni, dFim }` — dates AAAA-MM-DD
06 Multimodal	multimodal	`{ COTM, indNegociavel, seg[] }` — `indNegociavel`: 0=No, 1=Yes

The entire infModal block accepts versaoModal (default "4.00").

compl — Complementary data (optional)

Field	Type	Description
xCaracAd, xCaracSer, xEmi	string	Additional characteristic of the transport / of the service / issuer name
origCalc, destCalc	string	Origin / destination municipality for freight calculation
xObs	string	General observations
ObsCont / ObsFisco	array	Free observations of the taxpayer / tax authority: `[{ xCampo, xTexto }]`
fluxo, Entrega	object	Cargo flow (origin/passage/destination/route) and delivery forecast

* Required field. ⚠ At least one of CNPJ or CPF is required in the group.

Simplified example — Road Mode, Simples Nacional

        {
          "ide": {
            "CFOP": 5353,
            "natOp": "PRESTACAO DE SERVICO DE TRANSPORTE",
            "tpAmb": 2,
            "tpCTe": 0,
            "modal": "01",
            "tpServ": 0,
            "cMunEnv": 3550308,
            "xMunEnv": "SAO PAULO",
            "UFEnv": "SP",
            "cMunIni": 3550308,
            "xMunIni": "SAO PAULO",
            "UFIni": "SP",
            "cMunFim": 3304557,
            "xMunFim": "RIO DE JANEIRO",
            "UFFim": "RJ",
            "retira": 1,
            "indIEToma": 9,
            "toma": 0
          },
          "emit": {
            "CNPJ": "26638419000167",
            "IE": "141507411110",
            "CRT": 1,
            "xNome": "TF COMERCIO DE PRESENTES LTDA",
            "enderEmit": {
              "xLgr": "RUA QUINTANA",
              "nro": "34",
              "xBairro": "CIDADE MONCOES",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "04571010",
              "UF": "SP",
              "fone": "1133334444"
            }
          },
          "rem": {
            "CNPJ": "11111111000111",
            "IE": "ISENTO",
            "xNome": "EMPRESA REMETENTE LTDA",
            "fone": "1122223333",
            "enderReme": {
              "xLgr": "AV PAULISTA",
              "nro": "1500",
              "xBairro": "BELA VISTA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01310200",
              "UF": "SP"
            }
          },
          "dest": {
            "CNPJ": "22222222000122",
            "IE": "ISENTO",
            "xNome": "EMPRESA DESTINATARIA LTDA",
            "fone": "2133334444",
            "enderDest": {
              "xLgr": "AV RIO BRANCO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3304557",
              "xMun": "RIO DE JANEIRO",
              "CEP": "20040002",
              "UF": "RJ"
            }
          },
          "vPrest": {
            "vTPrest": 1500.00,
            "vRec": 1500.00,
            "Comp": [
              { "xNome": "FRETE PESO", "vComp": 1500.00 }
            ]
          },
          "imp": {
            "ICMS": {
              "ICMSSN": { "CST": "90", "indSN": 1 }
            },
            "vTotTrib": 0
          },
          "infCTeNorm": {
            "infCarga": {
              "vCarga": 10000.00,
              "proPred": "PRODUTOS DIVERSOS",
              "infQ": [
                { "cUnid": "01", "tpMed": "PESO BRUTO", "qCarga": 1000.0000 }
              ]
            },
            "infDoc": {
              "infNFe": [
                { "chave": "35260526638419000167550030000006561341688760" }
              ]
            },
            "infModal": {
              "versaoModal": "4.00",
              "rodo": {
                "RNTRC": "12345678"
              }
            }
          }
        }

Success response

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

Rejection response

        {
          "success": false,
          "message": "Rejeicao: ...",
          "data": {
            "cStat": "539",
            "chCTe": "",
            "nProt": "",
            "xml": ""
          }
        }

POST /api/cte/cancel

Cancel CT-e

Cancels an authorized CT-e (event 110111). Requires that the CT-e has been authorized (has a protocol) and is not yet cancelled.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chCTe *	string	Access key of the CT-e (44 digits)
xJust *	string	Cancellation justification (minimum 15 characters as required by SEFAZ)
nProt	string	Authorization protocol. Optional: when omitted, uses the protocol registered at issuance

* Required field.

Example payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xJust": "Cancelamento por erro no preenchimento dos dados da prestacao"
        }

Success response

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123457",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/cce

Correction Letter (CC-e)

Registers an Electronic Correction Letter (event 110110) on an authorized CT-e. The CC-e cannot correct values that impact the tax, registration data that change the issuer/service taker/sender/recipient, or the issuance date. Each correction indicates the group, field and new value.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chCTe *	string	Access key of the CT-e (44 digits)
infCorrecao[] *	array	Corrections (minimum 1, up to 20)
infCorrecao[].grupoAlterado *	string	Changed group (e.g.: `"ide"`, `"rem"`, `"dest"`)
infCorrecao[].campoAlterado *	string	Changed field (e.g.: `"xNome"`)
infCorrecao[].valorAlterado *	string	New value
infCorrecao[].nroItemAlterado	int	Number of the changed item (when the group is a list)

* Required field. The condition of use (xCondUso) is filled in automatically by the server.

Example payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "infCorrecao": [
            {
              "grupoAlterado": "compl",
              "campoAlterado": "xObs",
              "valorAlterado": "OBSERVACAO CORRIGIDA"
            }
          ]
        }

Success response

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123458",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/desacordo

Service Disagreement

Registers the Service Provision Disagreement (event 610110) — used by the service taker to declare that the provision described in the CT-e is in disagreement with what was contracted. The CNPJ that registers the event (the service taker) is that of the token's company; it does not need to be the issuer of the CT-e.

Required headers

Header	Type	Description
token	string	Token of the company (service taker)
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chCTe *	string	Access key of the CT-e (44 digits)
xObs *	string	Description of the disagreement (minimum 15 characters)

* Required field. The disagreement operation indicator is always 1 (PL-CTe v4.00).

Example payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xObs": "Valor do frete cobrado diverge do contratado entre as partes"
        }

Success response

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123459"
          }
        }

POST /api/cte/consult

Consult the status of the CT-e

Consults the status of the CT-e at SEFAZ from the access key. When the CT-e is cancelled (local record), the response reflects the cancellation.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
chCTe *	string	Access key of the CT-e (44 digits)

* Required field.

Example payload

        {
          "chCTe": "35260626638419000167570010000000011123456780"
        }

Response

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

POST /api/cte/inutilize

Void a numbering range

Voids a range of CT-e numbering that will not be used (for example, after a sequence break). Voiding is permanent.

Required headers

Header	Type	Description
token	string	Token of the issuing company
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Field	Type	Description
tpAmb *	int	Environment: `1`=production, `2`=staging
CNPJ *	string	Issuer's CNPJ (14 digits)
ano *	int	Numbering year (2 digits, e.g.: `26` for 2026)
serie *	int	Numbering series
nCTIni *	long	Start number of the range
nCTFin *	long	End number of the range (≥ `nCTIni`)
xJust *	string	Justification (minimum 15 characters)
mod	int	Model. Default: `57`

* Required field.

Example payload

        {
          "tpAmb": 2,
          "CNPJ": "26638419000167",
          "ano": 26,
          "serie": 1,
          "nCTIni": 51,
          "nCTFin": 55,
          "xJust": "Quebra de sequencia na numeracao por falha no sistema emissor"
        }

Success response

        {
          "success": true,
          "message": "Inutilizacao de numero homologado",
          "data": {
            "cStat": "102",
            "chCTe": "",
            "nProt": "135260000123460"
          }
        }

GET /api/cte/get_list

List CT-e (paginated)

Lists the company's CT-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: `"Success"` (authorized), `"Canceled"` (canceled), `"Processing"` (processing), `"Failed"` (failed), `"Unknown"` (unknown)

* Required field.

Call example

GET /api/cte/get_list?page=1&page_size=20&status=Success

Response

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190570010000000011000000019",
                "serie": 1,
                "number": 1,
                "modal": "01",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

vpn_key SSO — Automatic Login via Token

Base URL (Production)

https://api.tffiscal.com

Authentication

Headers: sign, timestamp, token

Ticket Validity

60 seconds — single use

SSO (Single Sign-On) allows your ERP to generate a direct access link to TFiscal for the user, already authenticated in the corresponding company and in the desired language — without requiring them to enter credentials.

How it works:

The ERP calls POST /api/sso/create_ticket sending the company token.
TFiscal returns a redirectUrl containing a single-use opaque ticket.
The ERP redirects the user's browser to that URL.
The page consumes the ticket and the user logs in automatically on the company panel.

⚠️ Security: the actual company token never appears in the URL. Only the ephemeral ticket (valid for 60 seconds and single use) is exposed to the browser.

POST /api/sso/create_ticket

Generate automatic login link

Generates a single-use ticket that can be used within 60 seconds to automatically log the user into the company panel matching the token.

Required Headers

Header	Type	Description
token	string	Company token (same as used to issue NF-e)
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Payload

        {
          "token": "TOKEN_DA_EMPRESA",
          "language": "br",
          "page": "emitir_nfe"
        }

Fields

Field	Required	Type	Description
token	Yes	string	Company token (`w_company.token`) — same one used in `/api/invoice/create`
language	No	string	UI language: `br`, `en`, `zh`, `es`, `ja`, `ko`. Default: `br`
page	No	string	Landing page after login. Accepted values: `emitir_nfe`. Empty or missing opens the default panel (`/company/kanban`).

Success Response

        {
          "success": true,
          "message": "ticket",
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
          "redirectUrl": "https://www.tffiscal.com/sso#ticket=nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
          "expiresInSeconds": 60,
          "expiresAt": "2026-04-24T18:34:56.0000000Z"
        }

Response Fields

Field	Type	Description
success	boolean	`true` when the ticket was successfully generated
ticket	string	Opaque ticket (random, 32 bytes base64url)
redirectUrl	string	Full URL where the ERP should redirect the user's browser
expiresInSeconds	number	Validity in seconds (always 60)
expiresAt	string	UTC expiration date/time (ISO 8601)

Error Responses

Message	Cause
`Token is required`	The `token` field was not sent in the body
`Invalid token`	Token does not match any registered company
`This token is linked to multiple companies. Send the specific company token you want to access.`	Integrator token with more than one company — send the specific company token
`Rate limit exceeded`	More than 30 calls per minute for the same token

POST /api/sso/consume_ticket

Consume ticket and receive the session JWT

Exchanges the ticket generated by /api/sso/create_ticket for the TFiscal session JWT. This endpoint is called by the frontend (route /sso) and does not require sign/timestamp headers — the opaque ticket itself is the credential. Each ticket can be consumed only once and expires in 60 seconds.

Body

Field	Type	Description
ticket *	string	Ticket returned by `create_ticket`

* Required field.

Payload example

        {
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg"
        }

Success response

        {
          "success": true,
          "message": "Login succeeded",
          "access_token": "eyJhbGciOi...",
          "type": "user",
          "uid": 1234,
          "company_id": 5678,
          "language": "br",
          "page": "emitir_nfe"
        }

Response fields

Field	Type	Description
access_token	string	Session JWT (365-day validity). Use in the `Authorization` header of TFiscal calls
type	string	User type (`user`, `admin`, etc.)
uid	int	Internal user ID
company_id	int	ID of the company selected in `create_ticket`
language	string	Language chosen in `create_ticket` (always normalized)
page	string	Target page (or empty string if not set)

Error responses

Message	Cause
`Ticket inválido`	Body without `ticket` field
`Ticket inválido ou expirado`	Ticket does not exist, has already been consumed, or is past the 60-second limit
`Rate limit exceeded`	More than 60 consumes per minute from the same IP
`Sessão inválida`	The user linked to the ticket no longer exists

lock Restrictions and Security

Ticket characteristics

Characteristic	Value
Validity	60 seconds after generation
Usage	Single use — once consumed, cannot be reused
Rate limit	30 tickets/minute per token · 60 consumptions/minute per IP
Storage	MongoDB with automatic TTL — expired tickets are removed

Navigation restrictions

Users logged in via SSO have access only to the corresponding company screens (/invoice/company/*). Attempts to access other areas (reseller panels, general reports, administration) are automatically redirected to the company panel.

Session after login

After exchanging the ticket for a JWT, the user has a normal TFiscal session (JWT valid for 365 days, same as traditional login). The 60 seconds are only the window between generating the ticket and opening the link — afterwards the user remains logged in normally until they sign out.

⚠️ Important: the create_ticket must be called exclusively server-side by the ERP. Never call this endpoint directly from the browser — that would expose the company token in the front-end.

badge Accountant (Contador)

API for retrieving accountant registration data linked to a company. Useful for external accounting systems that need to fetch the complete data of the accountant responsible for a given company.

POST /api/accountant/get_info

Get information of the accountant linked to the company

Returns the complete registration data of the accountant linked to the given company. The accountant must be previously linked to the company (same CNPJ) and the email must match the registration.

Required headers

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

Body

Field	Type	Description
companyId *	int	ID of the company linked to the token
accountantId *	string	Accountant ObjectId (24 hex chars)
email *	string	Accountant email (must match the registration)

* Required field.

Payload example

        {
          "companyId": 12345,
          "accountantId": "5f3a8b9c1d2e4f5a6b7c8d9e",
          "email": "contador@escritorio.com"
        }

Success response

        {
          "success": true,
          "data": {
            "email": "contador@escritorio.com",
            "officeDocumentType": "CNPJ",
            "officeDocument": "12345678000199",
            "officeName": "Escritório Contábil LTDA",
            "responsibleName": "João da Silva",
            "crc": "SP123456/O-7",
            "accountantCpf": "12345678909",
            "workAddress": "Rua Exemplo, 100 - Centro - São Paulo/SP",
            "site": "https://escritorio.com",
            "landline": "1133334444",
            "mobile": "11999998888",
            "assistantName": "Maria Souza",
            "assistantEmail": "maria@escritorio.com",
            "assistantPhone": "11988887777",
            "observations": "Atendimento de segunda a sexta, 9h às 18h"
          }
        }

Response fields

Field	Type	Description
email	string	Primary accountant email
officeDocumentType	string	Office document type: "CNPJ" or "CPF"
officeDocument	string	Office document (digits only)
officeName	string	Office corporate / business name
responsibleName	string	Name of the responsible accountant
crc	string	CRC number (Brazilian Regional Accounting Council)
accountantCpf	string	Accountant CPF (digits only)
workAddress	string	Business address
site	string	Office website
landline	string	Landline phone
mobile	string	Mobile phone
assistantName	string	Assistant name
assistantEmail	string	Assistant email
assistantPhone	string	Assistant phone
observations	string	Free-form registration notes

Error responses

Message	Cause
会计师ID参数异常或不存在	`accountantId` missing or not a valid ObjectId
该会计师邮箱异常或不存在	`email` invalid or not registered
发票账号{companyId}异常或不存在	`companyId` does not belong to the token user
该会计师未绑定该发票账号	Accountant is not linked to the given company

verified_user CPF and CNPJ Validation

API that validates CPF and CNPJ against the official Brazilian Federal Revenue (Receita Federal) database. For CPF, returns name, registration status, age and automatic blocking of minors (LGPD compliance). For CNPJ, returns corporate name, trade name, address, shareholders and full registration status. Recommended to validate registration data before issuing fiscal documents and to identify taxpayers with irregular status (suspended, cancelled, dropped).

POST /api/invoice/validar_cpf_cnpj

Validate CPF (with date of birth) or CNPJ against the official Brazilian Federal Revenue database

Accepts CPF or CNPJ, with or without formatting. The document type is detected automatically. For CPF, dataNascimento is required.

Required headers

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

Body

Field	Type	Description
cpfCnpj *	string	CPF (11 digits) or CNPJ (14 characters). Formatting is accepted.
dataNascimento	string	Date of birth — required only for CPF. Accepted formats: `dd/MM/yyyy`, `dd-MM-yyyy` or `ddMMyyyy`.

* Required field.

Payload example — CPF

        {
          "cpfCnpj": "407.105.368-28",
          "dataNascimento": "09/01/1997"
        }

Payload example — CNPJ

        {
          "cpfCnpj": "03.354.151/0001-36"
        }

Response — CPF found, regular status

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "nome": "FULANO DE TAL",
            "situacao_codigo": "0",
            "situação_descricao": "REGULAR",
            "menor_de_idade_lgpd": false,
            "idade": 29,
            "data_nascimento": "1997-01-09"
          }
        }

Response — CPF of a minor (LGPD)

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "situação_descricao": "Menor de idade",
            "menor_de_idade_lgpd": true
          }
        }

Response — CPF not found

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "Situação": "CPF não encontrado"
          }
        }

Response — Date of birth does not match CPF

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "Situação": "Data de nascimento não confere com o CPF"
          }
        }

Response — CNPJ found

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "03354151000136",
            "nome": "EMPRESA EXEMPLO LTDA",
            "situacao_codigo": "2",
            "situação_descricao": "Ativo",
            "nome_empresarial": "EMPRESA EXEMPLO LTDA",
            "nome_fantasia": "EXEMPLO",
            "data_situacao": "20180515",
            "motivo_situacao": ""
          }
        }

Response — CNPJ not found

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "12345678000199",
            "Situação": "Não encontrado"
          }
        }

CPF Status Codes

Code	Description
0	REGULAR (active)
2	SUSPENDED
3	HOLDER DECEASED
4	PENDING REGULARIZATION
5	CANCELLED FOR DUPLICATION
8	NULL
9	CANCELLED BY AUTHORITY

CNPJ Status Codes

Code	Description
1	Null
2	Active
3	Suspended
4	Unfit
8	Dropped

Error responses

Message	Cause
cpfCnpj é obrigatório	`cpfCnpj` field missing or empty
CPF inválido, verifique a quantidade de dígitos	The provided CPF does not have 11 digits
CPF inválido	The provided CPF has invalid check digits or contains letters
CNPJ inválido, verifique a quantidade de dígitos	The provided CNPJ does not have 14 characters
CNPJ inválido	The provided CNPJ has invalid check digits
é necessário informar a data de nascimento	CPF sent without `dataNascimento`
dataNascimento inválida (use dd/MM/yyyy)	Date format does not match any accepted pattern

NFE API Documentation

Important API Fields

Invoice Issuance Process Flow

1. Create Company

2. Information Push

3. Issue Invoice

4. Return Result

5. Generate Files

Fiscal Verification

Success

Failure

Endpoint Quick Reference

Success

Client Error

Server Error

NFE API

sync_alt System Flow

input Input Data

settings Processing

download Output

Main Endpoints

Required headers

Body

Payload example

Response

Required headers

Body

Payload example

Response

Required headers

Body

Payload example

Example — enable NFC-e and CT-e for the company

Response

Required headers

Query string

Call example

Response

Required headers

Call example

Response

Required headers

Query string

Call example

Response

Required headers

Call example

Response

Response example

Required headers

Body — top-level fields

Body — cliente (object, required)

Body — products[] (array, at least 1 item)

Body — products[].impostos / products[].tax_info

Body — products[].ii (Import Tax)

Body — products[].import_declarations[]

Body — shipping_address / delivery_address (objects, optional)

Body — transportation (object, optional)

Body — pag_info[] (array, optional)

Simplified example

Complete example (all fields)

Required headers

Query string

Call example

Response

Required headers

Query string

Call example

Response

Required headers

Body

Payload example

Required headers

Body

Payload example

Required headers

Body

Payload example

Required headers

Body

Body — `cliente` (object, required)

Body — `products[]` (array, at least 1 item)

Body — `products[].impostos` / `products[].tax_info`

Body — `products[].ii` (Import Tax)

Body — `products[].import_declarations[]`

Body — `shipping_address` / `delivery_address` (objects, optional)

Body — `transportation` (object, optional)

Body — `pag_info[]` (array, optional)

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` and `cofins[]` (same structure)

Body — `ibs_cbs[]` (Tax Reform)

Body — `is[]` (Selective Tax)