{ "openapi": "3.1.0", "info": { "title": "AllSign Enterprise API v2", "description": "\n # AllSign API V2 - Enterprise Security Edition\n \n ## 🔐 Authentication\n \n V2 uses **Bearer token authentication** following industry standards (Stripe, GitHub, AWS).\n \n ### Getting Started\n \n 1. **Create an API Key** via `POST /v2/api-keys` (requires JWT)\n 2. **Copy the key** (shown only once): `allsign_live_sk_8f3k2j9sd8f7s6d5f4g3h2j1k0m9n8b7`\n 3. **Click \"Authorize\" 🔓 button** above\n 4. **Paste your API key** in the \"Value\" field (just the key, no \"Bearer\" prefix)\n 5. **Click \"Authorize\"** then \"Close\"\n 6. Now **\"Try it out\"** on any endpoint\n \n **cURL example:**\n ```bash\n curl https://api.allsign.io/v2/documents \\\n -H \"Authorization: Bearer allsign_live_sk_8f3k2j9sd8f7s6d5f4g3h2j1k0m9n8b7\"\n ```\n \n ## 🎯 Permissions (Scopes)\n \n V2 uses OAuth-style scopes for granular access control:\n \n - `document:read` - Read and list documents\n - `document:write` - Create and update documents\n - `document:delete` - Delete documents\n - `document:*` - All document permissions\n - `signature:read` - Read signature status\n - `signature:write` - Create and sign documents\n - `*` - Full admin access\n \n ## 🔒 Security Features\n \n - ✅ **Bcrypt hashing** - Keys never stored in plaintext\n - ✅ **Bearer tokens** - Industry standard authentication\n - ✅ **Scope-based permissions** - Principle of least privilege\n - ✅ **Key expiration** - Automatic rotation support\n - ✅ **Rate limiting** - Per-key request limits\n - ✅ **Audit trails** - Complete request logging\n \n ## 🔄 Migration from V1\n \n V1 and V2 can coexist. Migrate at your own pace:\n \n 1. Create V2 API keys in your dashboard\n 2. Update your code to use Bearer tokens\n 3. Test thoroughly in `test` environment\n 4. Switch to V2 endpoints\n 5. Revoke V1 keys when ready\n \n ## 📚 API Compatibility\n \n Compatible with **any programming language** and automation platforms:\n - Make\n - n8n\n - Activepieces\n - Zapier\n - Custom integrations\n ", "version": "2.0.0" }, "servers": [ { "url": "/v2", "description": "V2 API base path" } ], "paths": { "/test/security": { "get": { "tags": [ "Security Test" ], "summary": "Test API Security", "description": "🔐 **Security Test Endpoint**\n \n Este endpoint simple retorna `true` si la autenticación es exitosa.\n \n **Propósito:**\n - Validar que tu API key V2 funciona correctamente\n - Verificar los scopes asignados\n - Probar la autenticación Bearer token\n \n **Requisitos:**\n - Header: `Authorization: Bearer allsign_live_sk_xxx`\n - Scope mínimo: `document:read` (o cualquier scope de documento)\n \n **Casos de prueba:**\n \n ✅ **Éxito (200):**\n ```bash\n curl -X GET \"https://api.allsign.io/v2/test/security\" \\\n -H \"Authorization: Bearer allsign_live_sk_8f3k2j9sd8f7s6d5f4g3h2j1k0m9n8b7\"\n ```\n \n ❌ **Sin autenticación (401):**\n ```bash\n curl -X GET \"https://api.allsign.io/v2/test/security\"\n ```\n \n ❌ **Key inválida (401):**\n ```bash\n curl -X GET \"https://api.allsign.io/v2/test/security\" \\\n -H \"Authorization: Bearer invalid_key_12345\"\n ```\n \n ❌ **Sin permisos (403):**\n ```bash\n # Si tu key solo tiene signature:read pero no document:*\n curl -X GET \"https://api.allsign.io/v2/test/security\" \\\n -H \"Authorization: Bearer allsign_live_sk_xxx\"\n ```\n \n **Respuesta exitosa:**\n ```json\n {\n \"success\": true,\n \"message\": \"API V2 security validated successfully\",\n \"authenticatedUser\": \"user@company.com\",\n \"tenantId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"scopes\": [\"document:read\", \"document:write\"],\n \"environment\": \"live\"\n }\n ```", "operationId": "test_security_test_security_get", "responses": { "200": { "description": "Autenticación exitosa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityTestResponse" }, "example": { "success": true, "message": "API V2 security validated successfully", "authenticatedUser": "user@company.com", "tenantId": "550e8400-e29b-41d4-a716-446655440000", "scopes": [ "document:read", "document:write", "signature:*" ], "environment": "live" } } } }, "401": { "description": "No autenticado - API key faltante o inválida", "content": { "application/json": { "example": { "detail": "Invalid or expired API key" } } } }, "403": { "description": "Sin permisos - Scopes insuficientes", "content": { "application/json": { "example": { "detail": "Insufficient permissions. Requires ANY of these scopes: document:read, document:*. Your scopes: signature:read" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] } }, "/documents/": { "post": { "tags": [ "Documents" ], "summary": "Create Document (With Credit Tracking)", "description": "# Create a new document with enterprise credit tracking\n \n ## Credit System Flow\n \n This endpoint demonstrates the complete credit lifecycle:\n \n ### 1. Pre-Authorization (Reserve)\n ```\n - Check if tenant has enough credits\n - Reserve credits before processing (2-phase commit)\n - If insufficient balance → 402 Payment Required\n ```\n \n ### 2. Processing\n ```\n - Create document in database\n - Process file (upload to S3, etc.)\n - Track performance metrics\n ```\n \n ### 3. Settlement\n ```\n Success path:\n - Settle reservation (commit credits)\n - Create immutable ledger entry\n - Track API usage event\n \n Failure path:\n - Release reservation (return credits)\n - Log error\n - Return appropriate error code\n ```\n \n ## Credits Required\n \n - **document_signature**: 1 credit per document\n - Configurable per tenant and plan\n \n ## Example\n \n ```bash\n curl -X POST \"https://api.allsign.io/v2/documents\" \\\n -H \"Authorization: Bearer allsign_live_sk_xxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Contract.pdf\",\n \"description\": \"Sample contract\"\n }'\n ```\n \n ## Response Codes\n \n - **201**: Document created successfully\n - **401**: Unauthorized (invalid API key)\n - **402**: Payment Required (insufficient credits)\n - **403**: Forbidden (insufficient scopes)\n - **500**: Internal error (credits released automatically)", "operationId": "create_document_v2_documents__post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "mode", "in": "query", "required": false, "schema": { "enum": [ "sync", "async" ], "type": "string", "description": "'sync' waits for completion (201). 'async' returns immediately (202) — use progressUrl for real-time updates.", "default": "sync", "title": "Mode" }, "description": "'sync' waits for completion (201). 'async' returns immediately (202) — use progressUrl for real-time updates." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreateRequestV2" } } } }, "responses": { "201": { "description": "Document created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleDocumentResponse" }, "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Contract.pdf", "description": "Sample contract", "createdAt": "2024-11-23T20:00:00Z", "creditsConsumed": 1 } } } }, "402": { "description": "Payment Required - Insufficient credits", "content": { "application/json": { "example": { "detail": "Insufficient credits. Required: 1, Available: 0. Please add credits to continue." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Documents" ], "summary": "List Documents (Cursor Pagination)", "description": "# Cursor-based document listing with filtering and scopes\n\n This endpoint now uses **only cursor pagination** to keep responses fast and stable.\n Request the first batch with `limit` and reuse the `nextCursor` value to continue.\n\n ```bash\n # First page\n GET /v2/documents?limit=20&scope=accessible\n\n # Next page\n GET /v2/documents?limit=20&scope=accessible&cursor={nextCursor}\n ```\n\n ## Highlights\n - ✅ Cursor pagination aligned with the sort order (created_at / updated_at)\n\n ## Response Meta\n ```json\n \"meta\": {\n \"limit\": 20,\n \"hasNext\": true,\n \"nextCursor\": \"eyJz...\",\n \"prevCursor\": null\n }\n ```\n\n ## Example filters\n ```bash\n GET /v2/documents?scope=org&name=invoice&createdAfter=2024-11-01&sortBy=created_at\n ```", "operationId": "get_documents_v2_documents__get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Limit" } }, { "name": "scope", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DocumentScopeEnum", "default": "owner" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folderid" } }, { "name": "signatureStatus", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signaturestatus" } }, { "name": "createdAfter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdafter" } }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdbefore" } }, { "name": "includeAllHistory", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includeallhistory" } }, { "name": "orgId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Orgid" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DocumentSortFieldEnum", "default": "created_at" } }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SortOrderEnum", "default": "desc" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "createdBy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdby" } }, { "name": "forUserId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Foruserid" } }, { "name": "includeSigners", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Includesigners" } }, { "name": "includeFolders", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includefolders" } }, { "name": "includeDocumentStats", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includedocumentstats" } }, { "name": "environment", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment" } } ], "responses": { "200": { "description": "Documents retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListV2Response" } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Insufficient scopes" }, "422": { "description": "Validation Error - Invalid query parameters" }, "500": { "description": "Internal Server Error" } } } }, "/documents/stats": { "get": { "tags": [ "Documents" ], "summary": "Get Document Statistics", "description": "Get aggregate statistics about user's documents.\n \n Returns:\n - Total document count\n - Count by document type\n - Recent documents (last 7 days)\n \n ## Date Filters\n - `createdAfter` / `createdBefore` accept ISO 8601 timestamps and reuse the same filtering semantics as `GET /v2/documents`.\n - If either parameter is provided, all counters (including `recentCount`) are computed only for the filtered range.\n - If both parameters are omitted, the API defaults to the last 365 days to keep queries bounded, and `recentCount` still reflects the last 7 days inside that window.", "operationId": "get_documents_stats_v2_documents_stats_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DocumentScopeEnum", "default": "accessible" } }, { "name": "createdAfter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdafter" } }, { "name": "createdBefore", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdbefore" } }, { "name": "includeAllHistory", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includeallhistory" } }, { "name": "environment", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentStatsV2Response" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}": { "get": { "tags": [ "Documents" ], "summary": "Get Document by ID", "description": "Retrieve a single document by its ID.\n \n Returns 404 if:\n - Document doesn't exist\n - User doesn't own the document", "operationId": "get_document_by_id_endpoint_documents__document_id__get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentV2Response" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Documents" ], "summary": "Update Document (Partial)", "description": "# Partially update a document\n \n Update specific fields of a document without affecting other fields.\n All fields are optional - only provided fields will be updated.\n \n ## Common Use Cases\n \n ### Move document to folder\n ```json\n {\"folderId\": \"550e8400-e29b-41d4-a716-446655440000\"}\n ```\n \n ### Remove from folder\n ```json\n {\"folderId\": null}\n ```\n \n ### Rename document\n ```json\n {\"name\": \"New Contract Name.pdf\"}\n ```\n \n ### Update config\n ```json\n {\n \"config\": {\n \"sendInvitations\": true,\n \"sendByEmail\": true,\n \"startAtStep\": 3\n }\n }\n ```\n \n ### Update permissions\n ```json\n {\n \"permissions\": {\n \"ownerEmail\": \"newowner@example.com\",\n \"collaborators\": [\n {\"email\": \"user@example.com\", \"permissions\": [\"read\", \"update\"]}\n ]\n }\n }\n ```\n \n ## Response Codes\n \n - **200**: Document updated successfully\n - **400**: Invalid request (no fields provided, validation error)\n - **401**: Unauthorized (invalid API key)\n - **403**: Forbidden (insufficient scopes)\n - **404**: Document not found or no access\n - **422**: Validation error (invalid folder_id, etc.)\n - **500**: Internal error", "operationId": "patch_document_v2_documents__document_id__patch", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPatchRequestV2" } } } }, "responses": { "200": { "description": "Document updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentV2Response" } } } }, "400": { "description": "Bad Request - No fields provided or validation error" }, "404": { "description": "Document not found or no access" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete Document", "description": "Delete a single document. Requires `document:delete` scope. Documents that are fully signed (TODOS_FIRMARON) or have signatures in progress (ESPERANDO_FIRMAS) cannot be deleted. Associated S3 files (PDFs, evidence, NOM-151 constancias) are cleaned up in the background.", "operationId": "delete_document_documents__document_id__delete", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDocumentResponseV2" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/extend": { "post": { "tags": [ "Documents" ], "summary": "Extend Document Signing Deadline", "description": "Extend or reactivate the signing deadline for a document.\n\n **Owner-only** — only the document owner can extend the deadline.\n\n If the document is in EXPIRADO status, it will be reactivated to\n ESPERANDO_FIRMAS with the new deadline and **every pending signer is\n reinvited** (a fresh signing-invitation workflow is started per signer).\n\n The `extendedCount` tracks how many times the deadline has been extended.\n `expirationReminders` is optional — when omitted the previously-stored\n reminders are reused for the new deadline.", "operationId": "extend_document_deadline_documents__document_id__extend_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtendDeadlineRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtendDeadlineResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/events": { "get": { "tags": [ "SSE Events", "documents", "sse" ], "summary": "SSE stream for document signing status", "description": "Opens a Server-Sent Events stream that pushes real-time updates about the document's signing status. Uses PG LISTEN/NOTIFY for instant notifications (~100ms latency), with automatic fallback to 3-second polling if the notification system is unavailable.", "operationId": "document_events_sse_documents__document_id__events_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "SSE event stream", "content": { "application/json": { "schema": {} }, "text/event-stream": {} } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/invite": { "post": { "tags": [ "Invitations", "Invitations" ], "summary": "Invite a single participant (guest mode)", "description": "Creates a GuestSession and sends the guest signing link via email and/or WhatsApp. The participant must already exist as a signer on the document.", "operationId": "invite_participant_v2_documents__document_id__invite_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteRequestV2" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResponseV2" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/invite-bulk": { "post": { "tags": [ "Invitations", "Invitations" ], "summary": "Invite multiple participants (guest mode)", "description": "Creates GuestSessions and sends guest signing links via email and/or WhatsApp for multiple participants in a single call.", "operationId": "invite_participants_bulk_v2_documents__document_id__invite_bulk_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInviteRequestV2" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResponseV2" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/start-signing": { "post": { "tags": [ "Invitations", "Signing Lifecycle" ], "summary": "Start the signing process", "description": "Advances the document from setup stages (RECOLECTANDO_FIRMANTES, SELLOS_PDF) to ESPERANDO_FIRMAS and charges credits based on the final stamp configuration.\n\nCredits are calculated from the document's current signature_validations in the DB, so the cost reflects whatever stamps were configured last.\n\nThis is idempotent — if credits were already settled for this document (e.g. during correction re-entry), no additional charge is made.\n\nIf you also need to send email/WhatsApp invitations, use `POST /{document_id}/invite-bulk` instead — it calls start-signing internally.", "operationId": "start_signing_documents__document_id__start_signing_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSigningResponse" } } } }, "402": { "description": "Payment Required - Insufficient credits", "content": { "application/json": { "example": { "detail": { "code": "INSUFFICIENT_CREDITS", "message": "Insufficient credits", "required": 3, "available": 1 } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/correction-context": { "get": { "tags": [ "Correction", "Correction" ], "summary": "Get document correction context", "description": "Returns what edit operations the admin can perform on this document. Uses DocuSign-style rules based on which signers have already signed.", "operationId": "get_document_correction_context_documents__document_id__correction_context_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionContextResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/void": { "post": { "tags": [ "Correction", "Correction" ], "summary": "Void document", "description": "Voids a document, cancelling all pending signatures. Already-signed signatures are preserved in the audit trail.", "operationId": "void_document_documents__document_id__void_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/enter-correction": { "post": { "tags": [ "Correction", "Correction" ], "summary": "Enter correction mode", "description": "Temporarily locks the document for editing. Signers will see 'Document is being updated' while in this state.", "operationId": "enter_correction_mode_documents__document_id__enter_correction_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/exit-correction": { "post": { "tags": [ "Correction", "Correction" ], "summary": "Exit correction mode", "description": "Unlocks the document after owner editing is complete. Returns the document to ESPERANDO_FIRMAS so signers can resume.", "operationId": "exit_correction_mode_documents__document_id__exit_correction_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/add-signer": { "post": { "tags": [ "Correction", "Correction" ], "summary": "Add signer to document", "description": "Add a signer to a document. Finds or creates the user under the tenant, grants document access, and creates the signature record.", "operationId": "add_signer_v2_documents__document_id__add_signer_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSignerRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSignerResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/signers/{signature_id}": { "delete": { "tags": [ "Correction", "Correction" ], "summary": "Remove signer from active document", "description": "Remove a signer from a document that has already been sent.\n\n**Validations**\n- The signer must not have signed yet.\n- There must be at least one other signer remaining.\n\n**Cascade effects (Phase 9 contract)**\nRemoving a signer transitively cleans up everything that pointed at them. In a single transaction:\n1. Deletes the `Signature` row.\n2. Deletes the matching `HasAccess` row.\n3. Soft-deletes any `DocumentRole` rows where `signer_user_id == removed_user_id`, with `delete_reason = 'signer_removed_via_correction'`.\n4. Sets `DocumentVariable.role_id = NULL` for every active variable tied to those roles — they fall back to *Sin asignar*.\n5. The BEFORE DELETE trigger `vc_0013` preserves `variable_chip` rows with `signature_id = NULL`.\n\n**Why cascade?** Integrators expect one DELETE to fully clean its dependents (Stripe/Plane style). A future `POST /add-signer` with the same `roleName` is free to create a fresh role.\n\n**Response**\n```json\n{\n \"success\": true,\n \"detail\": \"Firmante eliminado correctamente\",\n \"deletedRoleIds\": [\"\"],\n \"unassignedVariableNames\": [\"nombre_arrendador\"],\n \"vacatedRoleIds\": []\n}\n```\n`vacatedRoleIds` is kept as an empty array for backward compatibility with the Phase 8.1 shape.", "operationId": "remove_signer_correction_documents__document_id__signers__signature_id__delete", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "signature_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Signature Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Correction", "Correction" ], "summary": "Update signer attributes (currently: role assignment)", "description": "Updates a signer's role on the document. Works for signers added by email or by WhatsApp/phone — the role is matched primarily by the canonical `signer_user_id` link (with a legacy fallback to `contact_email` for roles that predate that field). If no role exists yet, a new one is created tied to the signer's user_id.", "operationId": "patch_signer_documents__document_id__signers__signature_id__patch", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "signature_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Signature Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchSignerRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchSignerResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/signature-fields": { "post": { "tags": [ "Signature Fields", "Signature Fields" ], "summary": "Add a signature field to a document", "description": "Add a signature field to a document.\n\nSupports both Bearer token and X-Service-Key authentication.", "operationId": "add_signature_field_v2_documents__document_id__signature_fields_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSignatureFieldRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureFieldResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Signature Fields", "Signature Fields" ], "summary": "Update a signature field in a document", "description": "Update position, page, or includeInAllPages for a signature field.\n\nSupports both Bearer token and X-Service-Key authentication.", "operationId": "update_signature_field_v2_documents__document_id__signature_fields_put", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSignatureFieldRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureFieldResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Signature Fields", "Signature Fields" ], "summary": "Delete a signature field from a document", "description": "Delete a signature field from a document.\n\nSupports both Bearer token and X-Service-Key authentication.", "operationId": "delete_signature_field_v2_documents__document_id__signature_fields_delete", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSignatureFieldRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureFieldResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/workflows/{workflow_id}/status": { "get": { "tags": [ "Document Progress", "Document Progress" ], "summary": "Get Document Creation Status (JSON)", "description": "Lightweight JSON endpoint for polling document creation progress.\n \n Use this if you prefer simple polling over SSE streaming.\n Poll every 2-5 seconds until `status` is `completed` or `failed`.\n \n ## Authentication\n - `Authorization: Bearer allsign_live_sk_xxx`\n\n ## Response Status Values\n - `processing` — Document is being created\n - `completed` — Document ready, `documentId` is set\n - `failed` — Processing failed, `error` is set", "operationId": "get_workflow_status_documents_workflows__workflow_id__status_get", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowStatusResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/workflows/{workflow_id}/progress": { "get": { "tags": [ "Document Progress", "Document Progress" ], "summary": "Stream Document Creation Progress (SSE)", "description": "Server-Sent Events endpoint for real-time document creation progress.\n \n Connect to this endpoint after receiving a 202 Accepted response from\n `POST /v2/documents?mode=async`.\n \n ## Authentication\n - `Authorization: Bearer allsign_live_sk_xxx`\n\n ## Event Types\n - **progress**: Processing step update with percentage\n - **complete**: Processing finished, includes final documentId\n - **error**: Processing failed\n \n ## Resumability\n On connect, checks both Redis stored state and Temporal workflow status\n to immediately send the current state — handles page refreshes and \n reconnections gracefully.", "operationId": "stream_document_progress_documents_workflows__workflow_id__progress_get", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "SSE event stream", "content": { "application/json": { "schema": {} }, "text/event-stream": {} } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/bulk": { "delete": { "tags": [ "Documents" ], "summary": "Bulk Delete Documents", "description": "Delete multiple documents at once. Requires `document:delete` scope. Returns per-document success/failure details. Maximum 100 documents per request. Documents that are fully signed or have signatures in progress will be skipped. Associated S3 files are cleaned up in the background.", "operationId": "bulk_delete_documents_documents_bulk_delete", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteRequestV2" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteResponseV2" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] } }, "/documents/{document_id}/detect-variables": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Detect variables in a DOCX document", "description": "Reads the DOCX source of a document and returns all `{{ variable }}` placeholders with their classification:\n\n- **role** — variable has a double-underscore prefix (e.g. `proveedor__nombre`). Will be auto-assigned to the signer role matching the prefix.\n- **sender** — prefix is `sender__`. Filled by the document owner at send time.\n- **unassigned** — plain variable name. Sender must decide who fills it (B6).\n\nReturns 422 if the document has no DOCX source (PDF-only document).", "operationId": "detect_variables_documents__document_id__detect_variables_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectVariablesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/assign-variables": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Assign variables to roles (sender configuration)", "description": "Persists the sender's variable-to-role assignment. Creates DocumentVariable rows that the signer will then fill via the onboarding-fill endpoints.\n\n**Idempotent**: re-calling with the same `variableName` + `roleId` updates the existing row (label, type, required, value) instead of creating a duplicate. The unique constraint uses NULLS NOT DISTINCT so sender-fixed variables also dedupe.\n\n**Sender-fixed variables**: pass `roleId=null` and a `value` to lock a value that the document owner provides up front (e.g. folio numbers).\n\nReturns the full list of assigned variables with each row's action ('created' or 'updated').", "operationId": "assign_variables_documents__document_id__assign_variables_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignVariablesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignVariablesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/content": { "get": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Get structured DOCX content (for chip viewer)", "description": "Returns the DOCX content as structured blocks (heading / paragraph / list_item / table). Each block's `text` may contain literal `{{ var }}` tokens — the dashboard splits on these to render inline variable chips. Resolves the DOCX from `source_docx_s3_key` first, falling back to `template_s3_key`. Returns 422 for PDF-only documents.", "operationId": "get_document_content_documents__document_id__content_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/chip-positions": { "get": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Get the visual position of every {{ var }} in the document's PDFs", "description": "Runs PyMuPDF text search for every active DocumentVariable across the document's PDFs. Returns positions as % of page dimensions (same coord system as DocumentField), so the frontend can render chip overlays on top of the PDF canvas. A variable that doesn't appear literally in the PDF (e.g. because its value was already filled during the create-from-template flow) returns `positions: []`.", "operationId": "get_chip_positions_documents__document_id__chip_positions_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChipPositionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/roles": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Create a DocumentRole (Capa 4: roles first-class)", "description": "Creates a DocumentRole for the given document with `contact_email = NULL`.\n\n**Idempotent**: case-insensitive name match returns the existing role instead of creating a duplicate (UNIQUE INDEX vc_0010).\n\n**Use case**: define roles before inviting signers so variables can be assigned to a role and chips can be placed without a signer attached.\n\nWhen a signer is later invited with `roleName=`, the workflow links them by name and propagates `signature_id` to all variable_chip rows tied to this role.", "operationId": "create_role_documents__document_id__roles_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/roles/{role_id}": { "patch": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Update a DocumentRole (rename, kind, color, contactEmail)", "description": "Partial update of a DocumentRole. Only the fields present in the body are changed.\n\n**Rename**: validated against the case-insensitive UNIQUE per (document, name, scope) — renaming to an existing active role's name returns **409** with a clear message.\n\n**contactEmail**: updating it does NOT re-send invitations.\n\nRenaming is allowed while signers are filling (LLENANDO_DATOS): fill sessions reference the role by id, not by name.", "operationId": "patch_role_documents__document_id__roles__role_id__patch", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "role_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Role Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchRoleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchRoleResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/variables": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Create a DocumentVariable manually (Track A)", "description": "Creates a single DocumentVariable for the given document. Used by the sender UI to add custom fields on PDF-only docs (where B5 returns nothing because there's no DOCX to scan), or to add ad-hoc fields to DOCX-sourced docs.\n\n**Idempotent** by `(document_id, variable_name, role_id, scope_pdf_id)`. If a row already exists, returns it with `action='existing'`.\n\n**roleName upsert**: pass `roleName` instead of `roleId` to upsert a DocumentRole on the fly (Capa 4 link-by-name).\n\n**createChip** (default true): also creates a `DocumentField` with type='variable_chip' at default canvas position. Set to false when the variable is form-only (no visible chip in the document).", "operationId": "create_variable_documents__document_id__variables_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVariableRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedVariable" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/regenerate-pdf": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Regenerate the document PDF with current variable values (wizard transition)", "description": "Renders the document's source DOCX with the current DocumentVariable values inlined and returns a presigned URL.\n\nUsed by the editor wizard when the sender transitions from paso ① (Datos) to paso ② (Firmas) so the canvas reflects the document as it will be sent.\n\n**Cached** by SHA-256 of (template_version_hash + sorted variable values). Re-calling with the same values returns the cached PDF instantly (no LibreOffice re-render). Frontend can lazy-preload.", "operationId": "regenerate_pdf_documents__document_id__regenerate_pdf_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegeneratePdfResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/pdf-hash": { "get": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Poll current pdf_hash for every active document_pdf row", "description": "Returns the current `pdf_hash` + `updatedAt` of every active `document_pdf` row. Used by polling UIs to detect when the `MaterializeDocumentPdfWorkflow` has finished re-rendering after the doc transitions LLENANDO_DATOS → ESPERANDO_FIRMAS.\n\nCheap (no bytes, no S3 download). Frontend should stop polling after 30s or once the hash is stable for two consecutive calls.", "operationId": "get_pdf_hash_documents__document_id__pdf_hash_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfHashResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/signers/{signature_id}/remind": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Send a manual reminder to a single signer (S3)", "description": "Re-delivers the invitation email/whatsapp to the specified Signature. Rate-limited to once every 4 hours per signer.\n\n**429** — last reminder was less than 4 hours ago. Response carries `nextAllowedAt` so the caller can disable the UI button.\n\n**422** — signer is in a terminal state (SIGNED, DECLINED, EXPIRED, REVOKED) and can't be reminded.\n\n**404** — document/signer not found or wrong tenant.", "operationId": "remind_signer_documents__document_id__signers__signature_id__remind_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "signature_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Signature Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemindResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/my-fill-info": { "get": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Fetch the variables assigned to the calling owner-signer", "operationId": "my_fill_info_documents__document_id__my_fill_info_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerFillInfoResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/my-fill-progress": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Partial save of owner-signer's variable values (no state transition)", "operationId": "my_fill_progress_documents__document_id__my_fill_progress_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerFillProgressRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerFillProgressResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/my-fill-submit": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Final submit of owner-signer's variables, transitions signature_state", "operationId": "my_fill_submit_documents__document_id__my_fill_submit_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerFillProgressRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerFillSubmitResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/my-fill-step/ensure": { "post": { "tags": [ "Variable Fill", "Variable Fill" ], "summary": "Ensure the authed signer has a fill_variables VerificationStep (Phase 10)", "description": "Idempotent. Returns the existing VerificationStep for the authed signer if one exists, or creates one when the signer has unfilled variables assigned to their DocumentRole.\n\nThe dashboard calls this on mount of /documents//awaiting so the owner-as-filler flow goes through the same VerificationPipeline as the guest signer flow.\n\nFeature-flagged via OWNER_FILL_STEP_ENABLED env var. When disabled returns `{ step: null, reason: 'feature_disabled' }` — clients should fallback to the legacy OwnerFillSection adapter.", "operationId": "ensure_my_fill_step_documents__document_id__my_fill_step_ensure_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyFillStepResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_id}/evidence": { "get": { "tags": [ "Documents", "Documents" ], "summary": "Get presigned URLs for the signed evidence PDF and NOM-151 constancia", "description": "Returns presigned download URLs (TTL 24 h) for:\n\n- **evidence_pdf** — sealed PDF with all signatures and full audit trail.\n- **nom_151** — NOM-151 constancia de conservación (timestamp + hash chain).\n\nBoth fields are `null` until every signer has completed. Poll `available` to know when the evidence is ready — the Temporal workflow may take a few seconds after the last signature.", "operationId": "get_document_evidence_documents__document_id__evidence_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentEvidenceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/folders": { "get": { "tags": [ "Folders" ], "summary": "List Folders in Tree Structure", "description": "Get folders in hierarchical tree structure.\n\n ## Tenant-aware behavior\n Folder visibility is determined automatically by the user's tenant membership:\n - **Tenant member (owner/admin)**: sees ALL folders belonging to their tenant.\n - **Tenant member (member/developer/viewer)**: sees tenant folders that contain\n documents they have access to (`has_access`).\n - **No tenant membership**: sees personal folders (`owner_id = user`).\n\n No extra parameters are needed — the server resolves the user's membership\n and role from the API key / X-User-Id header.\n\n Each folder in the response now includes a `tenantId` field (null for personal folders).\n\n ## Authentication Modes\n - **User API Key** (legacy): `Authorization: Bearer allsign_user_sk_xxx`\n - **App API Key + X-User-Id** (multi-tenant apps):\n ```\n Authorization: Bearer allsign_live_sk_xxx\n X-User-Id: 550e8400-e29b-41d4-a716-446655440000\n ```\n\n ## Response Structure\n Returns a tree where each folder can have `subfolders` array.\n Root-level folders have `parentId: null`.", "operationId": "get_folders_tree_endpoint_folders_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DocumentScopeEnum", "description": "Document scope: owner (default), org, tenant, or accessible", "default": "owner" }, "description": "Document scope: owner (default), org, tenant, or accessible" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Folders" ], "summary": "Create Folder", "description": "Create a new folder.\n\n If the user is a tenant member, the folder is automatically assigned to\n their tenant (`tenantId` in response). Viewers cannot create folders.\n\n ## Parameters\n - `name`: Folder name (1-255 characters)\n - `parentId`: Parent folder ID (optional, null = root level)\n\n ## Returns\n Created folder details with `hasDocs: false`", "operationId": "create_folder_endpoint_folders_post", "security": [ { "Bearer Token": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderV2Response" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/folders/{folder_id}": { "get": { "tags": [ "Folders" ], "summary": "Get Folder by ID", "description": "Get details of a single folder.\n\n Returns 404 if:\n - Folder doesn't exist\n - User doesn't have access (not in same tenant, or not the owner for personal folders)", "operationId": "get_folder_endpoint_folders__folder_id__get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Folder Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderV2Response" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Folders" ], "summary": "Rename or Move Folder", "description": "Update folder name and/or parent.\n\n ## Permissions\n - **owner/admin**: can rename or move any folder in the tenant.\n - **member/developer**: can only rename folders they created.\n - **viewer**: cannot update folders (403).\n\n ## Validation\n - Cannot move folder into itself\n - Cannot move folder into its descendants\n - Parent must exist\n\n Returns 400 if circular reference detected.", "operationId": "update_folder_endpoint_folders__folder_id__patch", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Folder Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderV2Response" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Folders" ], "summary": "Delete Folder", "description": "Delete a folder. Operation fails if the folder contains documents or subfolders.\n\n ## Permissions\n - **owner/admin**: can delete any folder in the tenant.\n - **member/developer**: can only delete folders they created.\n - **viewer**: cannot delete folders (403).", "operationId": "delete_folder_endpoint_folders__folder_id__delete", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Folder Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/folders/{folder_id}/documents": { "get": { "tags": [ "Folders" ], "summary": "Get Documents in Folder", "description": "Get all documents in a specific folder.\n \n This is an alias/convenience endpoint for:\n `GET /v2/documents?folderId={folder_id}`\n \n Supports pagination and all document filters.", "operationId": "get_folder_documents_endpoint_folders__folder_id__documents_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Folder Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Page number", "title": "Page" }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page", "default": 10, "title": "Limit" }, "description": "Items per page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListV2Response" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/users/me": { "get": { "tags": [ "Users" ], "summary": "Get current user profile", "description": "Returns basic metadata for the authenticated user (dual-mode auth supported). When impersonating via X-User-Id, the target user must belong to the same tenant as the API key owner.", "operationId": "get_current_user_profile_users_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileV2Response" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] } }, "/users/team": { "get": { "tags": [ "Users" ], "summary": "List Team Members", "description": "# List all members of your tenant (workspace)\n\n Returns the team members that belong to the same tenant as the authenticated user.\n Useful for obtaining user IDs to filter documents with `createdBy` on `GET /v2/documents`.\n\n ## Permissions\n - Requires **admin** or **owner** role within the tenant.\n\n ## Example\n\n ```bash\n curl -X GET \"https://api.allsign.io/v2/users/team\" \\\n -H \"Authorization: Bearer allsign_live_sk_xxx\"\n ```\n\n ## Use with documents filter\n\n ```bash\n # 1. List your team members\n GET /v2/users/team\n\n # 2. Use a member's ID to filter documents\n GET /v2/documents?scope=accessible&createdBy={memberId}\n ```", "operationId": "list_team_members_users_team_get", "responses": { "200": { "description": "Team members listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamListResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Requires admin/owner role" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] } }, "/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "Paginated list of contacts for the authenticated tenant. Supports search by name/email, filtering by tag, verification status, and source.", "operationId": "list_contacts_endpoint_contacts_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Pagesize" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search by name, email, or company", "title": "Search" }, "description": "Search by name, email, or company" }, { "name": "tag", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by tag", "title": "Tag" }, "description": "Filter by tag" }, { "name": "verified", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by identity verified", "title": "Verified" }, "description": "Filter by identity verified" }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by source: manual, api, invitation, onboarding", "title": "Source" }, "description": "Filter by source: manual, api, invitation, onboarding" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "description": "Create a new contact. If a user with this email already exists, a profile is linked to them.", "operationId": "create_contact_endpoint_contacts_post", "security": [ { "Bearer Token": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/contacts/autocomplete": { "get": { "tags": [ "Contacts" ], "summary": "Autocomplete contacts", "description": "Lightweight typeahead: returns up to 5 contacts matching the query.", "operationId": "autocomplete_contacts_endpoint_contacts_autocomplete_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "description": "Search query (min 2 chars)", "default": "", "title": "Q" }, "description": "Search query (min 2 chars)" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "description": "Field context: email | phone | any", "default": "any", "title": "Mode" }, "description": "Field context: email | phone | any" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/contacts/{contact_id}": { "get": { "tags": [ "Contacts" ], "summary": "Get contact detail", "description": "Full contact profile including linked documents and verification status.", "operationId": "get_contact_endpoint_contacts__contact_id__get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Update CRM fields (company, job title, notes, tags) on a contact profile.", "operationId": "update_contact_endpoint_contacts__contact_id__put", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact profile", "description": "Removes the CRM profile. The underlying user account is NOT deleted.", "operationId": "delete_contact_endpoint_contacts__contact_id__delete", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/contacts/bulk": { "post": { "tags": [ "Contacts" ], "summary": "Bulk create contacts", "description": "Create up to 100 contacts in a single request. Each item is processed independently — failures do NOT abort the batch. Response contains per-item success/failure details so clients can surface row-level errors in their import UI. Existing profiles (same email under the tenant) are returned as `success=true` with the existing `contactId`.", "operationId": "bulk_create_endpoint_contacts_bulk_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBulkCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBulkResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] }, "delete": { "tags": [ "Contacts" ], "summary": "Bulk delete contacts", "description": "Delete up to 100 contact profiles. Per-item tenant isolation (a contact from another tenant reports `Contact not found`). The underlying User rows are NOT deleted — only the CRM profile, matching the behaviour of `DELETE /v2/contacts/{id}`.", "operationId": "bulk_delete_endpoint_contacts_bulk_delete", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBulkDeleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBulkResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] }, "patch": { "tags": [ "Contacts" ], "summary": "Bulk update contacts", "description": "Partial update of up to 100 contacts. Each item requires an `id`. Per-item semantics are identical to `PUT /v2/contacts/{id}` — only the keys present in the item are touched. Failures are captured per item.", "operationId": "bulk_update_endpoint_contacts_bulk_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBulkUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBulkResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] } }, "/contacts/{contact_id}/custom-fields": { "patch": { "tags": [ "Contacts" ], "summary": "Patch contact custom fields", "description": "Atomic add/update/remove operation on ContactProfile.custom_fields. Prefer this over PUT /contacts/{id} with customFields when you only need to change a handful of keys — it is race-safe (a concurrent client touching different keys no longer clobbers yours) and supports bulk-delete in a single round-trip.\n\nExample — delete 3 fields + rename one:\n```json\n{\n \"set\": { \"RFC\": \"NEW123\" },\n \"remove\": [\"OldRFC\", \"TempNote\", \"LegacyKey\"]\n}\n```", "operationId": "patch_custom_fields_endpoint_contacts__contact_id__custom_fields_patch", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldsPatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/contacts/{contact_id}/documents": { "get": { "tags": [ "Contacts" ], "summary": "List documents for a contact", "description": "All documents where this contact is a signer.", "operationId": "list_contact_documents_endpoint_contacts__contact_id__documents_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/backfill-roles": { "post": { "tags": [ "DOCX Templates" ], "summary": "Backfill Variable Roles (all templates)", "description": "Re-run role inference on ALL active templates. Adds the 'role' field to variable_config.", "operationId": "backfill_roles_endpoint_templates_backfill_roles_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] } }, "/templates": { "post": { "tags": [ "DOCX Templates" ], "summary": "Upload Template", "description": "# Upload a Word (.docx) template\n\n Upload a `.docx` file containing Jinja2-style placeholders (`{{ variable_name }}`).\n The system will:\n\n 1. **Validate** the file is a valid DOCX\n 2. **Auto-detect** all `{{ }}` variables in the document\n 3. **Infer** variable types (text, date, currency, etc.) from names\n 4. **Store** the original file in S3 for later reuse\n 5. **Return** the list of detected variables with rich metadata\n\n ## Accepted formats\n - `.docx` files — full variable detection and AI editing support\n\n > PDFs cannot be used as templates because they don't support `{{ }}` variable injection.\n > To send a PDF for signing, create a document directly via `POST /v2/documents`.", "operationId": "upload_docx_template_templates_post", "security": [ { "Bearer Token": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_docx_template_templates_post" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocxTemplateUploadResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "DOCX Templates" ], "summary": "List Templates", "description": "List all active templates for the authenticated user or organization. Supports filtering by file type, tags, category, and text search.", "operationId": "list_docx_templates_templates_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "fileType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by 'docx' or 'pdf'", "title": "Filetype" }, "description": "Filter by 'docx' or 'pdf'" }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated tags filter", "title": "Tags" }, "description": "Comma-separated tags filter" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search by name or description", "title": "Q" }, "description": "Search by name or description" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocxTemplateListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}": { "get": { "tags": [ "DOCX Templates" ], "summary": "Get Template Detail", "description": "Get full template detail including variable configuration and test data sets.", "operationId": "get_template_detail_templates__template_id__get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocxTemplateDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "DOCX Templates" ], "summary": "Update Template", "description": "Update template metadata (name, description, tags, category, AI editable, variable config).", "operationId": "update_docx_template_templates__template_id__patch", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocxTemplateUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocxTemplateDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "DOCX Templates" ], "summary": "Delete Template", "description": "Delete a template. By default this is a soft-delete (marks the template inactive while preserving the S3 file for audit). Pass `?hard=true` to permanently remove the row and its underlying S3 object. The deletion is refused with 409 Conflict if any active document or chain still references this template — archive or complete those first.", "operationId": "delete_docx_template_templates__template_id__delete", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } }, { "name": "hard", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true, permanently delete the row and S3 object", "default": false, "title": "Hard" }, "description": "If true, permanently delete the row and S3 object" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocxTemplateDeleteResponse" } } } }, "404": { "description": "Template not found" }, "403": { "description": "Caller does not own the template" }, "409": { "description": "Template is in use by documents or chains" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/variables": { "get": { "tags": [ "DOCX Templates" ], "summary": "Get Template Variables", "description": "Returns the auto-detected Jinja2 variables for a template.\n\n Each variable includes:\n - `name`: The variable name as written in the DOCX (e.g., `nombre_cliente`)\n - `label`: A human-readable label (e.g., `Nombre Cliente`)\n - `type`: Inferred variable type (text, date, currency, textarea, number)\n - `required`: Whether the variable is required\n - `defaultValue`: Optional default value\n\n Use these to build a dynamic form in the frontend.", "operationId": "get_template_variables_templates__template_id__variables_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocxTemplateVariablesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/duplicate": { "post": { "tags": [ "DOCX Templates" ], "summary": "Duplicate Template", "description": "Create a copy of an existing template, including its S3 file and all metadata.", "operationId": "duplicate_docx_template_templates__template_id__duplicate_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocxTemplateUploadResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/recompute-roles": { "post": { "tags": [ "DOCX Templates" ], "summary": "Recompute Variable Roles", "description": "Re-run role inference on the template's variable_config. Useful for templates uploaded before role detection was added.", "operationId": "recompute_roles_endpoint_templates__template_id__recompute_roles_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/create-document": { "post": { "tags": [ "DOCX Templates" ], "summary": "Create Document from Template", "description": "# Create a document by filling a pre-saved DOCX template\n\n This endpoint:\n 1. Downloads the original DOCX template from S3\n 2. Replaces all `{{ variable }}` placeholders with provided values\n 3. Converts the result to PDF\n 4. Creates a full document (same as `POST /v2/documents`)\n 5. Increments usage count on the template\n\n ## Example\n\n ```json\n {\n \"templateId\": \"uuid-of-template\",\n \"values\": {\n \"nombre_arrendador\": \"Pedro Páramo\",\n \"nombre_arrendatario\": \"Juan Preciado\",\n \"monto_renta\": \"$15,000.00 MXN\"\n },\n \"participants\": [...],\n \"signatureValidation\": { \"autografa\": true },\n \"config\": { \"sendInvitations\": false }\n }\n ```", "operationId": "create_document_from_template_templates__template_id__create_document_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentFromTemplateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/test-data-sets": { "get": { "tags": [ "DOCX Templates" ], "summary": "List Test Data Sets", "description": "List predefined test data sets for previewing template variables.", "operationId": "list_template_test_data_sets_templates__template_id__test_data_sets_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TestDataSetResponse" }, "title": "Response List Template Test Data Sets Templates Template Id Test Data Sets Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "DOCX Templates" ], "summary": "Create Test Data Set", "description": "Create a predefined set of variable values for quick template preview.", "operationId": "create_template_test_data_set_templates__template_id__test_data_sets_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDataSetCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDataSetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/test-data-sets/{data_set_id}": { "delete": { "tags": [ "DOCX Templates" ], "summary": "Delete Test Data Set", "description": "Delete a test data set.", "operationId": "delete_template_test_data_set_templates__template_id__test_data_sets__data_set_id__delete", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } }, { "name": "data_set_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Data Set Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/ai-edit": { "post": { "tags": [ "DOCX Templates" ], "summary": "AI Edit Template", "description": "# Edit a DOCX template using AI\n\n Sends the template content to an LLM with your editing instructions.\n The AI will modify the document text while preserving all `{{ variables }}`.\n\n ## Edit Types\n - `full` — Edit the entire document\n - `selection` — Edit only the selected text (requires `selectionText`)\n - `clause` — Add or modify a legal clause\n - `tone` — Adjust formality/tone\n\n ## Flow\n 1. Creates a version snapshot (for undo)\n 2. Extracts document text\n 3. Sends prompt + document to LLM\n 4. Applies text replacements\n 5. Re-detects variables\n 6. Uploads new DOCX to S3\n 7. Records edit history\n\n ## Example\n ```json\n {\n \"prompt\": \"Hazlo más formal y agrega cláusula de confidencialidad\",\n \"editType\": \"full\",\n \"model\": \"gpt-4o\"\n }\n ```", "operationId": "ai_edit_docx_template_templates__template_id__ai_edit_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEditRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEditResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/versions": { "get": { "tags": [ "DOCX Templates" ], "summary": "List Template Versions", "description": "List all version snapshots for a template, newest first. Each version is an immutable snapshot of the DOCX at a point in time.", "operationId": "list_template_versions_templates__template_id__versions_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVersionResponse" }, "title": "Response List Template Versions Templates Template Id Versions Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/edit-history": { "get": { "tags": [ "DOCX Templates" ], "summary": "List AI Edit History", "description": "List all AI editing operations performed on a template, newest first. Includes prompts, model info, token usage, and change summaries.", "operationId": "list_template_edit_history_templates__template_id__edit_history_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateEditHistoryResponse" }, "title": "Response List Template Edit History Templates Template Id Edit History Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/rollback": { "post": { "tags": [ "DOCX Templates" ], "summary": "Rollback Template", "description": "Rollback a template to a previous version. This restores the DOCX, variables, and variable config from the target version.", "operationId": "rollback_docx_template_templates__template_id__rollback_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/download": { "get": { "tags": [ "DOCX Templates" ], "summary": "Download Template", "description": "Get a presigned S3 URL to download the original DOCX/PDF template file. The URL is valid for 1 hour.", "operationId": "download_template_templates__template_id__download_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/preview": { "post": { "tags": [ "DOCX Templates" ], "summary": "Preview Template", "description": "# Preview a template with filled variables\n\n Fill the template's `{{ variables }}` with provided values and return\n the rendered document as a base64-encoded PDF. This does NOT create\n a formal document or consume credits — it's purely for preview.\n\n ## Example\n ```json\n {\n \"values\": {\n \"nombre_arrendador\": \"Pedro Páramo\",\n \"monto_renta\": \"$15,000.00 MXN\"\n }\n }\n ```", "operationId": "preview_template_templates__template_id__preview_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/content": { "get": { "tags": [ "DOCX Templates" ], "summary": "Get Template Content", "description": "# Extract text content from a DOCX template\n\n Returns the document's text content in two formats:\n - `text`: Plain text with paragraph breaks\n - `blocks`: Structured content blocks with type info (heading, paragraph, table, list_item)\n\n Used by the frontend AI editor to display the document and allow selection-based editing.", "operationId": "get_template_content_templates__template_id__content_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/templates/{template_id}/autofill-suggestion": { "get": { "tags": [ "DOCX Templates" ], "summary": "Autofill Suggestion from Contact", "description": "# Smart autofill: match template variables to contact data\n\n Given a template and a contact, this endpoint returns a suggested mapping\n of template variable names → contact values, using fuzzy key matching.\n\n ## How matching works\n\n 1. Builds a pool of available contact data (standard fields + custom_fields)\n 2. For each template variable, finds the best fuzzy match from the pool\n 3. Returns only matches above 60% similarity threshold\n\n ## Example response\n\n ```json\n {\n \"suggestions\": {\n \"nombre_cliente\": \"Pedro Páramo\",\n \"rfc_cliente\": \"XAXX010101000\",\n \"empresa\": \"Acme Corp\"\n },\n \"unmatched\": [\"monto_renta\", \"fecha_inicio\"],\n \"contactName\": \"Pedro Páramo\"\n }\n ```", "operationId": "autofill_from_contact_templates__template_id__autofill_suggestion_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } }, { "name": "contactId", "in": "query", "required": true, "schema": { "type": "string", "description": "Contact profile UUID", "title": "Contactid" }, "description": "Contact profile UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/onboarding-sessions": { "post": { "tags": [ "Onboarding Fill Sessions" ], "summary": "Create Session Endpoint", "description": "Create an onboarding fill session.\n\n**type=contact**: Invite an external contact to fill document variables.\n**type=member**: Invite a new member to fill variables + join workspace.", "operationId": "create_session_endpoint_onboarding_sessions_post", "security": [ { "Bearer Token": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingFillSessionCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingFillSessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Onboarding Fill Sessions" ], "summary": "List Sessions Endpoint", "description": "List onboarding fill sessions with pagination and filters.", "operationId": "list_sessions_endpoint_onboarding_sessions_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Pagesize" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "name": "contactEmail", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactemail" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingFillSessionListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/onboarding-sessions/{session_id}": { "get": { "tags": [ "Onboarding Fill Sessions" ], "summary": "Get Session Endpoint", "description": "Get a single onboarding fill session by ID.", "operationId": "get_session_endpoint_onboarding_sessions__session_id__get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingFillSessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Onboarding Fill Sessions" ], "summary": "Cancel Session Endpoint", "description": "Cancel an onboarding fill session.", "operationId": "cancel_session_endpoint_onboarding_sessions__session_id__delete", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/onboarding-sessions/{session_id}/resend": { "post": { "tags": [ "Onboarding Fill Sessions" ], "summary": "Resend Invitation Endpoint", "description": "Resend the invitation with a fresh token.", "operationId": "resend_invitation_endpoint_onboarding_sessions__session_id__resend_post", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendOnboardingFillResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/kpis": { "get": { "tags": [ "Analytics" ], "summary": "Get KPI Metrics", "description": "Returns the main key performance indicators for your tenant:\n - Total documents\n - Completed / pending / expired counts\n - Completion rate (%)\n - Average signing time (hours)\n \n **Credits:** 1 credit per request.", "operationId": "analytics_kpis_analytics_kpis_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(7d|30d|90d|12m)$", "description": "Time period", "default": "30d", "title": "Period" }, "description": "Time period" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsKPIsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/funnel": { "get": { "tags": [ "Analytics" ], "summary": "Get Signing Funnel", "description": "Returns the signing funnel stages with document counts and percentages:\n Enviados → En progreso → Completados → Expirados.\n \n **Credits:** 1 credit per request.", "operationId": "analytics_funnel_analytics_funnel_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(7d|30d|90d|12m)$", "description": "Time period", "default": "30d", "title": "Period" }, "description": "Time period" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FunnelStepResponse" }, "title": "Response Analytics Funnel Analytics Funnel Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/trend": { "get": { "tags": [ "Analytics" ], "summary": "Get Monthly Trend", "description": "Returns signed document count and average signing time per month\n for the last 6 months.\n \n **Credits:** 1 credit per request.", "operationId": "analytics_trend_analytics_trend_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MonthlyTrendResponse" }, "type": "array", "title": "Response Analytics Trend Analytics Trend Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "Bearer Token": [] } ] } }, "/analytics/events": { "get": { "tags": [ "Analytics" ], "summary": "Get Recent Events", "description": "Returns the most recent user-facing document events across the tenant.\n Internal events (S3, PDF processing, evidence generation) are excluded.\n \n **Credits:** 1 credit per request.", "operationId": "analytics_events_analytics_events_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Max events to return", "default": 8, "title": "Limit" }, "description": "Max events to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecentEventResponse" }, "title": "Response Analytics Events Analytics Events Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/bottlenecks": { "get": { "tags": [ "Analytics" ], "summary": "Get Signing Bottlenecks", "description": "Returns the signers with the most pending signatures and the\n average number of days they have been pending.\n \n **Credits:** 1 credit per request.", "operationId": "analytics_bottlenecks_analytics_bottlenecks_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 1, "description": "Max bottleneck entries", "default": 5, "title": "Limit" }, "description": "Max bottleneck entries" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BottleneckResponse" }, "title": "Response Analytics Bottlenecks Analytics Bottlenecks Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/team": { "get": { "tags": [ "Analytics" ], "summary": "Get Team Activity", "description": "Returns per-member stats for the tenant:\n - Documents sent\n - Documents fully signed\n - Completion rate (%)\n \n **Credits:** 1 credit per request.", "operationId": "analytics_team_analytics_team_get", "security": [ { "Bearer Token": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(7d|30d|90d|12m)$", "description": "Time period", "default": "30d", "title": "Period" }, "description": "Time period" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMemberActivityResponse" }, "title": "Response Analytics Team Analytics Team Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/events": { "get": { "tags": [ "webhooks", "webhooks" ], "summary": "List available webhook event types", "description": "Returns the canonical catalog of webhook event types the platform can emit.", "operationId": "list_webhook_events_webhooks_events_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventCatalogResponse" } } } } } } } }, "components": { "schemas": { "AIEditChangeDetail": { "properties": { "section": { "type": "string", "title": "Section", "description": "Section/clause affected" }, "before": { "type": "string", "title": "Before", "description": "Original text" }, "after": { "type": "string", "title": "After", "description": "Modified text" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Reason for the change" } }, "type": "object", "required": [ "section", "before", "after" ], "title": "AIEditChangeDetail", "description": "A single change made by the AI." }, "AIEditRequest": { "properties": { "prompt": { "type": "string", "maxLength": 2000, "minLength": 3, "title": "Prompt", "description": "Instruction for the AI (e.g., 'Hazlo más formal', 'Agrega cláusula de confidencialidad')" }, "editType": { "type": "string", "title": "Edittype", "description": "Edit scope: 'full' (entire doc), 'selection' (specific text), 'clause' (add/modify clause), 'tone' (adjust formality)", "default": "full" }, "selectionText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Selectiontext", "description": "Selected text to edit (required when editType='selection')" }, "model": { "type": "string", "title": "Model", "description": "LLM model to use (gpt-4o, gpt-4o-mini)", "default": "gpt-4o" } }, "type": "object", "required": [ "prompt" ], "title": "AIEditRequest", "description": "Request for AI-assisted template editing." }, "AIEditResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true }, "editId": { "type": "string", "title": "Editid", "description": "Edit history record UUID" }, "summary": { "type": "string", "title": "Summary", "description": "AI summary of changes (in Spanish)" }, "changes": { "items": { "$ref": "#/components/schemas/AIEditChangeDetail" }, "type": "array", "title": "Changes", "description": "List of before/after changes" }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings", "description": "Legal warnings from the AI" }, "versionBefore": { "type": "integer", "title": "Versionbefore", "description": "Version before edit" }, "versionAfter": { "type": "integer", "title": "Versionafter", "description": "Version after edit" }, "modelUsed": { "type": "string", "title": "Modelused" }, "tokensUsed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokensused", "description": "Total tokens consumed" }, "latencyMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latencyms" } }, "type": "object", "required": [ "editId", "summary", "versionBefore", "versionAfter", "modelUsed" ], "title": "AIEditResponse", "description": "Response from AI editing, including diff and version info." }, "AddSignatureFieldRequest": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "ID of the signature field" }, "signerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signeremail", "description": "Email of the signer (optional if signerPhone provided)" }, "signerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signerphone", "description": "WhatsApp phone of the signer (must start with +). Optional if signerEmail provided." }, "x": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "X", "description": "X coordinate of the signature field" }, "y": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Y", "description": "Y coordinate of the signature field" }, "pageNumber": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pagenumber", "description": "Page number (1-based) where the field is placed. Required for coordinate placement (x/y). For anchorString placement it is OPTIONAL: omit it to search the whole document (one field per occurrence), or provide it to scope the search to a single page." }, "width": { "type": "number", "title": "Width", "description": "Width of the signature field", "default": 200 }, "height": { "type": "number", "title": "Height", "description": "Height of the signature field", "default": 100 }, "anchorString": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Anchorstring", "description": "Text anchor to search for in the PDF to position the signature field" }, "includeInAllPages": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Includeinallpages", "description": "Whether the signature field should be included in all pages", "default": false }, "excludeFromPages": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Excludefrompages", "description": "If includeInAllPages=True, exclude these page numbers" }, "totalPages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Totalpages", "description": "Total number of pages in the PDF (required when includeInAllPages=True)" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "Type of the field", "default": "signatureField" }, "documentPdfId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documentpdfid", "description": "Compound documents (compound_0009): UUID of the document_pdf row this field is anchored to. Optional — when omitted, the service resolves it server-side to the first (or only) PDF of the document, preserving 100% backward compatibility for single-PDF callers. Required to be sent explicitly only by clients that place fields on PDFs other than position=1 in a compound expediente." } }, "type": "object", "title": "AddSignatureFieldRequest", "description": "Request model for adding a single signature field to a document.\nAt least one of signerEmail or signerPhone must be provided." }, "AddSignerRequest": { "properties": { "signerEmail": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ], "title": "Signeremail", "description": "The email of the signer to add (optional if signerPhone provided)." }, "signerPhone": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Signerphone", "description": "The WhatsApp phone number of the signer (must start with +). Optional if signerEmail provided." }, "signerName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Signername", "description": "Display name of the signer." }, "invitedByEmail": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ], "title": "Invitedbyemail", "description": "The email of the user adding the signer. Optional — defaults to the API key owner." }, "roleName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Rolename", "description": "Semantic role for variable fill (e.g. 'proveedor'). Matches template syntax {{ role:proveedor/... }}. Optional." }, "variableNames": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 500 }, { "type": "null" } ], "title": "Variablenames", "description": "B5-detected variable names known by the dashboard. When provided, the endpoint upserts DocumentVariable records for any missing names before running the auto-link heuristic — bridges the B5→B6 gap for documents where B6 (assign-variables) has not run yet. Same pattern as PATCH /signers/{id}." } }, "type": "object", "title": "AddSignerRequest" }, "AddSignerResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "message": { "type": "string", "title": "Message" }, "signatureId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signatureid" }, "signerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signerid" }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid" }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolename" }, "roleContactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolecontactemail" }, "autoAssignedVariables": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Autoassignedvariables" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hint" } }, "type": "object", "required": [ "success", "message" ], "title": "AddSignerResponse" }, "AnalyticsKPIsResponse": { "properties": { "totalDocs": { "type": "integer", "title": "Totaldocs", "description": "Total documents in period" }, "completed": { "type": "integer", "title": "Completed", "description": "Documents fully signed" }, "pending": { "type": "integer", "title": "Pending", "description": "Documents awaiting signatures" }, "expired": { "type": "integer", "title": "Expired", "description": "Expired documents" }, "completionRate": { "type": "number", "title": "Completionrate", "description": "Completion percentage (0-100)" }, "avgSignTimeHours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avgsigntimehours", "description": "Average time to fully sign (hours)" } }, "type": "object", "required": [ "totalDocs", "completed", "pending", "expired", "completionRate" ], "title": "AnalyticsKPIsResponse", "description": "Key performance indicators for a tenant's signing activity." }, "AssignVariablesRequest": { "properties": { "assignments": { "items": { "$ref": "#/components/schemas/VariableAssignment" }, "type": "array", "minItems": 1, "title": "Assignments", "description": "List of variable assignments. Each row creates/updates one DocumentVariable." } }, "type": "object", "required": [ "assignments" ], "title": "AssignVariablesRequest" }, "AssignVariablesResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "created": { "type": "integer", "title": "Created" }, "updated": { "type": "integer", "title": "Updated" }, "total": { "type": "integer", "title": "Total" }, "chipsCreated": { "type": "integer", "title": "Chipscreated", "description": "DocumentField rows created with type='variable_chip'", "default": 0 }, "variables": { "items": { "$ref": "#/components/schemas/AssignedVariable" }, "type": "array", "title": "Variables" }, "chipWarnings": { "items": { "$ref": "#/components/schemas/ChipWarning" }, "type": "array", "title": "Chipwarnings", "description": "Variables whose chip could not be auto-positioned (placeholder not found → default-centered chip) or whose chip upsert failed. The variable row itself persisted fine." } }, "type": "object", "required": [ "documentId", "created", "updated", "total", "variables" ], "title": "AssignVariablesResponse" }, "AssignedVariable": { "properties": { "id": { "type": "string", "title": "Id" }, "variableName": { "type": "string", "title": "Variablename" }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "type": { "type": "string", "title": "Type" }, "required": { "type": "boolean", "title": "Required" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" }, "action": { "type": "string", "enum": [ "created", "updated" ], "title": "Action" } }, "type": "object", "required": [ "id", "variableName", "type", "required", "action" ], "title": "AssignedVariable" }, "Body_upload_docx_template_templates_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "The .docx template file" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Display name for the template" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Optional description" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tags", "description": "Comma-separated tags (e.g. 'legal,nda,ventas')" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Template category" }, "aiEditable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Aieditable", "description": "Enable AI editing", "default": true } }, "type": "object", "required": [ "file", "name" ], "title": "Body_upload_docx_template_templates_post" }, "BottleneckResponse": { "properties": { "signerName": { "type": "string", "title": "Signername" }, "signerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signeremail" }, "pendingCount": { "type": "integer", "title": "Pendingcount" }, "avgDays": { "type": "number", "title": "Avgdays", "description": "Avg days pending" } }, "type": "object", "required": [ "signerName", "pendingCount", "avgDays" ], "title": "BottleneckResponse", "description": "A signer with the most pending signatures." }, "BulkDeleteRequestV2": { "properties": { "documentIds": { "items": { "type": "string" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Documentids", "description": "List of document UUIDs to delete (max 100)." } }, "type": "object", "required": [ "documentIds" ], "title": "BulkDeleteRequestV2", "description": "Request body for bulk document deletion." }, "BulkDeleteResponseV2": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "True if at least one document was deleted" }, "message": { "type": "string", "title": "Message" }, "deletedCount": { "type": "integer", "title": "Deletedcount" }, "failedCount": { "type": "integer", "title": "Failedcount" }, "details": { "items": { "$ref": "#/components/schemas/DeleteResultDetail" }, "type": "array", "title": "Details", "default": [] } }, "type": "object", "required": [ "success", "message", "deletedCount", "failedCount" ], "title": "BulkDeleteResponseV2", "description": "Response for bulk document deletion." }, "BulkInviteRequestV2": { "properties": { "participants": { "items": { "$ref": "#/components/schemas/DocumentParticipantData2" }, "type": "array", "maxItems": 250, "minItems": 1, "title": "Participants", "description": "Participants to invite (max 250 per request)." }, "config": { "$ref": "#/components/schemas/ParticipantConfig", "description": "Shared delivery config for all participants." } }, "type": "object", "required": [ "participants", "config" ], "title": "BulkInviteRequestV2", "description": "Body for the bulk-invite endpoint." }, "ChipEntry": { "properties": { "variableName": { "type": "string", "title": "Variablename" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "required": { "type": "boolean", "title": "Required", "default": true }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid" }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolename" }, "roleContactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolecontactemail" }, "positions": { "items": { "$ref": "#/components/schemas/ChipPosition" }, "type": "array", "title": "Positions" } }, "type": "object", "required": [ "variableName" ], "title": "ChipEntry" }, "ChipPosition": { "properties": { "page": { "type": "integer", "title": "Page", "description": "0-based page index within the PDF" }, "x": { "type": "number", "title": "X", "description": "Top-left X as % of page width (0–100)" }, "y": { "type": "number", "title": "Y", "description": "Top-left Y as % of page height (0–100)" }, "w": { "type": "number", "title": "W", "description": "Width as % of page width" }, "h": { "type": "number", "title": "H", "description": "Height as % of page height" } }, "type": "object", "required": [ "page", "x", "y", "w", "h" ], "title": "ChipPosition" }, "ChipPositionsResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "pdfs": { "items": { "$ref": "#/components/schemas/PdfChipPositions" }, "type": "array", "title": "Pdfs" }, "totalChips": { "type": "integer", "title": "Totalchips" } }, "type": "object", "required": [ "documentId", "pdfs", "totalChips" ], "title": "ChipPositionsResponse" }, "ChipWarning": { "properties": { "variableName": { "type": "string", "title": "Variablename" }, "scopePdfId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scopepdfid" }, "reason": { "type": "string", "enum": [ "placeholder_not_found_in_pdf", "chip_upsert_failed" ], "title": "Reason" } }, "type": "object", "required": [ "variableName", "reason" ], "title": "ChipWarning", "description": "C1 (audit 2026-06): per-variable chip placement warning.\n\nBefore this field, chip-creation failures only went to the logs: the\nvariable persisted fine but had no (or only a default-centered) visual\nposition, and the sender had no idea. The UI uses these to surface\n\"variable sin posición — arrástrala al documento\"." }, "Collaborator": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "Email del colaborador" }, "permissions": { "items": { "$ref": "#/components/schemas/PermissionType" }, "type": "array", "title": "Permissions", "description": "Lista de permisos otorgados. Options: read, update, delete, sign, admin" } }, "type": "object", "required": [ "email" ], "title": "Collaborator", "description": "Colaborador con permisos específicos en el documento." }, "CompoundDocumentDetails": { "properties": { "pdfs": { "items": { "$ref": "#/components/schemas/CompoundPdfSummary" }, "type": "array", "title": "Pdfs" }, "roles": { "items": { "$ref": "#/components/schemas/CompoundRoleSummary" }, "type": "array", "title": "Roles" }, "variables": { "items": { "$ref": "#/components/schemas/CompoundVariableSummary" }, "type": "array", "title": "Variables" }, "itemCount": { "type": "integer", "title": "Itemcount" } }, "type": "object", "required": [ "itemCount" ], "title": "CompoundDocumentDetails", "description": "Compound-specific data surfaced in GET responses.\n\nOnly populated when `content._meta.compound = true` OR when a document has\nmultiple `document_pdf` rows (covers legacy compound documents persisted\nbefore _meta started to be tagged)." }, "CompoundPatchItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "UUID of the existing document_pdf to edit" }, "position": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Position", "description": "New 1-based position. New positions across the array must form 1..N with no gaps." }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind", "description": "One of: main | attachment | cover" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "dedupeScope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dedupescope", "description": "One of: document | pdf" } }, "type": "object", "required": [ "id" ], "title": "CompoundPatchItem", "description": "Edit a single existing document_pdf row inside a compound document.\n\nThe `id` is required (must reference an existing document_pdf belonging to\nthis document). Only metadata fields (position, kind, name, dedupeScope)\ncan be edited. Adding / removing / re-rendering items is out of scope for\nCD-1 (a future POST /v2/documents/{id}/pdfs will handle additions).\n\nSoft-delete semantics: if the PATCH request omits an existing item from\nthe `documents` array entirely, that row is soft-deleted (deleted_at).\nTo keep an item, include its `id` in the array (with or without other\nedits)." }, "CompoundPdfSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "position": { "type": "integer", "title": "Position" }, "kind": { "type": "string", "title": "Kind" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "s3Key": { "type": "string", "title": "S3Key" }, "pdfHash": { "type": "string", "title": "Pdfhash" }, "templateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Templateid" }, "dedupeScope": { "type": "string", "title": "Dedupescope" }, "fileType": { "type": "string", "title": "Filetype", "description": "PDF or DOCX" } }, "type": "object", "required": [ "id", "position", "kind", "s3Key", "pdfHash", "dedupeScope", "fileType" ], "title": "CompoundPdfSummary" }, "CompoundRoleSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactemail" }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactphone" }, "sortOrder": { "type": "integer", "title": "Sortorder" }, "kind": { "type": "string", "title": "Kind" } }, "type": "object", "required": [ "id", "name", "sortOrder", "kind" ], "title": "CompoundRoleSummary" }, "CompoundVariableSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "variableName": { "type": "string", "title": "Variablename" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "type": { "type": "string", "title": "Type" }, "required": { "type": "boolean", "title": "Required" }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" }, "filledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Filledat" }, "documentPdfIds": { "items": { "type": "string" }, "type": "array", "title": "Documentpdfids" } }, "type": "object", "required": [ "id", "variableName", "type", "required" ], "title": "CompoundVariableSummary" }, "ContactBulkCreateRequest": { "properties": { "contacts": { "items": { "$ref": "#/components/schemas/ContactCreateRequest" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Contacts", "description": "Contacts to create (max 100)." } }, "type": "object", "required": [ "contacts" ], "title": "ContactBulkCreateRequest", "description": "POST /v2/contacts/bulk — create up to 100 contacts in one request." }, "ContactBulkDeleteRequest": { "properties": { "contactIds": { "items": { "type": "string" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Contactids", "description": "ContactProfile ids to delete (max 100)." } }, "type": "object", "required": [ "contactIds" ], "title": "ContactBulkDeleteRequest", "description": "DELETE /v2/contacts/bulk — remove up to 100 contact profiles." }, "ContactBulkResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "True if ≥1 item succeeded" }, "message": { "type": "string", "title": "Message" }, "succeededCount": { "type": "integer", "title": "Succeededcount" }, "failedCount": { "type": "integer", "title": "Failedcount" }, "details": { "items": { "$ref": "#/components/schemas/ContactBulkResultItem" }, "type": "array", "title": "Details" } }, "type": "object", "required": [ "success", "message", "succeededCount", "failedCount" ], "title": "ContactBulkResponse", "description": "Bulk operation response. Mirrors BulkDeleteResponseV2 from documents." }, "ContactBulkResultItem": { "properties": { "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactid" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "success": { "type": "boolean", "title": "Success" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "success" ], "title": "ContactBulkResultItem", "description": "Per-item outcome in a bulk response." }, "ContactBulkUpdateItem": { "properties": { "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fullname" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company" }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jobtitle" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "customFields": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Customfields", "description": "Custom key-value pairs for template autofill" }, "id": { "type": "string", "title": "Id", "description": "ContactProfile id to update" } }, "type": "object", "required": [ "id" ], "title": "ContactBulkUpdateItem", "description": "ContactUpdateRequest plus the target contact id." }, "ContactBulkUpdateRequest": { "properties": { "contacts": { "items": { "$ref": "#/components/schemas/ContactBulkUpdateItem" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Contacts", "description": "Contacts to update (max 100). Each item requires `id`." } }, "type": "object", "required": [ "contacts" ], "title": "ContactBulkUpdateRequest", "description": "PATCH /v2/contacts/bulk — partial update of up to 100 contacts." }, "ContactCreateRequest": { "properties": { "email": { "type": "string", "title": "Email", "description": "Contact email — must be unique per tenant" }, "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fullname", "description": "Full name" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company" }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jobtitle" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "customFields": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Customfields", "description": "Custom key-value pairs for template autofill" } }, "type": "object", "required": [ "email" ], "title": "ContactCreateRequest", "description": "Create a contact manually." }, "ContactDetailResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "userId": { "type": "string", "title": "Userid" }, "fullName": { "type": "string", "title": "Fullname", "default": "" }, "email": { "type": "string", "title": "Email", "default": "" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company" }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jobtitle" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "customFields": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Customfields" }, "source": { "type": "string", "title": "Source", "default": "manual" }, "identityVerified": { "type": "boolean", "title": "Identityverified", "default": false }, "identityVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Identityverifiedat" }, "nameVerified": { "type": "boolean", "title": "Nameverified", "default": false }, "totalDocumentsSigned": { "type": "integer", "title": "Totaldocumentssigned", "default": 0 }, "totalDocumentsPending": { "type": "integer", "title": "Totaldocumentspending", "default": 0 }, "lastInteractionAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastinteractionat" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" }, "documents": { "items": { "$ref": "#/components/schemas/ContactDocumentItem" }, "type": "array", "title": "Documents" } }, "type": "object", "required": [ "id", "userId", "createdAt", "updatedAt" ], "title": "ContactDetailResponse", "description": "Full contact profile with all metadata." }, "ContactDocumentItem": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "documentName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documentname" }, "signatureStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signaturestatus" }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Signedat" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "documentId", "createdAt" ], "title": "ContactDocumentItem", "description": "A document linked to this contact (as signer)." }, "ContactListItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "ContactProfile ID" }, "userId": { "type": "string", "title": "Userid" }, "fullName": { "type": "string", "title": "Fullname", "default": "" }, "email": { "type": "string", "title": "Email", "default": "" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "authPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authphone" }, "primaryChannel": { "type": "string", "title": "Primarychannel", "default": "email" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company" }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jobtitle" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "customFields": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Customfields" }, "source": { "type": "string", "title": "Source", "default": "manual" }, "identityVerified": { "type": "boolean", "title": "Identityverified", "default": false }, "totalDocumentsSigned": { "type": "integer", "title": "Totaldocumentssigned", "default": 0 }, "totalDocumentsPending": { "type": "integer", "title": "Totaldocumentspending", "default": 0 }, "lastInteractionAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastinteractionat" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "userId", "createdAt" ], "title": "ContactListItem", "description": "Compact row for the contacts table." }, "ContactListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ContactListItem" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "pageSize": { "type": "integer", "title": "Pagesize" }, "totalPages": { "type": "integer", "title": "Totalpages" } }, "type": "object", "required": [ "items", "total", "page", "pageSize", "totalPages" ], "title": "ContactListResponse", "description": "Paginated list of contacts." }, "ContactUpdateRequest": { "properties": { "fullName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fullname" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company" }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jobtitle" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "customFields": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Customfields", "description": "Custom key-value pairs for template autofill" } }, "type": "object", "title": "ContactUpdateRequest", "description": "Partial update of a contact profile." }, "ContentBlock": { "properties": { "type": { "type": "string", "title": "Type", "description": "Block type: heading, paragraph, list_item, table" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Plain text of the block (for non-table blocks)" }, "style": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Style", "description": "DOCX paragraph style name, e.g. 'Heading 1'" }, "index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Index", "description": "Position of the block in the document" } }, "additionalProperties": true, "type": "object", "required": [ "type" ], "title": "ContentBlock" }, "CorrectionContextResponse": { "properties": { "signingStatus": { "type": "string", "title": "Signingstatus" }, "canAddSigner": { "type": "boolean", "title": "Canaddsigner" }, "isLocked": { "type": "boolean", "title": "Islocked" }, "signers": { "items": {}, "type": "array", "title": "Signers" } }, "type": "object", "required": [ "signingStatus", "canAddSigner", "isLocked" ], "title": "CorrectionContextResponse" }, "CreateDocumentFromTemplateRequest": { "properties": { "templateId": { "type": "string", "title": "Templateid", "description": "UUID of the pre-saved DOCX template" }, "values": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Values", "description": "Key-value pairs mapping template variable names to their values", "example": { "fecha_inicio": "1 de abril de 2026", "monto_renta": "$15,000.00 MXN", "nombre_arrendador": "Pedro Páramo", "nombre_arrendatario": "Juan Preciado" } }, "participants": { "items": { "$ref": "#/components/schemas/DocumentParticipant" }, "type": "array", "title": "Participants", "description": "List of participants (signers)" }, "fields": { "items": { "$ref": "#/components/schemas/SignatureFieldCreate" }, "type": "array", "title": "Fields", "description": "List of signature fields" }, "signatureValidation": { "$ref": "#/components/schemas/DocumentValidationSettings", "description": "Signature validation settings" }, "config": { "$ref": "#/components/schemas/DocumentConfig", "description": "Document configuration" }, "permissions": { "anyOf": [ { "$ref": "#/components/schemas/DocumentPermissions" }, { "type": "null" } ], "description": "Document permissions and ownership" }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folderid", "description": "Optional folder ID to organize the document" }, "folderName": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Foldername", "description": "Folder name – finds existing or creates one" } }, "type": "object", "required": [ "templateId", "values" ], "title": "CreateDocumentFromTemplateRequest", "description": "Request to create a document by filling a pre-saved DOCX template." }, "CreateRoleRequest": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name", "description": "Role name (case-insensitive idempotent)." }, "kind": { "type": "string", "enum": [ "signer", "witness", "notary", "carbon_copy", "approver", "in_person_signer" ], "title": "Kind", "description": "Role kind.", "default": "signer" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color", "description": "Hex color override for UI (e.g. '#8b5cf6')." }, "scopePdfId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scopepdfid", "description": "vc_0010: scope to a specific document_pdf in compound docs. null = doc-wide role (default)." } }, "type": "object", "required": [ "name" ], "title": "CreateRoleRequest" }, "CreateRoleResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "kind": { "type": "string", "title": "Kind" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color" }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactemail" }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactphone" }, "signerUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signeruserid" }, "scopePdfId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scopepdfid" }, "action": { "type": "string", "enum": [ "created", "existing" ], "title": "Action" } }, "type": "object", "required": [ "id", "name", "kind", "action" ], "title": "CreateRoleResponse" }, "CreateVariableRequest": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name", "description": "Variable name (snake_case recommended). Lowercased + trimmed. Will be the key the signer's fill flow references." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Human-readable label. Defaults to titleized name." }, "type": { "type": "string", "enum": [ "text", "date", "currency", "number", "select", "textarea", "rfc", "curp", "email", "phone" ], "title": "Type", "default": "text" }, "required": { "type": "boolean", "title": "Required", "default": true }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value", "description": "Pre-filled value when the variable is sender-fixed (no role). Triggers source='owner' on the row." }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid" }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolename", "description": "Capa 4: assign by role name (upserts a DocumentRole if no matching one exists)." }, "scopePdfId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scopepdfid", "description": "vc_0008: scope to a specific document_pdf in compound docs." }, "createChip": { "type": "boolean", "title": "Createchip", "description": "When true (default), also create a DocumentField type='variable_chip' at default position so the chip is visible on the canvas. Sender can drag it later.", "default": true } }, "type": "object", "required": [ "name" ], "title": "CreateVariableRequest" }, "CreatedVariable": { "properties": { "id": { "type": "string", "title": "Id" }, "variableName": { "type": "string", "title": "Variablename" }, "label": { "type": "string", "title": "Label" }, "type": { "type": "string", "title": "Type" }, "required": { "type": "boolean", "title": "Required" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid" }, "scopePdfId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scopepdfid" }, "chipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chipid", "description": "ID of the auto-created variable_chip DocumentField, if any." }, "chipX": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Chipx", "description": "X (% of page) of the chip, so the client can render it without a refetch." }, "chipY": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Chipy", "description": "Y (% of page) of the chip." }, "action": { "type": "string", "enum": [ "created", "existing" ], "title": "Action" } }, "type": "object", "required": [ "id", "variableName", "label", "type", "required", "action" ], "title": "CreatedVariable" }, "CustomFieldsPatchRequest": { "properties": { "set": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Set", "description": "Key/value pairs to upsert (merged with existing)." }, "remove": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Remove", "description": "Keys to remove. Applied after `set`." } }, "type": "object", "title": "CustomFieldsPatchRequest", "description": "Atomic patch operation for ContactProfile.custom_fields.\n\nSemantics:\n - `set` → upsert these key/value pairs (merges with existing).\n - `remove`→ delete these keys if present (no-op if missing).\n - Both can be specified in the same request; `remove` is applied\n AFTER `set` so callers can \"rename\" a field in one call.\n\nThis is race-safe: a concurrent client deleting a DIFFERENT key will\nno longer clobber your delete (which is what happens with the PUT\nendpoint that overwrites the full dict)." }, "DeleteDocumentResponseV2": { "properties": { "success": { "type": "boolean", "title": "Success" }, "message": { "type": "string", "title": "Message" }, "documentId": { "type": "string", "title": "Documentid" }, "s3KeysCleaned": { "type": "integer", "title": "S3Keyscleaned" } }, "type": "object", "required": [ "success", "message", "documentId", "s3KeysCleaned" ], "title": "DeleteDocumentResponseV2", "description": "Response for single document deletion." }, "DeleteResultDetail": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "success": { "type": "boolean", "title": "Success" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "documentId", "success" ], "title": "DeleteResultDetail", "description": "Per-document result in a bulk delete response." }, "DeleteSignatureFieldRequest": { "properties": { "fieldId": { "type": "string", "title": "Fieldid", "description": "ID of the signature field to delete" }, "signerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signeremail", "description": "Email of the signer who owns the field (optional if signerPhone provided)" }, "signerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signerphone", "description": "WhatsApp phone of the signer (must start with +). Optional if signerEmail provided." }, "deleteLinkedFields": { "type": "boolean", "title": "Deletelinkedfields", "description": "Whether to delete linked fields when deleting a signature field", "default": false } }, "type": "object", "required": [ "fieldId" ], "title": "DeleteSignatureFieldRequest", "description": "Request model for deleting a signature field from a document.\nAt least one of signerEmail or signerPhone must be provided." }, "DetectVariablesResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "docxSource": { "type": "string", "enum": [ "source_docx_s3_key", "template_s3_key", "compound_pdfs" ], "title": "Docxsource", "description": "Where the DOCX bytes came from. 'compound_pdfs' = iterated over multiple document_pdf rows (one DOCX per PDF)." }, "variables": { "items": { "$ref": "#/components/schemas/DetectedVariable" }, "type": "array", "title": "Variables" }, "total": { "type": "integer", "title": "Total" }, "pdfsScanned": { "type": "integer", "title": "Pdfsscanned", "default": 0 } }, "type": "object", "required": [ "documentId", "docxSource", "variables", "total" ], "title": "DetectVariablesResponse" }, "DetectedVariable": { "properties": { "name": { "type": "string", "title": "Name", "description": "Internal variable name as found in the DOCX (e.g. 'proveedor__nombre')" }, "label": { "type": "string", "title": "Label", "description": "Human-readable label derived from the variable name" }, "assignment": { "type": "string", "enum": [ "role", "sender", "unassigned" ], "title": "Assignment", "description": "How this variable is assigned. 'role': auto-assigned to a signer role (double-underscore prefix). 'sender': filled by the document owner (prefix 'sender__'). 'unassigned': needs manual assignment in the sender wizard." }, "suggestedRoleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suggestedrolename", "description": "For assignment='role': the inferred role name from the variable prefix." }, "type": { "type": "string", "title": "Type", "description": "Inferred input type (text, date, number, rfc, etc.)", "default": "text" }, "pdfOccurrences": { "items": { "$ref": "#/components/schemas/PdfOccurrence" }, "type": "array", "title": "Pdfoccurrences", "description": "Compound docs: where this variable appears across the document's PDFs. When `len(pdf_occurrences) > 1`, the sender should decide whether the variable shares values across PDFs (scope_pdf_id NULL) or is per-PDF (scope_pdf_id set on each assignment)." }, "multiPdfConflict": { "type": "boolean", "title": "Multipdfconflict", "description": "True when the same variable_name appears in 2+ PDFs without an obvious shared concept (no double-underscore role prefix). UI should prompt the sender for scope decision.", "default": false } }, "type": "object", "required": [ "name", "label", "assignment" ], "title": "DetectedVariable" }, "DocumentConfig": { "properties": { "sendInvitations": { "type": "boolean", "title": "Sendinvitations", "description": "Send invitations to participants. When true, the API auto-detects the best channel (email or WhatsApp) for each participant.", "default": false }, "sendByWhatsapp": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sendbywhatsapp", "description": "DEPRECATED: Channel is now auto-detected per participant when sendInvitations=true. Accepted for backward compatibility but ignored.", "deprecated": true }, "sendByEmail": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sendbyemail", "description": "DEPRECATED: Channel is now auto-detected per participant when sendInvitations=true. Accepted for backward compatibility but ignored.", "deprecated": true }, "startAtStep": { "type": "integer", "maximum": 3.0, "minimum": 1.0, "title": "Startatstep", "description": "Initial step (1=draft, 2=fields, 3=signatures)", "default": 1 }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiresat", "description": "Optional expiration deadline (ISO 8601). If set, the document will transition to EXPIRADO after this date." }, "expirationReminders": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Expirationreminders", "description": "Days before expiration to send reminders (e.g., [1, 3, 7]). Each value must be 1-365. Max 10 entries." } }, "type": "object", "title": "DocumentConfig", "description": "Configuración de documento." }, "DocumentContentResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "docxSource": { "type": "string", "enum": [ "source_docx_s3_key", "template_s3_key", "document_pdf_template_s3_key" ], "title": "Docxsource" }, "blocks": { "items": { "$ref": "#/components/schemas/ContentBlock" }, "type": "array", "title": "Blocks" }, "blockCount": { "type": "integer", "title": "Blockcount" }, "characterCount": { "type": "integer", "title": "Charactercount" } }, "type": "object", "required": [ "documentId", "docxSource", "blocks", "blockCount", "characterCount" ], "title": "DocumentContentResponse" }, "DocumentCreateRequestV2": { "properties": { "document": { "anyOf": [ { "$ref": "#/components/schemas/DocumentFile" }, { "type": "null" } ], "description": "[DEPRECATED] Use `documents` array instead. Single inline file (base64) — kept for backward compatibility. Removal planned 2026-Q3.", "deprecated": true }, "templateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Templateid", "description": "[DEPRECATED] Use `documents` array with each item's own templateId instead. Single DOCX template UUID — kept for backward compatibility. Removal planned 2026-Q3.", "deprecated": true }, "templateValues": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Templatevalues", "description": "[DEPRECATED] Use `documents[].templateValues` instead. Variable values for the legacy single-template path. Removal planned 2026-Q3.", "deprecated": true, "example": { "empresa": "Constantinopla S.A. de C.V.", "nombre_cliente": "Pedro Páramo" } }, "documents": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DocumentGroupItem" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Documents", "description": "Compound document group: 1..20 items concatenated by `position`. Each item is a stored template (`templateId`) or an inline file (`base64Content` + `fileType`). Supersedes `document` and `templateId` (both deprecated). Use this for any new integration." }, "placeholders": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Placeholders", "description": "Key-value pairs to replace in DOCX documents (e.g., {{ client_name }} → 'Juan'). Only applied for .docx files; ignored for PDFs.", "example": { "empresa": "Constantinopla S.A. de C.V.", "fecha_contrato": "20 de febrero de 2026", "monto": "$150,000.00 MXN", "nombre_cliente": "Pedro Páramo", "rfc": "CPL210301XYZ" } }, "participants": { "items": { "$ref": "#/components/schemas/DocumentParticipant" }, "type": "array", "maxItems": 250, "title": "Participants", "description": "List of participants (signers)" }, "fields": { "items": { "$ref": "#/components/schemas/SignatureFieldCreate" }, "type": "array", "maxItems": 5000, "title": "Fields", "description": "List of signature fields" }, "signatureValidation": { "$ref": "#/components/schemas/DocumentValidationSettings", "description": "Signature validation settings" }, "config": { "$ref": "#/components/schemas/DocumentConfig", "description": "Document configuration" }, "permissions": { "anyOf": [ { "$ref": "#/components/schemas/DocumentPermissions" }, { "type": "null" } ], "description": "Document permissions and ownership. If not specified, the API key owner is the document owner." }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folderid", "description": "Optional folder ID to organize the document" }, "folderName": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Foldername", "description": "Folder name – finds existing folder or creates one. Ignored if folderId is also provided." } }, "type": "object", "title": "DocumentCreateRequestV2", "description": "Request para crear documento V2 (Internal API).\n\nThree modes (mutually exclusive):\n- **Compound (preferred since 2026-05)**: provide `documents` array with one\n or more `DocumentGroupItem`s — supports concatenated multi-PDF documents.\n- **Legacy single template**: provide `templateId` (+ optional `templateValues`).\n- **Legacy single upload**: provide `document` with `base64Content`.\n\nThe two legacy modes are deprecated and will be removed once existing\nintegrators migrate to `documents`. New integrations MUST use `documents`." }, "DocumentEventResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "event_type": { "type": "string", "title": "Event Type" }, "success": { "type": "boolean", "title": "Success" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "actor_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Type" }, "signature_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signature Id" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "event_type", "success", "message", "actor_type", "signature_id", "metadata", "created_at" ], "title": "DocumentEventResponse" }, "DocumentEventsListResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/DocumentEventResponse" }, "type": "array", "title": "Events" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "events", "total" ], "title": "DocumentEventsListResponse" }, "DocumentEvidenceResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "available": { "type": "boolean", "title": "Available" }, "evidencePdf": { "anyOf": [ { "$ref": "#/components/schemas/EvidencePdfInfo" }, { "type": "null" } ] }, "nom151": { "anyOf": [ { "$ref": "#/components/schemas/Nom151Info" }, { "type": "null" } ] } }, "type": "object", "required": [ "documentId", "available" ], "title": "DocumentEvidenceResponse" }, "DocumentFile": { "properties": { "base64Content": { "type": "string", "minLength": 1, "title": "Base64Content", "description": "File content encoded in base64 (max 50MB before encoding)" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Original filename with extension (e.g., 'contract.pdf')" } }, "type": "object", "required": [ "base64Content", "name" ], "title": "DocumentFile", "description": "File information for document creation." }, "DocumentGroupItem": { "properties": { "templateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Templateid", "description": "UUID of a stored DOCX template. Mutually exclusive with base64Content." }, "base64Content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Base64Content", "description": "Inline file (PDF or DOCX) encoded as base64. Max 50 MB decoded." }, "fileType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filetype", "description": "Required when base64Content is set. One of: 'pdf', 'docx'." }, "templateValues": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Templatevalues", "description": "Owner-fixed variable values applied at render time. Only used for DOCX sources." }, "placeholders": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Placeholders", "description": "Alias of templateValues for backward compatibility with single-document API." }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Display name for this piece within the compound (e.g., 'Contrato principal')." }, "kind": { "type": "string", "title": "Kind", "description": "Item role: 'main' (renderable template), 'attachment' (read-only annex), 'cover' (system cover page).", "default": "main" }, "position": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Position", "description": "1-based concatenation order. If omitted, auto-assigned 1..N by array index." }, "dedupeScope": { "type": "string", "title": "Dedupescope", "description": "'document' = variables shared across compound items (default); 'pdf' = isolated to this item.", "default": "document" } }, "type": "object", "title": "DocumentGroupItem", "description": "One piece of a compound document.\n\nEach item produces exactly one row in `document.document_pdf` and\ncontributes its template variables to the parent document. Source can be:\n - a stored DOCX template (`templateId`), or\n - an inline file via `base64Content` + `fileType` ('pdf' | 'docx').\n\nMultiple items are concatenated in `position` order at sign time. Variable\ndeduplication across items follows `dedupeScope`:\n - 'document' (default) — same `variable_name` shares a single value\n across items in this group.\n - 'pdf' — variables are isolated to this item only (use when two items\n legitimately need the same name with different values, e.g. two copies\n of the same template filled with distinct data)." }, "DocumentListV2Response": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Request success status", "default": true }, "message": { "type": "string", "title": "Message", "description": "Response message", "default": "Documents retrieved successfully" }, "data": { "items": { "$ref": "#/components/schemas/DocumentV2Response" }, "type": "array", "title": "Data", "description": "Array of documents" }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Pagination metadata (total is null; use /v2/documents/total)" }, "folders": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Folders", "description": "Folders list (if includeFolders=true)" }, "documentStats": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Documentstats", "description": "Aggregated document statistics (if includeDocumentStats=true)" }, "environmentSummary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Environmentsummary", "description": "Present when using a dev/test API key. Shows how many documents are in the active environment vs. the total across all environments in the tenant." } }, "type": "object", "required": [ "data", "meta" ], "title": "DocumentListV2Response", "description": "Paginated list of documents with metadata and optional extras." }, "DocumentParticipant": { "properties": { "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email", "description": "Participant email (optional if whatsapp provided)" }, "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Participant name" }, "whatsapp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Whatsapp", "description": "WhatsApp number (must start with +)" }, "invitedBy": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Invitedby", "description": "Email of inviter" }, "roleName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Rolename", "description": "Semantic role name for variable assignment (e.g. 'proveedor'). Must match the role prefix in template variables like {{ role:proveedor/nombre }}. Optional — if omitted, variables must be assigned manually in /signers." } }, "type": "object", "required": [ "name" ], "title": "DocumentParticipant", "description": "Participant de documento.\n\nExactly one identifier (email or whatsapp) must be provided.\nEach participant uses a single notification channel." }, "DocumentParticipantData2": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "whatsapp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Whatsapp" }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolename" } }, "type": "object", "title": "DocumentParticipantData2" }, "DocumentPatchRequestV2": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New document name" }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folderid", "description": "Folder ID to move document to (null to remove from folder)" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/DocumentConfig" }, { "type": "null" } ], "description": "Document configuration updates" }, "signatureValidation": { "anyOf": [ { "$ref": "#/components/schemas/DocumentValidationSettings" }, { "type": "null" } ], "description": "Signature validation settings updates" }, "permissions": { "anyOf": [ { "$ref": "#/components/schemas/DocumentPermissions" }, { "type": "null" } ], "description": "Document permissions updates" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Advance the document's signature state status. Only whitelisted transitions are allowed: RECOLECTANDO_FIRMANTES → SELLOS_PDF. Other status changes use dedicated endpoints (start-signing, enter-correction, exit-correction, void)." }, "documents": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CompoundPatchItem" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Documents", "description": "Edit metadata of existing compound items (position, kind, name, dedupeScope). Items present in this list are updated; existing items omitted are soft-deleted. Adding new PDFs to an existing compound is not supported in CD-1 — create a new document instead." } }, "type": "object", "title": "DocumentPatchRequestV2", "description": "Request for partial document updates (PATCH).\n\nAll fields are optional. Only provided fields will be updated.\nCommon use cases:\n- Move document to folder: {\"folderId\": \"uuid\"}\n- Rename document: {\"name\": \"New Name.pdf\"}\n- Update config: {\"config\": {...}}\n- Update permissions: {\"permissions\": {...}}\n- Advance document status: {\"status\": \"SELLOS_PDF\"}\n- Edit/reorder compound items: {\"documents\": [{\"id\": \"uuid\", \"position\": 2}, ...]}" }, "DocumentPermissions": { "properties": { "ownerEmail": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Owneremail", "description": "Email del propietario del documento. Si no se especifica, el propietario es el usuario del API key." }, "collaborators": { "items": { "$ref": "#/components/schemas/Collaborator" }, "type": "array", "title": "Collaborators", "description": "Lista de colaboradores con permisos específicos (lectura, edición, eliminación, etc.)" }, "isPublicRead": { "type": "boolean", "title": "Ispublicread", "description": "Si el documento debe ser de lectura pública (sin autenticación requerida)", "default": false } }, "type": "object", "title": "DocumentPermissions", "description": "Sistema de permisos granular para documentos.\n\nPermite especificar el propietario del documento y colaboradores con permisos específicos.\nLos firmantes (signers) se definen en el campo 'participants' del request principal." }, "DocumentScopeEnum": { "type": "string", "enum": [ "owner", "org", "tenant", "accessible" ], "title": "DocumentScopeEnum", "description": "Document scope for filtering.\n\nDefines the scope of documents to retrieve:\n- OWNER: Only documents where user is the creator (default)\n- ORG: All documents in user's organization\n- TENANT: All documents in user's tenant (multi-org admin scope)\n- ACCESSIBLE: All documents where user is owner OR participant" }, "DocumentSortFieldEnum": { "type": "string", "enum": [ "created_at", "updated_at", "name", "document_type" ], "title": "DocumentSortFieldEnum", "description": "Valid sort fields for documents." }, "DocumentStatsV2Response": { "properties": { "totalDocuments": { "type": "integer", "title": "Totaldocuments", "description": "Total number of documents" }, "totalCompleted": { "type": "integer", "title": "Totalcompleted", "description": "Documents with completed signature flow" }, "totalPending": { "type": "integer", "title": "Totalpending", "description": "Documents waiting on signatures or processing" }, "totalConfiguring": { "type": "integer", "title": "Totalconfiguring", "description": "Documents being configured before invitations are sent" }, "recentCount": { "type": "integer", "title": "Recentcount", "description": "Documents created in last 7 days" } }, "type": "object", "required": [ "totalDocuments", "totalCompleted", "totalPending", "totalConfiguring", "recentCount" ], "title": "DocumentStatsV2Response", "description": "Statistics about user's documents.", "example": { "recentCount": 12, "totalCompleted": 42, "totalConfiguring": 15, "totalDocuments": 150, "totalPending": 93 } }, "DocumentV2Response": { "properties": { "id": { "type": "string", "title": "Id", "description": "Document UUID" }, "name": { "type": "string", "title": "Name", "description": "Document name" }, "documentType": { "type": "string", "title": "Documenttype", "description": "Document type" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "Last update timestamp" }, "ownerId": { "type": "string", "title": "Ownerid", "description": "Owner user ID" }, "orgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Orgid", "description": "Organization ID" }, "categoryId": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Categoryid", "description": "Category ID" }, "activePublicUrl": { "type": "boolean", "title": "Activepublicurl", "description": "Public URL status", "default": false }, "chainId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chainid", "description": "Document chain ID (null for standalone documents)" }, "chainStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chainstatus", "description": "Chain status (DRAFT, INVITED, FILLING, SIGNING, COMPLETED, VOIDED, EXPIRED)" }, "signersData": { "anyOf": [ { "$ref": "#/components/schemas/SignersData" }, { "type": "null" } ], "description": "Signers and signatures information" }, "folders": { "anyOf": [ { "items": { "$ref": "#/components/schemas/FolderSummary" }, "type": "array" }, { "type": "null" } ], "title": "Folders", "description": "Folders that reference this document (includeFolders=true)" }, "environment": { "type": "string", "title": "Environment", "description": "Document environment resolved from content._meta. Values: live | dev | test. Legacy documents without metadata return 'live'.", "default": "live" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiresat", "description": "Optional signing deadline (ISO 8601 UTC). When set, the document transitions to EXPIRADO after this date and signing is blocked. Sourced from signature_state.expires_at." }, "expirationReminders": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Expirationreminders", "description": "Days before expiration to send reminders, e.g. [1, 3, 7]. Sourced from signature_state.expiration_reminders." }, "extendedCount": { "type": "integer", "title": "Extendedcount", "description": "Number of times the signing deadline has been extended via POST /v2/documents/{id}/extend.", "default": 0 }, "compound": { "anyOf": [ { "$ref": "#/components/schemas/CompoundDocumentDetails" }, { "type": "null" } ], "description": "Compound document details (pdfs, roles, variables). Only populated when the document was created via `documents: [...]` or has multiple document_pdf rows. null for single-PDF documents." }, "livemode": { "type": "boolean", "title": "Livemode", "description": "False when the document was created with a dev or test API key. Check this field in webhook handlers to avoid processing test documents as real ones.", "readOnly": true } }, "type": "object", "required": [ "id", "name", "documentType", "createdAt", "updatedAt", "ownerId", "livemode" ], "title": "DocumentV2Response", "description": "Single document response with camelCase aliases.", "example": { "activePublicUrl": false, "categoryId": 1, "createdAt": "2024-11-23T10:00:00Z", "documentType": "EDITABLE", "environment": "live", "folders": [ { "id": "111e8400-e29b-41d4-a716-446655440000", "name": "Contratos" } ], "id": "550e8400-e29b-41d4-a716-446655440000", "livemode": true, "name": "Contract 2024.pdf", "orgId": "550e8400-e29b-41d4-a716-446655440002", "ownerId": "550e8400-e29b-41d4-a716-446655440001", "signersData": { "id": "cdc27f13-4d05-47d0-9690-fb69d005e7f8", "signatures": [ { "id": "63db6fa9-2709-4f68-9ea7-bc640194bade", "signer": { "email": "soy@israelortiz.com", "id": "99dc8f00-be5f-4331-ae66-db71bc2f6ccb" }, "status": "SIGNED" } ], "status": "TODOS_FIRMARON" }, "updatedAt": "2024-11-23T10:00:00Z" } }, "DocumentValidationSettings": { "properties": { "FEA": { "type": "boolean", "title": "Fea", "description": "validation with mexican Firma Electronica Avanzada", "default": false }, "eIDAS": { "type": "boolean", "title": "Eidas", "description": "eIDAS compliance", "default": false }, "nom151": { "type": "boolean", "title": "Nom151", "description": "NOM-151 compliance", "default": false }, "autografa": { "type": "boolean", "title": "Autografa", "description": "Autógrafa signature", "default": true }, "id_scan": { "type": "boolean", "title": "Id Scan", "description": "Standalone ID scan (INE, passport, etc.)", "default": false }, "biometric_signature": { "type": "boolean", "title": "Biometric Signature", "description": "Biometric selfie (face comparison against ID)", "default": false }, "confirm_name_to_finish": { "type": "boolean", "title": "Confirm Name To Finish", "default": false }, "ai_verification": { "type": "boolean", "title": "Ai Verification", "description": "Legacy catch-all — prefer modular flags below", "default": false }, "videofirma": { "type": "boolean", "title": "Videofirma", "description": "Video recording of the signer during signing process", "default": false }, "document_scan": { "type": "boolean", "title": "Document Scan", "description": "AI document classification + OCR extraction (GPT-4o)", "default": false }, "name_verification": { "type": "boolean", "title": "Name Verification", "description": "MRZ extraction + cross-check name verification (FastMRZ, deterministic)", "default": false }, "selfie_capture": { "type": "boolean", "title": "Selfie Capture", "description": "Capture selfie and verify it's a real face (no biometric comparison). Required if biometric_face_match is enabled.", "default": false }, "biometric_face_match": { "type": "boolean", "title": "Biometric Face Match", "description": "Selfie + ArcFace biometric comparison against ID photo. Requires selfie_capture to be enabled.", "default": false }, "deep_fake_shield": { "type": "boolean", "title": "Deep Fake Shield", "description": "Anti-fraud ML deepfake detection", "default": false }, "anti_spoof_shield": { "type": "boolean", "title": "Anti Spoof Shield", "description": "Presentation attack detection (printed photos, screen replay)", "default": false }, "id_reuse_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id Reuse Policy", "description": "Controls whether a signer's prior identity verification is reused. 'always_new' (default) always requests a fresh capture; 'auto' skips ID scan if a prior verification exists.", "default": "always_new" } }, "additionalProperties": true, "type": "object", "title": "DocumentValidationSettings", "description": "Configuración de validaciones de firma." }, "DocxTemplateDeleteResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Whether the deletion succeeded", "default": true }, "id": { "type": "string", "title": "Id", "description": "Template UUID that was deleted" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "message": { "type": "string", "title": "Message", "description": "Human-readable result message" }, "softDelete": { "type": "boolean", "title": "Softdelete", "description": "True if soft-deleted (marked inactive), False if hard-deleted", "default": true }, "s3Deleted": { "type": "boolean", "title": "S3Deleted", "description": "Whether the underlying S3 file was removed", "default": false }, "inUseBy": { "$ref": "#/components/schemas/TemplateDeleteUsage", "description": "Snapshot of references at deletion time" } }, "type": "object", "required": [ "id", "name", "message" ], "title": "DocxTemplateDeleteResponse", "description": "Response after a successful template deletion." }, "DocxTemplateDetailResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template UUID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Template description" }, "originalFilename": { "type": "string", "title": "Originalfilename", "description": "Original uploaded filename" }, "fileType": { "type": "string", "title": "Filetype", "description": "File type" }, "variables": { "items": { "type": "string" }, "type": "array", "title": "Variables", "description": "Variable names (flat list)" }, "variableConfig": { "items": { "$ref": "#/components/schemas/VariableConfigItem" }, "type": "array", "title": "Variableconfig", "description": "Rich variable metadata" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "User-defined tags" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Template category" }, "aiEditable": { "type": "boolean", "title": "Aieditable", "default": true }, "usageCount": { "type": "integer", "title": "Usagecount", "default": 0 }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastusedat" }, "currentVersion": { "type": "integer", "title": "Currentversion", "description": "Current active version number", "default": 1 }, "testDataSets": { "items": { "$ref": "#/components/schemas/TestDataSetResponse" }, "type": "array", "title": "Testdatasets", "description": "Predefined test data sets for preview" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "name", "originalFilename", "fileType", "createdAt", "updatedAt" ], "title": "DocxTemplateDetailResponse", "description": "Full detail response for a single template." }, "DocxTemplateListResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true }, "data": { "items": { "$ref": "#/components/schemas/DocxTemplateSummary" }, "type": "array", "title": "Data", "description": "Array of templates" }, "total": { "type": "integer", "title": "Total", "description": "Total number of templates" } }, "type": "object", "required": [ "data", "total" ], "title": "DocxTemplateListResponse", "description": "Paginated list of templates." }, "DocxTemplateSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template UUID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Template description" }, "originalFilename": { "type": "string", "title": "Originalfilename", "description": "Original uploaded filename" }, "fileType": { "type": "string", "title": "Filetype", "description": "File type: 'docx' or 'pdf'" }, "variableCount": { "type": "integer", "title": "Variablecount", "description": "Number of detected variables" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "User-defined tags" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Template category" }, "aiEditable": { "type": "boolean", "title": "Aieditable", "description": "AI editing enabled", "default": true }, "usageCount": { "type": "integer", "title": "Usagecount", "description": "Documents created from this template", "default": 0 }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Lastusedat", "description": "Last time a document was created" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "name", "originalFilename", "fileType", "variableCount", "createdAt", "updatedAt" ], "title": "DocxTemplateSummary", "description": "Summary view of a template for list endpoints." }, "DocxTemplateUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Replace tags entirely" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Template category" }, "aiEditable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Aieditable" }, "variableConfig": { "anyOf": [ { "items": { "$ref": "#/components/schemas/VariableConfigItem" }, "type": "array" }, { "type": "null" } ], "title": "Variableconfig", "description": "Override auto-generated variable metadata" } }, "type": "object", "title": "DocxTemplateUpdateRequest", "description": "Request to update template metadata (PATCH)." }, "DocxTemplateUploadResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Template UUID" }, "name": { "type": "string", "title": "Name", "description": "Template name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Template description" }, "originalFilename": { "type": "string", "title": "Originalfilename", "description": "Original uploaded filename" }, "fileType": { "type": "string", "title": "Filetype", "description": "File type: 'docx' or 'pdf'" }, "variables": { "items": { "type": "string" }, "type": "array", "title": "Variables", "description": "Auto-detected Jinja2 variable names from the DOCX" }, "variableConfig": { "items": { "$ref": "#/components/schemas/VariableConfigItem" }, "type": "array", "title": "Variableconfig", "description": "Rich variable metadata with types and labels" }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "User-defined tags" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Template category" }, "aiEditable": { "type": "boolean", "title": "Aieditable", "description": "AI editing enabled", "default": true }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "Creation timestamp" } }, "type": "object", "required": [ "id", "name", "originalFilename", "fileType", "createdAt" ], "title": "DocxTemplateUploadResponse", "description": "Response after uploading a DOCX template." }, "DocxTemplateVariablesResponse": { "properties": { "templateId": { "type": "string", "title": "Templateid", "description": "Template UUID" }, "templateName": { "type": "string", "title": "Templatename", "description": "Template name" }, "variables": { "items": { "$ref": "#/components/schemas/TemplateVariableInfo" }, "type": "array", "title": "Variables", "description": "Detected variables with labels and types" } }, "type": "object", "required": [ "templateId", "templateName" ], "title": "DocxTemplateVariablesResponse", "description": "Response with detected variables for a template." }, "EmailValidationWarning": { "properties": { "type": { "type": "string", "title": "Type" }, "email": { "type": "string", "title": "Email" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "type", "email", "message" ], "title": "EmailValidationWarning" }, "EvidencePdfInfo": { "properties": { "s3Key": { "type": "string", "title": "S3Key" }, "presignedUrl": { "type": "string", "title": "Presignedurl" }, "hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hash" } }, "type": "object", "required": [ "s3Key", "presignedUrl" ], "title": "EvidencePdfInfo" }, "ExtendDeadlineRequest": { "properties": { "newExpiresAt": { "type": "string", "format": "date-time", "title": "Newexpiresat", "description": "New expiration deadline (ISO 8601). Must be in the future." }, "expirationReminders": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Expirationreminders", "description": "Days before expiration to send reminders, e.g. [1, 3, 7]. Each value must be 1-365, max 10 entries, deduplicated. If null, reuses the reminders currently persisted on signature_state. Pass an empty list to clear reminders." } }, "type": "object", "required": [ "newExpiresAt" ], "title": "ExtendDeadlineRequest", "description": "Request to extend a document's signing deadline." }, "ExtendDeadlineResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "newExpiresAt": { "type": "string", "title": "Newexpiresat" }, "expirationReminders": { "items": { "type": "integer" }, "type": "array", "title": "Expirationreminders" }, "extendedCount": { "type": "integer", "title": "Extendedcount" }, "previousStatus": { "type": "string", "title": "Previousstatus" }, "newStatus": { "type": "string", "title": "Newstatus" }, "reinvitedSigners": { "items": { "type": "string" }, "type": "array", "title": "Reinvitedsigners", "description": "Identifiers (email or WhatsApp) of signers that received a fresh invitation as part of an EXPIRADO → ESPERANDO_FIRMAS reactivation. Empty when extending an already-active doc." } }, "type": "object", "required": [ "success", "newExpiresAt", "extendedCount", "previousStatus", "newStatus" ], "title": "ExtendDeadlineResponse", "description": "Response after extending a document's deadline." }, "FieldPosition": { "properties": { "x": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "X" }, "y": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Y" } }, "type": "object", "title": "FieldPosition" }, "FolderCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Folder name" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentid", "description": "Parent folder ID (null = root level)" } }, "type": "object", "required": [ "name" ], "title": "FolderCreateRequest", "description": "Create new folder.", "example": { "name": "Facturas 2024", "parentId": "550e8400-e29b-41d4-a716-446655440000" } }, "FolderListResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Request success status", "default": true }, "message": { "type": "string", "title": "Message", "description": "Response message", "default": "Folders retrieved successfully" }, "data": { "items": { "$ref": "#/components/schemas/FolderTreeResponse" }, "type": "array", "title": "Data", "description": "Array of folders in tree structure" } }, "type": "object", "required": [ "data" ], "title": "FolderListResponse", "description": "List of folders response." }, "FolderSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "Folder UUID" }, "name": { "type": "string", "title": "Name", "description": "Folder name" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentid", "description": "Parent folder UUID" } }, "type": "object", "required": [ "id", "name" ], "title": "FolderSummary", "description": "Minimal folder info to embed inside document payloads." }, "FolderTreeResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Folder UUID" }, "name": { "type": "string", "title": "Name", "description": "Folder name" }, "ownerId": { "type": "string", "title": "Ownerid", "description": "Owner user ID" }, "tenantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenantid", "description": "Tenant ID (null = personal folder)" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentid", "description": "Parent folder ID" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "Last update timestamp" }, "hasDocs": { "type": "boolean", "title": "Hasdocs", "description": "If folder has docs" }, "isMain": { "type": "boolean", "title": "Ismain", "description": "Is this the main/root folder?", "default": false }, "subfolders": { "items": { "$ref": "#/components/schemas/FolderTreeResponse" }, "type": "array", "title": "Subfolders", "description": "Child folders (recursive)" } }, "type": "object", "required": [ "id", "name", "ownerId", "createdAt", "updatedAt", "hasDocs" ], "title": "FolderTreeResponse", "description": "Folder with hierarchical structure (tree).", "example": { "createdAt": "2024-11-23T10:00:00Z", "hasDocs": true, "id": "550e8400-e29b-41d4-a716-446655440000", "isMain": true, "name": "Documentos", "ownerId": "550e8400-e29b-41d4-a716-446655440001", "subfolders": [ { "createdAt": "2024-11-23T10:00:00Z", "hasDocs": false, "id": "550e8400-e29b-41d4-a716-446655440002", "isMain": false, "name": "Contratos", "ownerId": "550e8400-e29b-41d4-a716-446655440001", "parentId": "550e8400-e29b-41d4-a716-446655440000", "subfolders": [], "updatedAt": "2024-11-23T10:00:00Z" } ], "updatedAt": "2024-11-23T10:00:00Z" } }, "FolderUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New folder name" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentid", "description": "New parent folder ID (to move folder)" } }, "type": "object", "title": "FolderUpdateRequest", "description": "Rename or move folder.", "example": { "name": "Contratos 2025", "parentId": "550e8400-e29b-41d4-a716-446655440001" } }, "FolderV2Response": { "properties": { "id": { "type": "string", "title": "Id", "description": "Folder UUID" }, "name": { "type": "string", "title": "Name", "description": "Folder name" }, "ownerId": { "type": "string", "title": "Ownerid", "description": "Owner user ID" }, "tenantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenantid", "description": "Tenant ID (null = personal folder)" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parentid", "description": "Parent folder ID (null = root)" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat", "description": "Last update timestamp" }, "hasDocs": { "type": "boolean", "title": "Hasdocs", "description": "If folder has docs" }, "isMain": { "type": "boolean", "title": "Ismain", "description": "Is this the main/root folder?", "default": false } }, "type": "object", "required": [ "id", "name", "ownerId", "createdAt", "updatedAt", "hasDocs" ], "title": "FolderV2Response", "description": "Single folder response without children.", "example": { "createdAt": "2024-11-23T10:00:00Z", "hasDocs": true, "id": "550e8400-e29b-41d4-a716-446655440000", "isMain": true, "name": "Contratos 2024", "ownerId": "550e8400-e29b-41d4-a716-446655440001", "tenantId": "550e8400-e29b-41d4-a716-446655440099", "updatedAt": "2024-11-23T10:00:00Z" } }, "FunnelStepResponse": { "properties": { "label": { "type": "string", "title": "Label", "description": "Stage label" }, "count": { "type": "integer", "title": "Count", "description": "Document count at this stage" }, "pct": { "type": "number", "title": "Pct", "description": "Percentage of total" } }, "type": "object", "required": [ "label", "count", "pct" ], "title": "FunnelStepResponse", "description": "One stage in the signing funnel." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InviteRequestV2": { "properties": { "participant": { "$ref": "#/components/schemas/DocumentParticipantData2", "description": "Participant to invite (email, name, whatsapp)." }, "config": { "$ref": "#/components/schemas/ParticipantConfig", "description": "Delivery config (email / whatsapp / invitedByEmail)." } }, "type": "object", "required": [ "participant", "config" ], "title": "InviteRequestV2", "description": "Body for the single-invite endpoint." }, "InviteResponseV2": { "properties": { "success": { "type": "boolean", "title": "Success" }, "message": { "type": "string", "title": "Message" }, "sentCount": { "type": "integer", "title": "Sentcount", "default": 0 }, "failedCount": { "type": "integer", "title": "Failedcount", "default": 0 }, "details": { "items": { "$ref": "#/components/schemas/InviteResultDetail" }, "type": "array", "title": "Details", "default": [] } }, "type": "object", "required": [ "success", "message" ], "title": "InviteResponseV2" }, "InviteResultDetail": { "properties": { "participant": { "type": "string", "title": "Participant" }, "success": { "type": "boolean", "title": "Success" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "guestLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Guestlink" } }, "type": "object", "required": [ "participant", "success" ], "title": "InviteResultDetail" }, "MonthlyTrendResponse": { "properties": { "month": { "type": "string", "title": "Month", "description": "Month abbreviation (e.g. 'Jan')" }, "signed": { "type": "integer", "title": "Signed", "description": "Number of fully signed documents" }, "avgHours": { "type": "number", "title": "Avghours", "description": "Average signing time (hours)" } }, "type": "object", "required": [ "month", "signed", "avgHours" ], "title": "MonthlyTrendResponse", "description": "Signed documents and average signing hours per month." }, "MyFillStepResponse": { "properties": { "step": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Step" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Why no step was returned. One of: feature_disabled, no_signature, no_role, no_variables, ready (step returned)." }, "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action", "description": "'created', 'existing', 'skipped'." } }, "type": "object", "title": "MyFillStepResponse", "description": "Response shape mirroring the dashboard's VerificationStepInstance.\n\n`step` is null when no step exists/was created for any of these reasons:\nfeature disabled, signer not bound, role not assigned, or no pending\nvariables for the role." }, "Nom151Info": { "properties": { "s3Key": { "type": "string", "title": "S3Key" }, "presignedUrl": { "type": "string", "title": "Presignedurl" }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Data" } }, "type": "object", "required": [ "s3Key", "presignedUrl" ], "title": "Nom151Info" }, "OnboardingFillSessionCreate": { "properties": { "type": { "$ref": "#/components/schemas/OnboardingFillType" }, "templateId": { "type": "string", "format": "uuid", "title": "Templateid" }, "roleName": { "type": "string", "maxLength": 255, "title": "Rolename" }, "roleId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Roleid", "description": "DocumentRole.id to scope this session. When set, the guest only sees/fills variables of that role — the role must be an active role of this session's document or the request is rejected (400). Standalone sessions (the common case for this endpoint) omit roleId: the guest fills the whole document created from the template. Role-scoped sessions are normally created by the signing invitation flow, not through this endpoint." }, "contactEmail": { "type": "string", "format": "email", "title": "Contactemail" }, "contactName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Contactname" }, "contactPhone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Contactphone" }, "variables": { "items": { "$ref": "#/components/schemas/OnboardingVariableAssignment" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Variables", "description": "Variables the guest will fill" }, "ownerValues": { "items": { "$ref": "#/components/schemas/OnboardingOwnerValue" }, "type": "array", "maxItems": 100, "title": "Ownervalues", "description": "Owner-provided fixed values (read-only for guest)" }, "webhookUrl": { "anyOf": [ { "type": "string", "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Webhookurl" }, "webhookSecret": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Webhooksecret" }, "channel": { "type": "string", "enum": [ "email", "whatsapp" ], "title": "Channel", "default": "email" }, "message": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Message", "description": "Custom message in the invitation" }, "expiresInDays": { "type": "integer", "maximum": 90.0, "minimum": 1.0, "title": "Expiresindays", "default": 7 }, "memberRole": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "developer", "member", "viewer" ] }, { "type": "null" } ], "title": "Memberrole", "description": "Tenant role (lowercase): owner, admin, developer, member, viewer" }, "memberPermissions": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Memberpermissions", "description": "Permission overrides for the new member" } }, "type": "object", "required": [ "type", "templateId", "roleName", "contactEmail", "variables" ], "title": "OnboardingFillSessionCreate", "description": "Create an onboarding fill session.\n\nDiscriminated by `type`:\n- \"contact\": fills variables for a document, optionally followed by signing\n- \"member\": fills variables + joins the workspace/tenant" }, "OnboardingFillSessionListResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/OnboardingFillSessionResponse" }, "type": "array", "title": "Sessions" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "pageSize": { "type": "integer", "title": "Pagesize" } }, "type": "object", "required": [ "sessions", "total", "page", "pageSize" ], "title": "OnboardingFillSessionListResponse", "description": "Paginated list of onboarding fill sessions." }, "OnboardingFillSessionResponse": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "type": { "type": "string", "title": "Type" }, "status": { "type": "string", "title": "Status" }, "templateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Templateid" }, "documentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documentid" }, "roleName": { "type": "string", "title": "Rolename" }, "contactEmail": { "type": "string", "title": "Contactemail" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactname" }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactphone" }, "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactid" }, "memberRole": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memberrole" }, "guestUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Guesturl" }, "webhookUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhookurl" }, "webhookStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhookstatus" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiresat" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completedat" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" } }, "type": "object", "required": [ "id", "type", "status", "documentId", "roleName", "contactEmail" ], "title": "OnboardingFillSessionResponse", "description": "Response for a single onboarding fill session." }, "OnboardingFillType": { "type": "string", "enum": [ "contact", "member" ], "title": "OnboardingFillType" }, "OnboardingOwnerValue": { "properties": { "variableName": { "type": "string", "maxLength": 255, "title": "Variablename" }, "value": { "type": "string", "maxLength": 10000, "title": "Value" } }, "type": "object", "required": [ "variableName", "value" ], "title": "OnboardingOwnerValue", "description": "Owner-provided fixed value (read-only for the guest)." }, "OnboardingVariableAssignment": { "properties": { "variableName": { "type": "string", "maxLength": 255, "title": "Variablename" }, "label": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Label" }, "type": { "type": "string", "title": "Type", "default": "text" }, "required": { "type": "boolean", "title": "Required", "default": true }, "inputMode": { "type": "string", "title": "Inputmode", "default": "free" }, "sourceHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcehint" }, "captureAction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Captureaction" } }, "type": "object", "required": [ "variableName" ], "title": "OnboardingVariableAssignment", "description": "Variable to be filled by the guest." }, "OwnerFillInfoResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "documentName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documentname" }, "signatureId": { "type": "string", "title": "Signatureid" }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid" }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolename" }, "variables": { "items": { "$ref": "#/components/schemas/OwnerFillVariable" }, "type": "array", "title": "Variables" }, "ownerVariables": { "items": { "$ref": "#/components/schemas/OwnerFillVariable" }, "type": "array", "title": "Ownervariables" }, "documentContent": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Documentcontent" } }, "type": "object", "required": [ "documentId", "signatureId", "variables" ], "title": "OwnerFillInfoResponse" }, "OwnerFillProgressRequest": { "properties": { "variables": { "items": { "$ref": "#/components/schemas/OwnerFillVariableInput" }, "type": "array", "title": "Variables" } }, "type": "object", "required": [ "variables" ], "title": "OwnerFillProgressRequest" }, "OwnerFillProgressResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "savedCount": { "type": "integer", "title": "Savedcount" }, "sessionStatus": { "type": "string", "title": "Sessionstatus" } }, "type": "object", "required": [ "success", "savedCount", "sessionStatus" ], "title": "OwnerFillProgressResponse" }, "OwnerFillSubmitResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "filledCount": { "type": "integer", "title": "Filledcount" }, "sessionStatus": { "type": "string", "title": "Sessionstatus" }, "stateTransition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statetransition" } }, "type": "object", "required": [ "success", "filledCount", "sessionStatus" ], "title": "OwnerFillSubmitResponse" }, "OwnerFillVariable": { "properties": { "variableName": { "type": "string", "title": "Variablename" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "type": { "type": "string", "title": "Type", "default": "text" }, "required": { "type": "boolean", "title": "Required", "default": true }, "inputMode": { "type": "string", "title": "Inputmode", "default": "free" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" }, "sourceHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcehint" }, "captureAction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Captureaction" }, "validation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Validation" } }, "type": "object", "required": [ "variableName" ], "title": "OwnerFillVariable" }, "OwnerFillVariableInput": { "properties": { "variableName": { "type": "string", "title": "Variablename" }, "value": { "type": "string", "title": "Value" }, "source": { "type": "string", "title": "Source", "default": "manual" } }, "type": "object", "required": [ "variableName", "value" ], "title": "OwnerFillVariableInput" }, "PaginationMeta": { "properties": { "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "description": "Items per page" }, "total": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Total", "description": "Total number of items (null when totals are fetched via /v2/documents/total)" }, "hasNext": { "type": "boolean", "title": "Hasnext", "description": "Whether there's a next page" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor", "description": "Cursor for next page" }, "prevCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prevcursor", "description": "Cursor for previous page" } }, "type": "object", "required": [ "limit", "hasNext" ], "title": "PaginationMeta", "description": "Pagination metadata for cursor-only responses.", "examples": [ { "title": "Cursor-based pagination", "value": { "hasNext": true, "limit": 20, "nextCursor": "550e8400-e29b-41d4-a716-446655440000" } } ] }, "ParticipantConfig": { "properties": { "sendInvitationByWhatsapp": { "type": "boolean", "title": "Sendinvitationbywhatsapp", "description": "DEPRECATED — channel is auto-determined per participant. Accepted but ignored.", "default": false }, "sendInvitationByEmail": { "type": "boolean", "title": "Sendinvitationbyemail", "description": "DEPRECATED — channel is auto-determined per participant. Accepted but ignored.", "default": false }, "invitedByEmail": { "type": "string", "title": "Invitedbyemail", "description": "The email of the user adding all the participants." }, "invitedByName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invitedbyname", "description": "Display name of the inviter (shown in email subject/body instead of raw email)." }, "signingMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signingmode", "description": "The signing mode of the document (Simple or Autógrafa) to customize invitation copy." }, "invitationMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invitationmessage", "description": "Owner's optional personalized message shown in the signing invitation (WhatsApp + email). Sanitized server-side and capped at 180 chars." } }, "type": "object", "required": [ "invitedByEmail" ], "title": "ParticipantConfig" }, "PatchRoleRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New role name. Validated against the case-insensitive UNIQUE per (document, name, scope) — a duplicate returns 409." }, "kind": { "anyOf": [ { "type": "string", "enum": [ "signer", "witness", "notary", "carbon_copy", "approver", "in_person_signer" ] }, { "type": "null" } ], "title": "Kind", "description": "Role kind." }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color", "description": "Hex color override for UI (e.g. '#8b5cf6')." }, "contactEmail": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Contactemail", "description": "Contact email hint for the role. Changing it does NOT re-send any invitation — invitations are managed through the signer endpoints." } }, "type": "object", "title": "PatchRoleRequest", "description": "Partial update — only the provided fields change." }, "PatchRoleResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "kind": { "type": "string", "title": "Kind" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color" }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactemail" }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contactphone" }, "signerUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signeruserid" }, "scopePdfId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scopepdfid" } }, "type": "object", "required": [ "id", "name", "kind" ], "title": "PatchRoleResponse" }, "PatchSignerRequest": { "properties": { "roleName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Rolename", "description": "Role name to assign to this signer. Creates the DocumentRole row if it doesn't exist for this signer's email; otherwise renames the existing role. Pass an empty string or null to leave the role untouched." }, "variableNames": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 500 }, { "type": "null" } ], "title": "Variablenames", "description": "Optional list of B5-detected variable names to ensure exist in document_variable before auto-linking. Allows auto-link to run even when B6 (assign-variables) hasn't been called yet." } }, "type": "object", "title": "PatchSignerRequest" }, "PatchSignerResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid" }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolename" }, "roleContactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolecontactemail" }, "autoAssignedVariables": { "items": { "type": "string" }, "type": "array", "title": "Autoassignedvariables" } }, "type": "object", "required": [ "success" ], "title": "PatchSignerResponse" }, "PdfChipPositions": { "properties": { "pdfId": { "type": "string", "title": "Pdfid" }, "position": { "type": "integer", "title": "Position" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "pageCount": { "type": "integer", "title": "Pagecount" }, "chips": { "items": { "$ref": "#/components/schemas/ChipEntry" }, "type": "array", "title": "Chips" } }, "type": "object", "required": [ "pdfId", "position", "pageCount", "chips" ], "title": "PdfChipPositions" }, "PdfHashResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "pdfs": { "items": { "$ref": "#/components/schemas/PdfHashRow" }, "type": "array", "title": "Pdfs" } }, "type": "object", "required": [ "documentId", "pdfs" ], "title": "PdfHashResponse" }, "PdfHashRow": { "properties": { "documentPdfId": { "type": "string", "title": "Documentpdfid" }, "position": { "type": "integer", "title": "Position" }, "s3Key": { "type": "string", "title": "S3Key" }, "pdfHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pdfhash" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updatedat" } }, "type": "object", "required": [ "documentPdfId", "position", "s3Key" ], "title": "PdfHashRow" }, "PdfOccurrence": { "properties": { "pdfId": { "type": "string", "title": "Pdfid" }, "position": { "type": "integer", "title": "Position" }, "pdfName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pdfname" }, "occurrenceCount": { "type": "integer", "title": "Occurrencecount" } }, "type": "object", "required": [ "pdfId", "position", "occurrenceCount" ], "title": "PdfOccurrence", "description": "Per-PDF count of how many times a variable appears in that PDF's DOCX." }, "PermissionType": { "type": "string", "enum": [ "read", "update", "delete", "sign", "admin" ], "title": "PermissionType", "description": "Tipos de permisos disponibles para colaboradores." }, "RecentEventResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "documentName": { "type": "string", "title": "Documentname" }, "eventType": { "type": "string", "title": "Eventtype" }, "actorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actorname" }, "actorInitials": { "type": "string", "title": "Actorinitials" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "documentName", "eventType", "actorInitials", "createdAt" ], "title": "RecentEventResponse", "description": "A recent document event for the tenant activity feed." }, "RegeneratePdfResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "pdfUrl": { "type": "string", "title": "Pdfurl", "description": "Presigned S3 URL (TTL 30 min) of the regenerated PDF" }, "cacheHit": { "type": "boolean", "title": "Cachehit" }, "valuesHash": { "type": "string", "title": "Valueshash" }, "variablesFilled": { "type": "integer", "title": "Variablesfilled" } }, "type": "object", "required": [ "documentId", "pdfUrl", "cacheHit", "valuesHash", "variablesFilled" ], "title": "RegeneratePdfResponse" }, "RemindResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "signatureId": { "type": "string", "title": "Signatureid" }, "sentAt": { "type": "string", "title": "Sentat" }, "nextAllowedAt": { "type": "string", "title": "Nextallowedat" }, "channel": { "type": "string", "title": "Channel" }, "delivered": { "type": "boolean", "title": "Delivered" } }, "type": "object", "required": [ "documentId", "signatureId", "sentAt", "nextAllowedAt", "channel", "delivered" ], "title": "RemindResponse" }, "ResendOnboardingFillResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "guestUrl": { "type": "string", "title": "Guesturl" } }, "type": "object", "required": [ "success", "guestUrl" ], "title": "ResendOnboardingFillResponse", "description": "Response after resending an invitation." }, "RollbackRequest": { "properties": { "targetVersion": { "type": "integer", "minimum": 1.0, "title": "Targetversion", "description": "Version number to rollback to" } }, "type": "object", "required": [ "targetVersion" ], "title": "RollbackRequest", "description": "Request to rollback a template to a previous version." }, "SecurityTestResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Always true if authenticated" }, "message": { "type": "string", "title": "Message", "description": "Success message" }, "authenticatedUser": { "type": "string", "title": "Authenticateduser", "description": "Email of authenticated user" }, "tenantId": { "type": "string", "title": "Tenantid", "description": "Tenant ID" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes", "description": "Granted scopes" }, "environment": { "type": "string", "title": "Environment", "description": "Key environment" } }, "type": "object", "required": [ "success", "message", "authenticatedUser", "tenantId", "scopes", "environment" ], "title": "SecurityTestResponse", "description": "Response schema for security test endpoint." }, "SignatureFieldCreate": { "properties": { "participantEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Participantemail", "description": "Email of the participant (optional if participantWhatsapp provided)" }, "participantWhatsapp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Participantwhatsapp", "description": "WhatsApp number of the participant (must start with +). Optional if participantEmail provided." }, "pageNumber": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pagenumber", "description": "Page number (1-indexed). For coordinate placement, defaults to page 1 if not provided. For anchorString placement, omit to search the whole document; provide a page number to scope the search to a single page (strict — no cross-page fallback).", "example": 1 }, "pageNumbers": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Pagenumbers", "description": "Specific page numbers (1-indexed) where the field should be placed. Conflicts with includeInAllPages." }, "position": { "anyOf": [ { "$ref": "#/components/schemas/FieldPosition" }, { "type": "null" } ] }, "anchorString": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Anchorstring", "description": "Text anchor to search for in the PDF to position the signature field" }, "includeInAllPages": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Includeinallpages", "default": false }, "excludeFromPages": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Excludefrompages", "description": "List of page numbers to exclude (starting from 1, not 0)", "example": [ 1, 2 ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Height", "description": "Height of the signature field in points. Width is automatically calculated using a 2:1 ratio.", "default": 100, "example": 100 } }, "type": "object", "title": "SignatureFieldCreate" }, "SignatureFieldResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Data" } }, "type": "object", "required": [ "success" ], "title": "SignatureFieldResponse", "description": "Response model for signature field operations" }, "SignatureInfo": { "properties": { "id": { "type": "string", "title": "Id", "description": "Signature ID" }, "status": { "type": "string", "title": "Status", "description": "Signature status (SENT, SIGNED, etc.)" }, "signer": { "$ref": "#/components/schemas/SignerInfo", "description": "Signer information" } }, "type": "object", "required": [ "id", "status", "signer" ], "title": "SignatureInfo", "description": "Signature information for a document." }, "SignerInfo": { "properties": { "id": { "type": "string", "title": "Id", "description": "Signer user ID" }, "email": { "type": "string", "title": "Email", "description": "Signer email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone", "description": "Signer phone (WhatsApp)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Display name set at invitation time" } }, "type": "object", "required": [ "id", "email" ], "title": "SignerInfo", "description": "Signer basic information." }, "SignersData": { "properties": { "id": { "type": "string", "title": "Id", "description": "Signature state ID" }, "status": { "type": "string", "title": "Status", "description": "Overall signature status (TODOS_FIRMARON, RECOLECTANDO_FIRMANTES, etc.)" }, "signatures": { "items": { "$ref": "#/components/schemas/SignatureInfo" }, "type": "array", "title": "Signatures", "description": "List of signatures" }, "signatureValidations": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Signaturevalidations", "description": "Validation flags for this document (autografa, FEA, nom151, firma_biometrica, eIDAS, etc.)" } }, "type": "object", "required": [ "id", "status" ], "title": "SignersData", "description": "Signers data for a document (signature state + signatures)." }, "SimpleDocumentResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Document ID" }, "name": { "type": "string", "title": "Name" }, "pdfBinaryB64": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pdfbinaryb64" }, "pdfHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pdfhash" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat" }, "creditsConsumed": { "type": "integer", "title": "Creditsconsumed" }, "warnings": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmailValidationWarning" }, "type": "array" }, { "type": "null" } ], "title": "Warnings", "description": "Non-blocking validation warnings" } }, "type": "object", "required": [ "id", "name", "createdAt", "creditsConsumed" ], "title": "SimpleDocumentResponse", "description": "Simplified document response." }, "SortOrderEnum": { "type": "string", "enum": [ "asc", "desc" ], "title": "SortOrderEnum", "description": "Sort order options." }, "StartSigningResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "message": { "type": "string", "title": "Message" }, "previousStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previousstatus" }, "currentStatus": { "type": "string", "title": "Currentstatus" }, "creditsConsumed": { "type": "integer", "title": "Creditsconsumed", "default": 0 } }, "type": "object", "required": [ "success", "message", "currentStatus" ], "title": "StartSigningResponse" }, "TeamListMeta": { "properties": { "total": { "type": "integer", "title": "Total", "description": "Total number of team members" } }, "type": "object", "required": [ "total" ], "title": "TeamListMeta" }, "TeamListResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true }, "data": { "items": { "$ref": "#/components/schemas/TeamMemberResponse" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/TeamListMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "TeamListResponse", "description": "Response for listing tenant team members." }, "TeamMemberActivityResponse": { "properties": { "userId": { "type": "string", "title": "Userid" }, "name": { "type": "string", "title": "Name" }, "initials": { "type": "string", "title": "Initials" }, "role": { "type": "string", "title": "Role" }, "sent": { "type": "integer", "title": "Sent", "description": "Documents sent by this member" }, "signed": { "type": "integer", "title": "Signed", "description": "Documents fully signed" }, "rate": { "type": "number", "title": "Rate", "description": "Completion rate percentage" } }, "type": "object", "required": [ "userId", "name", "initials", "role", "sent", "signed", "rate" ], "title": "TeamMemberActivityResponse", "description": "Per-member sending and signing stats." }, "TeamMemberResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "User ID (UUID)" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "email": { "type": "string", "title": "Email", "description": "Email address" }, "role": { "type": "string", "title": "Role", "description": "Tenant role (owner, admin, developer, member, viewer)" } }, "type": "object", "required": [ "id", "name", "email", "role" ], "title": "TeamMemberResponse", "description": "A single tenant team member.", "example": { "email": "pedro@empresa.com", "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Pedro García", "role": "admin" } }, "TemplateDeleteUsage": { "properties": { "documents": { "type": "integer", "title": "Documents", "description": "Active documents referencing this template", "default": 0 }, "chains": { "type": "integer", "title": "Chains", "description": "Document chains referencing this template", "default": 0 } }, "type": "object", "title": "TemplateDeleteUsage", "description": "Usage breakdown returned when a template is in use and cannot be deleted." }, "TemplateEditHistoryResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "prompt": { "type": "string", "title": "Prompt" }, "editType": { "type": "string", "title": "Edittype" }, "aiResponseSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Airesponsesummary" }, "changesCount": { "type": "integer", "title": "Changescount", "default": 0 }, "modelUsed": { "type": "string", "title": "Modelused" }, "tokensInput": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokensinput" }, "tokensOutput": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokensoutput" }, "latencyMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latencyms" }, "status": { "type": "string", "title": "Status" }, "versionBefore": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Versionbefore" }, "versionAfter": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Versionafter" }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Errormessage" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "prompt", "editType", "modelUsed", "status", "createdAt" ], "title": "TemplateEditHistoryResponse", "description": "Response for an AI edit history entry." }, "TemplateVariableInfo": { "properties": { "name": { "type": "string", "title": "Name", "description": "Variable name as written in the DOCX (snake_case)" }, "label": { "type": "string", "title": "Label", "description": "Human-readable label auto-generated from the variable name" }, "type": { "$ref": "#/components/schemas/VariableType", "description": "Variable type for form rendering", "default": "text" }, "required": { "type": "boolean", "title": "Required", "default": true }, "defaultValue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Defaultvalue" } }, "type": "object", "required": [ "name", "label" ], "title": "TemplateVariableInfo", "description": "Information about a single template variable." }, "TemplateVersionResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "versionNumber": { "type": "integer", "title": "Versionnumber" }, "s3Key": { "type": "string", "title": "S3Key" }, "createdBy": { "type": "string", "title": "Createdby", "description": "user, ai, or system" }, "variablesCount": { "type": "integer", "title": "Variablescount", "default": 0 }, "contentHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contenthash" }, "editHistoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Edithistoryid" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "versionNumber", "s3Key", "createdBy", "createdAt" ], "title": "TemplateVersionResponse", "description": "Response for a template version snapshot." }, "TestDataSetCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Display name" }, "values": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Values", "description": "Variable name → value pairs" } }, "type": "object", "required": [ "name", "values" ], "title": "TestDataSetCreateRequest", "description": "Request to create a test data set." }, "TestDataSetResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Test data set UUID" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "values": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Values", "description": "Variable name → value pairs" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "name", "createdAt" ], "title": "TestDataSetResponse", "description": "Response for a single test data set." }, "UpdateSignatureFieldRequest": { "properties": { "fieldId": { "type": "string", "title": "Fieldid", "description": "ID of the signature field to update" }, "signerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signeremail", "description": "Email of the signer (optional if signerPhone provided)" }, "signerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signerphone", "description": "WhatsApp phone of the signer (must start with +). Optional if signerEmail provided." }, "x": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "X", "description": "Updated X coordinate of the signature field" }, "y": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Y", "description": "Updated Y coordinate of the signature field" }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Width", "description": "Updated width of the signature field" }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Height", "description": "Updated height of the signature field" }, "pageNumber": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pagenumber", "description": "Page number (1-based). For anchorString repositioning it is optional: omit to search the whole document (first match), or set it to scope the search to one page." }, "anchorString": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Anchorstring", "description": "Reposition the field onto this text anchor. When provided without x/y, the field is moved to the resolved anchor position (PDF points). Explicit x/y take precedence over anchorString." }, "includeInAllPages": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Includeinallpages", "description": "Whether the signature field should be included in all pages" }, "totalPages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Totalpages", "description": "Total number of pages in the PDF (required when enabling includeInAllPages)" }, "propagateToLinked": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Propagatetolinked", "description": "When true, propagate resize/move changes to all linked fields (parent + copies)", "default": false }, "config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config", "description": "JSONB config for typed fields (placeholder, format, label, required, etc.)" } }, "type": "object", "required": [ "fieldId" ], "title": "UpdateSignatureFieldRequest", "description": "Request model for updating a signature field.\nAt least one of signerEmail or signerPhone must be provided." }, "UserProfileV2Response": { "properties": { "id": { "type": "string", "title": "Id", "description": "User ID" }, "fullName": { "type": "string", "title": "Fullname", "description": "Display-ready full name" }, "email": { "type": "string", "title": "Email", "description": "User email" }, "tenantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenantid", "description": "Tenant ID if available" }, "orgId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Orgid", "description": "Organization ID if available" } }, "type": "object", "required": [ "id", "fullName", "email" ], "title": "UserProfileV2Response", "description": "Lightweight user profile for V2 public APIs.", "example": { "email": "ada@example.com", "fullName": "Ada Lovelace", "id": "550e8400-e29b-41d4-a716-446655440000", "orgId": "7f89e0d1-2345-6789-abcd-ef0123456789", "tenantId": "1e2ec3d4-5b6a-7f89-0123-456789abcdef" } }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VariableAssignment": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "A10 (audit 2026-06): DocumentVariable UUID. When provided, the row is looked up by id (must belong to this document) and the update absorbs scopePdfId — this is the only way to MOVE a variable between scopes (the name+scope lookup treats scope as part of the key, so changing scope without id creates a sibling row instead). Omit for create/upsert-by-name (backwards-compatible behaviour)." }, "variableName": { "type": "string", "title": "Variablename", "description": "Variable name as it appears in the DOCX (e.g. 'nombre_arrendador')." }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Roleid", "description": "DocumentRole UUID this variable is assigned to. null = sender-fixed (filled by the document owner)." }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rolename", "description": "Capa 4: name of the role this variable is assigned to. If provided without role_id, B6 upserts a DocumentRole by name (case-insensitive) and uses its id. Lets the sender assign variables to a role before inviting any signer." }, "scopePdfId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scopepdfid", "description": "vc_0008: when set, the variable is scoped to that document_pdf (compound docs). null = doc-wide (default, value shared across every PDF that uses the same variable_name)." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Human-readable label shown to the signer (defaults to titleized name)." }, "type": { "type": "string", "title": "Type", "description": "Input type: text, date, currency, number, select, textarea, etc.", "default": "text" }, "required": { "type": "boolean", "title": "Required", "description": "Whether the signer must fill this variable.", "default": true }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value", "description": "Pre-filled value. Only meaningful for sender-fixed (roleId=null) vars." }, "validation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Validation", "description": "Validation rules persisted to DocumentVariable.validation JSONB. Recognised keys: maxLength (int), minLength (int), pattern (regex string), helpText (string shown to the signer)." } }, "type": "object", "required": [ "variableName" ], "title": "VariableAssignment" }, "VariableConfigItem": { "properties": { "name": { "type": "string", "title": "Name", "description": "Variable name as written in the DOCX (snake_case)" }, "label": { "type": "string", "title": "Label", "description": "Human-readable label" }, "type": { "$ref": "#/components/schemas/VariableType", "description": "Field type for form rendering", "default": "text" }, "required": { "type": "boolean", "title": "Required", "description": "Whether this variable is required", "default": true }, "defaultValue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Defaultvalue", "description": "Default value for the variable" }, "options": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Options", "description": "Options for 'select' type variables" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "description": "Inferred signer role from variable name prefix/suffix (e.g. 'Arrendador', 'Cliente')" } }, "type": "object", "required": [ "name", "label" ], "title": "VariableConfigItem", "description": "Rich metadata for a single template variable." }, "VariableType": { "type": "string", "enum": [ "text", "date", "currency", "textarea", "select", "number" ], "title": "VariableType", "description": "Supported variable types for template fields." }, "VoidRequest": { "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Reason for voiding" } }, "type": "object", "title": "VoidRequest" }, "VoidResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "success", "message" ], "title": "VoidResponse" }, "WebhookEventCatalogResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/WebhookEventInfo" }, "type": "array", "title": "Events" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "events", "total" ], "title": "WebhookEventCatalogResponse" }, "WebhookEventInfo": { "properties": { "event": { "type": "string", "title": "Event" }, "description": { "type": "string", "title": "Description" }, "category": { "type": "string", "title": "Category" } }, "type": "object", "required": [ "event", "description", "category" ], "title": "WebhookEventInfo" }, "WorkflowStatusResponse": { "properties": { "status": { "type": "string", "title": "Status", "description": "processing | completed | failed" }, "step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Step", "description": "Current pipeline step" }, "progress": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Progress", "description": "Progress 0-100" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Human-readable status" }, "documentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Documentid" }, "creditsConsumed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Creditsconsumed" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message (if failed)" } }, "type": "object", "required": [ "status" ], "title": "WorkflowStatusResponse", "description": "Current status of a document creation workflow." } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Enter your AllSign API key (e.g., allsign_live_sk_xxx)" } } }, "security": [ { "HTTPBearer": [] } ] }