REST API v2.5 システム稼働中

NFE API ドキュメント

NFE APIドキュメントへようこそ。ブラジルの電子請求書（NF-e）の発行、照会、キャンセルのための完全なAPIです。自動税計算（ICMS、IPI、PIS/COFINS）、XML生成、SEFAZ認証、管理システムとの統合をサポートしています。

list_alt

重要なAPIフィールド

重要なフィールドの解釈

このセクションでは、請求書発行の正確な機能に不可欠なNFE APIの最も重要なフィールドについて説明します。

⚠️ ATTENTION: これらのフィールドの正確な設定は、有効な請求書発行の基本です。常に現行の税法を参照してください。

フィールド	説明	可能な値	重要度
`invoice_type`	会社タイプ（法人/個人）	`juridica`, `fisica`	高 - 税制を定義
`nature_of_operation`	取引の性質（販売、返品など）	Ex: `SALE`, `RETURN`	高 - CFOPを決定
`transaction_type`	取引タイプ（入力/出力）	`INPUT`, `OUTPUT`	高 - 税務フローを方向付け
`model`	請求書モデル	`nfe`, `nfce`	高 - 文書モデル
`issuance_type`	発行タイプ（通常、緊急）	`NORMAL`, `CONTINGENCY`	中 - 発行モード
`ambiente`	処理環境	`PRODUCTION`, `HOMOLOGATION`	高 - 送信先SEFAZを定義
`cliente`	顧客/購入者タイプ	`CONSUMER`, `TAXPAYER`	高 - 税金に影響
`products.origem`	製品原産地（国内/輸入）	`0` to `8`	高 - 課税を決定
`products.indicador_total`	製品が請求書合計に含まれるかどうか	`true`, `false`	中 - サンプル品用

💡 TIP: 製品の場合、origemフィールドは重要です: 0-国内、1-外国直接輸入、2-国内市場で取得した外国製品など。商品原産地の完全な表を参照してください。

sync_alt

請求書発行プロセスフロー

完全なNF-e発行ダイアグラム

ブラジルの電子請求書発行の完全なフロー、企業作成から最終ファイル生成まで。

business

1. 企業登録

ブラジルの現地企業税務情報を作成

send

2. 情報送信

注文データ（ユーザー、住所、製品税）

receipt

3. 請求書発行

SEFAZ認証への処理と送信

assignment_returned

4. 結果返却

発行状態とNF-eデータ

description

5. ファイル生成

請求書のXMLとPDF

published_with_changes

税務検証

SEFAZでの検証

check_circle

Success

error

Failure

Initial Setup

Data Processing

Fiscal Issuance

Positive Results

📊 Detailed Flow: The process follows a logical 順序: (1) 企業設定 → (2) 注文データの受信 → (3) NF-eの処理と発行 → (4) 状態の返却 → (5) File generation. The decision point (税務検証) determines whether the issuance was authorized by SEFAZ.

flash_on

エンドポイントクイックリファレンス

すべてのNFE APIエンドポイント

利用可能なすべてのAPIエンドポイントの完全な概要です。このテーブルをクイックリファレンスとしてドキュメントを参照してください。

Base URL

https://api.tffiscal.com

パス	HTTPメソッド	機能
business 企業管理
`/api/company/create`	POST	企業登録
`/api/company/get_detail`	GET	企業照会
`/api/company/edit`	POST	企業変更
`/api/company/get_list`	GET	企業一覧
`/api/company/v2/create`	POST	企業登録（簡略化）
`/api/company/get_cep_detail`	GET	CEP検索
`/api/company/get_export_invoice_month_files`	GET	月次エクスポートファイル
category カテゴリ/税管理
`/api/category/get_list`	GET	税カテゴリ一覧
`/api/category/create`	POST	税カテゴリ作成
`/api/category/get_detail`	GET	カテゴリ詳細照会
`/api/category/edit`	POST	税カテゴリ編集
`/api/category/delete`	POST	税カテゴリ削除
receipt 請求書管理
`/api/invoice/create`	POST	請求書発行
`/api/invoice/get_list`	GET	請求書一覧
`/api/invoice/get_detail`	GET	請求書詳細照会
`/api/invoice/refresh`	POST	請求書状態更新
`/api/invoice/cancel`	POST	請求書キャンセル
`/api/invoice/invalid`	POST	請求書番号無効化
`/api/invoice/return`	POST	請求書返品
`/api/invoice/get_xml`	POST	請求書XMLエクスポート
receipt NFC-e (消費者電子請求書)
`/api/nfce/company/create`	POST	NFC-e企業登録
`/api/nfce/company/update`	POST	NFC-e企業更新
`/api/nfce/company/get`	POST	NFC-e企業照会
`/api/nfce/create`	POST	NFC-e発行
`/api/nfce/cancel`	POST	NFC-eキャンセル
`/api/nfce/get_detail`	POST	NFC-e照会
`/api/nfce/get_danfe`	POST	NFC-e DANFE取得
description NFS-e (サービス電子請求書)
`/api/nfse/create`	POST	NFS-e発行
`/api/nfse/cancel`	POST	NFS-eキャンセル
`/api/nfse/get_danfse`	POST	DANFSE取得 (PDF)
`/api/nfse/get_xml`	POST	NFS-e XMLダウンロード
account_balance 会計士管理

📋 重要事項:

すべてのエンドポイントはヘッダーによる認証が必要です: sign, timestamp, token
企業登録と企業一覧にはディストリビュータートークン（b2b_token）を使用してください
Content-Typeは常に次でなければなりません application/json;charset=utf-8
応答はJSON標準に従い、フィールド success, message and data

200

成功

リクエストが正常に処理されました

400

クライアントエラー

無効または欠落データ

500

サーバーエラー

内部サーバーエラー

account_balance

NFE API

ブラジル電子請求書 (NF-e)

ブラジルの電子請求書（NF-e）の発行、照会、キャンセルのための完全なAPIです。自動税計算（ICMS、IPI、PIS/COFINS）、XML生成、SEFAZ認証、管理システムとの統合をサポートしています。現在、ブラジル全土での製品請求書発行をサポートしています。

Base URL（本番環境）

https://api.tffiscal.com/v1

認証

Headers: sign, timestamp, token

要件

有効なA1デジタル証明書

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（補助文書）
Authorization status

主要エンドポイント

POST /api/company/create

新規発行企業の登録

ディストリビューター（b2b）アカウントに紐付く発行企業を登録します。会社データが既に揃っている場合に使用してください。デジタル証明書から自動抽出する場合は /api/company/v2/create を使用してください。

必須ヘッダー

ヘッダー	型	説明
token	string	ディストリビュータートークン（b2b — アカウントは `isb2b=true` である必要があります）
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
識別
cnpj *	string	発行企業の CNPJ
name *	string	会社名
ie *	string	州登録番号（Inscrição Estadual）
invoice_type *	string	税制（例: `"simples_nacional"`、`"normal"`）
unit *	string	単位タイプ
email	string	会社メールアドレス
住所
cep *	string	郵便番号
address *	string	通り住所
house_number *	string	住所番号
town *	string	地区
city *	string	市
state *	string	UF（州略称）
デジタル証明書
cert_file *	string	A1 デジタル証明書（.pfx または .p12）の HTTPS URL
cert_pwd *	string	証明書のパスワード
番号と設定
serie *	int	NF-e シリーズ
number *	int	番号の初期値
is_create_category_template	boolean	デフォルトの税カテゴリを自動作成。デフォルト: `true`

* 必須項目。

ペイロード例

        {
          "cnpj": "12345678000199",
          "name": "Empresa Exemplo LTDA",
          "ie": "123456789",
          "invoice_type": "simples_nacional",
          "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": "senha_do_certificado",
          "serie": 1,
          "number": 1
        }

レスポンス

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

POST /api/company/v2/create

証明書からの自動入力で会社を登録

/api/company/create の簡略版: API がデジタル証明書を検証し、会社名、IE、住所などのデータを内部照会で自動抽出します。cnpj、cert_file、cert_pwd のみ必須です。

必須ヘッダー

ヘッダー	型	説明
token	string	ディストリビュータートークン（b2b — アカウントは `isb2b=true` である必要があります）
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
cnpj *	string	発行企業の CNPJ
cert_file *	string	A1 デジタル証明書（.pfx または .p12）の HTTPS URL
cert_pwd *	string	証明書のパスワード
is_create_category_template	boolean	デフォルトの税カテゴリを自動作成。デフォルト: `true`

* 必須項目。

ペイロード例

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

レスポンス

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

POST /api/company/edit

会社データの編集

発行企業のデータを更新します。変更したい項目のみ送信してください — company_id 以外はすべて任意です。CNPJ は変更不可: 送信するとエラーを返します。cep を更新すると、システムが自動的に stateCode と ibge を解決します。cert_file と cert_pwd を一緒に送ると、証明書は保存前に検証されます。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
company_id *	string	編集する会社の ID
name	string	会社名
invoice_type	string	税制
ie	string	州登録番号
unit	string	単位タイプ
email	string	メールアドレス
cep	string	郵便番号（`stateCode` と `ibge` を自動更新）
address	string	通り住所
house_number	string	番号
town	string	地区
city	string	市
state	string	UF
cert_file	string	新しい証明書（.pfx または .p12）の HTTPS URL。`cert_pwd` と一緒に送ると、保存前に検証されます
cert_pwd	string	新しい証明書のパスワード
serie	int	新しい NF-e シリーズ
number	int	新しい初期番号

* 必須項目。cnpj を送るとエラーを返します。

ペイロード例

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

レスポンス

                {
                  "success": true
                }

GET /api/company/get_list

ディストリビューターの会社一覧

ディストリビューター（b2b）アカウントに紐付く発行企業をページネーション付きで一覧表示します。パラメータは クエリ文字列 で渡します。

必須ヘッダー

ヘッダー	型	説明
token	string	ディストリビュータートークン（b2b — アカウントは `isb2b=true` である必要があります）
sign	string	MD5 署名（path にクエリ文字列を含む）
timestamp	string	秒単位の Unix タイムスタンプ

クエリ文字列

パラメータ	型	説明
page *	int	ページ番号（≥ 1）
page_size *	int	ページサイズ（1–20）

* 必須項目。

呼び出し例

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

レスポンス

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

認証済み企業の詳細

token ヘッダーで識別された企業の完全なデータを返します。登録済みの税カテゴリ一覧を含みます。ボディもクエリ文字列も受け付けません。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

呼び出し例

GET /api/company/get_detail

レスポンス

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

CEP で住所を検索

ブラジルの CEP（郵便番号）を解決し、UF、IBGE 自治体コード、住所データを返します。会社や顧客の住所入力に便利です。ディストリビューター（b2b）アカウントが必要です。

必須ヘッダー

ヘッダー	型	説明
token	string	ディストリビュータートークン（b2b — アカウントは `isb2b=true` である必要があります）
sign	string	MD5 署名（path にクエリ文字列を含む）
timestamp	string	秒単位の Unix タイムスタンプ

クエリ文字列

パラメータ	型	説明
cep *	string	ブラジルの CEP（8 桁、ハイフン有無は問わない）

* 必須項目。

呼び出し例

GET /api/company/get_cep_detail?cep=01001000

レスポンス

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

生成済みの月次エクスポートファイル一覧

当年（タイムゾーン America/Sao_Paulo）に既に生成されている会社の月次エクスポートファイル一覧を返します。各月は最大 4 ファイルまで: Excel スプレッドシート 1 つ（ステータス Success のみ）+ XML 3 つ（ステータス Success、Canceled、Voided 別）。実際にエクスポートされたファイルのみがレスポンスに表示されます — 新しいものを生成するには /api/invoice/get_xml を使用してください。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

呼び出し例

GET /api/company/get_export_invoice_month_files

レスポンス

項目	型	説明
files[]	array	利用可能なファイル一覧
files[].url	string	OSS 上のファイル URL
files[].year	int	期間の年
files[].month	string	月（1–12）
files[].type	string	ファイルタイプ: `"xlsx"` または `"xml"`
files[].status	string	ファイル内のインボイスのステータス: `"Success"`、`"Canceled"`、`"Voided"`
files[].create	datetime	ファイル生成日時

レスポンス例

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

製品カテゴリ一覧

Returns all available categories for fiscal classification.

POST /api/invoice/create

新規請求書を発行

NF-e（モデル 55）を発行します。発行企業は token ヘッダーで識別されます。company_id はボディに含めないでください。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	秒単位の Unix タイムスタンプ（5 分間の有効期限）

Body — トップレベル項目

項目	型	説明
識別と取引
id	string	冪等性のためのクライアント側一意 ID（重複排除キーを構成）
nature_of_operation *	string	取引の性質（例: 「商品の販売」）
transaction_type *	string	種別: `"0"`=入庫、`"1"`=出庫、`"2"`=輸入、`"3"`=輸出
model *	string	ドキュメントモデル: `"55"`=NF-e
issuance_type *	string	発行種別（`"1"`=通常、`"9"`=コンティンジェンシー、など）
ambiente *	string	`"1"`=本番、`"2"`=ホモロゲーション
finalidade	string	用途: `"1"`=通常、`"2"`=補完、`"3"`=調整、`"4"`=返品
ref_nfe_chave	string	参照 NF-e の 44 桁アクセスキー（補完／調整／返品用）
is_reopen	boolean	発行済み NF-e を再オープン／上書きする
dh_sai_ent	string	出入庫日時（ISO 8601）。デフォルト: 現在のタイムスタンプ
金額と割引
total_discount_amount	decimal	請求書の合計割引額
troco	decimal	釣銭（NFC-e で一般的）
seguro	decimal	保険料（XML の `vSeg` として各製品に按分）
outras_despesas	decimal	その他費用（XML の `vOutro` として各製品に按分）
インジケーターと追加情報
ind_final	string	最終消費者: `"0"`=B2B、`"1"`=B2C
ind_pres	string	立会インジケーター: `"1"`=対面、`"2"`=インターネット、`"3"`=テレサービスなど
informacoes_complementares	string	補足情報（`infAdic.infCpl` に書き込まれます）
informacoes_fisco	string	税務当局向け情報（`infAdic.infAdFisco` に書き込まれます）

Body — `cliente`（オブジェクト、必須）

国内取引（transaction_type 0 または 1）の場合: cpf または cnpj、name、endereco、bairro（最小 2 文字）、city、uf、cep が必須です。輸入／輸出（transaction_type 2 または 3）の場合: name のみ必須です。

項目	型	説明
cpf	string	顧客の CPF（cnpj の代替）
cnpj	string	顧客の CNPJ（cpf の代替）
ie	string	州登録番号（Inscrição Estadual）
name *	string	会社名／顧客名
endereco	string	住所（通り）
complemento	string	住所の補足
numero	string	住所の番号
bairro	string	地区（国内取引では最小 2 文字）
city	string	市
uf	string	州（UF）— CEP から解決された UF で上書きされます
cep	string	郵便番号（UF と市を検証）
telefone	string	電話番号
email	string	メールアドレス
id_estrangeiro	string	外国 ID（輸入／輸出で使用）
c_pais	int	BACEN 国コード。デフォルト: `1058`（ブラジル）
x_pais	string	国名。デフォルト: `"BRASIL"`

Body — `products[]`（配列、最小 1 項目）

各製品には課税情報が必要です: category_id（事前登録済みの税カテゴリへの参照）、または impostos/tax_info オブジェクト（インライン設定）のいずれか。

項目	型	説明
codigo	string	製品の内部コード
name *	string	製品説明（CJK 文字は削除されます）
ncm *	string	8 桁の NCM
cest	string	CEST コード（ICMS-ST 適用時は必須）
gtin	string	GTIN／バーコード
gtin_tributavel	string	課税単位の GTIN
count *	decimal	数量
unit *	string	商用単位（例: "UN", "KG", "MT"）
unit_price *	decimal	単価
total_price *	decimal	項目の合計金額
discount_price	decimal	項目への割引
origem *	int	商品原産地（`0`=国内、`1`=外国—直接輸入など）
indicador_total *	int	NF-e の合計に含まれるか: `0`=いいえ、`1`=はい
category_id	string	事前登録済み税カテゴリ ID（`impostos`/`tax_info` を送らない場合は必須）
impostos	object	インライン税設定（`category_id` の代替）。構造は下記参照
tax_info	object	`impostos` のエイリアス（同じ構造）
disable_difal	boolean	この項目の DIFAL 計算を無効化
desconta_icms_pis_cofins	boolean	この品目のみ PIS/COFINS 課税標準から ICMS を控除（カテゴリ設定を上書き）
ii	object	輸入税 — CFOP 3.xxx の場合は必須。構造は下記参照
import_declarations	array	輸入申告書（DI） — `transaction_type="2"` の場合は必須。構造は下記参照
nItemPed	int	発注品目 (I61)。ルートの `id` から取得する `xPed` で参照される注文内の項目連番。有効範囲: 1–999999。デフォルト: 省略。

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

項目	型	説明
industria	string	基準の業種／税率（エイリアス: `aliquota`）
icms
icms.codigo_cfop	string	CFOP
icms.situacao_tributaria	string	ICMS の CST/CSOSN
icms.industria	string	ICMS 業種
icms.tipo_pessoa	string	人格区分（PF／PJ）
icms.codigo_beneficio_fiscal	string	cBenef（税制優遇コード）
ipi
ipi.codigo_enquadramento	string	IPI の法的位置付けコード
ipi.situacao_tributaria	string	IPI の CST
ipi.aliquota	string	IPI の税率
ipi.tipo_pessoa	string	人格区分
pis
pis.situacao_tributaria	string	PIS の CST
pis.aliquota	string	PIS の税率
pis.tipo_pessoa	string	人格区分
cofins
cofins.situacao_tributaria	string	COFINS の CST
cofins.aliquota	string	COFINS の税率
cofins.tipo_pessoa	string	人格区分
is（選択税）
is.cenario	string	IS シナリオ
is.situacao_tributaria	string	IS の CST
is.aliquota	string	IS の税率
is.tipo_pessoa	string	人格区分
ibs_cbs（税制改革）
ibs_cbs.situacao_tributaria	string	IBS/CBS の CST
ibs_cbs.tipo_pessoa	string	人格区分
ibs_cbs.classificacao_tributaria	string	IBS/CBS の税分類
difal
difal.disable_difal	boolean	項目の DIFAL を無効化（製品レベルの `disable_difal` の代替）

Body — `products[].ii`（輸入税）

項目	型	説明
vBC	decimal	II の計算基礎
vDespAdu	decimal	通関費用
vII	decimal	II 金額
vIOF	decimal	IOF 金額

Body — `products[].import_declarations[]`

項目	型	説明
nDI	string	DI 番号
dDI	string (date)	DI 日付
xLocDesemb	string	通関場所
UFDesemb	string	通関の州
dDesemb	string (date)	通関日
cExportador	string	輸出者コード
tpViaTransp	int	国際輸送モード
tpIntermedio	int	仲介種別
vAFRMM	decimal	AFRMM 金額
additions	array	DI の追加（項目: `nAdicao`、`nSeqAdic`、`cFabricante`、`vDescDI`、`nDraw`）

Body — `shipping_address` / `delivery_address`（オブジェクト、オプション）

shipping_address は受取場所（物理的な発送元、発行者と異なる場合）です。delivery_address は配送場所（物理的な配達先、顧客と異なる場合）です。指定する場合、両方とも以下が必須: cpf または cnpj、name、endereco、bairro（最小 2 文字）、city、uf、cep。両オブジェクトとも同じ構造です。

項目	型	説明
cpf	string	CPF（cnpj の代替）
cnpj	string	CNPJ（cpf の代替）
ie	string	州登録番号
name *	string	会社名／名前
endereco *	string	住所
complemento	string	補足
number	string	番号（注: フィールド名は `number` で、`numero` ではありません）
bairro *	string	地区
city *	string	市
uf *	string	州
cep *	string	郵便番号
telefone	string	電話番号
email	string	メールアドレス

Body — `transportation`（オブジェクト、オプション）

transportation を省略した場合、システムは transport_mode="9"（送料なし）と見なします。

項目	型	説明
transport_mode	string	送料区分: `"0"`=発行者負担、`"1"`=受取人負担、`"2"`=第三者負担、`"3"`=発送者自前輸送、`"4"`=受取人自前輸送、`"9"`=送料なし
freight_amount	decimal	送料合計
carrier_info — 運送業者
carrier_info.cpf	string	運送業者の CPF（cnpj の代替）
carrier_info.cnpj	string	運送業者の CNPJ（cpf の代替）
carrier_info.ie	string	州登録番号
carrier_info.name	string	会社名
carrier_info.endereco	string	住所
carrier_info.city	string	市
carrier_info.uf	string	州
carrier_info.cep	string	郵便番号
vehicle_info — 車両
vehicle_info.plate	string	ナンバープレート
vehicle_info.uf	string	ナンバープレートの州
vehicle_info.rntc	string	RNTC（国家貨物運送業者登録）
trailer_info — トレーラー（vehicle_info と同じ構造）
trailer_info.plate	string	トレーラーのプレート
trailer_info.uf	string	州
trailer_info.rntc	string	RNTC
packages[] — 容積物
packages[].qty	int	数量
packages[].gross_weight	decimal	総重量
packages[].net_weight	decimal	正味重量
packages[].packaging_type	string	梱包種別
packages[].number	string	番号
packages[].mark	string	マーク
packages[].seals	array<string>	封印
transport_tax_retention_info — 送料に対する ICMS の源泉徴収
transport_tax_retention_info.freight_service_amount	decimal	輸送サービス金額
transport_tax_retention_info.tax_base	decimal	源泉徴収の計算基礎
transport_tax_retention_info.tax_rate	decimal	源泉徴収率
transport_tax_retention_info.cfop	string	CFOP
transport_tax_retention_info.cep	string	郵便番号

Body — `pag_info[]`（配列、オプション）

省略した場合、システムは [{ "payment_method": "01", "payment_indicator": "0" }]（現金、一括）と見なします。

項目	型	説明
payment_method *	string	支払方法: `"01"`=現金、`"02"`=小切手、`"03"`=クレジットカード、`"04"`=デビットカード、`"05"`=店舗クレジット、`"10"`=食料品バウチャー、`"11"`=食事バウチャー、`"15"`=銀行振込票、`"17"`=PIX、`"90"`=無支払、`"99"`=その他
payment_indicator *	string	区分: `"0"`=一括、`"1"`=分割
payment_value	decimal	支払金額
card_info — カード情報（payment_method 03/04 用）
card_info.integration_type *	string	端末の連携種別（`card_info` 指定時は必須）
card_info.brand_code *	string	カードブランド（`card_info` 指定時は必須）
card_info.acquirer_cnpj	string	アクワイアラの CNPJ
card_info.authorization_code	string	承認コード

* 必須項目。

簡易例

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

完全な例(全フィールド)

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

NF-e の一覧（ページネーション）

会社の NF-e をページネーションで一覧表示します。パラメータは クエリ文字列 で渡します（ボディではありません）。時間フィルタは任意ですが、使用する場合は start_create_time と end_create_time の両方が必要です。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名（path にクエリ文字列を含む）
timestamp	string	秒単位の Unix タイムスタンプ

クエリ文字列

パラメータ	型	説明
page *	int	ページ番号（≥ 1）
page_size *	int	ページサイズ（1–50）
start_create_time	long	Unix タイムスタンプ（ミリ秒） — 開始（`end_create_time` が必要）
end_create_time	long	Unix タイムスタンプ（ミリ秒） — 終了
status	string	ステータスでフィルタ（値: `"Authorized"`、`"Canceled"`、`"Processing"`、`"Rejected"` など）

* 必須項目。

呼び出し例

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

レスポンス

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

NF-e の詳細を取得

UUID で特定の NF-e の詳細を返します。XML URL、DANFE URL（完全版、簡略版、ラベル版）およびメタデータを含みます。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名（path にクエリ文字列を含む）
timestamp	string	秒単位の Unix タイムスタンプ

クエリ文字列

パラメータ	型	説明
uuid *	string	NF-e の UUID

* 必須項目。

呼び出し例

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

レスポンス

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

請求書ステータスを更新

SEFAZ で NF-e の現在のステータスを照会し、ローカルの記録を更新します。発行が処理中またはコンティンジェンシーで残った場合に便利です。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
uuid *	string	照会する NF-e の UUID

* 必須項目。

ペイロード例

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/cancel

請求書をキャンセル

承認済みの NF-e をキャンセルします。SEFAZ に送られる正当化理由は固定です: "Erro no preenchimento da nota fiscal." — ペイロードでは設定できません。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
uuid *	string	キャンセルする NF-e の UUID（`/api/invoice/create` から返される内部識別子）

* 必須項目。

ペイロード例

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/invalid

番号範囲の無効化

承認されなかった NF-e 番号の連続範囲を無効化します（キャンセルと混同しないでください — キャンセルは承認済みの請求書に適用されます）。この操作は SEFAZ に記録され、元に戻せません。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
modelo *	string	ドキュメントモデル: `"55"`=NF-e、`"65"`=NFC-e。（注意: 項目名は `modelo` であり、`model` ではありません）
ambiente *	string	`"1"`=本番、`"2"`=ホモロゲーション
serie *	int	無効化する番号のシリーズ
start_number *	int	範囲の開始番号
end_number *	int	範囲の終了番号
motivo *	string	無効化の正当化理由（SEFAZ の要件により最少 15 文字）

* 必須項目。

ペイロード例

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

NF-e の DANFE(PDF)取得

NF-e の DANFE の 3 つの URL を返します:完全な DANFE(PDF)、簡易 DANFE の PDF(レシート形式)、簡易 DANFE の PNG(ラベル画像)。PDF は許可された XML からオンデマンドで生成され、OSS にキャッシュされます。後続の呼び出しでは、請求書のステータスが変更されていない場合、既存のキャッシュが返されます。ステータスが変更された場合(例:請求書がキャンセルされた)、PDF は再生成されます。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名:`MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ(秒、5 分のウィンドウ)

Body

フィールド	型	説明
uuid ⚠	string	NF-e の内部 UUID(`/api/invoice/create` から返される)
chave ⚠	string	NF-e のアクセスキー(44 桁)

⚠ uuid または chave のいずれかが必須。

ペイロード例

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

レスポンス

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

レスポンスフィールド

フィールド	型	説明
danfe	string	完全な DANFE PDF の URL(A4 形式)
danfe_simples	string	簡易 DANFE PDF の URL(レシート形式)
danfe_simples_png	string	簡易 DANFE PNG(ラベル画像)の URL

エラーレスポンス

メッセージ	原因
uuid/chave不能为空	`uuid` も `chave` も送信されていない
发票不存在	トークンユーザーの請求書が見つからない、または承認 XML がない
发票详情不存在	請求書の詳細(プロトコル付き)が見つからない
获取PDF失败:<理由>	XML から PDF の生成に失敗

POST /api/invoice/get_xml

XML/Excel 一括エクスポート(非同期)

ユーザーの請求書の一括エクスポート非同期タスクを開始し、期間とステータスでフィルタリングします。Excel スプレッドシート(メタデータのみ)または XML 入りの ZIP パッケージを生成できます。最初の呼び出しはタスクを作成して status: "Processing" を返します。同じパラメーターでの後続呼び出しは進捗を返し、status: "Success" になると url フィールドにダウンロードリンクが入ります。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

Body

フィールド	型	説明
type *	string	出力形式:`"excel"`(メタデータシート)またはその他の値(例:`"xml"`)で XML 入り ZIP
status	string	請求書ステータスでフィルタ(例:`"Success"`、`"Canceled"`、`"Voided"`)。`type=excel` の場合は内部で小文字化
month	int	月(1–12)。指定された場合、`start_create_time`/`end_create_time` をオーバーライド;`America/Sao_Paulo` タイムゾーンと当年(月が未来の場合は前年)を使用
start_create_time	long	期間開始(Unix タイムスタンプ、ミリ秒)
end_create_time	long	期間終了(Unix タイムスタンプ、ミリ秒)

* 必須フィールド。

ペイロード例

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

レスポンス — 処理中

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

レスポンス — 完了

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

レスポンスフィールド

フィールド	型	説明
status	string	タスク実行中は `"Processing"`、ファイルが準備できたら `"Success"`
progress_count	int	これまでに処理された請求書の数
total_count	int	処理すべき請求書の総数
url	string	最終ファイルのダウンロード URL(`status = Processing` の間は空)

冪等性: タスクはパラメーターのハッシュ(uid + token + 期間 + status + type)で重複排除されます。同じパラメーターでの繰り返し呼び出しは、新しい実行をトリガーせずに同じタスクの進捗を返します。

エラーレスポンス

メッセージ	原因
发票类型字段不能为空	`type` がない

POST /api/invoice/consultar_status

SEFAZ で NF-e/NFC-e のステータスを照会

アクセスキー(44 桁)を使って NfeConsultaProtocolo4 サービス経由で SEFAZ で直接 NF-e または NFC-e の現在のステータスを照会します。トークン企業が発行した自社請求書と、DistDFe 経由で取得した第三者請求書の両方で動作します。モデル(NF-e/NFC-e)はキーの 20-21 位置から自動検出されます。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン(その証明書が照会に使用されます)
sign	string	MD5 署名:`MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ(秒、5 分のウィンドウ)

Body

フィールド	型	説明
chave *	string	アクセスキー(44 桁の数字)。発行者の UF は 0-1 位置から、モデルは 20-21 位置から(`55`=NF-e、`65`=NFC-e)抽出されます。

* 必須フィールド。

ペイロード例

        {
          "chave": "35260512345678000199550010000000011000000018"
        }

レスポンス

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

レスポンスフィールド

フィールド	型	説明
chave	string	照会されたアクセスキー
status	string	正規化ステータス(下表参照)
cstat	int	SEFAZ の生の `cStat` コード
motivo	string	SEFAZ の生の `xMotivo` メッセージ

ステータスマッピング

`status`	SEFAZ の cStat	意味
autorizada	`100`, `150`	使用が承認された NF-e
cancelada	`101`, `151`	キャンセル(`cStat=100` でもキャンセルイベントがリンクされている場合に返されます)
denegada	`110`, `301`, `302`	SEFAZ により使用が拒否されました
inutilizada	`102`	無効化された番号(番号範囲)
nao_encontrada	`217`	NF-e が SEFAZ データベースに存在しません
desconhecido	その他	マッピングされていない cStat — 生の `cstat` と `motivo` を確認してください

エラーレスポンス

メッセージ	原因
chave inválida: deve ter 44 dígitos	キーがない、44 以外のサイズ、または数字以外の文字を含む
empresa não possui certificado configurado	トークン企業に `cert_file` が登録されていません
SEFAZ retornou resposta vazia	SEFAZ が応答を返しませんでした(タイムアウト、ダウン)
erro ao consultar SEFAZ: <詳細>	サービス呼び出し時の例外(無効な XML、タイムアウト、期限切れ証明書など)

POST /api/category/create

税カテゴリの作成

認証済みの企業に紐付く新しい税カテゴリ（税テンプレート）を作成します。各カテゴリは ICMS、IPI、PIS、COFINS のシナリオを集約し、オプションで IBS/CBS と IS を含みます。既存のものを編集するには /api/category/edit を使用してください。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body — トップレベル

項目	型	説明
descricao *	string	カテゴリの説明
category_id	string	カスタム ID。省略すると `"TF"` + 連番として自動生成されます
disable_difal	boolean	このカテゴリの DIFAL 計算を無効化。デフォルト: `false`
desconta_icms_pis_cofins	boolean	PIS/COFINS 課税標準から ICMS を控除（課税標準 = vProd − vICMS）。デフォルト: `false`
icms[] *	array	ICMS シナリオ（構造は下記）
ipi[] *	array	IPI シナリオ（構造は下記）
pis[] *	array	PIS シナリオ（構造は下記）
cofins[] *	array	COFINS シナリオ（構造は下記）
ibs_cbs[]	array	IBS/CBS シナリオ — 税制改革（構造は下記）
is[]	array	IS シナリオ — 選択税（構造は下記）

Body — `icms[]`

項目	型	説明
tipo_tributacao *	string	ICMS 課税タイプ
cenario *	string	シナリオ（例: `"saida_dentro_estado"`、`"saida_fora_estado"`、`"padrao"`）
tipo_pessoa *	string	`"fisica"` または `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	ICMS の CST/CSOSN
nao_contribuinte	boolean	非納税顧客
aliquota_importacao	string	輸入税率
aliquota_credito	decimal	クレジット税率（Simples Nacional 用 %）
aliquota_diferimento	decimal	繰延割合
aliquota_diferimentoFcp	string	FCP 繰延（注: フィールドは camelCase `diferimentoFcp`）
aliquota_reducao	decimal	ICMS 基礎の減額割合
aliquota_reducaoSt	decimal	ICMS-ST 基礎の減額割合（注: `reducaoSt` camelCase）
motivo_desoneracao	string	ICMS 免税理由コード
motivo_desoneracaoSt	string	ICMS-ST 免税理由コード（注: camelCase）
州別税率 — オプション
aliquota_mva[]	array	UF 別 MVA — 項目: `{ estado, aliquota }`
aliquota_icms[]	array	UF 別 ICMS 税率 — 項目: `{ estado, aliquota }`
aliquota_icms_st[]	array	UF 別 ICMS-ST 税率 — 項目: `{ estado, aliquota }`
aliquota_fcp[]	array	UF 別 FCP 税率 — 項目: `{ estado, aliquota }`
aliquota_fcp_st[]	array	UF 別 FCP-ST 税率 — 項目: `{ estado, aliquota }`
beneficio_fiscal[]	array	UF 別の税制優遇コード — 項目: `{ estado, codigo }`

Body — `ipi[]`

項目	型	説明
cenario *	string	シナリオ
tipo_pessoa *	string	`"fisica"` または `"juridica"`
situacao_tributaria *	string	IPI の CST
codigo_enquadramento *	string	法的位置付けコード
aliquota *	string	IPI 税率

Body — `pis[]` と `cofins[]`（同じ構造）

項目	型	説明
cenario *	string	シナリオ
tipo_pessoa *	string	`"fisica"` または `"juridica"`
situacao_tributaria *	string	PIS/COFINS の CST
aliquota *	string	税率

Body — `ibs_cbs[]`（税制改革）

項目	型	説明
cenario *	string	シナリオ
tipo_pessoa *	string	`"fisica"` または `"juridica"`
situacao_tributaria *	string	IBS/CBS の CST
classificacao_tributaria *	string	税分類

Body — `is[]`（選択税）

項目	型	説明
cenario *	string	シナリオ
tipo_pessoa *	string	`"fisica"` または `"juridica"`
situacao_tributaria *	string	IS の CST
aliquota *	string	IS 税率

* 必須項目。

最小例

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

レスポンス

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

GET /api/category/get_detail

税カテゴリの詳細

税カテゴリの完全な設定を返します: ICMS、IPI、PIS、COFINS、IBS/CBS のすべてのシナリオ、UF 別の配列（MVA、税率、税制優遇）を含みます。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン
sign	string	MD5 署名（path にクエリ文字列を含む）
timestamp	string	秒単位の Unix タイムスタンプ

クエリ文字列

パラメータ	型	説明
category_id *	string	税カテゴリ ID

* 必須項目。

呼び出し例

GET /api/category/get_detail?category_id=TF123

レスポンス

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

税カテゴリの一覧

認証済み企業の税カテゴリをページネーション付きで一覧表示します。各項目は category_id と descricao のみを返します — 完全な構成は /api/category/get_detail を使用してください。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン
sign	string	MD5 署名（path にクエリ文字列を含む）
timestamp	string	秒単位の Unix タイムスタンプ

クエリ文字列

パラメータ	型	説明
page *	int	ページ番号（≥ 1）
page_size *	int	ページサイズ（1–50）

* 必須項目。

呼び出し例

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

レスポンス

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

税カテゴリの編集

既存の税カテゴリを編集します。ボディは /api/category/create と同じですが、category_id が必須で既存のカテゴリに一致する必要があります。Upsert は icms、ipi、pis、cofins、ibs_cbs、is 配列を完全に置き換えます — 更新された全シナリオを送信してください（シナリオ単位のマージはありません）。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

ボディの完全な構造は /api/category/create に文書化されています。ここで category_id のみ扱いが異なります:

項目	型	説明
category_id *	string	編集するカテゴリの ID（存在する必要があり、そうでない場合はエラーを返します）
descricao *	string	説明
icms[] *	array	ICMS シナリオ（完全に置き換え）
ipi[] *	array	IPI シナリオ
pis[] *	array	PIS シナリオ
cofins[] *	array	COFINS シナリオ
ibs_cbs[]	array	IBS/CBS シナリオ（任意）
is[]	array	IS シナリオ（任意）
disable_difal	boolean	デフォルト: `false`
desconta_icms_pis_cofins	boolean	デフォルト: `false`

* 必須項目。各配列の内部項目（icms[].codigo_cfop など）については /api/category/create をご覧ください。

レスポンス

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

POST /api/category/delete

税カテゴリの削除

企業から税カテゴリを削除します。元に戻せない操作です。このカテゴリに紐付いていた製品は、削除された category_id を参照したままになるため NFe 発行が失敗します — 削除前に製品を更新してください。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
category_id *	string	削除するカテゴリの ID

* 必須項目。

ペイロード例

        {
          "category_id": "TF123"
        }

レスポンス

        {
          "success": true
        }

POST /api/invoice/return

返品 NF-e の発行

元の NF-e から返品 NF-e（モデル 55、用途 4）を発行します。2 つのモードに対応: 全額返品（元のインボイスを uuid または chave で参照）または 一部／カスタム返品（return_detail で完全なボディを送信）。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body — トップレベル項目

項目	型	説明
uuid	string	元の NF-e の UUID（`chave` が無い場合は必須。`return_detail` モードでは使用しません）
chave	string	元の NF-e の 44 桁アクセスキー（`return_detail` モードでは必須。簡易モードでは `uuid` の代替）
cfop *	string	返品 CFOP（例: `"1202"`、`"1411"`、`"2202"`、`"5202"`、`"5411"`、`"6202"`）
natureza_operacao	string	取引の性質（例: 「Devolução de venda」）。エイリアス対応: `nature_of_operation`
return_detail	object	返品 NF-e の完全なボディ。`/api/invoice/create` と同じ構造ですが、1 つの注意点があります: `return_detail.cliente` 内の住所番号項目は `number`（英語）であり `numero` ではありません。省略時は全額返品となり、元の NF-e をクローンします。

* 必須項目。uuid または chave も必須（どちらか一方）。

例 — 全額返品

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

例 — 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 完全な請求書発行例

輸送を含む完全な例

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

💡 INFORMATION: この例にはスクリーンショットで言及されたすべての重要なフィールドが含まれており、輸送、詳細な税務情報、支払いを含みます。特定のニーズに応じて値を調整してください。

輸入の完全な例

{
  "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: NFe輸入の例 (CFOP 3.xxx)。国内NFeとの違い：

transaction_type: "2" — 入庫（輸入）操作。
clienteはcnpj/cpf/uf/cepなし。id_estrangeiro、c_pais（BACENテーブル — 中国 = 1600）、x_paisを使用。
category_idはCFOP 3.xxxおよび輸入に対応するCST/CSOSNを持つ税分類を指す必要があります。
製品のorigem = 1（外国 — 直接輸入）または2（外国 — 国内市場で取得）。
iiブロック（輸入税）はCFOPが3.xxxの場合に必須です。値は通関業者が発行したDI（vBC、vDespAdu、vII、vIOF）から取得します。テストではゼロにできます。
import_declarationsブロック（輸入申告）には通関データを含みます：nDI、dDI、通関場所/UF/日付、輸送方法、仲介者、輸出者、追加情報。
vAFRMMはtpViaTransp = 1（海上）の場合に必須です。

vpn_key 認証

すべてのリクエストには次のヘッダーを含める必要があります:

ヘッダー	タイプ	必須	説明
Content-Type	string	はい	application/json;charset=utf-8
sign	string	はい	リクエストデジタル署名
timestamp	string	はい	リクエストUTCタイムスタンプ
token	string	はい	認証トークン

注意: 企業作成と企業リスト取得には、ディストリビュータートークン（b2b_token）を使用してください。

署名アルゴリズム (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();
    }
}

重要: signを計算する際、PathにはGETリクエストのクエリ文字列が含まれます。例: /api/nfce/category/get_detail?category_id=TF123. POSTリクエストの場合、Pathはルートのみです（例: /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`	現金
`1`	Credit

Payment Methods

`01`	現金
`02`	小切手
`03`	クレジットカード
`04`	デビットカード
`05`	ストアクレジット
`10`	食事バウチャー
`11`	食品バウチャー
`12`	Gift Voucher
`13`	燃料バウチャー
`15`	銀行振込票
`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

キャンセル、XMLダウンロード、番号無効化を試みる際に発生します、 or manifest an NF-e that was not successfully registered in SEFAZ database.

NF-eが承認されたか確認（状態「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

コード	説明	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

その他のエンドポイント

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

制限とレートリミット

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

リクエストパラメータ（クエリ）

パラメータ	必須	タイプ	説明
company_id	はい	String	Company ID
start_date	はい	Date	Period start date (YYYY-MM-DD)
end_date	はい	Date	Period end date (YYYY-MM-DD)
status	いいえ	String	Filter by status: `AUTHORIZED`, `CANCELED`, `DENIED`, `ALL` (default)
model	いいえ	String	Document model: `nfe`, `nfce`, `all` (default)
format	いいえ	String	Output format: `json` (default), `csv`, `pdf`
page	いいえ	Integer	Page number (default: 1)
per_page	いいえ	Integer	Records per page (default: 50, max: 200)

リクエスト例

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

レスポンス例

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

リクエストパラメータ（クエリ）

パラメータ	必須	タイプ	説明
company_id	はい	String	Company ID
year	はい	Integer	Reference year (e.g.: 2024)
group_by	いいえ	String	Group by: `month` (default), `week`, `day`

レスポンス例

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

ペイロードリクエスト

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

レスポンス例

{
  "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グローバル認証

すべてのTF Hub APIは統合認証システムを使用しています。

必須ヘッダー

ヘッダー	Value	説明
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（本番環境）

https://api.tffiscal.com

認証

Headers: sign, timestamp, token

要件

有効なA1デジタル証明書（.pfxまたは.p12）
CSC（納税者セキュリティコード）
CSC ID（SEFAZのCSC識別子）

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（納税者セキュリティコード） for QR Code generation

認証

すべてのNFC-eエンドポイントはメインAPIと同じ認証を使用します:

ヘッダー	タイプ	説明
token	string	Company token (obtained during registration)
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unixタイムスタンプ（秒単位、5分間有効）

重要: When calculating the sign, the path includes the query string for GET requests. 例: /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, デジタル証明書	Same as NFe — same required fields
CSC	Not used	必須 — `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)	任意対面販売の場合; 必須宅配の場合のみ (`ind_pres: "4"`)
Presence indicator	Not used	必須 — `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	任意	必須 — `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)
キャンセル	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

NFC-e 用の企業登録

NFC-e 発行用の企業を登録（または更新）します。会社名、IE、住所などのデータは CNPJ から SintegraWS 経由で自動抽出されます。CNPJ が既にユーザーに対して存在する場合、NFC-e フィールドが更新され既存の企業が返されます。

必須ヘッダー

ヘッダー	型	説明
token	string	ディストリビュータートークン（b2b）
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
cnpj *	string	発行企業の CNPJ
cert_file *	string	A1 デジタル証明書（.pfx または .p12）の HTTPS URL
cert_pwd *	string	証明書のパスワード
csc_id *	string	SEFAZ における CSC（納税者セキュリティコード）の ID
csc *	string	CSC トークン（SEFAZ と共有する秘密）
serie_nfce	int	NFC-e シリーズ
number_nfce	int	NFC-e の初期番号
telefone	string	会社の電話番号

* 必須項目。その他のデータ（名前、IE、住所など）は CNPJ から SintegraWS 経由で自動抽出されます。

ペイロード例

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

レスポンス

        {
          "success": true,
          "message": "NFC-e 用に企業が登録されました",
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/nfce/company/update

NFC-e 企業データの更新

token ヘッダーで識別される NFC-e 企業を更新します。Body のすべての項目は任意です — 変更したい項目のみ送信してください。cep を更新すると、システムが自動的に stateCode と ibge を解決します。cert_file と cert_pwd を一緒に送信すると、証明書は保存前に検証されます。

必須ヘッダー

ヘッダー	型	説明
token	string	NFC-e 企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body（すべての項目は任意 — 最低 1 つ送信）

項目	型	説明
識別
name	string	会社名
alias	string	商号
ie	string	州登録番号
invoice_type	string	税制
email	string	メールアドレス
telefone	string	電話番号
住所
cep	string	郵便番号（`stateCode` と `ibge` を自動更新）
address	string	通り住所
house_number	string	番号
complemento	string	補足
town	string	地区
city	string	市
state	string	UF
NFC-e
csc_id	string	CSC ID
csc	string	CSC トークン
serie_nfce	int	シリーズ
number_nfce	int	次の番号
cert_file	string	新しい A1 証明書（.pfx または .p12）の HTTPS URL
cert_pwd	string	証明書のパスワード

Body の少なくとも 1 項目が必須。CNPJ は変更不可。

ペイロード例

        {
          "alias": "Centro Store - Branch 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

レスポンス

        {
          "success": true,
          "message": "NFC-e 企業が更新されました"
        }

POST /api/nfce/company/get

NFC-e 企業の取得

token ヘッダーで識別される NFC-e 企業のデータを返します。注意: メソッドは POST ですが、Body フィールドはありません — 企業はトークンのみで解決されます。

必須ヘッダー

ヘッダー	型	説明
token	string	NFC-e 企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

空。{} を送信できます。

レスポンス

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "cnpj": "12345678000199",
            "name": "Empresa Exemplo LTDA",
            "alias": "Centro 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": "Centro",
            "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.

注意: 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

NFC-e 税務カテゴリ作成

NFC-e 税務カテゴリを作成します。各カテゴリは単一のシナリオ(内部出荷)を持ち、ICMS、PIS、COFINS、IBS/CBS にフラットオブジェクトを使用します(NFC-e はカテゴリごとに複数のシナリオを許可しないため、配列ではありません)。IPI はありません。

必須ヘッダー

ヘッダー	型	説明
token	string	NFC-e 企業トークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

Body(ルート)

フィールド	型	説明
descricao *	string	カテゴリの説明
codigo_cfop *	string	CFOP コード(例:5102、5405)
icms *	object	ICMS 設定(フラットオブジェクト)
pis *	object	PIS 設定(フラットオブジェクト)
cofins *	object	COFINS 設定(フラットオブジェクト)
ibs_cbs	object	IBS/CBS 設定(税制改革、オプション)

icms

フィールド	型	説明
situacao_tributaria *	string	CST/CSOSN(例:102、500)
aliquota_reducao	decimal	課税標準の削減率
motivo_desoneracao	string	免税理由コード
aliquota_icms	array	州別レート:`[{ "estado": "SP", "aliquota": 18.00 }]`
aliquota_fcp	array	州別 FCP:`[{ "estado": "SP", "aliquota": 0.00 }]`
beneficio_fiscal	array	州別税制優遇:`[{ "estado": "SP", "codigo": "SP800001" }]`

pis / cofins

フィールド	型	説明
situacao_tributaria *	string	PIS/COFINS の CST
aliquota *	string	パーセント率(例:"0.00"、"1.65"、"7.60")

ibs_cbs(オプション)

フィールド	型	説明
situacao_tributaria *	string	IBS/CBS の CST
classificacao_tributaria *	string	税分類コード

* 必須フィールド。

ペイロード例

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

レスポンス

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

GET /api/nfce/category/get_detail

NFC-e 税務カテゴリ詳細取得

NFC-e 税務カテゴリの全データ(説明、CFOP、ICMS、PIS、COFINS、IBS/CBS)を返します。

必須ヘッダー

ヘッダー	型	説明
token	string	NFC-e 企業トークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

クエリ文字列

フィールド	型	説明
category_id *	string	NFC-e カテゴリ ID

* 必須フィールド。

リクエスト例

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

レスポンス

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

NFC-e 税務カテゴリ一覧

認証された企業に登録されている NFC-e 税務カテゴリのページネーション付き一覧を返します。

必須ヘッダー

ヘッダー	型	説明
token	string	NFC-e 企業トークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

クエリ文字列

フィールド	型	説明
page *	int	ページ番号(最小 1)
page_size *	int	1 ページあたりの件数(1〜50)

* 必須フィールド。

リクエスト例

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

レスポンス

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

NFC-e 税務カテゴリ編集

注意: /api/nfce/category/create エンドポイントと同じ構造で、必須フィールド category_id が追加されます。icms、pis、cofins、ibs_cbs フィールドは全置換されます(マージされません)。

必須ヘッダー

ヘッダー	型	説明
token	string	NFC-e 企業トークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

追加フィールド

フィールド	型	説明
category_id *	string	編集するカテゴリの ID

* 必須フィールド。

ペイロード例

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

レスポンス

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

POST /api/nfce/category/delete

NFC-e 税カテゴリの削除

NFC-e 税カテゴリを削除します。元に戻せない操作です。このカテゴリに紐付いていた製品は、削除された category_id を参照したままになります — 先に更新してください。

必須ヘッダー

ヘッダー	型	説明
token	string	NFC-e 企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
category_id *	string	削除する NFC-e カテゴリの ID

* 必須項目。

ペイロード例

        {
          "category_id": "TF123"
        }

レスポンス

        {
          "success": true
        }

POST /api/nfce/create

NFC-e 発行

NFC-e(モデル 65、常に州内出荷、配送なし)を発行します。NFe エンドポイントとの主な違い:消費者オブジェクトは client(cliente ではない);住所番号は client.number;消費者はオプション;impostos.ipi、shipping_address、delivery_address、transportation は存在しない。pag_info の金額フィールドは amount。

必須ヘッダー

ヘッダー	型	説明
token	string	NFC-e 企業トークン
sign	string	MD5 署名:`MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ(秒、5 分のウィンドウ)

Body(ルート)

フィールド	型	説明
nature_of_operation *	string	取引の性質(例:"商品販売")
issuance_type *	string	発行タイプ:"1"(通常)、"9"(NFC-e オフライン緊急時)
ambiente *	string	"1" 本番、"2" ホモロゲーション
products *	array	商品リスト(下記参照)
id	string	外部識別子
ind_pres	string	購入者の在席:"1" 対面(デフォルト)、"4" 自宅配送、"5" 店舗外対面、"9" 該当なし
ind_intermed	string	"0" 仲介者なし、"1" マーケットプレイス。`ind_pres` = 2、3、4 のときに必須
total_discount_amount	decimal	請求書の合計割引
troco	decimal	お釣りの金額
seguro	decimal	保険金額
outras_despesas	decimal	その他付帯費用
informacoes_complementares	string	消費者向け補足情報
informacoes_fisco	string	税務当局向け情報
client	object	消費者データ(オプション — 下記参照)
pag_info	array	支払い(デフォルト:現金 — 下記参照)

client(オプション)

消費者が識別される場合のみ記入。CPF または CNPJ は数字のみで送信。

フィールド	型	説明
cpf	string	CPF(個人として設定)
cnpj	string	CNPJ(法人)
ie	string	州登録番号
name	string	氏名 / 法人名
endereco	string	通り
number	string	住所番号 (注意:NFe では `numero` を使用)
complemento	string	補足
bairro	string	地区
city	string	市
uf	string	州(CEP がある場合は検証)
cep	string	郵便番号(数字のみ)
telefone	string	電話番号
email	string	E メール

products[](各項目)

フィールド	型	説明
name *	string	商品名(CJK 文字は除去されます)
ncm *	string	NCM(8 桁)
count *	decimal	数量
unit *	string	商業単位(例:"UN"、"KG")
unit_price *	decimal	単価
total_price *	decimal	項目の合計金額
origem *	int	商品の原産地(0..8)
indicador_total *	int	1 = 請求書合計を構成;0 = 構成しない
category_id ⚠	string	NFC-e 税務カテゴリ ID(`impostos` を送信しない場合は必須)
impostos ⚠	object	手動税(`category_id` の代替、IPI なし)
tax_info ⚠	object	`impostos` のエイリアス(同じ構造)。`impostos` がない場合のみ使用
codigo	string	内部商品コード
cest	string	CEST
gtin	string	商業 GTIN/EAN
gtin_tributavel	string	課税 GTIN
discount_price	decimal	項目割引
nItemPed	int	発注品目 (I61)。ルートの `id` から取得する `xPed` で参照される注文内の項目連番。有効範囲: 1–999999。デフォルト: 省略。

pag_info[](各項目)

フィールド	型	説明
payment_indicator *	string	"0" 現金、"1" 信用
payment_method *	string	支払い方法(01=現金、03=クレジットカード、04=デビットカード、17=PIX、99=その他など)
amount	decimal	この方法で支払った金額
card_info.integration_type	string	"1" 統合、"2" 非統合(カード 03/04 のとき必須)
card_info.brand_code	string	カードブランド(カード 03/04 のとき必須)
card_info.acquirer_cnpj	string	アクワイアラ CNPJ
card_info.authorization_code	string	認証コード

* 必須フィールド。⚠ category_id、impostos、tax_info のいずれかが必須。

簡易例

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

完全な例(全フィールド)

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

レスポンス

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

POST /api/nfce/cancel

NFC-e のキャンセル

承認済みの NFC-e をキャンセルします。NFe と違い、キャンセル理由はクライアントが指定し SEFAZ に転送されます。SEFAZ のキャンセル窓口は短く（通常承認後 15〜30 分）です。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
chave *	string	NFC-e の 44 桁アクセスキー（注意: 他のエンドポイントの `uuid` ではなく `chave` です）
motivo *	string	キャンセルの正当化理由（SEFAZ の要件により最少 15 文字）

* 必須項目。

ペイロード例

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

GET /api/nfce/get_detail

NFC-e の詳細を取得

UUID で特定の NFC-e の詳細を返します。XML と DANFE（サーマルレシート）の URL、提供されている場合は顧客データを含みます。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名（path にクエリ文字列を含む）
timestamp	string	秒単位の Unix タイムスタンプ

クエリ文字列

パラメータ	型	説明
uuid *	string	NFC-e の UUID

* 必須項目。

呼び出し例

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

レスポンス

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

NFC-e DANFE（サーマルレシート）の生成／取得

NFC-e DANFE（電子財務レシート）の PDF URL を返します。SEFAZ 照会用の QR コードを含みます。オンデマンド生成され、ハッシュ（アクセスキー + ステータス）でキャッシュされます。重複呼び出しでは既存の URL を返します。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
uuid *	string	NFC-e の UUID（注意: ここでは `uuid` で、`cancel` の `chave` とは異なります）

* 必須項目。

ペイロード例

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

レスポンス

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

重要:

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)

認証

NFe発行と同じエンドポイントと認証を使用します:

ヘッダー	タイプ	説明
token	string	Company token (obtained during registration)
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unixタイムスタンプ（秒単位、5分間有効）

description NFS-e - 電子サービス請求書

NFS-e APIは、電子サービス請求書の発行、キャンセル、照会を可能にします。システムは自動的に企業の市区町村を検出し、正しいAPIにルーティングします：

サンパウロ (SP) - Nota Fiscal Paulistana (SOAP) による発行
その他の市区町村 - 国家API (ADN/SEFIN) による発行

インテグレーターはどのAPIを使用するか心配する必要はありません。データを送信するだけで、企業に登録されている市区町村のIBGEコードによって自動的にルーティングされます。

エンドポイント	メソッド	説明
`/api/nfse/create`	POST	NFS-e 発行
`/api/nfse/cancel`	POST	NFS-e キャンセル
`/api/nfse/get_danfse`	POST	DANFSE 取得 (PDF)
`/api/nfse/get_xml`	POST	XML ダウンロード

POST /api/nfs/company/create

NFS-e 発行のための企業登録

NFS-e 発行のために企業を登録(または更新)します。CNPJ がユーザーに対して既に存在する場合、NFS-e フィールドと証明書のみが更新されます。それ以外の場合は、新しい企業が作成され、専用トークンが返されます。パスに注意:/api/nfs/...("e" なし)、他の NFS-e エンドポイントとは異なります。

必須ヘッダー

ヘッダー	型	説明
token	string	インテグレーター B2B トークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

Body

フィールド	型	説明
cnpj *	string	企業 CNPJ(数字のみ)
name *	string	法人名
cep *	string	郵便番号(数字のみ)
address *	string	通り
house_number *	string	住所番号
town *	string	地区
city *	string	市
state *	string	州(2 桁、例:"SP")
cert_file *	string	A1 デジタル証明書(.pfx)の URL
cert_pwd *	string	デジタル証明書のパスワード
im *	string	市町村登録番号(Inscrição Municipal)
codigo_municipio_nfse *	string	発行市町村の IBGE コード
codigo_servico_nfse *	string	デフォルトサービスコード(LC 116)
alias	string	屋号
ie	string	州登録番号
invoice_type	string	税制
unit	string	ユニット / 支店
email	string	連絡先メール
telefone	string	電話番号
complemento	string	住所の補足
cnae_nfse	string	デフォルト活動 CNAE
serie_nfse	int	NFS-e の初期シリーズ
number_nfse	int	NFS-e の初期番号
regime_especial_tributacao	int	特別税制コード
optante_simples_nacional	bool	Simples Nacional への加入

* 必須フィールド。

ペイロード例

        {
          "cnpj": "43649380000100",
          "name": "Empresa Exemplo LTDA",
          "alias": "サンプル",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contact@example.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "サンプル通り",
          "house_number": "86",
          "complemento": "2 階",
          "town": "中央",
          "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
        }

レスポンス

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

注意: 返された token は、他の NFS-e 呼び出し(/api/nfse/create、/cancel、/get_danfse、/get_xml)で使用する必要があります。企業がすでに存在する場合、メッセージは "Empresa atualizada para NFS-e" になり、返されるトークンは既存のトークンです。

POST /api/nfse/create

NFS-e 発行

必須ヘッダー

ヘッダー	タイプ	説明
token	string	企業トークン
sign	string	MD5署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unixタイムスタンプ（秒単位、5分間有効）

ペイロード

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

主要フィールド

フィールド	タイプ	説明
ambiente	string	`"1"` = 本番環境, `"2"` = テスト環境
id	string	外部参照ID（任意）
descricao_servico	string	サービスの説明（必須）
valor_servico	decimal	サービス合計金額（R$）（必須）
aliquota_iss	decimal	ISS税率（%）（例: 2.90）
iss_retido	boolean	`false` = 源泉徴収なし, `true` = 支払者が源泉徴収
valor_iss	decimal	ISS 値のオーバーライド。0 より大きい場合、自動計算 (base_calculo × aliquota_iss ÷ 100) をオーバーライド。デフォルト:自動計算
codigo_servico	string	サービスコード。空の場合、企業のデフォルトを使用
cnae	string	CNAE。空の場合、企業のデフォルトを使用
tomador	object	サービス受領者データ（必須）

支払者フィールド

フィールド	タイプ	説明
cnpj	string	支払者CNPJ（数字のみ）
cpf	string	支払者CPF（cnpjまたはcpfを使用）
name	string	名前/会社名（必須）
email	string	支払者メール
telefone	string	電話番号
cep	string	郵便番号（必須）
endereco	string	住所（必須）
numero	string	番地（必須）
complemento	string	住所補足
bairro	string	地区（必須）
city	string	市区町村
uf	string	州（2桁）
codigo_municipio	string	IBGE市区町村コード

成功レスポンス

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

NFS-e キャンセル

必須ヘッダー

ヘッダー	タイプ	説明
token	string	企業トークン
sign	string	MD5署名
timestamp	string	Unixタイムスタンプ（秒）

ペイロード

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

フィールド

フィールド	タイプ	説明
chave	string	NFS-e 検証コード（必須）
motivo	string	キャンセル理由（必須、最低15文字）

成功レスポンス

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

POST /api/nfse/get_danfse

DANFSE 取得 (PDF)

必須ヘッダー

ヘッダー	タイプ	説明
token	string	企業トークン
sign	string	MD5署名
timestamp	string	Unixタイムスタンプ（秒）

ペイロード

{
  "chave": "Z685RI9C"
}

フィールド

フィールド	タイプ	説明
chave	string	NFS-e 検証コード（必須）

レスポンス

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

注意： Paulistana (SP) の場合、市役所のPDF直接URLを返します。国家APIの場合、base64形式のPDFを返します。

POST /api/nfse/get_xml

NFS-e XML ダウンロード

必須ヘッダー

ヘッダー	タイプ	説明
token	string	企業トークン
sign	string	MD5署名
timestamp	string	Unixタイムスタンプ（秒）

ペイロード

{
  "chave": "Z685RI9C"
}

フィールド

フィールド	タイプ	説明
chave	string	NFS-e 検証コード（必須）

レスポンス

{
  "success": true,
  "data": {
    "dpsXml": "<PedidoEnvioRPS>...</PedidoEnvioRPS>",
    "nfseXml": "<RetornoEnvioRPS>...</RetornoEnvioRPS>"
  }
}

dpsXml: 市役所/ADNに送信されたXML。 nfseXml: 発行結果を含む返却XML。

POST /api/invoice/create

補足NFe発行（finalidade = 2）

必須ヘッダー

ヘッダー	タイプ	説明
token	string	企業トークン
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unixタイムスタンプ（秒単位、5分間有効）

ペイロード

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

フィールド	タイプ	説明
finalidade	string	`"2"` for Supplementary (required)
ref_nfe_chave	string	Access key of the original invoice — 44 digits (required)

注意: 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": 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

調整NFe発行（finalidade = 3）

必須ヘッダー

ヘッダー	タイプ	説明
token	string	企業トークン
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unixタイムスタンプ（秒単位、5分間有効）

ペイロード

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

フィールド	タイプ	説明
finalidade	string	`"3"` for Adjustment (required)
ref_nfe_chave	string	Access key of the original invoice — 44 digits (required)

Available finalidade values:

Value	説明
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

認証

すべてのCC-eエンドポイントはメインAPIと同じ認証を使用します:

ヘッダー	タイプ	説明
token	string	Company token (obtained during registration)
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unixタイムスタンプ（秒単位、5分間有効）

POST /api/invoice/cce/send

訂正書（CC-e）の送信

既に承認された NF-e のデータを訂正するため、CC-e（イベント 110110）を SEFAZ に送信します。シーケンス番号（nSeqEvento）は自動的に計算されます — 送信しないでください。非財務データのみ訂正可能です（金額、CNPJ、IE などは訂正できません）。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
uuid	string	NF-e の UUID（`chave` が無い場合は必須）
chave	string	NF-e の 44 桁アクセスキー（`uuid` が無い場合は必須）
correcao *	string	訂正テキスト（SEFAZ の制限: 15–1000 文字）

* 必須項目。uuid または chave のいずれか少なくとも 1 つも必須です。

ペイロード例

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

レスポンス

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

POST /api/invoice/cce/get_list

NF-e の CC-e 一覧

特定の NF-e に発行されたすべての CC-e（訂正書）を新しい順に返します。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
uuid	string	NF-e の UUID（`chave` が無い場合は必須）
chave	string	NF-e の 44 桁アクセスキー（`uuid` が無い場合は必須）

uuid または chave のうち少なくとも 1 つが必須です。

ペイロード例

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

レスポンス

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

POST /api/invoice/cce/download_pdf

CC-e PDF のダウンロード

CC-e の PDF URL を返します。PDF は初回呼び出し時にオンデマンドで生成され（インボイスの XML + CC-e の XML からレンダリング）、OSS に保存されます。以降の呼び出しでは既存の URL を返します。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
cce_id *	string	`/api/invoice/cce/get_list` の `id` フィールドで返される CC-e ID（ObjectId）

* 必須項目。

ペイロード例

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

レスポンス

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

POST /api/invoice/cce/download_xml

CC-e XML のダウンロード

CC-e の署名済み XML URL を返します（SEFAZ への送信後、すでに OSS に保存されています）。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	秒単位の Unix タイムスタンプ

Body

項目	型	説明
cce_id *	string	`/api/invoice/cce/get_list` の `id` フィールドで返される CC-e ID（ObjectId）

* 必須項目。

ペイロード例

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

レスポンス

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

how_to_reg 受信者表明 (Manifestação do Destinatário)

受信者表明は、NF-e の受信者が自社の CNPJ 宛に発行された請求書に対して正式に意思表示を行う仕組みです。SEFAZ により定義された 4 種類のイベントがあり、それぞれに法的な意味があります。

イベントの種類

コード	名称	意味	理由
210210	操作の認識	受信者は NF-e の存在を認識しましたが、まだ確認も拒否もしていません。通常は最初に送信するイベントで、DistDFe 経由で完全な XML をダウンロードするための前提条件です。	不要
210200	操作の確認	受信者は取引が行われ、商品/サービスが受領されたことを確認します。最終イベントとして受領を証明します。	不要
210220	操作の否認	受信者は取引を認識していないことを宣言します（不正の疑い、CNPJ の不正利用など）。	必須 (15〜255 文字)
210240	操作未実施	受信者は取引を認識しているが、実際には行われなかったことを宣言します（返品、受領拒否など）。	必須 (15〜255 文字)

順序ルール: 認識 (210210) を送信した後、確認 (210200) または否認 (210220) または未実施 (210240) のいずれかを送信できます。確認/否認/未実施は最終状態であり、上書きすることはできません。

注意: cnpj フィールドで送信する CNPJ は NF-e の受信者（表明者）であり、使用するトークンに紐付くシステムに登録されている必要があります。そうでない場合、SEFAZ は「イベント作成者が NF-e の受信者と異なります」という拒否を返します。

cStat 戻りコード

cStat	意味
135	✅ イベントが正常に登録されました
573	✅ イベント重複 — 既に登録済み（成功として扱われる）
236	❌ アクセスキーが無効
491	❌ 表明は既に登録済み — 最終状態を上書きできません
596	❌ 受信者 CNPJ が通知された値と異なります
656	❌ 不適切な消費（レート制限）

POST /api/invoice/manifest

受信者表明イベントを送信

必須ヘッダー

ヘッダー	型	説明
token	string	会社のトークン
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ（秒、5 分のウィンドウ）

Payload

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

フィールド

フィールド	型	必須	説明
chave	string	はい	NF-e アクセスキー — 44 桁
cnpj	string	はい	受信者 CNPJ（表明者） — 14 桁、書式なし。システムに登録済みである必要があります
tipo_evento	int	はい	イベントコード: `210200`、`210210`、`210220` または `210240`
justificativa	string	条件付き	`210220` と `210240` で必須。15〜255 文字。`210200` と `210210` では無視されます

シーケンス (nSeqEvento): 自動計算されます。同じ組み合わせ (cnpj + chave + tipo_evento) では各呼び出しごとに増分されます — 重複は cStat: 573 を返し、エラーなしで保存されます。

成功レスポンス

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

レスポンスフィールド

フィールド	型	説明
id	string	表明レコードの内部 ObjectId（`/get_xml` で使用）
chave	string	表明された NF-e のアクセスキー
cnpj	string	表明を行った受信者 CNPJ
tipo_evento	int	送信されたイベントコード (210200/210210/210220/210240)
desc_evento	string	イベントのテキスト説明 (SEFAZ オリジナル)
nProt	string	SEFAZ プロトコル番号 — イベントの受領証
cStat	int	SEFAZ ステータスコード。`135` = 登録済み、`573` = 重複（同じく受理）
xMotivo	string	SEFAZ の説明メッセージ
nSeqEvento	int	自動的に割り当てられたイベントシーケンス
xml_url	string	OSS に保存された procEvento XML（署名・プロトコル付き）の公開 URL

例 — 理由付きの否認 (210220)

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

送信済みの表明を一覧（履歴）

必須ヘッダー

ヘッダー	型	説明
token	string	会社のトークン
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ（秒、5 分のウィンドウ）

Payload

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

フィールド

フィールド	型	必須	説明
cnpj	string	いいえ	受信者 CNPJ でフィルタリング。省略時はユーザーの全 CNPJ を対象
chave	string	いいえ	特定の NF-e アクセスキー（44 桁）でフィルタリング
start_create_time	string/long	いいえ	開始日。次の形式が利用可能: `"dd/MM/yyyy"`、`"yyyy-MM-dd"`、`"dd/MM/yyyy HH:mm:ss"` または Unix タイムスタンプ（秒）。日付のみの場合は 00:00:00 UTC とみなされます
end_create_time	string/long	いいえ	終了日。同じ形式。日付のみの場合は 23:59:59.999 UTC とみなされます
page	int	いいえ	ページ番号（デフォルト `1`）
page_size	int	いいえ	ページあたりのアイテム数（デフォルト `20`、最大 `100`）

成功レスポンス

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

レスポンスフィールド

フィールド	型	説明
total	int	フィルタ条件に一致するレコードの総数（ページネーション対象外）
page	int	返された現在のページ
page_size	int	返されたページサイズ
list[].id	string	レコードの内部 ObjectId
list[].chave	string	表明された NF-e のアクセスキー
list[].cnpj	string	表明を行った受信者 CNPJ
list[].tipo_evento	int	イベントコード (210200/210210/210220/210240)
list[].desc_evento	string	イベントのテキスト説明
list[].justificativa	string	送信された理由（210220/210240 のみ入力）
list[].nProt	string	イベントの SEFAZ プロトコル番号
list[].nSeqEvento	int	イベントシーケンス
list[].cStat	int	SEFAZ ステータスコード
list[].xMotivo	string	SEFAZ の説明メッセージ
list[].xml_url	string	OSS の procEvento XML の公開 URL
list[].create	string	レコードの UTC タイムスタンプ（形式 `yyyy-MM-dd HH:mm:ss`）

並び順: レコードは新しいものから古いものへの順（create 降順）で返されます。

POST /api/invoice/manifest/get_xml

特定の表明 XML の URL を取得

必須ヘッダー

ヘッダー	型	説明
token	string	会社のトークン
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ（秒、5 分のウィンドウ）

Payload

{
  "id": "67341a8f5d4e1f2a3b4c5d6e"
}

フィールド

フィールド	型	必須	説明
id	string	はい	表明の ObjectId — `/manifest` または `/manifest/list` から返されたもの

成功レスポンス

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

よくあるエラー

メッセージ	原因
id inválido	値が有効な ObjectId ではありません
manifestação não encontrada	ObjectId は存在しますが、トークンのユーザーに属していないか、削除されています

cloud_download DistDFe取得 — 受信NFe

SEFAZ（全国環境）の NFeDistribuicaoDFe サービス経由で、自社 CNPJ 宛の NFe およびイベントを照会・ダウンロードできます。取得は NSU（一意連番）による増分処理で、各呼び出しでは未取得分のみがダウンロードされます。

返されるドキュメントタイプ

doc_type	内容	説明
resNFe	NFe サマリー	基本メタデータ（キー、金額、発行者、状態）。認識イベント送信前に届きます — 商品/税金は含まれません
procNFe	完全な認可済み NFe	完全な NF-e XML（商品、税金、運送など）。受信者がそのキーに対して認識 (210210) を送信した後でのみ取得できます
resEvento	イベントサマリー	イベントメタデータ（キー、種別、シーケンス、理由）
procEvento	完全イベント	完全なイベント XML（CC-e、キャンセル、他の受信者からの表明など）

推奨フロー:

/received/sync を呼び出し — 新しいドキュメントをすべてダウンロード
/received/list で doc_type: "resNFe" フィルタを使い、認識未送信の請求書を確認
必要な各キーに対して /invoice/manifest を tipo_evento: 210210 で呼び出す
再度 /received/sync を呼び出し — SEFAZ が表明済みキーの procNFe（完全 XML）を返します
/received/get_xml で XML URL を取得し、処理

SEFAZ レート制限: SEFAZ は CNPJ ごとに 1 時間あたり最大 1 回の DistDFe 呼び出しを許可します。超過すると cStat: 656（不適切な消費）が返されます。検証環境ではより緩いルールが適用されます。

DistDFe 戻り cStat コード

cStat	意味
137	✅ ドキュメントなし（ループの正常終了）
138	✅ ドキュメント発見 — ループ継続
656	❌ 不適切な消費 — 1 時間待って再試行
252	❌ 通知された環境と異なる（本番 vs 検証）
280	❌ 証明書の有効期限切れまたは無効

POST /api/invoice/received/sync

同期 — SEFAZ から DistDFe 経由で新しい NFe/イベントをダウンロード

必須ヘッダー

ヘッダー	型	説明
token	string	会社のトークン
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ（秒、5 分のウィンドウ）

Payload

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

フィールド

フィールド	型	必須	説明
cnpj	string	はい	受信者会社の CNPJ — 14 桁、書式なし。トークンに紐付くシステムに登録済みである必要があります
max_iterations	int	いいえ	1 実行あたりの SEFAZ 呼び出し最大数。各呼び出しでは最大 50 ドキュメントをダウンロード。デフォルト `50`（約 2,500 ドキュメント）、最大 `200`

動作の仕組み:

(uid + cnpj) に対して保存された最新の ultNSU を読み取り
cStat ≠ 138 または max_iterations に達するまで SEFAZ を呼び出してループ
返された XML（gzip）を解凍
各ドキュメントを w_invoice_received に保存し、XML を OSS にアップロード
w_invoice_received_sync の ultNSU と maxNSU を更新
(uid + cnpj + nsu) による重複排除 — 繰り返し呼び出しても重複しません

成功レスポンス

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

レスポンスフィールド

フィールド	型	説明
cnpj	string	照会した受信者 CNPJ
uf	string	照会で使用された受信者の州コード
initial_nsu	long	開始 NSU — この実行前に処理された最後の NSU
ult_nsu	long	同期後の新しい最終 NSU
max_nsu	long	照会時点で SEFAZ AN に存在する最大 NSU
pending	long	残りの保留ドキュメント (`max_nsu - ult_nsu`)。> 0 の場合、`/sync` を再度呼び出して残りをダウンロード
iterations	int	この実行で行われた SEFAZ 呼び出し数
last_cstat	int	SEFAZ が返した最後の cStat。`137` は正常終了、`656` はレート制限
last_motivo	string	SEFAZ の最後のレスポンスの説明メッセージ
stats.resNFe	int	この実行でダウンロードされた NFe サマリー数
stats.procNFe	int	ダウンロードされた完全 NFe の数
stats.resEvento	int	ダウンロードされたイベントサマリー数
stats.procEvento	int	ダウンロードされた完全イベント数
stats.skipped	int	スキップされたドキュメント（重複または個別のパースエラー）

初回ボリューム: これまで同期していない会社には、数百〜数千の履歴ドキュメントが存在する場合があります。初回実行は時間がかかり、max_iterations で中断されることがあります。レスポンスの pending を確認し、> 0 の場合は再度呼び出してください（レート制限を尊重）。

POST /api/invoice/received/list

取得済みドキュメント（NFe・イベント）の一覧

必須ヘッダー

ヘッダー	型	説明
token	string	会社のトークン
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ（秒、5 分のウィンドウ）

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
}

フィールド

フィールド	型	必須	説明
cnpj	string	いいえ	受信者 CNPJ（自社 CNPJ）でフィルタリング。省略時はユーザーの全件
doc_type	string	いいえ	ドキュメントタイプでフィルタ: `resNFe`、`procNFe`、`resEvento` または `procEvento`
chave	string	いいえ	アクセスキー（44 桁）でフィルタリング
emitente_cnpj	string	いいえ	NF-e 発行者 CNPJ（仕入先）でフィルタリング
start_create_time	string/long	いいえ	開始日。`"dd/MM/yyyy"`、ISO または Unix タイムスタンプを受け付け
end_create_time	string/long	いいえ	終了日。同じ形式
page	int	いいえ	ページ番号（デフォルト `1`）
page_size	int	いいえ	ページあたりのアイテム数（デフォルト `20`、最大 `100`）

成功レスポンス

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

レスポンスフィールド

フィールド	型	説明
total	int	フィルタ条件に一致するレコードの総数
page	int	現在のページ
page_size	int	ページサイズ
list[].id	string	内部 ObjectId（`/received/get_xml` で使用）
list[].nsu	long	SEFAZ がこのドキュメントに割り当てた NSU
list[].doc_type	string	ドキュメントタイプ: `resNFe`、`procNFe`、`resEvento`、`procEvento`
list[].schema	string	ドキュメントスキーマ（例 `resNFe_v1.01.xsd`）
list[].chave	string	NF-e アクセスキー（44 桁）
list[].cnpj_destinatario	string	受信者 CNPJ（自社 CNPJ）
list[].emitente_cnpj	string	NF-e 発行者 CNPJ（仕入先）
list[].emitente_nome	string	発行者の会社名
list[].valor	decimal	NF-e 合計金額 (`vNF`)
list[].dh_emi	string	NF-e の発行日時
list[].serie	int	NF-e のシリーズ（`procNFe` のみ入力）
list[].number	long	NF-e の番号（`procNFe` のみ入力）
list[].tp_nf	int	取引タイプ: `0`=入庫、`1`=出庫（発行者の視点）
list[].c_sit_nfe	int	NF-e の状態（`resNFe` 内）: `1`=承認済み、`2`=拒否、`3`=キャンセル
list[].tp_evento	int	イベントコード（`resEvento`/`procEvento` 内）。例: `110110`=CC-e、`110111`=キャンセル、`210210`=認識
list[].desc_evento	string	イベントのテキスト説明
list[].n_seq_evento	int	イベントシーケンス
list[].dh_evento	string	イベントの日時（イベントのみ）
list[].xml_url	string	OSS のドキュメント XML の公開 URL
list[].create	string	取得時の UTC タイムスタンプ

並び順: レコードは NSU 降順（最新が先）で返されます。

POST /api/invoice/received/get_xml

特定の受信ドキュメントの XML URL を取得

必須ヘッダー

ヘッダー	型	説明
token	string	会社のトークン
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ（秒、5 分のウィンドウ）

Payload

{
  "id": "6a04a70d3201b5a62f3ac2f8"
}

フィールド

フィールド	型	必須	説明
id	string	はい	ドキュメントの ObjectId — `/received/list` で返されたもの

成功レスポンス

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

返される XML について:

resNFe — XML はサマリーのみで、商品/税金は含まれません。認識送信前の監査・選別用
procNFe — 発行時に生成されたものと同等の完全な署名済み XML。クライアントの ERP にインポート可能
procEvento — 署名およびプロトコル付きの完全なイベント XML

よくあるエラー

メッセージ	原因
id inválido	値が有効な ObjectId ではありません
documento recebido não encontrado	ObjectId は存在しますが、トークンのユーザーに属していません

POST /api/invoice/received/get_sync_status

DistDFe 同期の現在の状態を確認（SEFAZ を呼び出さない）

必須ヘッダー

ヘッダー	型	説明
token	string	会社のトークン
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ（秒、5 分のウィンドウ）

Payload

{
  "cnpj": "26638419000167"
}

フィールド

フィールド	型	必須	説明
cnpj	string	はい	受信者会社の CNPJ — 14 桁、書式なし

レスポンス — 同期済みの会社

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

レスポンス — 未同期の会社

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

レスポンスフィールド

フィールド	型	説明
cnpj	string	照会された CNPJ
uf	string	最終同期時に使用された受信者の州コード（未同期の場合は空）
ult_nsu	long	最後に処理された NSU。`0` = 未同期
max_nsu	long	最終同期時に SEFAZ に存在する最大 NSU
pending	long	保留中ドキュメント (`max_nsu - ult_nsu`)。> 0 の場合、SEFAZ に新しいドキュメントがあります
last_sync	string	最後の成功した同期の UTC 日時。未同期の場合は `null`

典型的な使い方: /received/sync を呼び出す前にこのエンドポイントを呼び出して、SEFAZ を呼び出すかどうかを判断します。このエンドポイントは SEFAZ のレート制限を消費せず、ローカル MongoDB の状態のみを読み取ります。

local_shipping MDF-e — 電子税務文書マニフェスト

MDF-e API(モデル 58、PL-MDFe 3.00 レイアウト)は、輸送マニフェストの発行、照会、取消、終了を可能にします。MDF-e は輸送業務に関連する NF-e および/または CT-e を集約し、4 つのモーダル(道路、航空、水路、鉄道)をサポートします。すべての運用情報(運転手、車両、契約者、CIOT、通行料バウチャー、支払)は /create ボディに含まれます — 発行後の追加/変更イベントはありません。

エンドポイント	メソッド	説明
`/api/mdfe/create`	POST	MDF-e 発行
`/api/mdfe/consult`	POST	MDF-e の状態照会
`/api/mdfe/cancel`	POST	MDF-e キャンセル(承認後 24 時間以内)
`/api/mdfe/close`	POST	MDF-e 終了(旅行終了後)

POST /api/mdfe/create

MDF-e 発行

送信されたボディから MDF-e を発行します。フィールド serie、nMDF、cMDF、cDV、cUF、dhEmi、mod、tpEmis、procEmi、verProc はサーバーによって自動的に計算されます。クライアントはビジネスフィールドのみを送信します。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名:`MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ(秒、5 分のウィンドウ)

Body — ルート

フィールド	型	説明
ide *	object	MDF-e 識別
emit *	object	発行者データ
infModal *	object	モーダル情報(4 つのうち 1 つだけ:`rodo`、`aereo`、`aquav`、`ferrov`)
infDoc *	object	関連税務文書
tot *	object	貨物の合計
prodPred	object	主要貨物製品
seg	array	保険情報
lacres	array	MDF-e の封印
autXML	array	XML へのアクセスが許可された CNPJ/CPF
infAdic	object	追加情報(税務当局と納税者)
infRespTec	object	技術担当者(CNPJ、連絡先、メールなど)

ide — 識別

フィールド	型	説明
tpAmb *	int	環境:`1`=本番、`2`=ホモロゲーション
tpEmit *	int	発行者タイプ:`1`=運送業者、`2`=自社貨物、`3`=輸送サービスプロバイダー
modal *	string	モード:`"1"`=道路、`"2"`=航空、`"3"`=水路、`"4"`=鉄道
UFIni *	string	旅行開始の UF(2 文字)
UFFim *	string	旅行終了の UF
infMunCarrega[] *	array	積み込み市町村:`[{ cMunCarrega, xMunCarrega }]`
infPercurso[]	array	ルートの UF:`[{ UFPer }]`
tpTransp	string	運送業者タイプ(道路)
dhIniViagem	string	旅行開始日時(ISO 8601)
indCanalVerde	string	グリーンチャネルインジケータ
indCarregaPosterior	string	後続積み込みインジケータ

emit — 発行者

フィールド	型	説明
CNPJ ⚠	string	発行者 CNPJ(14 桁)
CPF ⚠	string	発行者 CPF(11 桁)
IE	string	州登録番号
xNome *	string	法人名
xFant	string	屋号
enderEmit	object	住所:`{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email }`

infModal — 道路モーダル(modal="1")

フィールド	型	説明
rodo.veicTracao *	object	トラクター車両:`{ placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop }`
rodo.veicTracao.condutor[] *	array	運転手:`[{ xNome, CPF }]` — 最小 1
rodo.veicReboque[]	array	トレーラー車両(運転手なしの veicTracao と同じ構造)
rodo.infANTT	object	ANTT 情報:`{ RNTRC, infCIOT[], valePed, infContratante[], infPag[] }`
rodo.codAgPorto	string	港湾予約コード
rodo.lacRodo[]	array	モーダル封印:`[{ nLacre }]`

infModal — 航空モーダル(modal="2")

フィールド	型	説明
aereo.nac *	string	航空機国籍マーク
aereo.matr *	string	航空機登録
aereo.nVoo *	string	フライト番号
aereo.cAerEmb *	string	搭乗空港 IATA コード
aereo.cAerDes *	string	目的地空港 IATA コード
aereo.dVoo *	string	フライト日(YYYY-MM-DD)

infModal — 水路モーダル(modal="3")

フィールド	型	説明
aquav.irin *	string	船舶 IRIN
aquav.tpEmb *	string	船舶タイプ(2 桁)。Zeus 内部の `byte` 切り捨てを避けるため ≥ 10 の値を使用(例:`"10"`、`"11"`)
aquav.cEmbar *	string	船舶コード
aquav.xEmbar *	string	船舶名
aquav.nViag *	string	航海番号。ゼロで始められません(スキーマ検証) — `"1"`、`"100"` など。
aquav.cPrtEmb *	string	搭乗港コード
aquav.cPrtDest *	string	目的港コード
aquav.prtTrans	string	積み替え港
aquav.tpNav	string	航行タイプ
aquav.infTermCarreg[]	array	積込ターミナル:`[{ cTermCarreg, xTermCarreg }]`
aquav.infTermDescarreg[]	array	荷降しターミナル
aquav.infEmbComb[]	array	船団船舶:`[{ cEmbComb, xBalsa }]`
aquav.infUnidCargaVazia[]	array	空の貨物ユニット
aquav.infUnidTranspVazia[]	array	空の輸送ユニット

infModal — 鉄道モーダル(modal="4")

フィールド	型	説明
ferrov.trem *	object	列車データ:`{ xPref, dhTrem, xOri, xDest, qVag }`
ferrov.vag[] *	array	貨車:`[{ pesoBC, pesoR, tpVag, serie, nVag, nSeq, TU }]` — 最小 1。Zeus/SEFAZ の制約: `serie` は正確に 3 桁(100+ を使用、例:`"100"`);`nVag` は数字のみ(内部的に `long`、例:`"100001"`);`nSeq` はオプションで 1〜3 桁。

infDoc — 関連文書

フィールド	型	説明
infMunDescarga[] *	array	荷降市町村 — 最小 1
infMunDescarga[].cMunDescarga *	string	市町村 IBGE コード
infMunDescarga[].xMunDescarga *	string	市町村名
infMunDescarga[].infNFe[]	array	関連 NF-e:`[{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }]`
infMunDescarga[].infCTe[]	array	関連 CT-e
infMunDescarga[].infMDFeTransp[]	array	輸送 MDF-e(サブコントラクト)

prodPred — 主要製品

フィールド	型	説明
tpCarga *	string	貨物タイプ:`"01"`=固体ばら積み、`"02"`=液体ばら積み、`"03"`=冷蔵、`"04"`=コンテナ、`"05"`=一般貨物、`"06"`=新ばら積み、`"07"`=危険物、`"08"`=加圧ばら積み
xProd *	string	主要製品説明
cEAN	string	GTIN/EAN
NCM	string	NCM
infLotacao	object	ロット:`{ infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} }`

tot — 合計

フィールド	型	説明
vCarga *	decimal	貨物総額(> 0)
cUnid *	string	単位コード:`"01"`=KG、`"02"`=TON
qCarga *	decimal	貨物総量(> 0)
qCTe	int	Quantidade de 関連 CT-e
qNFe	int	関連 NF-e の数
qMDFe	int	関連 MDF-e の数

* 必須フィールド。⚠ CNPJ または CPF のいずれかが必須。

簡易例 — 道路モーダル

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

簡易例 — 航空モーダル

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

簡易例 — 水路モーダル

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

簡易例 — 鉄道モーダル

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

完全な例(全フィールド) — 道路モーダル

        {
          "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": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "nMDF": 1,
            "serie": 1,
            "protocolo": "135260000123456",
            "xml": "https://storage.../mdfe/2026-05-21/35260512345678000199580010000000011000000018.xml"
          }
        }

POST /api/mdfe/consult

MDF-e の状態照会

アクセスキーを使って SEFAZ で直接 MDF-e の状態を照会します。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

Body

フィールド	型	説明
chMDFe *	string	MDF-e アクセスキー(44 桁)

* 必須フィールド。

ペイロード例

        {
          "chMDFe": "35260512345678000199580010000000011000000018"
        }

レスポンス

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

MDF-e キャンセル

承認された MDF-e をキャンセルします。ウィンドウ: 承認後最大 24 時間。MDF-e が既に終了している場合は許可されません。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

Body

フィールド	型	説明
chMDFe *	string	MDF-e アクセスキー(44 桁)
xJust *	string	キャンセル理由(SEFAZ 要件により最小 15 文字)

* 必須フィールド。

ペイロード例

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

レスポンス

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

MDF-e 終了

旅行の終了時に MDF-e を終了します。終了後はキャンセルできなくなります。フィールド dtEnc、cUF、cMun はオプションです — 省略された場合、システムは元の MDF-e から推測します(現在の日付、発行者の UF と市町村)。

必須ヘッダー

ヘッダー	型	説明
token	string	発行企業のトークン
sign	string	MD5 署名
timestamp	string	Unix タイムスタンプ(秒)

Body

フィールド	型	説明
chMDFe *	string	MDF-e アクセスキー(44 桁)
dtEnc	string	終了日(YYYY-MM-DD)。デフォルト:現在の日付
cUF	int	終了が発生した UF の IBGE コード。デフォルト:発行者の UF
cMun	string	市町村 IBGE コード onde ocorreu o encerramento. Default: município do emitente

* 必須フィールド。

ペイロード例

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

レスポンス

        {
          "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 — トークンによる自動ログイン

ベース URL（本番）

https://api.tffiscal.com

認証

Headers: sign, timestamp, token

チケット有効期限

60 秒 — 1 回限り

SSO（シングルサインオン）を使用すると、ERP はユーザー向けに TFiscal への直接アクセスリンクを生成でき、資格情報を入力することなく、対応する会社と希望の言語で既に認証された状態で利用できます。

動作方法:

ERP は会社トークンを送信して POST /api/sso/create_ticket を呼び出します。
TFiscal は、1 回限りの不透明チケットを含む redirectUrl を返します。
ERP はユーザーのブラウザをその URL にリダイレクトします。
ページがチケットを消費し、ユーザーは会社パネルに自動的にログインします。

⚠️ セキュリティ: 実際の会社トークンは URL に決して表示されません。短期チケット（60 秒有効、1 回限り）のみがブラウザに公開されます。

POST /api/sso/create_ticket

自動ログインリンクの生成

60 秒以内に使用でき、ユーザーをトークンに対応する会社パネルに自動的にログインさせる 1 回限りのチケットを生成します。

必須ヘッダー

Header	型	説明
token	string	会社トークン（NF-e 発行に使用されるものと同じ）
sign	string	MD5 署名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 秒タイムスタンプ（5 分ウィンドウ）

Payload

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

フィールド

フィールド	必須	型	説明
token	はい	string	会社トークン（`w_company.token`）— `/api/invoice/create` で使用されるものと同じ
language	いいえ	string	UI 言語: `br`、`en`、`zh`、`es`、`ja`、`ko`。デフォルト: `br`
page	いいえ	string	ログイン後のランディングページ。許可される値: `emitir_nfe`。空または未指定の場合はデフォルトのパネル（`/company/kanban`）が開きます。

成功レスポンス

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

レスポンスフィールド

フィールド	型	説明
success	boolean	チケットが正常に生成された場合 `true`
ticket	string	不透明チケット（ランダム、32 バイト base64url）
redirectUrl	string	ERP がユーザーのブラウザをリダイレクトすべき完全な URL
expiresInSeconds	number	有効期限（秒）（常に 60）
expiresAt	string	UTC 有効期限（ISO 8601）

エラーレスポンス

メッセージ	原因
`Token は必須です`	body に `token` フィールドが送信されていない
`無効な Token`	トークンが登録された会社と一致しない
`このトークンは複数の会社に関連付けられています。アクセスしたい特定の会社のトークンを送信してください。`	複数会社を持つ統合業者トークン — 特定の会社のトークンを送信してください
`Rate limit exceeded`	同じトークンに対して 1 分あたり 30 回を超える呼び出し

POST /api/sso/consume_ticket

チケット消費でセッション JWT 取得

/api/sso/create_ticket で生成されたチケットを TFiscal セッション JWT と交換します。このエンドポイントはフロントエンド(/sso ルート)から呼び出され、sign/timestamp ヘッダーは不要です — 不透明なチケット自体が認証情報です。各チケットは 1 回だけ消費でき、60 秒で期限切れになります。

Body

フィールド	型	説明
ticket *	string	`create_ticket` から返されたチケット

* 必須フィールド。

ペイロード例

        {
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg"
        }

成功レスポンス

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

レスポンスフィールド

フィールド	型	説明
access_token	string	セッション JWT(365 日有効)。TFiscal 呼び出しの `Authorization` ヘッダーで使用
type	string	ユーザータイプ(`user`、`admin` など)
uid	int	内部ユーザー ID
company_id	int	`create_ticket` で選択された企業の ID
language	string	`create_ticket` で選択された言語(常に正規化)
page	string	遷移先ページ(未設定なら空文字列)

エラーレスポンス

メッセージ	原因
`Ticket inválido`	Body に `ticket` フィールドがない
`Ticket inválido ou expirado`	チケットが存在しない、すでに消費済み、または 60 秒の期限切れ
`Rate limit exceeded`	同じ IP から 1 分あたり 60 回を超える消費
`Sessão inválida`	チケットに紐付けられたユーザーが存在しなくなった

lock 制限とセキュリティ

チケットの特徴

特徴	値
有効期限	生成後 60 秒
使用	1 回限り — 消費後は再利用不可
レート制限	トークンあたり 30 チケット/分 · IP あたり 60 消費/分
ストレージ	自動 TTL の MongoDB — 期限切れチケットは削除されます

ナビゲーション制限

SSO で認証されたユーザーは、対応する会社の画面（/invoice/company/*）にのみアクセスできます。他のエリア（ディストリビューターパネル、一般レポート、管理）へのアクセス試行は会社パネルに自動的にリダイレクトされます。

ログイン後のセッション

チケットを JWT と交換すると、ユーザーは TFiscal の通常のセッションを持ちます（JWT は 365 日有効、従来のログインと同じ）。60 秒はチケット生成とリンクを開く間のウィンドウにすぎません — その後、ユーザーはサインアウトするまで通常どおりログインしたままです。

⚠️ 重要: create_ticket は ERP によってサーバーサイドでのみ呼び出される必要があります。ブラウザから直接このエンドポイントを呼び出さないでください — フロントエンドで会社トークンが公開されてしまいます。

badge 会計士(Contador)

企業に紐付けられた会計士の登録データを取得するための API。特定の企業を担当する会計士の完全なデータを取得する必要がある外部会計システムに便利です。

POST /api/accountant/get_info

企業に紐付けられた会計士の情報取得

指定された企業に紐付けられた会計士の完全な登録データを返します。会計士は事前に企業(同じ CNPJ)に紐付けられており、指定されたメールアドレスは登録と一致する必要があります。

必須ヘッダー

ヘッダー	型	説明
token	string	企業トークンまたはインテグレーター B2B トークン
sign	string	MD5 署名:`MD5(token + path + body + timestamp)`
timestamp	string	Unix タイムスタンプ(秒、5 分のウィンドウ)

Body

フィールド	型	説明
companyId *	int	トークンに紐付けられた企業 ID
accountantId *	string	会計士 ObjectId(24 桁の 16 進数)
email *	string	会計士メール(登録と一致する必要あり)

* 必須フィールド。

ペイロード例

      {
        "companyId": 12345,
        "accountantId": "5f3a8b9c1d2e4f5a6b7c8d9e",
        "email": "accountant@office.com"
      }

成功レスポンス

      {
        "success": true,
        "data": {
          "email": "accountant@office.com",
          "officeDocumentType": "CNPJ",
          "officeDocument": "12345678000199",
          "officeName": "会計事務所 LTDA",
          "responsibleName": "山田 太郎",
          "crc": "SP123456/O-7",
          "accountantCpf": "12345678909",
          "workAddress": "サンプル通り 100 - 中央 - São Paulo/SP",
          "site": "https://office.com",
          "landline": "1133334444",
          "mobile": "11999998888",
          "assistantName": "佐藤 花子",
          "assistantEmail": "hanako@office.com",
          "assistantPhone": "11988887777",
          "observations": "月曜〜金曜、9 時〜18 時受付"
        }
      }

レスポンスフィールド

フィールド	型	説明
email	string	会計士のプライマリメール
officeDocumentType	string	事務所書類タイプ:"CNPJ" または "CPF"
officeDocument	string	事務所書類(数字のみ)
officeName	string	事務所の法人名 / 名称
responsibleName	string	担当会計士の氏名
crc	string	CRC 番号(ブラジル地域会計評議会)
accountantCpf	string	会計士 CPF(数字のみ)
workAddress	string	事業所住所
site	string	事務所ウェブサイト
landline	string	固定電話
mobile	string	携帯電話
assistantName	string	アシスタント名
assistantEmail	string	アシスタントメール
assistantPhone	string	アシスタント電話
observations	string	登録のフリー備考

エラーレスポンス

メッセージ	原因
会计师ID参数异常或不存在	`accountantId` がないか有効な ObjectId ではない
该会计师邮箱异常或不存在	`email` が無効または未登録
发票账号{companyId}异常或不存在	`companyId` がトークンユーザーに属していない
该会计师未绑定该发票账号	会計士が指定された企業に紐付けられていない

NFE API ドキュメント

重要なAPIフィールド

請求書発行プロセスフロー

1. 企業登録

2. 情報送信

3. 請求書発行

4. 結果返却

5. ファイル生成

税務検証

Success

Failure

エンドポイント クイックリファレンス

成功

クライアントエラー

サーバーエラー

NFE API

sync_alt System Flow

input Input Data

settings Processing

download Output

主要エンドポイント

必須ヘッダー

Body

ペイロード例

レスポンス

必須ヘッダー

Body

ペイロード例

レスポンス

必須ヘッダー

Body

ペイロード例

レスポンス

必須ヘッダー

クエリ文字列

呼び出し例

レスポンス

必須ヘッダー

呼び出し例

レスポンス

必須ヘッダー

クエリ文字列

呼び出し例

レスポンス

必須ヘッダー

呼び出し例

レスポンス

レスポンス例

必須ヘッダー

Body — トップレベル項目

Body — cliente（オブジェクト、必須）

Body — products[]（配列、最小 1 項目）

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

Body — products[].ii（輸入税）

Body — products[].import_declarations[]

Body — shipping_address / delivery_address（オブジェクト、オプション）

Body — transportation（オブジェクト、オプション）

Body — pag_info[]（配列、オプション）

簡易例

完全な例(全フィールド)

必須ヘッダー

クエリ文字列

呼び出し例

レスポンス

必須ヘッダー

クエリ文字列

呼び出し例

レスポンス

必須ヘッダー

Body

ペイロード例

必須ヘッダー

Body

ペイロード例

必須ヘッダー

Body

ペイロード例

必須ヘッダー

Body

ペイロード例

エンドポイントクイックリファレンス

Body — `cliente`（オブジェクト、必須）

Body — `products[]`（配列、最小 1 項目）

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

Body — `products[].ii`（輸入税）

Body — `products[].import_declarations[]`

Body — `shipping_address` / `delivery_address`（オブジェクト、オプション）

Body — `transportation`（オブジェクト、オプション）

Body — `pag_info[]`（配列、オプション）

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` と `cofins[]`（同じ構造）

Body — `ibs_cbs[]`（税制改革）

Body — `is[]`（選択税）