Может ли gPdf рассчитать receipt total?

Нет. Ваша payment или commerce system владеет totals, discounts, tax и refund state. gPdf рендерит values, которые вы отправляете.

Receipts лучше делать через JSON Render или Template Render?

Используйте JSON Render во время проектирования layout. Используйте Template Render, когда receipt layout и field contract стабильны.

Может ли receipt содержать QR code?

Да. gPdf поддерживает QR code barcode elements в PDF output. Ваша система отвечает за URL или payload, закодированный в QR code.

Это то же самое, что e-invoice API?

Нет. Ordinary receipt PDFs используют JSON Render или Template Render. Factur-X и ZUGFeRD packaging использует E-Invoice Render endpoint.

Счета и финансы

Receipt PDF API для ecommerce и SaaS payments

Генерируйте receipt PDFs из order, payment, tax и refund data: с QR codes, barcodes, PDF/A settings и повторяемым template output.

ОСНОВНАЯ API JSON Render

ENDPOINT /api/v1/pdf/render

СИСТЕМЫ ecommerce backend / billing backend / SaaS platform / POS export service

Попробовать в Playground Читать документацию

Задача сценария

Превращать completed order, payment, refund и tax data в receipt PDF, который можно отправить по email, хранить, печатать или прикреплять к customer account без того, чтобы каждый caller владел PDF drawing code.

Когда использовать эту API

Ваша система уже владеет payment status, receipt number, tax lines и customer data.
Нужен receipt PDF для email, account history, support workflows или audit export.
Нужны QR codes или barcodes внутри receipt для lookup, refund или pickup flows.
Нужен стабильный receipt template после утверждения layout.

Что она не заменяет

Нужны payment processing или refund execution. gPdf рендерит receipt; payment system отвечает за движение денег.
Нужен legal e-invoice packaging. Для Factur-X или ZUGFeRD output используйте E-Invoice Render endpoint.
Нужны POS hardware control или cash drawer logic.

Какой endpoint вызывать

ОСНОВНОЙ

/api/v1/pdf/render

JSON Render — путь по умолчанию для этого сценария.

ДОПОЛНИТЕЛЬНЫЙ 1

/api/v1/template-render

Используйте, когда сценарию нужен связанный API-путь, контракт шаблона или проверка возможностей.

Минимальный запрос

POST /api/v1/pdf/render - compact receipt с lookup QR code.

{
  "pages": [
    {
      "size": "a6",
      "elements": [
        {
          "type": "text",
          "x": 10,
          "y": 12,
          "content": "Receipt R-2026-1001",
          "style": { "font_size": 16, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "text",
          "x": 10,
          "y": 28,
          "content": "Order total: $82.40\nPaid by card ending 4242\nTax: $6.10",
          "style": { "font_size": 10, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "barcode",
          "format": "qrcode",
          "content": "https://example.com/receipts/R-2026-1001",
          "x": 10,
          "y": 58,
          "width": 28,
          "height": 28
        }
      ]
    }
  ]
}

Что выполняет gPdf

Receipt page rendering из JSON Render payloads.
Text, totals, item lines, QR codes, barcodes, metadata и optional PDF/A settings.
Template Render binding, когда тот же receipt layout используется повторно.
Binary PDF output с общим gPdf error envelope при failure.

Что контролирует ваша система

Payment authorization, capture, refund, tax calculation и receipt numbering.
Customer identity, order state, currency formatting и retention policy.
Email delivery, account storage и duplicate receipt handling.

Production-чеклист

Используйте стабильный receipt number и передавайте X-Request-Id при каждом render.
Решите, receipts нужно регенерировать из source data или хранить после первого render.
Проверьте длинные item names, refunds, discounts, multi-tax lines и zero-value orders.
Переходите на Template Render после утверждения layout support и finance teams.
Держите payment и tax decisions вне rendering request.

Границы заявлений

gPdf не обрабатывает payments, не рассчитывает tax и не выполняет refunds.
Receipt PDF не становится автоматически legal e-invoice.
Ваша система владеет business truth; gPdf рендерит PDF representation.

Receipt PDFs — это rendering outputs

Это не отдельный payment или POS endpoint. Ваш ecommerce, billing или POS backend решает, что receipt существует, затем отправляет receipt content в gPdf как DocumentRequest или data для published template.

Rendering layer должен оставаться детерминированным. Если support agent снова запрашивает тот же receipt, ваша система может либо replay source data, либо вернуть ранее stored PDF согласно retention policy.

Template path для повторяемых receipts

Receipt layouts обычно быстро стабилизируются. После утверждения дизайна опубликуйте template и вызывайте POST /api/v1/template-render с receipt fields. Так payment systems остаются сфокусированы на data, а layout ownership остается в одном месте.

FAQ

Может ли gPdf рассчитать receipt total?: Нет. Ваша payment или commerce system владеет totals, discounts, tax и refund state. gPdf рендерит values, которые вы отправляете.
Receipts лучше делать через JSON Render или Template Render?: Используйте JSON Render во время проектирования layout. Используйте Template Render, когда receipt layout и field contract стабильны.
Может ли receipt содержать QR code?: Да. gPdf поддерживает QR code barcode elements в PDF output. Ваша система отвечает за URL или payload, закодированный в QR code.
Это то же самое, что e-invoice API?: Нет. Ordinary receipt PDFs используют JSON Render или Template Render. Factur-X и ZUGFeRD packaging использует E-Invoice Render endpoint.