FIZ 請求書発行は何をしますか？

FIZ Public API（https://api.fiz.co）を使用して請求書を発行します。このスキルは、顧客の検索・作成、品目の検索・作成、下書き請求書の作成、発行（法的拘束力のあるステップ）、PDFダウンロードの全ライフサイクルを案内します。

セットアップ

すべてのリクエストには、x-api-keyヘッダーにクライアントのAPIキーが必要です。キーは以下で取得できます： https://app.fiz.co/settings/integrations

環境変数に保存し、コマンドにハードコードされないようにします：

export FIZ_API_KEY="fiz_api_..."     # app.fiz.coからのユーザーキー
export FIZ_API_URL="https://api.fiz.co"   # オプション；デフォルト値

以下の例はすべて$FIZ_API_KEYと$FIZ_API_URLを使用します。FIZ_API_URLが未設定の場合はhttps://api.fiz.coを使用します。FIZ_API_KEYが未設定の場合は、ユーザーに環境変数への設定を促して停止します（シェルでexport FIZ_API_KEY=…、またはシークレットマネージャーを使用）— チャットにキーを貼り付けるように求めないでください。APIキーは資格情報です。会話の記録に残さないでください。

再利用可能なcurlヘルパーはscripts/fiz.shにあります。コマンドはセッションの作業ディレクトリ（プロジェクトルート）から実行されるため、スキルディレクトリからではありません。絶対パス${CLAUDE_SKILL_DIR}を使用してヘルパーを読み込みます（Claude Codeはこれをスキル自身のディレクトリに設定します）：

source "${CLAUDE_SKILL_DIR}/scripts/fiz.sh"   # 任意の作業ディレクトリから解決
fiz GET /invoices

CLAUDE_SKILL_DIRを提供しないランタイムでは、そのランタイム相当のスキルディレクトリパスに置き換えます（単なる相対パスscripts/fiz.shはプロジェクトルートから解決されません）。

ヘルパーはHTTPステータスを出力し、4xx/5xxでは非ゼロを返すため、エラーレスポンスが成功と誤解されることはありません — 以下の「エラーハンドリング」を参照してください。プレーンなcurlの例もインラインで示します。生のcurlを使用する場合は、コマンドの終了コードだけでなく、常にHTTPステータスを確認してください。

基本概念

請求書は顧客（IDで参照）と1つ以上の品目（IDで参照）を参照します。そのため、顧客と品目は請求書を作成する前に存在している必要があります。
POST /invoicesは下書きを作成します。下書きはまだ法的文書ではありません — 税務当局に送信されず、自由に編集・削除できます。
POST /invoices/:id/issueで発行します — 正式な番号とATCUDが割り当てられ、ポルトガル税務当局（AT）と同期され、最終確定します。 発行は取消不能です。発行前にユーザーに確認してください。 発行された請求書は削除できません — 取り消す唯一の方法はクレジットノートです。
「作成してから発行」の唯一の例外は、作成時にpaymentオブジェクトをINVOICE_RECEIPTまたはSIMPLIFIED_INVOICEタイプに渡す場合です。この場合、支払いが記録されます — ただし、最終確定には発行が必要です。

書き込み前の確認

これらのエンドポイントはユーザーのアカウントの状態を変更します。注意すべき2つのレベル：

計画、そして最初の書き込みの前にすべての書き込みをプレビューします。 リクエストに必要な内容がわかったら、このタスクで行う予定のすべての書き込みをリストアップします — 各エンドポイントとそのJSONペイロード（作成する顧客、各品目、下書き請求書）を、1つのプレビューでユーザーに表示します。計画が承認されたら、書き込みを進めます。実行中に計画が変更された場合（例：品目の検索に失敗し、新規作成が必要になった場合）、新しい書き込みを送信する前にプレビューします。顧客データ、税務項目、金額を勝手に作成しないでください — ユーザーから提供されたものだけを使用します。
POST /invoices/:id/issueの前 — これは取消不能で、税務当局に報告されます。常に明示的かつ個別の確認（上記の計画承認とは別に）を取得し、下書きの顧客、明細行、VAT、合計を表示します。自分の判断で発行しないでください。

呼び出しポリシー（意図的）： このスキルはモデルの自動呼び出しを有効にしています — descriptionは発見の表面であり、実際の安全策は上記の「全書き込みプレビュー+個別発行確認」であり、発見を制限するものではありません。Codexマニフェスト（agents/openai.yaml）は一致するように設定されています（allow_implicit_invocation: true）。手動のみの使用を希望するオペレーターは、フロントマターでdisable-model-invocation: trueを設定できます（/fiz-invoicingでのみ読み込まれます）。

これはポルトガルの税務請求書です — 正確さが重要な理由

FIZは法的拘束力のある税務書類を発行し、ポルトガル税務当局（Autoridade Tributária、"AT"）に報告されます。誤ったVAT税率や免税理由の欠落は単なる見た目の問題ではありません — 誤った税務書類を作成し、発行後はクレジットノートでのみ修正できます。発行前に税務項目を正しく設定してください。

最も間違いやすい2つのことと、その対処方法：

1. VAT税率（各品目のvatRate）— 決して推測しないでください。 税率帯（NORMAL | INTERMEDIATE | REDUCED | EXEMPT）とそれに対応するパーセンテージは、地域（本土 / アゾレス / マデイラ）に依存します。デフォルトはNORMAL — REDUCED/INTERMEDIATEは法的に定義された特定のカテゴリ（特定の食品、レストラン、文化イベントなど）にのみ適用されます。ユーザーがそのようなカテゴリを指定していない場合は、NORMALを使用してその旨を伝えるか、質問してください。勝手に軽減税率を適用しないでください。地域別のパーセンテージ表はdomain.mdにあります。

2. VAT免税には理由コード（vatExemptionReason）が必要です。 vatRateがEXEMPTの場合、ポルトガル法ではmotivo de isenção（免税理由）— 法的根拠を示すMコード — が必要です。常に設定してください。有効な理由のない免税項目は無効な文書となり、発行時に拒否される可能性があります。コードは実際の理由を反映している必要があります：小規模事業者制度 → M10、性質上免税の活動（医療/教育）→ M07、EU B2B / リバースチャージ → M40/M16/M19。ユーザーが免税であるがコードを知らない場合は、理由を尋ねてマッピングしてください — 任意に選択しないでください。完全なコードリストと法的参照はdomain.mdにあります。

その他の知っておくべきドメインルール（詳細はdomain.md）：

CAEは5桁のポルトガル経済活動コードで、事業者が登録しているものでなければなりません。勝手に作成しないでください — ユーザーに尋ねるか、以前の請求書からCAEを再利用します。現在の（Rev. 4）コードである必要があります。
NIF（taxpayerNumber）は9桁のポルトガル税番号でチェックサムがあります。B2Bでは必須、最終消費者ではオプションです。EU B2Bの場合、リバースチャージ処理のため顧客のVAT番号が重要です。
源泉徴収税（retenção na fonte: IRS/IRC/IS）は品目に設定され、個人事業主のサービスでは一般的に25%です。支払者が源泉徴収し、実際の支払額を減らします。
文書タイプはルールに影響します：SIMPLIFIED_INVOICEは小売販売向けで、顧客情報を省略できます。事業者向けで€1,000を超えるINVOICEには顧客のNIFが必要です。

ワークフロー

以下の手順に従ってください。ユーザーがすでに顧客IDと品目IDを提供している場合は、手順1～2をスキップします。

手順1 — 顧客を特定する

重複を避けるためにまず検索し、必要に応じて作成します。

例ではfizヘルパー（セットアップを参照）を使用します — これによりHTTPステータスが自動的にチェックされます。同等の生のcurlは付録にあります。

検索語（名前、税番号、メール）で検索：

fiz GET "/customers?search=Joao"

顧客を作成（必須はnameのみ）：

fiz POST /customers '{
  "name": "João Silva",
  "email": "[email protected]",
  "taxpayerNumber": "303741791",
  "country": "PT"
}'

返されたidを保持します — これが請求書のcustomerIdです。

手順2 — 品目（製品/サービス）を特定する

既存の品目を検索：

fiz GET "/items?search=consulting"

税務項目が販売内容と一致する場合にのみ、既存の品目を再利用します。 名前が一致する検索結果だけでは十分ではありません — 税務書類の場合、品目のvatRate、vatTerritory、vatExemptionReason、taxRate、源泉徴収フィールドが、この顧客と販売に対して意図する処理と一致している必要があります。これらのいずれかが異なる場合（例：同じサービスだが顧客が免税対象、別の地域、または源泉徴収の対象）、一致しないものを再利用するのではなく、正しいフィールドで新しい品目を作成します。不明な場合は、見つかった品目のフィールドを確認し、ユーザーに確認してください。

品目を作成します。必須：name、type（PRODUCT | SERVICE）、unitPrice、vatRate（NORMAL | INTERMEDIATE | REDUCED | EXEMPT）：

fiz POST /items '{
  "name": "Consulting hour",
  "type": "SERVICE",
  "unitPrice": 80,
  "vatRate": "NORMAL"
}'

返された各idを保持します — これらが請求書の品目IDです。

unitPriceは単価です。明細ごとの合計は、請求書で指定するquantityからFIZが計算します。vatRateは意図的に選択してください — 上記のドメインセクションを参照。カテゴリが明らかに軽減税率を正当化する場合を除き、デフォルトはNORMALです。vatRateがEXEMPTの場合は、販売が免税となる理由に一致するvatExemptionReason Mコードを常に設定します（例：小規模事業者制度の場合はM10）。このフィールドは品目作成時に技術的にはオプションですが、有効な理由のない免税項目は不正であり、後で請求書を発行する際に拒否される可能性があります。完全なコードリストはdomain.mdを参照してください。

手順3 — 下書き請求書を作成する

必須フィールド：dueDate（ISO 8601）、cae（ポルトガル経済活動コード）、type、customerId、items（少なくとも1つの{ id, quantity }）。

fiz POST /invoices '{
  "dueDate": "2026-07-18T00:00:00.000Z",
  "cae": "62010",
  "type": "INVOICE",
  "customerId": "6863b1513117c5892ff55296",
  "items": [
    { "id": "68483e978073231c3947077c", "quantity": 10 }
  ]
}'

レスポンスには新しい請求書のid（発行に必要）とstatus（DRAFT）が含まれます。請求書のdateは現在時刻に設定され、currencyはAPIによってEURに設定されます — これらを送信する必要はありません。

オプション — 全体割引（summary）：

"summary": { "globalDiscountType": "PERCENT", "globalDiscountPercent": 10 }

固定額割引の場合は、代わりに"AMOUNT"とglobalDiscountAmountを使用します。

オプション — 作成時の支払い（payment）：typeがINVOICE_RECEIPTまたはSIMPLIFIED_INVOICEの場合のみ許可されます。それ以外の場合はAPIが400を返します。

"payment": { "method": "mbWay", "date": "2026-07-18T00:00:00.000Z" }

methodは次のいずれか：cash、card、bankTransfer、mbWay、multibanco、spin、other。

手順4 — 請求書を発行する

これが拘束力のあるステップです。ユーザーに確認してから、以下を実行します：

fiz POST /invoices/{id}/issue

レスポンスには正式なnumber、status: ISSUED、syncWithAtブロックが含まれます。syncWithAt.statusを確認してください — これがFAILEDの場合、請求書はローカルに作成されましたが税務当局と同期していません。成功と主張する代わりに、atMessageとisRetriableがtrueかどうかをユーザーに報告します。

手順5 — PDFをダウンロードする（オプション）

fiz GET /invoices/{id}/pdf

{ id, name, url }を返します。urlはPDFへのダウンロード可能なリンクです。レイアウトを選択するには?format=A4または?format=RECEIPTを追加します。

文書タイプ（`type`）

値：INVOICE · INVOICE_RECEIPT · SIMPLIFIED_INVOICE · RECEIPT · CREDIT_NOTE · DEBIT_NOTE。ユーザーがレシートまたは簡易請求書を要求しない限り、デフォルトはINVOICE。作成時にpaymentオブジェクトを受け入れるのはINVOICE_RECEIPTとSIMPLIFIED_INVOICEのみです。各タイプの意味と使用タイミングについてはdomain.mdを参照してください。

共通操作リファレンス

アクション	メソッドとパス
顧客の一覧/検索	`GET /customers?search=…`
顧客の作成	`POST /customers`
品目の一覧/検索	`GET /items?search=…`
品目の作成	`POST /items`
下書きの作成	`POST /invoices`
発行	`POST /invoices/:id/issue`
請求書の一覧	`GET /invoices`
1件の請求書を取得	`GET /invoices/:id`
PDFのダウンロード	`GET /invoices/:id/pdf`
削除（下書き）	`DELETE /invoices/:id`

エラーハンドリング

コマンドが実行されたかどうかだけでなく、常にHTTPステータスを確認してください。 エラー時、APIは正常に見えるJSONボディ — { "statusCode": 400, "message": "...", "timestamp": "..." } — を対応するHTTPステータスとともに返します。生のcurl -sではそのボディが出力され、curlは依然として終了コード0で終了するため、エラーを結果と誤認しやすいです。fizヘルパーはこれを防ぎます。HTTP <code>行を出力し、4xx/5xxでは非ゼロを返します。生のcurlを使用する必要がある場合は、-w '\n%{http_code}'（または-o body -w '%{http_code}'）を追加してコードを検査します。

一般的なステータス：

401 — APIキーがないか無効です。ユーザーに環境変数FIZ_API_KEYを設定するよう伝えてください（チャット内では設定しないでください）。
400 — 検証エラー。messageに問題のあるフィールドが示されます。一般的なケース：空のitems、サポートされていないtypeでのpayment、不明/余分なフィールド（厳格なホワイトリスト）、不正な形式のdueDate（完全なISO 8601とタイムゾーンが必要。例：2026-07-18T00:00:00.000Z）。
5xx — バックエンド/ATの問題。内容を表示し、同じ書き込みを盲目的にリトライしないでください（作成が部分的に成功している可能性があります — 最初にGETで確認してください）。

盲目的にリトライする代わりに、常にAPIのmessageをユーザーにそのまま返します。

完全で権威あるリクエスト/レスポンス契約は、ライブSwagger UI（**https://api.fiz.co/**）にあります。ここにあるフィールドが古いと思われる場合はそちらを参照してください。

詳細が必要な場合

このスキルディレクトリ内の2つの補助ファイル：

domain.md — ポルトガルの税務ドメイン：地域別VAT税率、免税（M）コードの完全リストとそれぞれの適用条件、文書タイプ、CAE/NIFルール、源泉徴収税、AT同期/発行の取消不能性の仕組み。税務上の判断が明白でない場合（特にvatRateや免税理由の選択）は、必ずこれを読んでください。
reference.md — 完全なフィールド別APIリファレンス（すべての顧客/品目/請求書フィールド、すべてのenum値、完全なリクエスト/レスポンス形式）。

付録 — 生のcurl（ヘルパーなし）

上記のfizヘルパーを優先してください。HTTPステータスをチェックします。使用できない場合は、-w '\n%{http_code}'を付けて生のcurlを使用します。

# GET /customers
resp=$(curl -s -w "\n%{http_code}" \
  -H "x-api-key: $FIZ_API_KEY" \
  "$FIZ_API_URL/customers?search=Joao")
http_code=$(tail -n1 "$resp")
body=$(sed \$d "$resp")
if [ "$http_code" -ge 400 ]; then
  echo "エラー $http_code: $body"
fi

ヘルパーなしで生のcurlのみを使用する場合、スキルはヘルパーを使用する場合と同じことを行いますが、-wフラグを使用してHTTPステータスコードを手動で抽出します。

FIZ 請求書発行