الواجهة البرمجية والإشعارات

curl https://books.basmtak.com/partner/v1/ping \
  -H "Authorization: Bearer bsk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

# the first page of invoices changed since a moment
curl "https://books.basmtak.com/partner/v1/invoices?updated_since=2026-09-01T00:00:00%2B03:00&per_page=100" \
  -H "Authorization: Bearer $BOOKS_KEY"

# every list answers: data, page, per_page, total, last_page
# with updated_since it adds: cursor { updated_since, since_id } and has_more
# pass both cursor values on the next call

curl -X POST https://books.basmtak.com/partner/v1/invoices \
  -H "Authorization: Bearer $BOOKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "shop-order-10482",
    "contact_id": 118,
    "date": "2026-09-30",
    "issue": true,
    "lines": [
      { "item_id": 13, "quantity": 2 },
      { "description": "Delivery", "quantity": 1, "unit_price": 40 }
    ]
  }'

# answers { "invoice": { ... }, "created": true }
# the same external_id again answers the same invoice with "created": false

curl -X POST https://books.basmtak.com/partner/v1/webhooks \
  -H "Authorization: Bearer $BOOKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/books",
    "events": ["invoice.issued", "receipt.created"],
    "description": "Online store"
  }'

# the answer holds the signing secret (whsec_...) once: store it now

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before any JSON parsing
function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const signed = `${parts.t}.${rawBody}`;
  const expected = crypto.createHmac('sha256', secret).update(signed).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < toleranceSeconds;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

// header: req.headers['x-books-signature'], e.g. t=1790000000,v1=9f2c...
// answer any 2xx to confirm delivery