מתשלום למסמך: חשבונית אוטומטית על כל תשלום

export async function handle(source, { headers, rawBody, query = new URLSearchParams() }) {
  const secret = process.env[`${source.name.toUpperCase()}_WEBHOOK_SECRET`]
  // 1. Is it really from them? Checked on the raw bytes, before anything is parsed. A source
  //    that signs nothing is read back from the provider instead, and answers the body to trust.
  const trusted = await source.verify({ headers, rawBody, query, secret })
  if (!trusted) return 401

  // 2. What happened? null is an event this server does not act on, answered 200 so the
  //    sender stops retrying it.
  const event = source.parse({ headers, rawBody: typeof trusted === 'string' ? trusted : rawBody })
  if (!event) return 200

  // 3. A payment becomes a document; a refund becomes the credit note of that document.
  //    Both calls are idempotent, so a notification that repeats what is known changes nothing.
  const ctx = { apiKey, businessId }
  if (event.payment) {
    const payment = event.payment
    if (source.lineItems && payment.sessionId) payment.items = await source.lineItems(payment.sessionId, process.env.STRIPE_SECRET_KEY)
    const document = await issueForPayment(payment, ctx)
    documents.set(`${payment.source}:${payment.id}`, document.id)
    console.log(`${payment.source}:${payment.id} -> document ${document.docNumber}`)
  }
  for (const refund of event.refunds || (event.refund ? [event.refund] : [])) {
    const documentId = documents.get(`${refund.source}:${refund.paymentId}`)
    if (!documentId) continue // a payment this server never invoiced
    const credit = await creditForRefund(refund, { ...ctx, documentId })
    console.log(`${refund.source}:refund:${refund.id} -> credit note ${credit.docNumber}`)
  }
  return 200
}

export async function issueForPayment(payment, { apiKey, businessId }) {
  const { business } = await call('GET', `/businesses/${businessId}`, { apiKey })
  // The money is already in, so the document carries the sale and its payment together:
  // a tax invoice/receipt (320). An exempt dealer (osek patur) may not issue a tax invoice,
  // and gives a receipt (400) instead.
  const docType = business.dealerType === 'patur' ? 400 : 320

  // The items are printed only when they add up to what was charged. Shipping, a coupon or a
  // rounding rule on the shop's side would otherwise make a document that disagrees with the
  // payment, and the payment is the fact.
  const itemsTotal = payment.items.reduce((sum, i) => sum + Math.round(i.quantity * i.unitAmount), 0)
  const lines = payment.items.length && itemsTotal === payment.amount
    ? payment.items.map((i) => ({ description: i.description, quantity: i.quantity, unitPriceExVat: i.unitAmount }))
    : [{ description: payment.description, quantity: 1, unitPriceExVat: payment.amount }]

  const { name, email, phone, taxId } = payment.customer
  const { document } = await call('POST', `/businesses/${businessId}/documents`, {
    apiKey,
    // The source's own payment id. A notification delivered twice lands on the same document.
    idempotencyKey: `${payment.source}:${payment.id}`,
    body: {
      docType,
      // The customer was charged a VAT-inclusive price. In gross mode unitPriceExVat carries
      // that price, the total is exactly what was paid, and the VAT is derived from it.
      priceMode: 'gross',
      ...(payment.currency === 'ILS' ? {} : { currency: payment.currency }),
      party: { name: name || email || 'לקוח', ...(email ? { email } : {}), ...(phone ? { phone } : {}), ...(taxId ? { taxId } : {}) },
      lines,
      payments: [{ method: payment.method, amount: payment.amount }],
    },
  })
  // A retry of a notification that was already handled: the document exists and is final.
  if (document.status === 'issued') return document
  // Issuing gives the document its number and signs the PDF. From here it never changes.
  const issued = await call('POST', `/businesses/${businessId}/documents/${document.id}/issue`, { apiKey })
  return issued.document
}

toMinor('349.90')   // 34990
toMinor('0.07')     // 7
Math.round(349.9 * 100)   // works here, and fails on the day a product lands on 34989.999

// An issued document is never edited or deleted. Money that went back is a credit note that
// names the original: in full when no amount is given, in part otherwise.
export async function creditForRefund(refund, { apiKey, businessId, documentId }) {
  const { document } = await call('POST', `/businesses/${businessId}/documents/${documentId}/credit-note`, {
    apiKey,
    // The source's refund id: a refund notified twice is one credit note.
    idempotencyKey: `${refund.source}:refund:${refund.id}`,
    body: {
      reason: refund.reason || 'החזר כספי',
      ...(refund.amount ? { amount: refund.amount } : {}),
      // The money was handed back, so an invoice/receipt also gets its negative receipt.
      refund: true,
    },
  })
  return document
}

git clone https://github.com/billos-dev/billos && cd billos/examples/payment-to-invoice
npx billos sandbox      # a free sandbox key: approve it once in the browser
npx billos seed         # a demo business to issue from
cp .env.example .env    # the key, the business id and your source's secret
node --env-file=.env server.mjs
node --test             # every source, end to end, with no network