使用 PineBill 自动化您的电子商务开票

Source: Dev.to

PineBill 能提供的功能

PineBill 是一款拥有 23 条 API 端点的开票 SaaS，覆盖：

• Invoices – 创建、读取、更新发票
• Customers – 完整的 CRUD 操作
• Products – 库存管理（7 条端点）
• Categories – 商品分类管理
• Payment Methods – 交易处理方式
• Exchange Rates – 多币种支持

API 遵循 OpenAPI 3.1 规范，使用 Bearer Token 认证，并在全球 CDN 上运行，正常运行时间达 99.99 %。

入门指南

1. 获取 API Key

在 PineBill 注册并进入仪表盘。从 API Keys 区域生成一个 API Key。

套餐

2. 基础 URL 与认证

所有 API 请求均发送至：

https://api.pinebill.app

在 Authorization 头部中加入你的 API Key：

Authorization: Bearer YOUR_API_KEY

电子商务核心集成

编程方式创建发票

当客户完成购买后，触发发票创建：

const createInvoice = async (orderData) => {
  const response = await fetch('https://api.pinebill.app/invoices', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      products: orderData.productIds,
      customerID: orderData.customerId,
      paymentMethods: ['pm_card', 'pm_bank_transfer'],
      invoiceMode: 'PRODUCT',
      taxRate: 10,
      taxType: 'PERCENT',
      issueDate: new Date().toISOString().split('T')[0],
      currency: 'USD'
    })
  });

  return response.json();
};

从平台同步客户

用户注册时，在 PineBill 中创建对应的客户记录：

const syncCustomer = async (user) => {
  const response = await fetch('https://api.pinebill.app/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: user.fullName,
      email: user.email,
      phone: user.phone,
      address: user.billingAddress
    })
  });

  const customer = await response.json();
  // 将 customer.id 存入你的数据库，以便后续开票使用
  return customer;
};

商品管理

保持商品目录同步：

// 创建商品
const createProduct = async (product) => {
  const response = await fetch('https://api.pinebill.app/products', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: product.name,
      price: product.price,
      description: product.description,
      categoryId: product.categoryId
    })
  });

  return response.json();
};

// 切换商品状态（激活/停用）
const toggleProductStatus = async (productId) => {
  await fetch(`https://api.pinebill.app/products/${productId}/toggle-status`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
};

// 复制商品
const duplicateProduct = async (productId) => {
  const response = await fetch(`https://api.pinebill.app/products/${productId}/duplicate`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  return response.json();
};

多币种支持

获取实时汇率，以便为国际客户开具发票：

const getExchangeRates = async () => {
  const response = await fetch('https://api.pinebill.app/exchange-rates/latest', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  return response.json();
};

在为不同币种的客户创建发票时使用这些汇率。

实际集成模式

电商订单 Webhook 处理器

// Express.js webhook 处理示例
app.post('/webhooks/order-completed', async (req, res) => {
  const order = req.body;

  try {
    // 1. 确保客户已存在
    let customer = await findCustomerByEmail(order.customer.email);
    if (!customer) {
      customer = await syncCustomer(order.customer);
    }

    // 2. 将订单商品映射到 PineBill 商品 ID
    const productIds = await mapOrderItemsToProducts(order.items);

    // 3. 创建发票
    const invoice = await createInvoice({
      productIds,
      customerId: customer.id
    });

    // 4. 保存发票引用
    await saveInvoiceReference(order.id, invoice.invoiceNumber);

    res.status(200).json({ success: true, invoiceNumber: invoice.invoiceNumber });
  } catch (error) {
    console.error('Invoice creation failed:', error);
    res.status(500).json({ error: 'Failed to create invoice' });
  }
});

订阅平台集成

为 SaaS 或订阅业务自动生成周期性发票：

// 每月计费的定时任务
const processMonthlySubscriptions = async () => {
  const activeSubscriptions = await getActiveSubscriptions();

  for (const subscription of activeSubscriptions) {
    const response = await fetch('https://api.pinebill.app/invoices', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        // 这里放置具体的负载数据
      })
    });
    // 处理响应...
  }
};