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.
- Authentication: header
Authorization: Bearer rv_live_...(API keys and scopes) - Required scope:
write:deals
openapi.json).Parameters
| Field | In | Type | Required | Description |
|---|---|---|---|---|
idempotency-key | header | string | no | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response (Idempotent-Replay: true). |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
dealId | string (uuid) | yes | |
kind | "contract" | "logistics_contract" | "invoice" | "act" | "power_of_attorney" | "specification" | "receipt" | "eta_notice" | "customs_package" | "custom" | yes | |
legalEntityId | string | null (uuid) | no | |
paymentId | string | null (uuid) | no | |
templateId | string | null (uuid) | no | |
title | string | null | no | |
overrides | object | no | |
overrides.poa | object | no | |
overrides.poa.valid_until | string | no | |
overrides.poa.representative_name | string | no | |
overrides.poa.representative_tax_id | string | null | no | |
overrides.poa.representative_passport | string | null | no | |
overrides.poa.representative_address | string | null | no | |
overrides.poa.broker_name | string | null | no | |
overrides.poa.customs_post | string | null | no | |
overrides.handover | object | no | |
overrides.eta | object | no | |
overrides.payment | object | no | |
overrides.extra | object | no | |
overrides.documentDate | string | no |
Responses
201
The generated draft.
application/json · Schema: DocumentGenerated
| Field | Type | Required | Description |
|---|---|---|---|
documentId | string (uuid) | yes | |
number | string | yes | Sequential document number of the tenant, e.g. VZ-D-2026-000123. |
kind | string | yes | |
status | string | yes | draft | sent | signed | void. |
pdfFileId | string | null (uuid) | yes | Id of the PDF in the platform file storage (download via Desk/Track; no public URL is returned). |
docxFileId | string | null (uuid) | yes | |
verifyUrl | string | null | yes | Public verification page (QR) of the document. |
warnings | string[] | yes | |
existing | boolean | yes | Always false for API calls. |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Schema: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Schema: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Schema: Problem
404
Deal, payment or template not found in this tenant.
application/problem+json · Schema: Problem
409
A request with this Idempotency-Key is still being processed.
application/problem+json · Schema: 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 · Schema: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Schema: Problem
502
Document renderer or storage unavailable.
application/problem+json · Schema: Problem