Invoice PDF — это то же самое, что e-invoice?

Нет. Ordinary invoice PDF — человекочитаемый output. Factur-X или ZUGFeRD e-invoice также встраивает EN 16931 CII XML внутри PDF/A-3b wrapper.

Какой endpoint использовать для повторяемых invoices?

Используйте Template Render, когда invoice layout стабилен и callers должны отправлять только template_id плюс data. Используйте JSON Render, когда code владеет layout.

Рассчитывает ли gPdf taxes?

Нет. Ваша billing или accounting system рассчитывает taxes, totals, discounts и payment state перед отправкой render data.

Можно ли использовать PDF/A для invoice PDFs?

Да, JSON Render поддерживает PDF/A settings. Используйте E-Invoice Render именно тогда, когда invoice нужно упаковать как Factur-X или ZUGFeRD.

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

Invoice PDF API для billing и finance systems

Генерируйте ordinary invoice PDFs из billing data через JSON Render или Template Render, оставляя tax и accounting logic в вашей системе.

ОСНОВНАЯ API JSON Render

ENDPOINT /api/v1/pdf/render

СИСТЕМЫ billing backend / ERP / accounting system / SaaS app

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

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

Преобразовать invoice data из billing, ERP или SaaS system в читаемый PDF invoice, оставляя numbering, tax, payment state и accounting semantics внутри системы caller.

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

Нужны ordinary invoice PDFs для customers, receipts, statements или accounting exports.
Ваша система уже владеет invoice numbers, tax calculation, line items и payment state.
Нужны tables, totals, metadata и опциональные PDF/A settings без запуска браузера.
Нужен контракт `template_id` для повторяемых invoice layouts.

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

Нужен legal e-invoice package, например Factur-X или ZUGFeRD. Используйте E-Invoice Render.
Вы ожидаете, что gPdf рассчитает tax, проверит accounting rules или сверит payments.
Нужна arbitrary HTML invoice conversion вместо structured JSON или templates.

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

ОСНОВНОЙ

/api/v1/pdf/render

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

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

/api/v1/template-render

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

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

/api/v1/e-invoice/render

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

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

POST /api/v1/pdf/render - минимальный invoice header и total.

{
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 24,
          "content": "Invoice INV-1007",
          "style": { "font_size": 18, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "text",
          "x": 20,
          "y": 42,
          "content": "Bill to: Example Customer\nAmount due: USD 245.00",
          "style": { "font_size": 11, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "line",
          "x1": 20,
          "y1": 62,
          "x2": 190,
          "y2": 62
        }
      ]
    }
  ]
}

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

Invoice PDF rendering из JSON pages или template data.
Text, tables, totals blocks, pagination, metadata и optional PDF/A output.
Template Render для стабильных invoice layouts, используемых несколькими системами.
Binary PDF response и consistent API error envelope.

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

Invoice numbers, payment state, tax calculation, discounts, credits и ledger meaning.
Customer and issuer data, line-item mapping, currencies и rounding rules.
Retention, delivery, email, payment links и accounting-system reconciliation.

Production-чеклист

Подтвердите, что каждое видимое invoice field мапится на source billing data.
Проверьте line-item overflow, длинные customer names, multi-page invoices и totals.
Решите, принадлежит ли layout JSON Render или published template.
Держите ordinary invoice PDF generation отдельно от legal e-invoice packaging.
Храните request IDs и output filenames вместе с invoice records.

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

Ordinary invoice PDFs — не то же самое, что legal e-invoice mandates.
gPdf рендерит invoice document; он не рассчитывает tax или accounting state.
Factur-X / ZUGFeRD output находится на POST /api/v1/e-invoice/render.

Ordinary invoices и e-invoices

Ordinary invoice PDF — документ, который читает customer. Его можно генерировать через JSON Render или Template Render. Ваша система определяет invoice number, taxes, line items, currency и payment state, затем gPdf рендерит видимый PDF.

Legal e-invoice устроен иначе. Factur-X и ZUGFeRD объединяют читаемый PDF/A-3b invoice со встроенным EN 16931 CII XML. Для такого package используйте POST /api/v1/e-invoice/render.

Template Render обычно production endpoint

Finance teams редко хотят, чтобы каждый service заново собирал invoice coordinates. Обычный путь — один раз спроектировать invoice, опубликовать его как template и дать callers стабильный template_id плюс data schema. JSON Render остается полезным для custom layouts, internal tools и template prototyping.

Accounting logic остается upstream

gPdf должен получать final display values, а не unresolved accounting decisions. Рассчитайте tax, discounts, rounding, payment status и invoice eligibility до вызова render API. Это делает PDF output детерминированным и оставляет financial system source of truth.

FAQ

Invoice PDF — это то же самое, что e-invoice?: Нет. Ordinary invoice PDF — человекочитаемый output. Factur-X или ZUGFeRD e-invoice также встраивает EN 16931 CII XML внутри PDF/A-3b wrapper.
Какой endpoint использовать для повторяемых invoices?: Используйте Template Render, когда invoice layout стабилен и callers должны отправлять только template_id плюс data. Используйте JSON Render, когда code владеет layout.
Рассчитывает ли gPdf taxes?: Нет. Ваша billing или accounting system рассчитывает taxes, totals, discounts и payment state перед отправкой render data.
Можно ли использовать PDF/A для invoice PDFs?: Да, JSON Render поддерживает PDF/A settings. Используйте E-Invoice Render именно тогда, когда invoice нужно упаковать как Factur-X или ZUGFeRD.