API 開發文件

🔐 認證方式

所有 API 請求都需要在 HTTP Header 中加入 API Key：

您可以在管理後台取得您的 API Key。每個客戶帳號都有獨立的 API Key。

速率限制

為確保服務品質，API 有以下限制：

• 每分鐘最多 60 次請求
• 連續 5 次驗證失敗將被暫時封鎖 30 分鐘

📡 API 端點

Base URL: https://invoice.aaservice.cc/api/invoice.php

1. 開立 B2C 發票 (二聯式)

請求參數：

參數	類型	必填	說明
buyer_name	string	是	買受人名稱
buyer_email	string	否	買受人 Email
items	array	是	商品明細陣列
carrier_type	string	否	載具類型 (3J0002=手機條碼, CQ0001=自然人憑證)
carrier_id	string	否	載具號碼
donate	boolean	否	是否捐贈
donate_code	string	否	捐贈碼

{
  "buyer_name": "王小明",
  "buyer_email": "wang@example.com",
  "items": [
    {
      "description": "商品名稱",
      "quantity": 1,
      "unit_price": 1000,
      "unit": "個"
    }
  ],
  "carrier_type": "3J0002",
  "carrier_id": "/ABC1234"
}

2. 開立 B2B 發票 (三聯式)

額外必填參數：

參數	類型	必填	說明
buyer_tax_id	string	是	買受人統一編號 (8碼)
buyer_name	string	是	買受人公司名稱
buyer_address	string	否	買受人地址

3. 作廢發票

{
  "invoice_number": "AA00000001",
  "reason": "客戶退貨"
}

4. 查詢發票

查詢參數：

參數	類型	必填	說明
start_date	string	否	起始日期 (YYYY-MM-DD)
end_date	string	否	結束日期 (YYYY-MM-DD)
status	string	否	發票狀態 (issued/voided/uploaded)

5. 取得單一發票

6. 上傳至財政部

將待上傳的發票資料上傳至財政部 Turnkey 系統。

📋 回應格式

所有 API 回應都是 JSON 格式：

成功回應

{
  "success": true,
  "message": "發票開立成功",
  "data": {
    "invoice_number": "AA00000001",
    "invoice_date": "2025-01-15",
    "total_amount": 1050,
    "tax_amount": 50
  }
}

錯誤回應

{
  "success": false,
  "error": "缺少必要欄位"
}

💻 PHP 範例程式碼

<?php
// 設定 API Key
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://invoice.aaservice.cc/api/invoice.php';

// 準備發票資料
$data = [
    'buyer_name' => '王小明',
    'buyer_email' => 'wang@example.com',
    'items' => [
        [
            'description' => '高級行李箱',
            'quantity' => 1,
            'unit_price' => 5000
        ]
    ],
    'carrier_type' => '3J0002',
    'carrier_id' => '/ABC1234'
];

// 呼叫 API
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $baseUrl . '?action=issue_b2c',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['success']) {
    echo "發票開立成功！\n";
    echo "發票號碼: " . $result['data']['invoice_number'] . "\n";
} else {
    echo "錯誤: " . $result['error'] . "\n";
}
?>

⚠️ HTTP 狀態碼

狀態碼	說明
200	成功
201	建立成功
400	請求格式錯誤或缺少必要參數
401	身分驗證失敗 (API Key 無效)
403	權限不足或 IP 被封鎖
404	資源不存在
429	請求過於頻繁
500	伺服器錯誤

📊 系統狀態

資料庫連線	連線失敗
PHP 版本	8.1.33
系統時間	2026-01-16 13:20:30