台灣電子發票 API 串接 Shopify Plus 教學：完整實作指南

1mutation {
2  webhookSubscriptionCreate(
3    topic: ORDERS_PAID
4    webhookSubscription: {
5      callbackUrl: "https://invoice.example.com/hooks/orders-paid"
6      format: JSON
7    }
8  ) {
9    webhookSubscription { id }
10    userErrors { field message }
11  }
12}

1import crypto from 'node:crypto';
2import express from 'express';
3
4const app = express();
5app.use('/hooks', express.raw({ type: 'application/json' }));
6
7function verifyShopifyHmac(req) {
8  const hmac = req.get('X-Shopify-Hmac-Sha256') || '';
9  const digest = crypto
10    .createHmac('sha256', process.env.SHOPIFY_WEBHOOK_SECRET)
11    .update(req.body) // 必須是 raw buffer，不能是 parsed object
12    .digest('base64');
13  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(digest));
14}
15
16app.post('/hooks/orders-paid', async (req, res) => {
17  if (!verifyShopifyHmac(req)) return res.status(401).send('bad hmac');
18  res.status(200).send('ok');           // 先回 200，避免 Shopify 判定逾時
19  await enqueue('issue-invoice', JSON.parse(req.body.toString()));
20});

1async function enqueue(job, payload) {
2  const key = `inv:${payload.id}`;
3  const first = await kv.set(key, 'pending', { nx: true, ex: 86400 });
4  if (!first) return;  // 已處理過，直接略過
5  await queue.send({ job, payload });
6}

1function toInvoicePayload(order) {
2  const attrs = Object.fromEntries(
3    (order.note_attributes || []).map(a => [a.name, a.value])
4  );
5
6  const items = order.line_items.map(li => ({
7    ItemName: li.title.slice(0, 100),
8    ItemCount: li.quantity,
9    ItemWord: '件',
10    ItemPrice: Number(li.price),          // 含稅單價
11    ItemTaxType: '1',                      // 1=應稅 2=零稅率 3=免稅
12    ItemAmount: Number(li.price) * li.quantity
13  }));
14
15  // 運費也要開立，否則發票總額對不上
16  const shipping = Number(order.total_shipping_price_set.shop_money.amount);
17  if (shipping > 0) {
18    items.push({ ItemName: '運費', ItemCount: 1, ItemWord: '式',
19      ItemPrice: shipping, ItemTaxType: '1', ItemAmount: shipping });
20  }
21
22  const salesAmount = items.reduce((s, i) => s + i.ItemAmount, 0);
23
24  return {
25    MerchantID: process.env.ECPAY_MERCHANT_ID,
26    RelateNumber: order.name.replace('#', ''), // 自訂關聯編號，需唯一
27    CustomerName: attrs['invoice_title'] || `${order.customer?.last_name ?? ''}${order.customer?.first_name ?? ''}`,
28    CustomerEmail: order.email,
29    CustomerIdentifier: attrs['tax_id'] || '',  // 統編，有填則為 B2B
30    Print: attrs['tax_id'] ? '1' : '0',
31    Donation: attrs['love_code'] ? '1' : '0',
32    LoveCode: attrs['love_code'] || '',
33    CarrierType: attrs['carrier_type'] || '',
34    CarrierNum: attrs['carrier_num'] || '',
35    TaxType: '1',
36    SalesAmount: Math.round(salesAmount),
37    Items: items,
38    InvType: '07'
39  };
40}

1import crypto from 'node:crypto';
2
3const KEY = process.env.ECPAY_HASH_KEY;  // 16 bytes
4const IV  = process.env.ECPAY_HASH_IV;   // 16 bytes
5
6function encrypt(obj) {
7  const plain = encodeURIComponent(JSON.stringify(obj));
8  const cipher = crypto.createCipheriv('aes-128-cbc', KEY, IV);
9  return Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()])
10    .toString('base64');
11}
12
13function decrypt(b64) {
14  const d = crypto.createDecipheriv('aes-128-cbc', KEY, IV);
15  const plain = Buffer.concat([d.update(Buffer.from(b64, 'base64')), d.final()]);
16  return JSON.parse(decodeURIComponent(plain.toString('utf8')));
17}
18
19async function issueInvoice(payload) {
20  const base = process.env.ECPAY_BASE;  // stage 或 production
21  const body = {
22    MerchantID: process.env.ECPAY_MERCHANT_ID,
23    RqHeader: { Timestamp: Math.floor(Date.now() / 1000) },
24    Data: encrypt(payload)
25  };
26
27  const res = await fetch(`${base}/B2CInvoice/Issue`, {
28    method: 'POST',
29    headers: { 'Content-Type': 'application/json' },
30    body: JSON.stringify(body)
31  });
32
33  const json = await res.json();
34  const data = decrypt(json.Data);
35  if (data.RtnCode !== 1) {
36    throw new InvoiceError(data.RtnCode, data.RtnMsg, payload.RelateNumber);
37  }
38  return { invoiceNo: data.InvoiceNo, invoiceDate: data.InvoiceDate,
39           randomNumber: data.RandomNumber };
40}

1{
2  "RtnCode": 1,
3  "RtnMsg": "開立發票成功",
4  "InvoiceNo": "AB12345678",
5  "InvoiceDate": "2026-01-15 14:02:11",
6  "RandomNumber": "4716"
7}

1mutation SetInvoice($id: ID!, $no: String!, $date: String!) {
2  metafieldsSet(metafields: [
3    { ownerId: $id, namespace: "tw_invoice", key: "number",
4      type: "single_line_text_field", value: $no },
5    { ownerId: $id, namespace: "tw_invoice", key: "issued_at",
6      type: "single_line_text_field", value: $date }
7  ]) {
8    metafields { id key value }
9    userErrors { field message }
10  }
11}

1async function onRefund(refund, order) {
2  const inv = await getInvoiceMeta(order.id);
3  if (!inv) return flagForManualReview(order, 'no invoice found');
4
5  const refundAmount = Number(refund.transactions?.[0]?.amount ?? 0);
6  const isFull = refundAmount >= Number(order.total_price);
7  const samePeriod = inSameInvoicePeriod(inv.issuedAt, new Date());
8
9  if (isFull && samePeriod) {
10    return callEcpay('/B2CInvoice/Invalid', {
11      MerchantID: process.env.ECPAY_MERCHANT_ID,
12      InvoiceNo: inv.number,
13      InvoiceDate: inv.issuedAt.slice(0, 10),
14      Reason: '訂單取消'
15    });
16  }
17  return callEcpay('/B2CInvoice/Allowance', {
18    MerchantID: process.env.ECPAY_MERCHANT_ID,
19    InvoiceNo: inv.number,
20    InvoiceDate: inv.issuedAt.slice(0, 10),
21    AllowanceNotify: 'E',
22    NotifyMail: order.email,
23    AllowanceAmount: Math.round(refundAmount),
24    Items: buildAllowanceItems(refund)
25  });
26}