PineBill으로 전자상거래 청구서 발행을 자동화하세요

Source: Dev.to

PineBill이 제공하는 기능

PineBill은 23개의 API 엔드포인트를 갖춘 인보이스 SaaS이며, 다음을 포함합니다:

• Invoices – 인보이스 생성, 조회, 업데이트
• Customers – 전체 CRUD 작업
• Products – 재고 관리 (7개 엔드포인트)
• Categories – 제품 조직화
• Payment Methods – 결제 처리 옵션
• Exchange Rates – 다중 통화 지원

API는 OpenAPI 3.1 사양을 따르고, Bearer 토큰 인증을 사용하며, 전 세계 CDN에서 99.99 % 가동 시간을 보장합니다.

시작하기

1. API 키 발급받기

PineBill에 가입하고 대시보드로 이동합니다. API Keys 섹션에서 API 키를 생성합니다.

플랜

2. 기본 URL 및 인증

모든 API 요청은 다음 주소로 전송됩니다:

https://api.pinebill.app

Authorization 헤더에 API 키를 포함합니다:

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();
  // Store customer.id in your database for future invoices
  return customer;
};

제품 관리

제품 카탈로그를 동기화합니다:

// Create a product
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();
};

// Toggle product status (active/inactive)
const toggleProductStatus = async (productId) => {
  await fetch(`https://api.pinebill.app/products/${productId}/toggle-status`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
};

// Duplicate a product
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();
};

다른 통화를 사용하는 고객에게 인보이스를 만들 때 위 환율을 활용하세요.

실제 적용 패턴

전자상거래 주문 웹훅 핸들러

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

  try {
    // 1. Ensure customer exists
    let customer = await findCustomerByEmail(order.customer.email);
    if (!customer) {
      customer = await syncCustomer(order.customer);
    }

    // 2. Map order items to PineBill product IDs
    const productIds = await mapOrderItemsToProducts(order.items);

    // 3. Create invoice
    const invoice = await createInvoice({
      productIds,
      customerId: customer.id
    });

    // 4. Store invoice reference
    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 또는 구독 비즈니스를 위한 반복 인보이스 자동화:

// Cron job for monthly billing
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({
        // payload details would go here
      })
    });
    // handle response...
  }
};