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取得
`/api/nfce/get_list`	GET	NFC-e 一覧（ページネーション）
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ダウンロード
`/api/nfse/get_list`	GET	NFS-e 一覧（ページネーション）
`/api/nfs/company/create`	POST	NFS-e発行用の企業を登録
receipt_long NF-e — イベントと照会
`/api/invoice/get_danfe`	POST	NF-e の DANFE（PDF）取得
`/api/invoice/consultar_status`	POST	SEFAZ で NF-e/NFC-e の状態を照会
`/api/invoice/validar_cpf_cnpj`	POST	連邦国税庁のデータベースで CPF/CNPJ を検証
`/api/invoice/cce/send`	POST	訂正状（CC-e）を送信
`/api/invoice/cce/get_list`	POST	NF-e の CC-e 一覧
`/api/invoice/cce/download_pdf`	POST	CC-e の PDF ダウンロード
`/api/invoice/cce/download_xml`	POST	CC-e の XML ダウンロード
mark_email_read NF-e — 表明と受信ドキュメント
`/api/invoice/manifest`	POST	受信者の表明イベントを送信
`/api/invoice/manifest/list`	POST	送信済みの表明を一覧
`/api/invoice/manifest/get_xml`	POST	表明の XML を取得
`/api/invoice/received/sync`	POST	受信した NF-e/イベントを同期（DistDFe）
`/api/invoice/received/list`	POST	受信ドキュメントを一覧
`/api/invoice/received/get_xml`	POST	受信ドキュメントの XML を取得
`/api/invoice/received/get_sync_status`	POST	DistDFe 同期の状態を照会
category NFC-e — 税務カテゴリ
`/api/nfce/category/create`	POST	NFC-e 税務カテゴリを作成
`/api/nfce/category/edit`	POST	NFC-e 税務カテゴリを編集
`/api/nfce/category/delete`	POST	NFC-e 税務カテゴリを削除
`/api/nfce/category/get_detail`	GET	NFC-e カテゴリの詳細を取得
`/api/nfce/category/get_list`	GET	NFC-e 税務カテゴリを一覧
local_shipping MDF-e（電子税務文書マニフェスト）
`/api/mdfe/create`	POST	MDF-e 発行
`/api/mdfe/consult`	POST	MDF-e の状態照会
`/api/mdfe/cancel`	POST	MDF-e キャンセル
`/api/mdfe/close`	POST	MDF-e 終了
`/api/mdfe/get_list`	GET	MDF-e 一覧（ページネーション）
inventory_2 DC-e（電子内容物申告）
`/api/dce/create`	POST	DC-e 発行
`/api/dce/consult`	POST	DC-e の状態照会
`/api/dce/cancel`	POST	DC-e キャンセル
`/api/dce/pdf`	POST	DC-e の DACE（PDF）取得
`/api/dce/get_list`	GET	DC-e 一覧（ページネーション）
local_shipping CT-e（電子運送状）
`/api/cte/create`	POST	CT-e 発行
`/api/cte/cancel`	POST	CT-e キャンセル
`/api/cte/cce`	POST	訂正状（CC-e）
`/api/cte/desacordo`	POST	役務提供の不承認
`/api/cte/consult`	POST	CT-e の状態照会
`/api/cte/inutilize`	POST	番号の範囲を無効化
`/api/cte/get_list`	GET	CT-e 一覧（ページネーション）
vpn_key SSO（自動ログイン）
`/api/sso/create_ticket`	POST	自動ログインリンクを生成
`/api/sso/consume_ticket`	POST	チケットを消費しセッション JWT を取得
account_balance 会計士
`/api/accountant/get_info`	POST	企業に紐付けられた会計士の情報取得

📋 重要事項:

すべてのエンドポイントはヘッダーによる認証が必要です: 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	番号の初期値
輸送 (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e のシリーズ
number_mdfe	int	MDF-e の開始番号（採番の起点）
serie_cte	int	CT-e のシリーズ
number_cte	int	CT-e の開始番号（採番の起点）
serie_dce	int	DC-e のシリーズ
number_dce	int	DC-e の開始番号（採番の起点）
is_create_category_template	boolean	デフォルトの税カテゴリを自動作成。デフォルト: `true`

* 必須項目。

ペイロード例

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

レスポンス

        {
          "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://exemplo.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 を一緒に送ると、証明書は保存前に検証されます。

会社は NF-e の設定で作成されます（/api/company/create 経由）。他の帳票を有効にするには、ここで登録を完了してください: このエンドポイントは NFC-e、NFS-e、MDF-e、CT-e、DC-e の項目も受け付けます（下記のセクションを参照）。会社が発行する帳票の項目のみ送信してください。

必須ヘッダー

ヘッダー	型	説明
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	新しい初期番号
alias	string	屋号
telefone	string	電話番号
complemento	string	住所の補足
NFC-e
csc_id	string	SEFAZ における CSC（納税者セキュリティコード）の ID
csc	string	CSC トークン（SEFAZ と共有する秘密）
serie_nfce	int	NFC-e シリーズ
number_nfce	int	NFC-e の次の番号
NFS-e
im	string	市町村登録番号(Inscrição Municipal)
codigo_municipio_nfse	string	発行市町村の IBGE コード
codigo_servico_nfse	string	デフォルトサービスコード(LC 116)
cnae_nfse	string	デフォルト活動 CNAE
serie_nfse	int	NFS-e の初期シリーズ
number_nfse	int	NFS-e の初期番号
regime_especial_tributacao	int	特別税制コード
optante_simples_nacional	bool	Simples Nacional への加入
輸送 (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e のシリーズ
number_mdfe	int	MDF-e の開始番号（採番の起点）
serie_cte	int	CT-e のシリーズ
number_cte	int	CT-e の開始番号（採番の起点）
serie_dce	int	DC-e のシリーズ
number_dce	int	DC-e の開始番号（採番の起点）

* 必須項目。cnpj を送るとエラーを返します。その他の項目はすべて任意です — 変更したい項目のみ送信してください。

ペイロード例

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

例 — 会社で NFC-e と CT-e を有効化

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

レスポンス

        {
          "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": "contato@empresa.com",
                "cep": "01001000",
                "address": "Rua Exemplo",
                "house_number": "100",
                "town": "Centro",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://exemplo.com/cert.pfx",
                "cert_pwd": "***",
                "serie": 1,
                "number": 142
              }
            ],
            "page": 1,
            "total": 8,
            "total_pages": 1
          }
        }

GET /api/company/get_detail

認証済み企業の詳細

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": "contato@empresa.com",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://exemplo.com/cert.pfx",
            "cert_pwd": "***",
            "serie": 1,
            "number": 142,
            "categorys": [
              {
                "category_id": "cat_001",
                "descricao": "Venda de mercadoria",
                "disable_difal": false,
                "desconta_icms_pis_cofins": false
              }
            ]
          }
        }

GET /api/company/get_cep_detail

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	ステータスでフィルタ（値: `"Success"`（承認済み）、`"Canceled"`（キャンセル済み）、`"Voided"`（無効化済み）、`"Processing"`（処理中）、`"InvoicingFailed"`（発行失敗）、`"Failed"`（失敗）、`"Contingencia"`（オフライン緊急）、`"Unknown"`（不明））

* 必須項目。

呼び出し例

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

レスポンス

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

GET /api/invoice/get_detail

NF-e の詳細を取得

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

必須ヘッダー

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

クエリ文字列

パラメータ	型	説明
uuid	string	NF-e の UUID
chave	string	NF-e のアクセスキー（44 桁）

uuid または chave のいずれかを指定してください（少なくとも 1 つ）。両方を送信した場合は uuid が優先されます。

呼び出し例

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

レスポンス

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

POST /api/invoice/refresh

請求書ステータスを更新

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" }],
          "ibs_cbs":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "000", "classificacao_tributaria": "000001" }]
        }

レスポンス

        {
          "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 で参照 — 返品は元の NF-e の完全なクローン）または 一部／カスタム返品（chave + インボイスの完全な項目をボディ直下で送信。/api/invoice/create と同じ構造）。

必須ヘッダー

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

Body — トップレベル項目

項目	型	説明
uuid	string	元の NF-e の UUID（全額返品用。`chave` が無い場合は必須）。送信された場合は常に全額返品となり、一部返品の項目は無視されます
chave	string	元の NF-e の 44 桁アクセスキー（一部返品では必須。全額返品では `uuid` の代替）
cfop *	string	返品 CFOP（例: `"1202"`、`"1411"`、`"2202"`、`"5202"`、`"5411"`、`"6202"`）
natureza_operacao	string	取引の性質（例: 「Devolução de venda」）。エイリアス対応: `nature_of_operation`
transaction_type	string	取引タイプ: `"0"`=入庫、`"1"`=出庫（一部返品では必須）。返品 NF-e は常に入庫（`tpNF=0`）として発行されます
model	string	ドキュメントモデル: `"55"`（一部返品では必須）
issuance_type	string	発行タイプ: `"1"`=通常（一部返品では必須）
ambiente	string	環境: `"1"`=本番、`"2"`=検証（一部返品では必須）
cliente	object	受取人データ。`/api/invoice/create` と同じ構造（一部返品では必須）。注意点: 住所番号項目は `number`（英語）であり `numero` ではありません。`number` が無い場合、住所は nro "S/N" で出力されます。IBGE コード・市・州は `cep` から解決されます
products	array	返品対象の商品。`/api/invoice/create` と同じ構造（一部返品では必須）。`codigo` は任意 — 省略時は cProd に `name` が使われます

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

返品時の自動処理: 支払いは 90（支払いなし）で出力され、pag_info は無視されます。natureza_operacao 未指定時は「Devolução de Mercadoria」が使われます。品目の税務情報（CST/CSOSN、PIS/COFINS、IPI、IBS/CBS）は category_id の税務カテゴリから、人区分とシナリオに応じて解決されます。

例 — 全額返品

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

例 — 一部返品（完全な項目をボディに記載）

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

code 完全な請求書発行例

輸送を含む完全な例

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

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

輸入の完全な例

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

💡 情報: 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（海上）の場合に必須です。

percent 詳細な税務パラメータ

scale_balance ICMS パラメータ

課税シナリオ

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado entrada_dentro_estado

税務状況（CST）

00: 全額課税

02: 課税（免除扱い）

10: ICMS 徴収を伴う課税

20: 課税標準の軽減あり

30: 免税または非課税

40: 免税

41: 非課税

50: 停止

51: 繰延

60: ICMS 既徴収

70: 軽減および徴収

90: その他

pie_chart PIS/COFINS パラメータ

課税シナリオ

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado entrada_dentro_estado

税務状況（CST）

01: 課税取引（通常税率）

02: 課税取引（差別税率）

03: 課税取引（免税）

04: 課税取引（停止）

05: 課税取引（ST）

06: 課税取引（ゼロ税率）

07: 拠出金免除取引

08: 拠出金非課税取引

09: 拠出金停止取引

49: その他の出庫取引

50: 控除権（自社取引）

51: 控除権（仕入）

52: 貸方計上

53: 借方計上

54: 貸方計上（期限外）

55: 借方計上（期限外）

56: みなし控除

60: みなし控除（仕入）

61: みなし控除（輸入）

62: みなし控除（農業活動）

63: みなし控除（その他）

64: みなし控除（非発生）

65: みなし控除（代替）

66: みなし控除（代替）

67: みなし控除（輸出）

70: 控除権のない仕入取引

71: 免除付き仕入取引

72: 停止付き仕入取引

73: ゼロ税率の仕入取引

74: 非課税の仕入取引

75: 代替による仕入取引

98: その他の入庫取引

99: その他の取引

💡 情報: tipo_pessoa 項目は fisica（個人）または juridica（法人）を受け付けます。 PIS/COFINS では、aliquota 項目は小数点以下 2 桁の文字列（例: "1.65"）でフォーマットする必要があります。

credit_card 支払いパラメータ

支払い指標

`0`	即時払い
`1`	後払い

支払い方法

`01`	現金
`02`	小切手
`03`	クレジットカード
`04`	デビットカード
`05`	ストアクレジット
`10`	食品バウチャー（Vale Alimentação）
`11`	食事バウチャー（Vale Refeição）
`12`	ギフト券
`13`	燃料バウチャー
`15`	銀行振込票
`90`	支払いなし
`99`	その他

カードブランド

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

bug_report XML トラブルシューティング

warning 拒否 225 - XML スキーマエラー

SEFAZ のデータベースに正常に登録されていない NF-e に対して、キャンセル、XML ダウンロード、番号の無効化、またはマニフェスト登録を行おうとしたときに発生します。

NF-e が承認されたか確認（ステータス「承認済み」）

承認されていない場合は NF-e を再発行

未使用の場合は番号を無効化

lightbulb SEFAZ オンライン検証

公式バリデーターを使用して XML の問題を特定:


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

よくある問題: 住所の不備、無効な NCM、値のフォーマット誤り、必須項目の欠落。

error SEFAZ エラーコード

コード	説明	解決策
`217`	発行日が古すぎる	コンティンジェンシーで発行するか正規化する
`404`	宛先の CNPJ/CPF が無効	顧客の書類を確認
`563`	取引で許可されていない CFOP	取引の CFOP を見直す

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

レスポンス

        {
          "success": true,
          "message": "Empresa cadastrada para 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": "Loja Centro - Filial 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

レスポンス

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

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": "Loja Centro",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contato@empresa.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "complemento": "Sala 5",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://exemplo.com/cert.pfx",
            "csc_id": "000001",
            "csc": "ABCDEF0123456789",
            "serie_nfce": 1,
            "number_nfce": 42
          }
        }

NFC-e Fiscal Category Management

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

注意: 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": "Success",
            "modelo": "nfce",
            "total_price": 145.90,
            "nprot": "135210000123456",
            "motivo": "",
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave_nfce.pdf",
            "client_cpf": "12345678909",
            "client_cnpj": "",
            "client_name": "Cliente",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/nfce/get_danfe

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

GET /api/nfce/get_list

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

会社の NFC-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	ステータスでフィルタ。値: `"Success"`（承認済み）、`"Canceled"`（キャンセル済み）、`"Processing"`（処理中）、`"Failed"`（失敗）、`"Unknown"`（不明）

* 必須項目。

呼び出し例

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

レスポンス

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

code NFC-e Complete Examples

Example 1 — In-Person Sale (no recipient)

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

Example 2 — Home Delivery (with recipient)

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

tune NFe Adjustment / Supplementary

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

Supplementary NFe (finalidade = 2):

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

Adjustment NFe (finalidade = 3):

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

重要:

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": "Exemplo",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contato@empresa.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "Rua Exemplo",
          "house_number": "86",
          "complemento": "Andar 2",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://storage.exemplo.com/cert.pfx",
          "cert_pwd": "senha-do-certificado",
          "im": "12345678",
          "codigo_municipio_nfse": "3550308",
          "codigo_servico_nfse": "07498",
          "cnae_nfse": "6201501",
          "serie_nfse": 1,
          "number_nfse": 1,
          "regime_especial_tributacao": 0,
          "optante_simples_nacional": true
        }

レスポンス

        {
          "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": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_dps.xml",
            "nfseXml": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_nfse.xml"
          }
        }

dpsXml: 市役所/ADNに送信されたXMLのリンク（OSS URL）。 nfseXml: 発行結果を含む返却XMLのリンク。XMLは初回リクエスト時にOSSへアップロードされ、URLはキャッシュされます。

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

Specific Fields

フィールド	タイプ	説明
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": "CHAVE_NFE_AQUI",
          "nature_of_operation": "Ajuste fiscal",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "ind_final": "1",
          "ind_pres": "2",
          "cliente": {
            "cpf": "264.438.800-72",
            "name": "Nome do Destinatário",
            "endereco": "Rua Example",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "indIEDest": "9"
          },
          "products": [
            {
              "codigo": "001",
              "name": "Ajuste fiscal - Regularização",
              "ncm": "82100090",
              "count": 1,
              "unit": "UN",
              "unit_price": 0.01,
              "total_price": 0.01,
              "category_id": "SEU_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5949"
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

Specific Fields

フィールド	タイプ	説明
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 の状態のみを読み取ります。

GET /api/nfse/get_list

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

会社の NFS-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	ステータスでフィルタ。値: `"autorizada"`、`"cancelada"`、`"pendente"`、`"rejeitada"`

* 必須項目。

呼び出し例

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

レスポンス

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

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

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 を発行します。フィールド cMDF、cDV、cUF、dhEmi、mod、tpEmis、procEmi、verProc はサーバーによって自動的に計算されます。serie と nMDF は任意です。省略時（または 0 の場合）はサーバーが自動的に採番し、リクエストで指定された場合はその値が尊重されます（例えば SEFAZ で重複が発生した後に番号をスキップする際に便利です）。クライアントはビジネスフィールドのみを送信します。

必須ヘッダー

ヘッダー	型	説明
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	後続積み込みインジケータ
serie	int	MDF-e のシリーズ（アクセスキーの 3 桁）。任意 — 省略時または `0` の場合は自動割り当て（企業の MDF-e シリーズ）、送信時はその値が使用されます
nMDF	int	MDF-e の番号（アクセスキーを構成）。任意 — 省略時または `0` の場合はサーバーが自動採番、送信時はその値が使用されます（番号をスキップしたい場合、例: 重複後などに便利です）

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

GET /api/mdfe/get_list

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

会社の MDF-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	ステータスでフィルタ。値: `"Success"`（承認済み）、`"Canceled"`（キャンセル済み）、`"Voided"`（終了）、`"Processing"`（処理中）、`"Failed"`（失敗）、`"Unknown"`（不明）

* 必須項目。

呼び出し例

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

レスポンス

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

inventory_2 DC-e — 電子内容物申告（Declaração de Conteúdo Eletrônica）

DC-e API（モデル 99、レイアウト 1.00）は、電子内容物申告の発行・照会・キャンセル・PDF（DACE）取得を可能にします。DC-e は、税務文書（ノタフィスカル）の発行義務がない場合 — 例えば ICMS の非納税者を含む発送など — に物品や商品の輸送を裏付ける税務文書です。発行者は常に法人（CNPJ）であり、受取人は法人（CNPJ）または個人（CPF）のいずれでも構いません。業務データは /create のボディに渡します。アクセスキーの技術的な項目（cDC、cDV、cUF、dhEmi、mod）はサーバーが自動的に計算します。

エンドポイント	メソッド	説明
`/api/dce/create`	POST	DC-e を発行
`/api/dce/consult`	POST	DC-e の状況を照会
`/api/dce/cancel`	POST	承認済みの DC-e をキャンセル
`/api/dce/pdf`	POST	DC-e の DACE（PDF）を取得

DC-e は発行者の UF の認可機関へルーティングされます。ide.cUF 項目は emit.enderEmit.UF に指定された UF と一致している必要があります — 不一致の場合、SEFAZ は cStat=220 で拒否します。省略された場合、cUF はその UF から導出されます。

POST /api/dce/create

DC-e を発行

送信されたボディから DC-e を発行します。クライアントは業務データのみを送信します。アクセスキーの技術的な識別項目はサーバーが計算します（ide テーブルの下の注記を参照）。クレジットの引き落としは本番環境（tpAmb=1）でのみ、かつ DC-e が承認された場合にのみ発生します。

必須ヘッダー

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

Body — ルート

項目	型	説明
ide *	object	DC-e の識別情報
emit *	object	発行者／差出人のデータ（CNPJ、または Marketplace 経由の CPF — 下記参照）
dest *	object	受取人のデータ
det *	array	申告する品目／物品 — 最低 1 件
total *	object	申告の合計
transp	object	輸送のデータ
marketplace	object	マーケットプレイスのデータ（`ide.tpEmit=1` の場合のみ）
fisco	object	税務当局機関のデータ（`ide.tpEmit=0` の場合のみ）
autXML	array	XML へのアクセスを許可された CNPJ／CPF
infAdic	object	追加情報

リクエストの必須項目: ide.tpAmb；emit.CNPJ（14 桁）または emit.CPF（11 桁、Marketplace 経由の個人差出人 — emit の注記を参照）、emit.xNome および emit.enderEmit（xLgr、nro、xBairro、cMun、xMun、CEP は 8 桁、UF）；dest は CNPJ または CPF、dest.xNome および dest.enderDest（同じ住所項目）；det に最低 1 件、xProd、NCM（2 桁または 8 桁）、qCom > 0 および vProd > 0 を含むこと；そして total.vDC > 0。それ以外のすべての項目は任意です。

ide — 識別情報

項目	型	説明
tpAmb *	int	環境: `1`=本番、`2`=検証。`ide` の中で唯一の真に必須な項目。
tpEmit	int	発行者の種別: `0`=税務当局アプリ、`1`=マーケットプレイス、`2`=自己発行者。任意 — デフォルト: `2`
cUF	int	発行者の UF の IBGE コード（2 桁）。任意 — 省略時は `emit.enderEmit.UF` から導出。送信する場合はその UF と一致している必要があります（不一致の場合 SEFAZ は `cStat=220` で拒否）
serie	int	税務文書のシリーズ（アクセスキーの 3 桁）— DC-e の採番グループを識別します。任意 — デフォルト: 企業に登録された DC-e のシリーズ
nDC	long	DC-e の連番（アクセスキーを構成）。任意 — 省略時または `0` の場合、サーバーが自動採番
nSiteAutoriz	int	DC-e を処理した認可サイトの識別（アクセスキーの 1 桁）。通常は `0`（プライマリサイト）。任意 — デフォルト: `0`
tpEmis	int	発行形態: `1`=通常、`9`=コンティンジェンシー。任意 — デフォルト: `1`

サーバーが自動的に設定 — 送信する必要はありません: mod（99 に固定）と cDV（キーのチェックディジット）は常にサーバーが設定します。cDC（6 桁の数値コード）、dhEmi（発行日時）、verProc（プロセスのバージョン）は省略時に生成されます。上のテーブルの serie、nDC、cUF も省略時に自動的に設定されます。

emit — 発行者 / 差出人

項目	型	説明
CNPJ ⚠	string	発行者の CNPJ（14 桁）。省略時はトークンの企業の CNPJ が設定されます
CPF ⚠	string	個人差出人の CPF（11 桁）。Marketplace 経由の発行でのみ許可されます — 下記の注記を参照
xNome *	string	発行者／差出人の氏名または商号
enderEmit *	object	発行者の住所（下記の構造を参照）

個人差出人（CPF）: SEFAZ の規則により、CPF は自己発行者になれません（tpEmit=2 は CNPJ が必須）。CPF を差出人として発行するには、emit.CPF を送信するだけです（emit.CNPJ なし）。サーバーが自動的に tpEmit=1（Marketplace）を設定し、アクセスキーの認可発行者として貴社の CNPJ（トークンの企業）を使用し、marketplace ブロックに企業のデータを設定します。入力した CPF は emit の差出人として表示されます。

dest — 受取人

項目	型	説明
CNPJ ⚠	string	受取人の CNPJ（14 桁）
CPF ⚠	string	受取人の CPF（11 桁）
xNome *	string	受取人の氏名または商号
enderDest *	object	受取人の住所（下記の構造を参照）

enderEmit / enderDest — 住所

項目	型	説明
xLgr *	string	街路名
nro *	string	番地
xCpl	string	補足
xBairro *	string	地区
cMun *	long	自治体の IBGE コード（7 桁）
xMun *	string	自治体名
CEP *	string	CEP（郵便番号、8 桁）
UF *	string	UF の略号（2 文字）
cPais	int	国コード。デフォルト: `1058`（ブラジル）
xPais	string	国名。デフォルト: `BRASIL`
fone	string	電話番号
email	string	メールアドレス

det[] — 申告品目

項目	型	説明
nItem	int	品目の連番
xProd *	string	申告する物品／商品の説明
NCM *	string	NCM コード（2 桁または 8 桁）
qCom *	decimal	数量（> 0）
vUnCom	decimal	単価
vProd *	decimal	品目の合計金額（> 0）
infAdProd	string	品目の追加情報

total — 合計

項目	型	説明
vDC *	decimal	申告合計金額（> 0）

transp — 輸送

項目	型	説明
modTrans	int	輸送形態: `0`=郵便（Correios）、`1`=自社、`2`=運送業者。デフォルト: `2`
CNPJTransp	string	運送業者の CNPJ

marketplace — マーケットプレイス（`tpEmit=1` の場合のみ）

項目	型	説明
CNPJ	string	マーケットプレイスの CNPJ
xNome	string	マーケットプレイスの名称
Site	string	マーケットプレイスのサイト

fisco — 税務当局機関（`tpEmit=0` の場合のみ）

項目	型	説明
CNPJ	string	機関の CNPJ
xOrgao	string	機関の名称
UF	string	機関の UF

autXML[] — XML 許可対象

項目	型	説明
CNPJ	string	XML の照会／ダウンロードを許可された CNPJ
CPF	string	XML の照会／ダウンロードを許可された CPF

infAdic — 追加情報

項目	型	説明
infAdFisco	string	税務当局向けの情報
infCpl	string	納税者向けの補足情報
infAdMarketPlace	string	マーケットプレイスの追加情報

* 必須項目。⚠ 発行者と受取人では、CNPJ または CPF の少なくとも一方が必須です。

簡略例（最小限の項目）

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

完全例（すべての項目）

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

成功レスポンス

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

拒否レスポンス

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

POST /api/dce/consult

DC-e の状況を照会

アクセスキーから SEFAZ における DC-e の現在の状況を照会します。DC-e がキャンセル済みの場合、レスポンスはキャンセルのデータを反映します（キャンセルについてはローカルのデータベースが信頼できる情報源となります）。

必須ヘッダー

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

Body

項目	型	説明
chDCe *	string	DC-e のアクセスキー（44 桁）

* 必須項目。

ペイロード例

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

レスポンス — DC-e 有効

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

レスポンス — DC-e キャンセル済み

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

POST /api/dce/cancel

DC-e をキャンセル

承認済みの DC-e をキャンセルします（イベント 110111）。DC-e が承認済み（プロトコルを持つ）であり、まだキャンセルされていないことが必要です。各 DC-e はキャンセルを 1 回のみ行えます。

必須ヘッダー

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

Body

項目	型	説明
chDCe *	string	DC-e のアクセスキー（44 桁）
xJust *	string	キャンセルの理由（SEFAZ の要件により最低 15 文字）
nProt	string	承認プロトコル。任意: 省略時は発行時に記録されたプロトコルを使用します

* 必須項目。

ペイロード例

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

成功レスポンス

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

拒否された場合、レスポンスは success=false、拒否の cStat／xMotivo、および診断用に送信した XML を含む追加項目 xmlEnviadoDebug を返します。

POST /api/dce/pdf

DC-e の DACE（PDF）を取得

DACE — DC-e の PDF 表現 — の URL を返します。PDF がまだストレージに存在しない場合は、オンデマンドで生成して送信します。ストレージが利用できない場合は、PDF をレスポンス本文内に base64 で返します。

必須ヘッダー

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

Body

項目	型	説明
chDCe *	string	DC-e のアクセスキー（44 桁）

* 必須項目。

ペイロード例

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

レスポンス — PDF の URL

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

レスポンス — base64 フォールバック（ストレージ利用不可）

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

GET /api/dce/get_list

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

会社の DC-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	ステータスでフィルタ。値: `"Success"`（承認済み）、`"Canceled"`（キャンセル済み）、`"Processing"`（処理中）、`"Failed"`（失敗）、`"Unknown"`（不明）

* 必須項目。

呼び出し例

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

レスポンス

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

local_shipping CT-e — 電子運送状（Conhecimento de Transporte Eletrônico）

CT-e API（モデル 57、レイアウト 4.00 + NT2025/001）は、電子運送状の発行・キャンセル・訂正（CC-e）・役務提供の不承認の登録・照会・番号の無効化を可能にします。CT-e は貨物輸送の役務提供を裏付ける文書です。6 つのモーダル（道路、航空、水運、鉄道、パイプライン、複合輸送）と 4 種類の CT-e（通常、補完、取消、代替）に対応します。業務データは /create のボディに渡します。アクセスキーの技術的な項目（cCT、cDV、cUF、dhEmi、mod）はサーバーが自動的に計算します。serie と nCT は任意です。省略時（または 0 の場合）はサーバーが自動的に採番し、リクエストで指定された場合はその値が尊重されます（例えば SEFAZ で重複が発生した後に番号をスキップする際に便利です）。

エンドポイント	メソッド	説明
`/api/cte/create`	POST	CT-e を発行
`/api/cte/cancel`	POST	CT-e をキャンセル（イベント 110111）
`/api/cte/cce`	POST	訂正状 — CC-e（イベント 110110）
`/api/cte/desacordo`	POST	役務提供の不承認（イベント 610110、荷主が登録）
`/api/cte/consult`	POST	CT-e の状況を照会
`/api/cte/inutilize`	POST	番号の範囲を無効化

役務の荷主（運賃の支払者）は ide.toma で定義します: 0=差出人、1=発送人、2=受領人、3=荷受人、4=その他（この場合は ide.toma4 を入力）。

POST /api/cte/create

CT-e を発行

送信されたボディから CT-e を発行します。クライアントは業務データのみを送信します。アクセスキーの技術的な識別項目はサーバーが計算します（ide テーブルの下の注記を参照）。クレジットの引き落としは本番環境（tpAmb=1）でのみ、かつ CT-e が承認された場合にのみ発生します。以下の例は最も一般的なケースを扱います: 道路モーダル（modal=01）かつ 通常 CT-e（tpCTe=0）。

必須ヘッダー

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

リクエストの必須項目: ide（tpAmb、CFOP、natOp、modal、tpCTe、toma、cMunIni、UFIni、cMunFim、UFFim）；emit は CNPJ または CPF と xNome；rem は CNPJ または CPF；dest は CNPJ または CPF；vPrest.vTPrest > 0；imp（ICMS のいずれか 1 つのバリアントを含む）。tpCTe=0（通常）の場合: infCTeNorm に infCarga（proPred + 最低 1 件の infQ）と infModal（ide.modal に対応するモーダル；modal=01 の場合は rodo.RNTRC が必須）。その他の項目は任意です。

Body — ルート

項目	型	説明
ide *	object	CT-e の識別情報
emit *	object	発行者（運送人）のデータ
rem *	object	貨物の差出人
dest *	object	貨物の荷受人
vPrest *	object	役務提供の金額
imp *	object	税（ICMS + 各種税）
infCTeNorm *	object	通常 CT-e の本体 — `tpCTe=0`（通常）または `3`（代替）の場合に必須
exped	object	発送人（任意）
receb	object	受領人（任意）
compl	object	補完データ（備考、フロー、配送）
infCteComp	object	補完された CT-e のキー — `tpCTe=1`（補完）の場合に必須: `{ chCTe }`
infCteAnu	object	取消された CT-e のキー — `tpCTe=2`（取消）の場合に必須: `{ chCte, dEmi }`
autXML	array	XML へのアクセスを許可された CNPJ／CPF: `[{ CNPJ } \| { CPF }]`
infRespTec	object	技術責任者 — サーバーが UF ごとに自動的に設定

ide — 識別情報

項目	型	説明
tpAmb *	int	環境: `1`=本番、`2`=検証
CFOP *	int	取引の財務コード（例: 州内は `5353`、州間は `6353`）
natOp *	string	取引の性質（例: `"PRESTACAO DE SERVICO DE TRANSPORTE"`）
modal *	string	モーダル: `"01"`=道路、`"02"`=航空、`"03"`=水運、`"04"`=鉄道、`"05"`=パイプライン、`"06"`=複合輸送
tpCTe *	int	CT-e の種別: `0`=通常、`1`=補完、`2`=取消、`3`=代替
tpServ *	int	役務の種別: `0`=通常、`1`=下請、`2`=再発送、`3`=中間再発送、`4`=複合輸送に連動する役務
toma *	int	役務の荷主: `0`=差出人、`1`=発送人、`2`=受領人、`3`=荷受人、`4`=その他
toma4	object	荷主のデータ — `toma=4` の場合に必須（下記のテーブルを参照）
indIEToma	int	荷主の IE 指標: `1`=ICMS 納税者、`2`=免除、`9`=非納税者（`9` の場合、荷主の IE は自動的に省略されます）
cMunIni *	long	役務開始の自治体の IBGE コード（7 桁）
xMunIni	string	開始自治体名
UFIni *	string	開始の UF（2 文字）
cMunFim *	long	役務終了の自治体の IBGE コード（7 桁）
xMunFim	string	終了自治体名
UFFim *	string	終了の UF（2 文字）
cMunEnv	long	発行自治体の IBGE コード
xMunEnv	string	発行自治体名
UFEnv	string	発行の UF
retira	int	発地での引取: `0`=あり、`1`=なし。デフォルト: `1`
xDetRetira	string	引取の詳細
tpImp	int	DACTE の形式: `1`=縦向き、`2`=横向き。デフォルト: `1`
infPercurso	array	経路の UF: `[{ UFPer }]`
dhCont	string	コンティンジェンシー移行の日時（ISO 8601）
xJust	string	コンティンジェンシーの理由
serie	int	CT-e のシリーズ（アクセスキーの 3 桁）。任意 — 省略時または `0` の場合は自動割り当て（企業の CT-e シリーズ）、送信時はその値が使用されます
nCT	long	CT-e の番号（アクセスキーを構成）。任意 — 省略時または `0` の場合はサーバーが自動採番、送信時はその値が使用されます（番号をスキップしたい場合、例: 重複後などに便利です）

サーバーが自動的に設定 — 送信する必要はありません: mod（固定 57）、cCT（8 桁の数値コード）、cDV（チェックディジット）、cUF（発行者の UF から導出）、dhEmi（現在の日時）、tpEmis（デフォルト 1=通常）、procEmi および verProc。

toma4 — 荷主「その他」（`ide.toma=4` の場合）

項目	型	説明
CNPJ ⚠ / CPF ⚠	string	荷主の証票（いずれか一方）
IE	string	州登録番号
xNome	string	商号／氏名
xFant, fone, email	string	屋号、電話番号、メールアドレス
enderToma	object	住所: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, cPais, xPais }`

emit — 発行者（運送人）

項目	型	説明
CNPJ ⚠	string	発行者の CNPJ（14 桁）
CPF ⚠	string	発行者の CPF（11 桁）
IE	string	州登録番号
IEST	string	代替納税義務者の州登録番号
xNome *	string	商号
xFant	string	屋号
CRT	int	課税制度コード: `1`=シンプレス・ナシオナル、`2`=SN 上限超過、`3`=通常制度、`4`=MEI。デフォルト: `3`
enderEmit	object	住所: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone }`

rem — 差出人

項目	型	説明
CNPJ ⚠ / CPF ⚠	string	差出人の証票（いずれか一方）
IE	string	州登録番号（または `"ISENTO"`）
xNome	string	商号／氏名
xFant, fone, email	string	屋号、電話番号、メールアドレス
enderReme	object	差出人の住所（下記の構造）
locColeta	array	集荷場所（任意）: `[{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }]`

dest — 荷受人

項目	型	説明
CNPJ ⚠ / CPF ⚠	string	荷受人の証票（いずれか一方）
IE	string	州登録番号（または `"ISENTO"`）
xNome	string	商号／氏名
fone, email, ISUF	string	電話番号、メールアドレス、SUFRAMA 登録番号
enderDest	object	荷受人の住所（下記の構造）
locEnt	object	配送場所（任意）: `{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }`

exped / receb — 発送人 / 受領人（任意）

項目	型	説明
CNPJ / CPF	string	証票（いずれか一方）
IE, xNome, fone, email	string	州登録番号、氏名、電話番号、メールアドレス
enderExped / enderReceb	object	住所（下記の汎用構造と同じ）

住所（enderEmit / enderReme / enderExped / enderReceb / enderDest）

項目	型	説明
xLgr	string	街路名
nro	string	番地
xCpl	string	補足
xBairro	string	地区
cMun	string	自治体の IBGE コード（7 桁）
xMun	string	自治体名
CEP	string	CEP（郵便番号、8 桁）— `enderEmit` では使用されません
UF	string	UF の略号（2 文字）
cPais	string	国コード（任意、デフォルト 1058 ブラジル）
xPais	string	国名（任意）
fone	string	電話番号（`enderEmit` でのみ）

vPrest — 役務提供の金額

項目	型	説明
vTPrest *	decimal	役務提供の合計金額（> 0）
vRec	decimal	受取金額
Comp	array	金額の構成要素: `[{ xNome, vComp }]` — 例: `"FRETE PESO"`、`"PEDÁGIO"`、`"GRIS"`

imp — 税

項目	型	説明
ICMS *	object	ICMS の課税 — バリアントのいずれか 1 つだけを入力（下記参照）
vTotTrib	decimal	税の合計概算額
infAdFisco	string	税務当局向けの追加情報
ICMSUFFim	object	DIFAL（州間配分、任意）: `{ vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni }`
infTribFed	object	連邦税（任意）: `{ vPIS, vCOFINS, vIR, vINSS, vCSLL }`

ICMS — バリアント（1 つだけ入力）

バリアント	使用する場面	項目
ICMS00	通常課税	`{ vBC, pICMS, vICMS }`（CST 00）
ICMS20	課税標準の減額あり	`{ pRedBC, vBC, pICMS, vICMS }`（CST 20）
ICMS45	免除／非課税／繰延	`{ CST }` — `"40"`=免除、`"41"`=非課税、`"51"`=繰延
ICMS60	納税義務代替により徴収される ICMS	`{ vBCSTRet, vICMSSTRet, pICMSSTRet, vCred }`（CST 60）
ICMS90	その他（特別制度）	`{ pRedBC, vBC, pICMS, vICMS, vCred }`（CST 90）
ICMSOutraUF	他の UF に納付すべき ICMS	`{ pRedBCOutraUF, vBCOutraUF, pICMSOutraUF, vICMSOutraUF }`
ICMSSN	シンプレス・ナシオナルの発行者	`{ CST: "90", indSN: 1 }`

infCTeNorm — 通常 CT-e（`tpCTe=0`/`3` の場合に必須）

項目	型	説明
infCarga *	object	貨物の情報（下記のテーブル）
infDoc	object	輸送される書類（下記のテーブル）
infModal *	object	モーダルの情報（下記のテーブル）
docAnt	object	先行書類（下請／再発送）: `{ emiDocAnt[]{ CNPJ\|CPF, IE, UF, xNome, idDocAnt[] } }`
seg	array	貨物の保険: `[{ respSeg, xSeg, CNPJ, nApol, nAver, vCarga }]` — `respSeg`: 1=差出人…6=荷主
cobr	object	請求／インボイス: `{ fat{ nFat, vOrig, vDesc, vLiq }, dup[]{ nDup, dVenc, vDup } }`
veicNovos	array	輸送される新車: `[{ chassi, cCor, xCor, cMod, vUnit, vFrete }]`
infCteSub	object	代替 — `tpCTe=3` の場合に必須: `{ chCte, indAltToma, refNF, tomaICMS, tomaNaoICMS }`

infCTeNorm.infCarga — 貨物

項目	型	説明
proPred *	string	主要な品目
vCarga	decimal	貨物の合計金額
xOutCat	string	貨物のその他の特性（例: FRIA、GRANEL、REFRIGERADA）
vCargaAverb	decimal	査定目的の貨物の金額
infQ[] *	array	数量 — 最低 1 件: `[{ cUnid, tpMed, qCarga }]`
infQ[].cUnid	string	単位: `"00"`=M³、`"01"`=KG、`"02"`=TON、`"03"`=UNIDADE、`"04"`=LITROS、`"05"`=MMBTU
infQ[].tpMed	string	計量の種別（例: `"PESO BRUTO"`、`"PESO DECLARADO"`）
infQ[].qCarga	decimal	数量

infCTeNorm.infDoc — 輸送される書類

項目	型	説明
infNFe	array	アクセスキーによる NF-e: `[{ chave, PIN, dPrev, infUnidCarga[], infUnidTransp[] }]` — `chave` は 44 桁
infNF	array	紙の伝票（レガシー）: `[{ mod, serie, nDoc, dEmi, vBC, vICMS, vProd, vNF, nCFOP, nPeso, … }]`
infOutros	array	その他の書類: `[{ tpDoc, descOutros, nDoc, dEmi, vDocFisc }]` — `tpDoc`: `"00"`=申告、`"10"`=パイプライン、`"99"`=その他

infCTeNorm.infModal — モーダル（`ide.modal` に対応するものだけ入力）

モーダル	オブジェクト	項目
01 道路	rodo	`{ RNTRC* }` — RNTRC は 8 桁または `"ISENTO"`。任意: `occ[]`（集荷指示）
02 航空	aereo	`{ nMinu, nOCA, dPrevAereo, natCarga{ xDime, cInfManu[] }, tarifa{ CL, cTar, vTar }, peri[] }` — `dPrevAereo` AAAA-MM-DD
03 水運	aquav	`{ vPrest, vAFRMM, xNavio, nViag, direc, irin, tpNav, balsa[], detCont[] }` — `direc`: N/L/S/O；`tpNav`: 0=内陸、1=沿岸
04 鉄道	ferrov	`{ tpTraf, respFat, ferrEmi, vFrete, chCTeFerroOrigem, ferroEnv[] }` — `tpTraf`: 0=自社、1=相互、2=道路鉄道併用、3=道路
05 パイプライン	duto	`{ vTar, dIni, dFim }` — 日付 AAAA-MM-DD
06 複合輸送	multimodal	`{ COTM, indNegociavel, seg[] }` — `indNegociavel`: 0=いいえ、1=はい

infModal ブロック全体は versaoModal（デフォルト "4.00"）を受け付けます。

compl — 補完データ（任意）

項目	型	説明
xCaracAd, xCaracSer, xEmi	string	輸送の追加特性／役務の追加特性／発行者名
origCalc, destCalc	string	運賃計算用の発地／着地の自治体
xObs	string	一般的な備考
ObsCont / ObsFisco	array	納税者／税務当局の自由記述の備考: `[{ xCampo, xTexto }]`
fluxo, Entrega	object	貨物のフロー（発地／経由地／着地／ルート）と配送予定

* 必須項目。⚠ グループ内で CNPJ または CPF の少なくとも一方が必須です。

簡易例 — 道路モーダル、シンプレス・ナシオナル

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

成功レスポンス

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

拒否レスポンス

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

POST /api/cte/cancel

CT-e をキャンセル

承認済みの CT-e をキャンセルします（イベント 110111）。CT-e が承認済み（プロトコルを持つ）であり、まだキャンセルされていないことが必要です。

必須ヘッダー

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

Body

項目	型	説明
chCTe *	string	CT-e のアクセスキー（44 桁）
xJust *	string	キャンセルの理由（SEFAZ の要件により最低 15 文字）
nProt	string	承認プロトコル。任意: 省略時は発行時に記録されたプロトコルを使用します

* 必須項目。

ペイロード例

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

成功レスポンス

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

POST /api/cte/cce

訂正状（CC-e）

承認済みの CT-e に対して電子訂正状（イベント 110110）を登録します。CC-e では、税に影響する金額、発行者／荷主／差出人／荷受人を変更する登録データ、または発行日を訂正することはできません。各訂正はグループ、項目、新しい値を示します。

必須ヘッダー

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

Body

項目	型	説明
chCTe *	string	CT-e のアクセスキー（44 桁）
infCorrecao[] *	array	訂正（最低 1 件、最大 20 件）
infCorrecao[].grupoAlterado *	string	変更されたグループ（例: `"ide"`、`"rem"`、`"dest"`）
infCorrecao[].campoAlterado *	string	変更された項目（例: `"xNome"`）
infCorrecao[].valorAlterado *	string	新しい値
infCorrecao[].nroItemAlterado	int	変更された項目の番号（グループがリストの場合）

* 必須項目。使用条件（xCondUso）はサーバーが自動的に設定します。

ペイロード例

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

成功レスポンス

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

POST /api/cte/desacordo

役務提供の不承認

役務提供の不承認（イベント 610110）を登録します — 役務の荷主が、CT-e に記載された役務提供が契約内容と相違していることを表明するために使用します。イベントを登録する CNPJ（荷主）はトークンの企業のものです。CT-e の発行者である必要はありません。

必須ヘッダー

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

Body

項目	型	説明
chCTe *	string	CT-e のアクセスキー（44 桁）
xObs *	string	不承認の説明（最低 15 文字）

* 必須項目。不承認操作の指標は常に 1 です（PL-CTe v4.00）。

ペイロード例

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

成功レスポンス

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

POST /api/cte/consult

CT-e の状況を照会

アクセスキーから SEFAZ における CT-e の状況を照会します。CT-e がキャンセルされている場合（ローカル登録）、レスポンスはキャンセルを反映します。

必須ヘッダー

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

Body

項目	型	説明
chCTe *	string	CT-e のアクセスキー（44 桁）

* 必須項目。

ペイロード例

        {
          "chCTe": "35260626638419000167570010000000011123456780"
        }

レスポンス

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

POST /api/cte/inutilize

番号の範囲を無効化

使用されない CT-e の番号の範囲を無効化します（例えば、採番に欠番が生じた後）。無効化は確定的です。

必須ヘッダー

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

Body

項目	型	説明
tpAmb *	int	環境: `1`=本番、`2`=検証
CNPJ *	string	発行者の CNPJ（14 桁）
ano *	int	採番の年（2 桁、例: 2026 の場合 `26`）
serie *	int	採番のシリーズ
nCTIni *	long	範囲の開始番号
nCTFin *	long	範囲の終了番号（≥ `nCTIni`）
xJust *	string	理由（最低 15 文字）
mod	int	モデル。デフォルト: `57`

* 必須項目。

ペイロード例

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

成功レスポンス

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

GET /api/cte/get_list

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

会社の CT-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	ステータスでフィルタ。値: `"Success"`（承認済み）、`"Canceled"`（キャンセル済み）、`"Processing"`（処理中）、`"Failed"`（失敗）、`"Unknown"`（不明）

* 必須項目。

呼び出し例

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

レスポンス

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

vpn_key SSO — トークンによる自動ログイン

ベース 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": "contador@escritorio.com"
        }

成功レスポンス

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

レスポンスフィールド

フィールド	型	説明
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` がトークンユーザーに属していない
该会计师未绑定该发票账号	会計士が指定された企業に紐付けられていない

verified_user CPFとCNPJの検証

ブラジル国税庁 (Receita Federal) の公式データベースで CPF と CNPJ を検証する API です。CPF では、氏名、登録状況、年齢、および未成年者の自動ブロック (LGPD 準拠) を返します。CNPJ では、会社名、商号、住所、株主構成、および登録状況の詳細を返します。電子税務文書を発行する前の登録情報の確認、状況が不正規 (停止、抹消、登録抹消) の納税者の特定に推奨されます。

POST /api/invoice/validar_cpf_cnpj

CPF (生年月日付き) または CNPJ をブラジル国税庁の公式データベースで検証します

CPF または CNPJ を、フォーマット有無を問わず受け付けます。文書タイプは自動的に判別されます。CPF の場合、dataNascimento は必須です。

必須ヘッダー

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

Body

フィールド	型	説明
cpfCnpj *	string	CPF (11桁の数字) または CNPJ (14文字)。フォーマット可。
dataNascimento	string	生年月日 — CPF の場合のみ必須。受付形式: `dd/MM/yyyy`、`dd-MM-yyyy`、`ddMMyyyy`。

* 必須項目。

ペイロード例 — CPF

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

ペイロード例 — CNPJ

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

レスポンス — CPF 発見、正常な状況

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

レスポンス — 未成年者の CPF (LGPD)

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

レスポンス — CPF が見つかりません

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

レスポンス — 生年月日が CPF と一致しません

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

レスポンス — CNPJ 発見

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

レスポンス — CNPJ が見つかりません

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

CPF 状況コード

コード	説明
0	正常 (REGULAR)
2	停止
3	名義人死亡
4	正規化保留中
5	重複により取消
8	無効
9	職権により取消

CNPJ 状況コード

コード	説明
1	無効
2	有効
3	停止
4	不適格
8	登録抹消

エラーレスポンス

メッセージ	原因
cpfCnpj é obrigatório	`cpfCnpj` フィールドが欠落または空
CPF inválido, verifique a quantidade de dígitos	送信された CPF が11桁ではありません
CPF inválido	送信された CPF のチェックディジットが無効、または英字を含みます
CNPJ inválido, verifique a quantidade de dígitos	送信された CNPJ が14文字ではありません
CNPJ inválido	送信された CNPJ のチェックディジットが無効です
é necessário informar a data de nascimento	`dataNascimento` なしで CPF が送信された
dataNascimento inválida (use dd/MM/yyyy)	日付の形式がどの受付パターンにも一致しません

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

ペイロード例

例 — 会社で NFC-e と CT-e を有効化

レスポンス

必須ヘッダー

クエリ文字列

呼び出し例

レスポンス

必須ヘッダー

呼び出し例

レスポンス

必須ヘッダー

クエリ文字列

呼び出し例

レスポンス

必須ヘッダー

呼び出し例

レスポンス

レスポンス例

必須ヘッダー

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[]`（選択税）