POST /v1/documents/generate
Generate a document for a deal
Generate a document for a deal
Renders a contract, invoice, act, power of attorney, etc. (PDF + DOCX) from a tenant or system template. The document is created as a draft with the next sequential number; sending for signature and signing happen in Desk (the document.signed webhook reports it). Supports Idempotency-Key: always send one, otherwise a retry creates a second numbered document. Requires scope write:deals.
- Автентифікація: заголовок
Authorization: Bearer rv_live_...(API-ключі та scopes) - Потрібний scope:
write:deals
openapi.json) і подається англійською, як у самому API.Параметри
| Поле | Де | Тип | Обов’язк. | Опис |
|---|---|---|---|---|
idempotency-key | header | string | ні | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response (Idempotent-Replay: true). |
Тіло запиту
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
dealId | string (uuid) | так | |
kind | "contract" | "logistics_contract" | "invoice" | "act" | "power_of_attorney" | "specification" | "receipt" | "eta_notice" | "customs_package" | "custom" | так | |
legalEntityId | string | null (uuid) | ні | |
paymentId | string | null (uuid) | ні | |
templateId | string | null (uuid) | ні | |
title | string | null | ні | |
overrides | object | ні | |
overrides.poa | object | ні | |
overrides.poa.valid_until | string | ні | |
overrides.poa.representative_name | string | ні | |
overrides.poa.representative_tax_id | string | null | ні | |
overrides.poa.representative_passport | string | null | ні | |
overrides.poa.representative_address | string | null | ні | |
overrides.poa.broker_name | string | null | ні | |
overrides.poa.customs_post | string | null | ні | |
overrides.handover | object | ні | |
overrides.eta | object | ні | |
overrides.payment | object | ні | |
overrides.extra | object | ні | |
overrides.documentDate | string | ні |
Відповіді
201
The generated draft.
application/json · Схема: DocumentGenerated
| Поле | Тип | Обов’язк. | Опис |
|---|---|---|---|
documentId | string (uuid) | так | |
number | string | так | Sequential document number of the tenant, e.g. VZ-D-2026-000123. |
kind | string | так | |
status | string | так | draft | sent | signed | void. |
pdfFileId | string | null (uuid) | так | Id of the PDF in the platform file storage (download via Desk/Track; no public URL is returned). |
docxFileId | string | null (uuid) | так | |
verifyUrl | string | null | так | Public verification page (QR) of the document. |
warnings | string[] | так | |
existing | boolean | так | Always false for API calls. |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Схема: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Схема: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Схема: Problem
404
Deal, payment or template not found in this tenant.
application/problem+json · Схема: Problem
409
A request with this Idempotency-Key is still being processed.
application/problem+json · Схема: Problem
422
Data required by the template is missing (code data_missing, fields in errors[]), or Idempotency-Key reused with a different request.
application/problem+json · Схема: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Схема: Problem
502
Document renderer or storage unavailable.
application/problem+json · Схема: Problem