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
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
account_balance Accountant Management

📋 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
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": "contact@company.com",
          "cep": "01001000",
          "address": "Example Street",
          "house_number": "100",
          "town": "Downtown",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://example.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 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://example.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.

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

* Required field. Sending cnpj returns an error.

Payload example

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

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": "contact@example.com",
                "cep": "01001000",
                "address": "Example Street",
                "house_number": "100",
                "town": "Downtown",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://example.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": "contact@example.com",
            "cep": "01001000",
            "address": "Example Street",
            "house_number": "100",
            "town": "Downtown",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://example.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: `"Authorized"`, `"Canceled"`, `"Processing"`, `"Rejected"`, etc.)

* Required field.

Call example

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

Response

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Authorized",
                "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. 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

* Required field.

Call example

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

Response

        {
          "success": true,
          "data": {
            "id": "order-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Authorized",
            "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" }]
        }

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) or partial/custom return (provide the full body via return_detail).

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 (required if `chave` is absent; not used in `return_detail` mode)
chave	string	44-digit access key of the original NF-e (required in `return_detail` mode; alternative to `uuid` in simple mode)
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`
return_detail	object	Full body of the return NF-e. Same structure as `/api/invoice/create`, with one quirk: inside `return_detail.cliente` the address number field is `number` (in English), not `numero`. When absent, the return is a full clone of the original NF-e.

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

Example — full return

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

Example — partial return via return_detail

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "Devolução parcial",
          "return_detail": {
            "nature_of_operation": "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": "Sale of goods",
  "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": "Example Street",
    "number": "123",
    "complemento": "Room 45",
    "bairro": "Downtown",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01234567",
    "telefone": "11999999999",
    "email": "contact@company.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": "Carrier Street",
      "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": "Sender Street",
    "number": "100",
    "bairro": "Downtown",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01001000"
  },
  "delivery_address": {
    "cnpj": "98765432000111",
    "name": "Destinatário Ltda",
    "endereco": "Recipient Street",
    "number": "200",
    "bairro": "Downtown",
    "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 mentioned in screenshots, 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).

vpn_key Authentication

All requests must include the following headers:

Header	Type	Required	Description
Content-Type	string	Yes	application/json;charset=utf-8
sign	string	Yes	Request digital signature
timestamp	string	Yes	Request UTC timestamp
token	string	Yes	Authentication token

Note: For creating company and getting company list, use distributor token (b2b_token).

Signature Algorithm (SIGN)

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

Important: When calculating the sign, the Path includes the query string for GET requests. Example: /api/nfce/category/get_detail?category_id=TF123. For POST requests, the Path is just the route (e.g., /api/company/create).

percent Detailed Tax Parameters

scale_balance ICMS Parameters

Taxation Scenario

default output_outside_state output_inside_state input_outside_state input_inside_state

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

default output_outside_state output_inside_state input_outside_state input_inside_state

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`	Cash
`1`	Credit

Payment Methods

`01`	Cash
`02`	Check
`03`	Credit Card
`04`	Debit Card
`05`	Store Credit
`10`	Meal Voucher
`11`	Food Voucher
`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

Other Endpoints

4. List Categories: GET /api/category/get_list

5. Category Details: GET /api/category/get_detail

6. Edit Category: POST /api/category/edit

7. Delete Category: POST /api/category/delete

CFOP Examples (Fiscal Operation Code):

5102: Sale of merchandise acquired from third parties - within state

6102: Sale of merchandise acquired from third parties - to another state

6108: Sale of merchandise acquired from third parties - to another state (individual)

1000: Merchandise entry

speed

Limits and Rate Limiting

API usage policies

Limits by Plan

Free Plan	100 requests/day
Basic Plan	1,000 requests/day
Pro Plan	10,000 requests/day
Enterprise Plan	Customized

Values for `transport_mode`:

0: Freight contracted by Sender (CIF)

1: Freight contracted by Recipient (FOB)

2: Freight contracted by Third Party

3: Own Transport by Sender

4: Own Transport by Recipient

9: No Transportation Occurrence

CFOP Examples (Fiscal Operation Code):

5102: Sale of merchandise acquired from third parties - within state

6102: Sale of merchandise acquired from third parties - to another state

6108: Sale of merchandise acquired from third parties - to another state (individual)

1000: Merchandise entry

assessment NFe Reports

Generate detailed reports of issued Electronic Invoices (NF-e), with filters by period, status and operation type. Ideal for fiscal monitoring, audits and management control.

1. Issued Invoices Report

GET /api/invoice/report

Request Parameters (Query)

Parameter	Required	Type	Description
company_id	Yes	String	Company ID
start_date	Yes	Date	Period start date (YYYY-MM-DD)
end_date	Yes	Date	Period end date (YYYY-MM-DD)
status	No	String	Filter by status: `AUTHORIZED`, `CANCELED`, `DENIED`, `ALL` (default)
model	No	String	Document model: `nfe`, `nfce`, `all` (default)
format	No	String	Output format: `json` (default), `csv`, `pdf`
page	No	Integer	Page number (default: 1)
per_page	No	Integer	Records per page (default: 50, max: 200)

Request Example

GET /api/invoice/report?company_id=comp_123456&start_date=2024-01-01&end_date=2024-01-31&status=AUTHORIZED&format=json

Response Example

{
  "success": true,
  "data": {
    "summary": {
      "total_invoices": 152,
      "total_value": 458320.50,
      "authorized": 145,
      "canceled": 5,
      "denied": 2
    },
    "invoices": [
      {
        "invoice_id": "nf_789012",
        "number": 1045,
        "series": 1,
        "access_key": "35210112345678901234...",
        "status": "AUTHORIZED",
        "issue_date": "2024-01-10T10:30:00Z",
        "total_value": 3000.00,
        "customer_name": "Empresa Cliente Ltda",
        "customer_document": "12.345.678/0001-99",
        "nature_of_operation": "VENDA",
        "model": "nfe"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total_pages": 4,
      "total_records": 152
    }
  }
}

2. Period Summary Report

GET /api/invoice/report/summary

Returns a consolidated summary of fiscal operations grouped by month, with totals for value, quantity and taxes.

Request Parameters (Query)

Parameter	Required	Type	Description
company_id	Yes	String	Company ID
year	Yes	Integer	Reference year (e.g.: 2024)
group_by	No	String	Group by: `month` (default), `week`, `day`

Response Example

{
  "success": true,
  "data": {
    "company_id": "comp_123456",
    "year": 2024,
    "periods": [
      {
        "period": "2024-01",
        "total_invoices": 152,
        "total_value": 458320.50,
        "total_tax": 82497.69,
        "authorized": 145,
        "canceled": 5,
        "denied": 2
      },
      {
        "period": "2024-02",
        "total_invoices": 178,
        "total_value": 523180.75,
        "total_tax": 94172.54,
        "authorized": 170,
        "canceled": 6,
        "denied": 2
      }
    ]
  }
}

3. Export Report

POST /api/invoice/report/export

Generates and exports the full report in PDF or CSV format. The export is processed asynchronously and returns a download URL when completed.

Payload Request

{
  "company_id": "comp_123456",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "format": "pdf",
  "status": "ALL",
  "include_details": true,
  "include_taxes": true
}

Response Example

{
  "success": true,
  "message": "Report processing",
  "data": {
    "report_id": "rpt_abc123",
    "status": "processing",
    "estimated_time": "30s",
    "callback_url": "https://api.tffiscal.com/v1/report/status/rpt_abc123"
  }
}

Response After Processing

{
  "success": true,
  "data": {
    "report_id": "rpt_abc123",
    "status": "completed",
    "download_url": "https://storage.tffiscal.com/reports/rpt_abc123.pdf",
    "expires_at": "2024-02-01T23:59:59Z",
    "file_size": "2.4 MB"
  }
}

💡 TIP: Use the format=csv parameter to integrate data with ERP systems or spreadsheets. The PDF format is ideal for presentations and fiscal audits.

⚠️ WARNING: The maximum allowed period per query is 12 months. For full annual reports, use the export endpoint (/report/export). Queries with large data volumes may take a few seconds to process.

vpn_key TF Hub Global Authentication

All TF Hub APIs use a unified authentication system.

Required Headers

Header	Value	Description
X-API-Key	String	API key provided in dashboard
X-Timestamp	Unix Timestamp	Request timestamp in milliseconds
X-Signature	String	HMAC-SHA256 signature

point_of_sale NFC-e — Electronic Consumer Invoice

Base URL (Production)

https://api.tffiscal.com

Authentication

Headers: sign, timestamp, token

Requirements

Valid A1 Digital Certificate (.pfx or .p12)
CSC (Taxpayer Security Code)
CSC ID (CSC Identifier at SEFAZ)

NFC-e (model 65) is the electronic fiscal document for retail sales to end consumers, either in-person or via home delivery. It replaces the old fiscal coupon (ECF).

NFC-e Characteristics:

Always an intrastate operation — no DIFAL
No IPI (Industrialized Product Tax)
Recipient is optional for in-person sales (ind_pres: "1")
Recipient is required for home delivery (ind_pres: "4")
Requires CSC (Taxpayer Security Code) for QR Code generation

Authentication

All NFC-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)

Important: When calculating the sign, the path includes the query string for GET requests. Example: /api/nfce/category/get_detail?category_id=TF123. For POST requests, the path is just the route (e.g., /api/nfce/company/create).

compare_arrows NFe vs NFC-e — What Changes for Integrators?

If you have already integrated with NFe (model 55), integrating NFC-e (model 65) is very similar. Below are the key differences you need to know.

apartment Company Registration

Aspect	NFe `/api/company/create`	NFC-e `/api/nfce/company/create`
Basic fields	cnpj, name, alias, ie, invoice_type, address, digital certificate	Same as NFe — same required fields
CSC	Not used	Required — `csc_id` and `csc` (obtained from the SEFAZ portal)
Series / Numbering	`serie` and `number`	`serie_nfce` and `number_nfce` — independent numbering from NFe
Returned token	Same `token` — if the company already exists, the NFC-e fields are added automatically

Tip: If the company was already registered for NFe, just call /api/nfce/company/create with the same CNPJ. The system will recognize the existing company and add the NFC-e fields (CSC, series, numbering). The token remains the same.

receipt_long Invoice Emission

Aspect	NFe `/api/invoice/create`	NFC-e `/api/nfce/create`
Recipient	Always required (CNPJ/CPF, name, full address)	Optional for in-person sales; required only for home delivery (`ind_pres: "4"`)
Presence indicator	Not used	Required — `ind_pres`: `"1"` in-person, `"4"` home delivery
Taxes calculated	ICMS, PIS, COFINS, IPI, DIFAL (interstate)	ICMS, PIS, COFINS — no IPI, no DIFAL (always intrastate)
CFOP	Varies (5xxx intrastate, 6xxx interstate)	Always 5xxx (intrastate) — e.g., `5102`
Payment	Optional	Required — `pag_info` with payment method (cash, PIX, card, etc.)
Product fields	Same — same structure (codigo, name, ncm, count, unit, unit_price, total_price, category_id, cfop, origem)
Cancellation	24-hour window	30-minute window (varies by state)
DANFE	A4 PDF	Thermal receipt (80mm roll) with QR Code

Summary: If you have already integrated NFe, to integrate NFC-e you just need to:

Register the company's CSC (/api/nfce/company/create)
Switch the emission endpoint to /api/nfce/create
Add ind_pres and pag_info to the payload
Remove IPI/DIFAL data (if present)

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://example.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "telefone": "11999999999"
        }

Response

        {
          "success": true,
          "message": "Company registered for 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": "Downtown Store - Branch 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

Response

        {
          "success": true,
          "message": "NFC-e company updated successfully"
        }

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": "Downtown Store",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contact@company.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Example Street",
            "house_number": "100",
            "complemento": "Room 5",
            "town": "Downtown",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://example.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": "Authorized",
            "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"
          }
        }

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": "BEVERAGES_DEFAULT",
      "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": "FOOD",
      "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": "Example",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contact@example.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "Example Street",
          "house_number": "86",
          "complemento": "Floor 2",
          "town": "Downtown",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://storage.example.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": "<PedidoEnvioRPS>...</PedidoEnvioRPS>",
    "nfseXml": "<RetornoEnvioRPS>...</RetornoEnvioRPS>"
  }
}

dpsXml: XML sent to the city hall/ADN. nfseXml: Return XML with the issuance result.

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": "NFE_KEY_HERE",
  "nature_of_operation": "Price supplement",
  "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": "YOUR_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": "NFE_KEY_HERE",
  "nature_of_operation": "Tax adjustment",
  "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": "YOUR_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": "Correct recipient name to Company 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.

local_shipping MDF-e — Manifesto Eletrônico de Documentos Fiscais

A API de MDF-e (modelo 58, layout PL-MDFe 3.00) permite emitir, consultar, cancelar e encerrar manifestos de transporte. O MDF-e agrega NF-es e/ou Linked CT-es a uma operação de transporte, suportando 4 modais: rodoviário, aéreo, aquaviário e ferroviário. Toda informação operacional (condutor, veículo, contratante, CIOT, vale-pedágio, pagamento) vai no corpo do /create — não há eventos de inclusão/alteração após a emissão.

Endpoint	Método	Descrição
`/api/mdfe/create`	POST	Issue MDF-e
`/api/mdfe/consult`	POST	Consultar situação do MDF-e
`/api/mdfe/cancel`	POST	Cancel MDF-e (até 24h após autorização)
`/api/mdfe/close`	POST	Close MDF-e (após finalizar viagem)

POST /api/mdfe/create

Issue MDF-e

Emite um MDF-e a partir do corpo enviado. Os campos serie, nMDF, cMDF, cDV, cUF, dhEmi, mod, tpEmis, procEmi, verProc são calculados automaticamente pelo servidor. O cliente envia apenas os campos de negócio.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Issuing company token
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp in seconds (5-minute window)

Body — raiz

Campo	Tipo	Descrição
ide *	object	Identificação do MDF-e
emit *	object	Issuer data
infModal *	object	Informações do modal (apenas UM dos quatro: `rodo`, `aereo`, `aquav`, `ferrov`)
infDoc *	object	Linked tax documents
tot *	object	Cargo totals
prodPred	object	Predominant cargo product
seg	array	Informações de seguro
lacres	array	MDF-e seals
autXML	array	CNPJs/CPFs authorized to access the XML
infAdic	object	Informações adicionais (fisco e contribuinte)
infRespTec	object	Responsável técnico (CNPJ, contato, email, etc.)

ide — Identificação

Campo	Tipo	Descrição
tpAmb *	int	Ambiente: `1`=produção, `2`=homologação
tpEmit *	int	Tipo do emitente: `1`=transportador, `2`=carga própria, `3`=prestador de serviço de transporte
modal *	string	Modal: `"1"`=rodoviário, `"2"`=aéreo, `"3"`=aquaviário, `"4"`=ferroviário
UFIni *	string	UF de início da viagem (2 letras)
UFFim *	string	Trip end UF
infMunCarrega[] *	array	Municípios de carregamento: `[{ cMunCarrega, xMunCarrega }]`
infPercurso[]	array	Route UFs: `[{ UFPer }]`
tpTransp	string	Tipo de transportador (rodoviário)
dhIniViagem	string	Data/hora de início da viagem (ISO 8601)
indCanalVerde	string	Green channel indicator
indCarregaPosterior	string	Later loading indicator

emit — Emitente

Campo	Tipo	Descrição
CNPJ ⚠	string	CNPJ do emitente (14 dígitos)
CPF ⚠	string	CPF do emitente (11 dígitos)
IE	string	Inscrição Estadual
xNome *	string	Razão social
xFant	string	Trade name
enderEmit	object	Endereço: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email }`

infModal — Modal Rodoviário (modal="1")

Campo	Tipo	Descrição
rodo.veicTracao *	object	Veículo de tração: `{ placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop }`
rodo.veicTracao.condutor[] *	array	Condutores: `[{ xNome, CPF }]` — mínimo 1
rodo.veicReboque[]	array	Veículos de reboque (mesma estrutura de veicTracao sem condutor)
rodo.infANTT	object	Informações da ANTT: `{ RNTRC, infCIOT[], valePed, infContratante[], infPag[] }`
rodo.codAgPorto	string	Código de agendamento no porto
rodo.lacRodo[]	array	Modal seals: `[{ nLacre }]`

infModal — Modal Aéreo (modal="2")

Campo	Tipo	Descrição
aereo.nac *	string	Aircraft nationality mark
aereo.matr *	string	Matrícula da aeronave
aereo.nVoo *	string	Número do voo
aereo.cAerEmb *	string	Código IATA do aeroporto de embarque
aereo.cAerDes *	string	Código IATA do aeroporto de destino
aereo.dVoo *	string	Flight date (YYYY-MM-DD)

infModal — Modal Aquaviário (modal="3")

Campo	Tipo	Descrição
aquav.irin *	string	IRIN da embarcação
aquav.tpEmb *	string	Vessel type (2 digits). Use values ≥ 10 to avoid Zeus internal `byte` truncation (e.g. `"10"`, `"11"`)
aquav.cEmbar *	string	Código da embarcação
aquav.xEmbar *	string	Nome da embarcação
aquav.nViag *	string	Voyage number. Cannot start with zero (schema validation) — use `"1"`, `"100"`, etc.
aquav.cPrtEmb *	string	Código do porto de embarque
aquav.cPrtDest *	string	Código do porto de destino
aquav.prtTrans	string	Transshipment port
aquav.tpNav	string	Tipo de navegação
aquav.infTermCarreg[]	array	Loading terminals: `[{ cTermCarreg, xTermCarreg }]`
aquav.infTermDescarreg[]	array	Unloading terminals
aquav.infEmbComb[]	array	Embarcações de comboio: `[{ cEmbComb, xBalsa }]`
aquav.infUnidCargaVazia[]	array	Empty cargo units
aquav.infUnidTranspVazia[]	array	Empty transport units

infModal — Modal Ferroviário (modal="4")

Campo	Tipo	Descrição
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 constraints: `serie` must be exactly 3 digits (use 100+, e.g. `"100"`); `nVag` accepts digits only (`long` internally, e.g. `"100001"`); `nSeq` optional 1-3 digits.

infDoc — Documentos vinculados

Campo	Tipo	Descrição
infMunDescarga[] *	array	Municípios de descarga — mínimo 1
infMunDescarga[].cMunDescarga *	string	Código IBGE do município
infMunDescarga[].xMunDescarga *	string	Nome do município
infMunDescarga[].infNFe[]	array	Linked NF-es: `[{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }]`
infMunDescarga[].infCTe[]	array	Linked CT-es
infMunDescarga[].infMDFeTransp[]	array	MDF-es de transporte (subcontratação)

prodPred — Produto predominante

Campo	Tipo	Descrição
tpCarga *	string	Tipo de carga: `"01"`=granel sólido, `"02"`=granel líquido, `"03"`=frigorificada, `"04"`=conteinerizada, `"05"`=carga geral, `"06"`=neogranel, `"07"`=perigosa, `"08"`=granel pressurizado
xProd *	string	Descrição do produto predominante
cEAN	string	GTIN/EAN
NCM	string	NCM
infLotacao	object	Lotação: `{ infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} }`

tot — Totalizadores

Campo	Tipo	Descrição
vCarga *	decimal	Total cargo value (> 0)
cUnid *	string	Código da unidade: `"01"`=KG, `"02"`=TON
qCarga *	decimal	Total cargo quantity (> 0)
qCTe	int	Quantidade de Linked CT-es
qNFe	int	Number of linked NF-es
qMDFe	int	Number of linked MDF-es

* Campo obrigatório. ⚠ Pelo menos um de CNPJ ou CPF é obrigatório.

Exemplo simplificado — Modal Rodoviário

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

Exemplo simplificado — Modal Aéreo

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

Exemplo simplificado — Modal Aquaviário

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

Exemplo simplificado — Modal Ferroviário

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

Exemplo completo (todos os campos) — Modal Rodoviário

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

Consultar situação do MDF-e

Consulta a situação do MDF-e diretamente na SEFAZ a partir da chave de acesso.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Issuing company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Campo	Tipo	Descrição
chMDFe *	string	Chave de acesso do MDF-e (44 dígitos)

* Campo obrigatório.

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

Cancela um MDF-e autorizado. Janela: até 24 horas após a autorização. Não permitido se o MDF-e já tiver sido encerrado.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Issuing company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Campo	Tipo	Descrição
chMDFe *	string	Chave de acesso do MDF-e (44 dígitos)
xJust *	string	Justificativa do cancelamento (mínimo 15 caracteres por exigência SEFAZ)

* Campo obrigatório.

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

Encerra um MDF-e ao final da viagem. Após o encerramento, não é mais possível cancelar. Os campos dtEnc, cUF e cMun são opcionais — quando omitidos, o sistema infere a partir do MDF-e original (data atual, UF e município do emitente).

Headers obrigatórios

Header	Tipo	Descrição
token	string	Issuing company token
sign	string	MD5 signature
timestamp	string	Unix timestamp in seconds

Body

Campo	Tipo	Descrição
chMDFe *	string	Chave de acesso do MDF-e (44 dígitos)
dtEnc	string	Closing date (YYYY-MM-DD). Default: current date
cUF	int	Código IBGE da UF onde ocorreu o encerramento. Default: UF do emitente
cMun	string	Código IBGE do município onde ocorreu o encerramento. Default: município do emitente

* Campo obrigatório.

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

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": "accountant@office.com"
      }

Success response

      {
        "success": true,
        "data": {
          "email": "accountant@office.com",
          "officeDocumentType": "CNPJ",
          "officeDocument": "12345678000199",
          "officeName": "Accounting Office LTDA",
          "responsibleName": "John Silva",
          "crc": "SP123456/O-7",
          "accountantCpf": "12345678909",
          "workAddress": "Example St, 100 - Downtown - São Paulo/SP",
          "site": "https://office.com",
          "landline": "1133334444",
          "mobile": "11999998888",
          "assistantName": "Mary Souza",
          "assistantEmail": "mary@office.com",
          "assistantPhone": "11988887777",
          "observations": "Available Monday to Friday, 9am to 6pm"
        }
      }

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

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

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

Payload example

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)