---
name: "fapiao-vibe-coding"
description: "AI Agent 对接数电发票(电子发票)接口的 Vibe Coding 速成指南。提供极简对接流程、Mermaid 流程图、8种语言 SDK 索引、Code 200/420/430/401 异常处理模式。Invoke when AI agent needs to integrate electronic invoice (数电发票/电子发票) API for blue invoice (蓝票开具), red invoice (红冲), invoice query, or tax calculation."
---

# 🤖 AI Agent Vibe Coding 快速对接指南

> 面向 AI Agent 的极简对接流程。先跑通，再完善。

## 1. 对接前准备

访问 [https://open.fa-piao.com](https://open.fa-piao.com) 注册账号 → 添加企业 → 获取 **AppKey** 和 **AppSecret**。

```text
┌─────────────────────────────────────┐
│  open.fa-piao.com 用户中心           │
│  → 企业管理 → 添加企业（纳税人识别号）   │
│  → 获得: AppKey + AppSecret          │
└─────────────────────────────────────┘
```

![电子发票接口](https://fa-piao.com/image/fapiao.png)

## 2. 对接流程

```mermaid
flowchart TD
    Start([🚀 开始]) --> Step1{1️⃣ 获取授权}

    %% --- 第1步：获取授权 ---
    Step1 -- "缓存有效 (30天)" --> UseCache[使用缓存 Token]
    Step1 -- "无缓存/过期" --> CallAuth[调用 v5/enterprise/authorization]
    CallAuth --> SaveCache[缓存 Token]
    SaveCache --> UseCache

    %% --- 第2步：开具接口 ---
    UseCache --> Step2[2️⃣ 数电蓝票开具接口]
    Step2 --> Switch{3️⃣ Switch Code 判断}

    %% --- Case 200 ---
    Switch -- "Code: 200" --> GetFile[获取销项数电版式文件]
    GetFile --> SavePDF[保存 PDF 链接]
    SavePDF --> EndSuccess([✅ 结束: 成功])

    %% --- Case 420 ---
    Switch -- "Code: 420" --> SMS1[发送短信验证码]
    SMS1 --> SMS2[验证短信验证码]
    SMS2 --> CheckSMS{验证通过?}
    CheckSMS -- 是 --> Step2
    CheckSMS -- 否 --> EndSMS([❌ 结束: 短信验证失败])

    %% --- Case 430 ---
    Switch -- "Code: 430" --> Face1[获取人脸二维码]
    Face1 --> Face2[前端转图 & 引导App扫码]
    Face2 --> Face3[用户完成人脸认证]
    Face3 --> Face4[获取人脸认证状态]
    Face4 --> CheckFace{认证通过?}
    CheckFace -- 是 --> Step2
    CheckFace -- 否 --> EndFace([❌ 结束: 人脸认证失败])

    %% --- ⭐ 第4步：401 处理 (显式标注) ⭐ ---
    Switch -- "Code: 401" --> Step4_Node[获取授权 & 更新缓存]
    Step4_Node -->|手动重试 | Step2

    %% --- Default ---
    Switch -- "Default" --> ErrorLog[记录错误参数]
    ErrorLog --> TechSupport[根据错误提示修改或者反馈技术协助]
    TechSupport --> EndError([⚠️ 结束: 异常])

    %% --- 样式定义 ---
    style Start fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style Step1 fill:#bbdefb,stroke:#1565c0
    style Step2 fill:#bbdefb,stroke:#1565c0
    style Switch fill:#fff9c4,stroke:#fbc02d,stroke-width:2px
    style EndSuccess fill:#c8e6c9,stroke:#2e7d32
    style EndSMS fill:#ffcdd2,stroke:#c62828
    style EndFace fill:#ffcdd2,stroke:#c62828
    style EndError fill:#ffe0b2,stroke:#ef6c00
```

### 流程要点（Vibe Coding 速记版）

| 步骤 | 接口 | 关键点 |
|------|------|--------|
| **1. 获取授权** | `POST /v5/enterprise/authorization` | 传 `nsrsbh` + `username` + `password`，Token **缓存30天** |
| **2. 蓝票开具** | `POST /v5/enterprise/blueTicket` | 必填: `fplxdm`, `kplx`, `xhdwsbh`, `xhdwmc`, `fyxm[]`, `hjje`, `hjse`, `jshj` |
| **3. Code 判断** | — | 200=成功 / 420=短信 / 430=人脸 / 401=Token过期 |
| **4. 获取PDF** | `POST /v5/enterprise/pdfOfdXml` | `downflag=4` PDF/OFD/XML的下载URL,  |

### 金额计算铁律

```
jshj (价税合计) = Σ fyxm[].je
hjse (合计税额) = Σ fyxm[].se
hjje (合计金额) = jshj - hjse     ← 注意：不是 je 之和！
```

## 3. 安装 SDK 和参考 Demo

> 推荐直接使用 SDK，签名/Token缓存/异常处理都已封装。

### 3.1 Python

```bash
pip install tax-invoice
```

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [basic_example.py](https://github.com/fapiaoapi/invoice-sdk-python/blob/master/examples/basic_example.py) | [basic_example.py](https://gitee.com/fapiaoapi/invoice-sdk-python/blob/master/examples/basic_example.py) |
| 税额计算 (tax) | [tax_example.py](https://github.com/fapiaoapi/invoice-sdk-python/blob/master/examples/tax_example.py) | [tax_example.py](https://gitee.com/fapiaoapi/invoice-sdk-python/blob/master/examples/tax_example.py) |
| 红冲 (red) | [red_invoice_example.py](https://github.com/fapiaoapi/invoice-sdk-python/blob/master/examples/red_invoice_example.py) | [red_invoice_example.py](https://gitee.com/fapiaoapi/invoice-sdk-python/blob/master/examples/red_invoice_example.py) |

### 3.2 Node.js / TypeScript

```bash
npm install tax-invoice
```

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [basic_example.ts](https://github.com/fapiaoapi/invoice-sdk-nodejs/blob/master/examples/basic_example.ts) | [basic_example.ts](https://gitee.com/fapiaoapi/invoice-sdk-nodejs/blob/master/examples/basic_example.ts) |
| 税额计算 (tax) | [tax_example.ts](https://github.com/fapiaoapi/invoice-sdk-nodejs/blob/master/examples/tax_example.ts) | [tax_example.ts](https://gitee.com/fapiaoapi/invoice-sdk-nodejs/blob/master/examples/tax_example.ts) |
| 红冲 (red) | [red_invoice_example.ts](https://github.com/fapiaoapi/invoice-sdk-nodejs/blob/master/examples/red_invoice_example.ts) | [red_invoice_example.ts](https://gitee.com/fapiaoapi/invoice-sdk-nodejs/blob/master/examples/red_invoice_example.ts) |

### 3.3 Java 17+（推荐）

```xml
<!-- Maven -->
<dependency>
    <groupId>io.github.fapiaoapi</groupId>
    <artifactId>invoice</artifactId>
    <version>1.0.26</version>
</dependency>
```

```gradle
// Gradle
implementation 'io.github.fapiaoapi:invoice:1.0.26'
```

中央仓库: https://central.sonatype.com/artifact/io.github.fapiaoapi/invoice

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [BasicExample.java](https://github.com/fapiaoapi/invoice-sdk-java/blob/master/src/main/java/tax/invoice/example/BasicExample.java) | [BasicExample.java](https://gitee.com/fapiaoapi/invoice-sdk-java/blob/master/src/main/java/tax/invoice/example/BasicExample.java) |
| 税额计算 (tax) | [TaxExample.java](https://github.com/fapiaoapi/invoice-sdk-java/blob/master/src/main/java/tax/invoice/example/TaxExample.java) | [TaxExample.java](https://gitee.com/fapiaoapi/invoice-sdk-java/blob/master/src/main/java/tax/invoice/example/TaxExample.java) |
| 红冲 (red) | [RedInvoiceExample.java](https://github.com/fapiaoapi/invoice-sdk-java/blob/master/src/main/java/tax/invoice/example/RedInvoiceExample.java) | [RedInvoiceExample.java](https://gitee.com/fapiaoapi/invoice-sdk-java/blob/master/src/main/java/tax/invoice/example/RedInvoiceExample.java) |

### 3.4 Java 8-16（单文件版）

无需 Maven/Gradle，直接下载 Java 文件即可使用。

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [BasicExample.java](https://github.com/fapiaoapi/invoice/blob/master/BasicExample.java) | [BasicExample.java](https://gitee.com/fapiaoapi/invoice/blob/master/BasicExample.java) |
| 税额计算 (tax) | [TaxExample.java](https://github.com/fapiaoapi/invoice/blob/master/TaxExample.java) | [TaxExample.java](https://gitee.com/fapiaoapi/invoice/blob/master/TaxExample.java) |
| 红冲 (red) | [RedInvoiceExample.java](https://github.com/fapiaoapi/invoice/blob/master/RedInvoiceExample.java) | [RedInvoiceExample.java](https://gitee.com/fapiaoapi/invoice/blob/master/RedInvoiceExample.java) |

### 3.5 Go

```bash
go get github.com/fapiaoapi/invoice-sdk-golang
```

文档: https://pkg.go.dev/github.com/fapiaoapi/invoice-sdk-golang

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [basic_example.go](https://github.com/fapiaoapi/invoice-sdk-golang/blob/master/examples/basic_example.go) | [basic_example.go](https://gitee.com/fapiaoapi/invoice-sdk-golang/blob/master/examples/basic_example.go) |
| 税额计算 (tax) | [tax_example.go](https://github.com/fapiaoapi/invoice-sdk-golang/blob/master/examples/tax_example.go) | [tax_example.go](https://gitee.com/fapiaoapi/invoice-sdk-golang/blob/master/examples/tax_example.go) |
| 红冲 (red) | [red_invoice_example.go](https://github.com/fapiaoapi/invoice-sdk-golang/blob/master/examples/red_invoice_example.go) | [red_invoice_example.go](https://gitee.com/fapiaoapi/invoice-sdk-golang/blob/master/examples/red_invoice_example.go) |

### 3.6 PHP

```bash
composer require tax/invoice
```

Packagist: https://packagist.org/packages/tax/invoice

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [basic_example.php](https://github.com/fapiaoapi/invoice-sdk-php/blob/master/examples/basic_example.php) | [basic_example.php](https://gitee.com/fapiaoapi/invoice-sdk-php/blob/master/examples/basic_example.php) |
| 税额计算 (tax) | [tax_example.php](https://github.com/fapiaoapi/invoice-sdk-php/blob/master/examples/tax_example.php) | [tax_example.php](https://gitee.com/fapiaoapi/invoice-sdk-php/blob/master/examples/tax_example.php) |
| 红冲 (red) | [red_invoice_example.php](https://github.com/fapiaoapi/invoice-sdk-php/blob/master/examples/red_invoice_example.php) | [red_invoice_example.php](https://gitee.com/fapiaoapi/invoice-sdk-php/blob/master/examples/red_invoice_example.php) |

### 3.7 RUST

```bash
cargo add tax-invoice
```

Cargo: https://crates.io/crates/tax-invoice

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [basic_example.rs](https://github.com/fapiaoapi/invoice-sdk-rust/blob/master/examples/basic_example.rs) | [basic_example.rs](https://gitee.com/fapiaoapi/invoice-sdk-rust/blob/master/examples/basic_example.rs) |
| 税额计算 (tax) | [tax_example.rs](https://github.com/fapiaoapi/invoice-sdk-rust/blob/master/examples/tax_example.rs) | [tax_example.rs](https://gitee.com/fapiaoapi/invoice-sdk-rust/blob/master/examples/tax_example.rs) |
| 红冲 (red) | [red_invoice_example.rs](https://github.com/fapiaoapi/invoice-sdk-rust/blob/master/examples/red_invoice_example.rs) | [red_invoice_example.rs](https://gitee.com/fapiaoapi/invoice-sdk-rust/blob/master/examples/red_invoice_example.rs) |

### 3.7 C# 12

```bash
dotnet add package Tax.Invoice --version 1.0.9
```

NuGet: https://www.nuget.org/packages/Tax.Invoice

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [BasicExample.cs](https://github.com/fapiaoapi/invoice-sdk-csharp/blob/master/Example/BasicExample.cs) | [BasicExample.cs](https://gitee.com/fapiaoapi/invoice-sdk-csharp/blob/master/Example/BasicExample.cs) |
| 税额计算 (tax) | [TaxExample.cs](https://github.com/fapiaoapi/invoice-sdk-csharp/blob/master/Example/TaxExample.cs) | [TaxExample.cs](https://gitee.com/fapiaoapi/invoice-sdk-csharp/blob/master/Example/TaxExample.cs) |
| 红冲 (red) | [RedInvoiceExample.cs](https://github.com/fapiaoapi/invoice-sdk-csharp/blob/master/Example/RedInvoiceExample.cs) | [RedInvoiceExample.cs](https://gitee.com/fapiaoapi/invoice-sdk-csharp/blob/master/Example/RedInvoiceExample.cs) |

### 3.8 C# 8-11（单文件版）

无需 NuGet，直接下载 .cs 文件即可使用。

| Demo | GitHub | Gitee |
|------|--------|-------|
| 开票 (basic) | [BasicExample.cs](https://github.com/fapiaoapi/invoice/blob/master/BasicExample.cs) | [BasicExample.cs](https://gitee.com/fapiaoapi/invoice/blob/master/BasicExample.cs) |
| 税额计算 (tax) | [TaxExample.cs](https://github.com/fapiaoapi/invoice/blob/master/TaxExample.cs) | [TaxExample.cs](https://gitee.com/fapiaoapi/invoice/blob/master/TaxExample.cs) |
| 红冲 (red) | [RedInvoiceExample.cs](https://github.com/fapiaoapi/invoice/blob/master/RedInvoiceExample.cs) | [RedInvoiceExample.cs](https://gitee.com/fapiaoapi/invoice/blob/master/RedInvoiceExample.cs) |

## 4. AI Agent 调用建议

1. **优先使用 SDK**：签名、Token 缓存、Code 200/420/430/401 全部自动处理
2. **Token 必须缓存**：30 天有效，缓存到 Redis（key: `{nsrsbh}@{username}:TOKEN`）
3. **金额严格校验**：`jshj = Σ je`、`hjje = jshj - hjse`，否则会开票失败
4. **流水号防重**：`fpqqlsh` 用订单号，保证唯一
5. **异常重试**：
   - 420 → 提示用户输入短信码后重试
   - 430 → 展示二维码给用户扫码后重试
   - 401 → 自动重新授权后重试
6. **查看完整参数**：参考 [SKILL-old.md](./SKILL-old.md) 中的"完整接口索引"和"公共请求规范"章节

## 5. MCP Server 集成（推荐 AI Agent 使用）

如果你的 AI Agent 支持 MCP 协议，可直接使用现成的 MCP Server：

```json
{
  "mcpServers": {
    "tax-invoice": {
      "command": "npx",
      "args": ["-y", "@fapiaoapi/tax-invoice-mcp"],
      "env": {
        "APP_KEY": "your_app_key",
        "APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

仓库: [GitHub](https://github.com/fapiaoapi/tax-invoice-mcp) | [tax-invoice-mcp](https://gitee.com/fapiaoapi/tax-invoice-mcp)