{{client_name}}
", "margin_top": 10, "margin_bottom": 10, "margin_left": 15, "margin_right": 15, "variables_attributes": [ {"title": "client_name", "description": "Client name", "field_type": "text", "seed_value": "John Doe"} ] } } ``` Accepted fields: `title`, `description`, `content`, `orientation`, `margin_top`, `margin_bottom`, `margin_left`, `margin_right`, `variables_attributes` (array of `id`, `_destroy`, `title`, `description`, `seed_value`, `field_type`, `allowed_values`). ### PATCH /api/v1/templates/:id Update a custom template. Returns 200 with detail view. Only send fields you want to change. Inline variable management via `variables_attributes`: - Update: include `id` + changed fields - Create: omit `id` - Delete: include `id` + `"_destroy": true` ### DELETE /api/v1/templates/:id Soft-delete (archive) a custom template. Returns 204. ### PUT /api/v1/templates/:id/publish Publish a template. Returns 200 with detail view. ### PUT /api/v1/templates/:id/unpublish Unpublish a template. Returns 200 with detail view. --- ## Variables ### Variable Object Fields - `id` — unique identifier - `title` — name (alphanumeric + underscores, auto-lowercased, unique per template) - `description` — expected content and format - `field_type` — `text`, `checkbox`, `radio`, or `select` - `seed_value` — preview value (accepted on write, only returned in template detail view) - `allowed_values` — array of accepted values (for radio/select only) ### GET /api/v1/templates/:template_id/variables List all variables of a template. Response: ```json [ {"id": 200001, "title": "client_name", "description": "Full name", "field_type": "text", "allowed_values": []}, {"id": 200002, "title": "status", "description": "Client status", "field_type": "select", "allowed_values": ["active", "inactive"]} ] ``` Note: `seed_value` is NOT included in variable API responses. ### POST /api/v1/templates/:template_id/variables Create a variable. Returns 201. Request: ```json {"variable": {"title": "city", "description": "City name", "field_type": "text", "seed_value": "Paris"}} ``` Response: ```json {"id": 200003, "title": "city", "description": "City name", "field_type": "text", "allowed_values": []} ``` ### PATCH /api/v1/templates/:template_id/variables/:id Update a variable. Returns 200. ### DELETE /api/v1/templates/:template_id/variables/:id Delete a variable. Returns 204. --- ## Document Requests Document generation is asynchronous. You create a request, and results are delivered via webhook. ### Document Request Object Fields - `id` — unique identifier - `tag` — custom identifier (optional) - `type` — `asynchrone` - `priority` — `critical` (default), `default`, or `low`. Sandbox forces `low`. - `sandbox_mode` — boolean - `external_application` — `{id, name, environment, active}` - `documents_generations` — array of Document Generation objects ### Document Generation Object Fields Short view (list, webhook): - `id`, `tag`, `generated_at`, `created_at`, `generation_status`, `file` Detail view (GET show): - All of the above plus: `generation_duration` (ms), `generation_error`, `sent_payload`, `template` File object: `{filename, url, size}` S3 URL expiration: **2 hours** (webhook) / **20 hours** (GET show) Generation statuses: `created` → `in_progress` → `success` | `error` ### POST /api/v1/document_requests Create a document request (up to 100 documents). Returns 201. Webhook URL must be configured on the external application. Request: ```json { "document_request": { "type": "asynchrone", "priority": "critical", "tag": "Batch#12", "document_generations": [ { "template_id": "100017", "tag": "Subscription#102", "variables": {"firstname": "John", "lastname": "Doe", "city": "Paris"} }, { "template_id": "100014", "tag": "Subscription#103", "variables": {"firstname": "Lea", "lastname": "Maquize", "city": "London"} } ] } } ``` Response: ```json { "id": 100004, "tag": "Batch#12", "type": "asynchrone", "sandbox_mode": true, "status": "in_progress" } ``` Results are delivered via webhook when generation completes. ### GET /api/v1/document_requests List document requests (paginated). Returns index view with `id`, `tag`, `type`, `external_application`, `documents_generations` (short view). ### GET /api/v1/document_requests/:id View a document request with full detail including `sent_payload`, `generation_duration`, `generation_error`, and `template` per generation. ### Variable Validation Errors When a radio/select variable receives a value not in `allowed_values`, returns 422: ```json { "error": "Invalid variables", "invalid_variables": [ {"field": "status", "value": "unknown", "allowed_values": ["active", "inactive", "pending"]} ] } ``` --- ## Webhooks ### Configuration Set a `webhook_url` (HTTPS) on your external application from the DocLift dashboard. Required for document requests. ### Payload POST to your webhook URL when generation completes: ```json { "id": 100004, "tag": "Batch#12", "type": "asynchrone", "timestamp": "2024-01-15T10:35:00+01:00", "documents_generations": [ { "id": 100230, "tag": "Subscription#102", "generated_at": "2024-01-15 10:35:00 +0100", "created_at": "2024-01-15 10:34:58 +0100", "generation_status": "success", "file": {"filename": "Contract.pdf", "url": "https://doclift.s3...?...", "size": 40290} } ] } ``` S3 URLs expire after **2 hours**. ### Signature Verification Header: `X-Doclift-Signature: sha256={hmac_hex_digest}` The signature is HMAC-SHA256 of the raw request body, signed with your API secret key, prefixed with `sha256=`. Verification example (Ruby): ```ruby computed = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", api_secret_key, request.raw_post) valid = computed == request.headers["X-Doclift-Signature"] ``` ### Response Your endpoint must return HTTP 2xx within **3 seconds**. ### Retry Policy On failure: exponential backoff — `delay = min(30 * 2^(n-1), 1800)` seconds. - Retry 1: 30s - Retry 2: 60s - Retry 3: 120s - Max delay: 30 minutes Default max retries: 3 (configurable via `webhooks_replays_count`). Failed webhooks can be recovered via GET /api/v1/document_requests/:id.