PDF рахунку — це те саме, що електронний рахунок?

Ні. Звичайний PDF рахунку — це читабельний для людини вивід. Електронний рахунок Factur-X або ZUGFeRD також вбудовує EN 16931 CII XML усередину оболонки PDF/A-3b.

Який маршрут API використовувати для повторюваних рахунків?

Використовуйте Template Render, коли макет рахунку стабільний і сервіси-викликачі мають надсилати лише template_id плюс data. Використовуйте JSON Render, коли код відповідає за макет.

Чи розраховує gPdf податки?

Ні. Ваша білінгова або бухгалтерська система розраховує податки, підсумки, знижки й стан оплати перед надсиланням даних для рендерингу.

Чи можуть PDF рахунків використовувати PDF/A?

Так, JSON Render підтримує налаштування PDF/A. Використовуйте E-Invoice Render саме тоді, коли рахунок потрібно запакувати як Factur-X або ZUGFeRD.

Рахунки та фінанси

Invoice PDF API для платіжних і фінансових систем

Генеруйте звичайні PDF рахунків із платіжних даних через JSON Render або Template Render, залишаючи податкову й бухгалтерську логіку у вашій системі.

ОСНОВНА API JSON Render

ШЛЯХ API /api/v1/pdf/render

СИСТЕМИ білінговий бекенд / ERP / бухгалтерська система / SaaS-застосунок

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

Задача сценарію

Перетворити дані рахунку з білінгової, ERP або SaaS-системи на читабельний PDF рахунку, залишаючи нумерацію, податки, стан оплати й бухгалтерську семантику всередині системи-викликача.

Коли використовувати цю API

Потрібні звичайні PDF рахунків для клієнтів, квитанцій, виписок або бухгалтерського експорту.
Ваша система вже відповідає за номери рахунків, розрахунок податків, рядки позицій і стан оплати.
Потрібні таблиці, підсумки, метадані й необов’язкові налаштування PDF/A без запуску браузера.
Потрібен контракт template_id для повторюваних макетів рахунків.

Що вона не замінює

Потрібен юридичний пакет електронного рахунку, наприклад Factur-X або ZUGFeRD. Використовуйте E-Invoice Render.
Очікуєте, що gPdf розрахує податок, перевірить бухгалтерські правила або звірить платежі.
Потрібне довільне перетворення HTML-рахунку замість структурованого JSON або шаблонів.

Який шлях API викликати

ОСНОВНИЙ

/api/v1/pdf/render

JSON Render — типовий шлях для цього сценарію.

ДОДАТКОВИЙ 1

/api/v1/template-render

Використовуйте, коли сценарію потрібен пов’язаний API-шлях, контракт шаблону або перевірка можливостей.

ДОДАТКОВИЙ 2

/api/v1/e-invoice/render

Використовуйте, коли сценарію потрібен пов’язаний API-шлях, контракт шаблону або перевірка можливостей.

Мінімальний запит

POST /api/v1/pdf/render - мінімальний заголовок рахунку й підсумок.

{
  "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

Рендеринг PDF рахунку з JSON-сторінок або template data.
Текст, таблиці, блоки підсумків, пагінацію, метадані та необов’язковий вивід PDF/A.
Template Render для стабільних макетів рахунків, які використовуються кількома системами.
Бінарну PDF-відповідь і послідовний конверт API-помилок.

Що контролює ваша система

Номери рахунків, стан оплати, розрахунок податків, знижки, кредити й зміст ledger.
Дані клієнта й issuer, мапінг line items, валюти та правила округлення.
Зберігання, доставку email, платіжні посилання й звірку з бухгалтерською системою.

Чеклист для робочого запуску

Підтвердьте, що кожне видиме поле рахунку мапиться на джерельні білінгові дані.
Протестуйте переповнення line items, довгі імена клієнтів, багатосторінкові рахунки й підсумки.
Вирішіть, чи макет належить JSON Render або опублікованому шаблону.
Тримайте створення звичайних PDF рахунків окремо від юридичного пакування електронних рахунків.
Зберігайте request IDs і вихідні імена файлів разом із записами рахунків.

Межі заявлених можливостей

Звичайні PDF рахунків — не те саме, що юридичні мандати електронних рахунків.
gPdf рендерить документ рахунку; він не розраховує податок або бухгалтерський стан.
Вивід Factur-X / ZUGFeRD належить до POST /api/v1/e-invoice/render.

Звичайні рахунки й електронні рахунки

Звичайний PDF рахунку — це документ, який читає ваш клієнт. Його можна створити через JSON Render або Template Render. Ваша система визначає номер рахунку, податки, позиції, валюту й стан оплати, а gPdf рендерить видимий PDF.

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

Template Render зазвичай є бойовим маршрутом API

Фінансові команди рідко хочуть, щоб кожен сервіс заново будував координати рахунку. Типовий шлях — один раз спроєктувати рахунок, опублікувати його як шаблон і дати сервісам-викликачам стабільний template_id плюс схему data. JSON Render залишається корисним для власних макетів, внутрішніх інструментів і прототипування шаблонів.

Тримайте бухгалтерську логіку вище за рендерер

gPdf має отримувати фінальні відображувані значення, а не нерозв’язані бухгалтерські рішення. Розраховуйте податок, знижки, округлення, статус оплати й допустимість рахунку до виклику render API. Так PDF-вивід лишається детермінованим, а фінансова система — джерелом істини.

FAQ

PDF рахунку — це те саме, що електронний рахунок?: Ні. Звичайний PDF рахунку — це читабельний для людини вивід. Електронний рахунок Factur-X або ZUGFeRD також вбудовує EN 16931 CII XML усередину оболонки PDF/A-3b.
Який маршрут API використовувати для повторюваних рахунків?: Використовуйте Template Render, коли макет рахунку стабільний і сервіси-викликачі мають надсилати лише template_id плюс data. Використовуйте JSON Render, коли код відповідає за макет.
Чи розраховує gPdf податки?: Ні. Ваша білінгова або бухгалтерська система розраховує податки, підсумки, знижки й стан оплати перед надсиланням даних для рендерингу.
Чи можуть PDF рахунків використовувати PDF/A?: Так, JSON Render підтримує налаштування PDF/A. Використовуйте E-Invoice Render саме тоді, коли рахунок потрібно запакувати як Factur-X або ZUGFeRD.