{"openapi":"3.1.0","info":{"title":"doculisto API","version":"1","description":"# Inicio rápido\n\nLa API de doculisto crea documentos para firmar a partir de tus PDF (permisos, consentimientos, contratos…), los envía a las personas que firman y te devuelve el PDF sellado con todas las firmas, más un certificado de auditoría firmado.\n\nTodo pasa por `https://doculisto.mx/v1`, con JSON, y cada petición lleva tu clave:\n\n```http\nAuthorization: Bearer fk_…\n```\n\nLa clave identifica a tu organización y lo que puede hacer (sus permisos). Guárdala en tu servidor: nunca en el navegador ni en una app móvil.\n\n## Sandbox y producción\n\nLas claves de prueba empiezan con `fk_test_` y las de producción con `fk_live_`. Una clave sandbox trabaja sobre su propia organización de prueba, con la API completa, pero lo que crea no puede pasar por un documento real:\n\n- Cada página lleva la marca de agua *PRUEBA · SIN VALIDEZ LEGAL*, también en las copias de un maestro, y el certificado de auditoría dice que es un documento de prueba.\n- Solo envía correos a quien pidió la clave (o a otras direcciones de su dominio, si es el de una empresa). SMS y WhatsApp no están disponibles. Para probar con otras personas usa `\"delivery\": \"none\"` sin `email` y comparte tú el `signing_url`.\n- Crea hasta 10 documentos, de cualquier tipo.\n- No se cobra ni se envía a conservación NOM-151.\n\nCada respuesta de la API trae el encabezado `doculisto-environment` (`sandbox` o `production`), y cada sobre el campo `environment`. Para producción, escríbenos: creamos tu organización de producción con tu configuración de firma integrada y las plantillas que elijas (con identificadores nuevos, que te enviamos junto con la clave `fk_live_`). Los sobres creados en sandbox se quedan ahí, con su marca de agua, y tu clave sandbox sigue funcionando para pruebas.\n\n### Importar plantillas del sandbox\n\nCon la clave de producción puedes traer plantillas del sandbox cuando quieras, una por una: en el editor (*Importar del sandbox*) o por API. `GET /v1/sandbox/templates` lista las del sandbox y si ya las importaste y siguen al día; `POST /v1/templates/import` copia una:\n\n```sh\ncurl https://doculisto.mx/v1/templates/import \\\n  -H \"Authorization: Bearer $DOCULISTO_LIVE_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{ \"sandbox_template_id\": \"tpl_…\" }'\n```\n\nSi la vuelves a importar después de cambiarla en el sandbox, se agregan los cambios como una versión nueva de **la misma** plantilla de producción: su identificador no cambia y tu código sigue funcionando. Solo se copia la plantilla (PDF, firmantes, campos y variables), nunca los sobres. Una clave sandbox no puede importar ni cambiar nada en producción.\n\n> **Probar desde esta página.** El botón *Test Request* de cada endpoint hace peticiones reales a producción con la clave que pegues en *Authentication*. Usa una clave sandbox (pídela en la [página principal](/#sandbox): llega a tu correo y crea hasta 10 documentos). Trabaja sobre una organización de prueba, aislada de los datos reales. Sin clave, las peticiones responden `401`.\n\n## Los conceptos\n\n- **Plantilla:** tu PDF con campos colocados encima y los roles que firman (por ejemplo, `tenant` y `landlord` en un contrato). Se edita como borrador y se publica.\n- **Variables:** campos que llena *tu sistema* al crear el envío (el domicilio, la renta, la fecha de inicio). Los demás campos los llena quien firma.\n- **Sobre (envelope):** un documento concreto para personas concretas, creado desde una plantilla publicada. Tiene un destinatario por rol.\n- **Maestro:** un documento que alguien firma una sola vez y del que salen copias para cada persona, ya con esa firma. Ver *Documentos maestros*.\n\n## Del PDF al documento firmado\n\n**1. Sube el PDF.** doculisto lo revisa y lo normaliza en segundo plano (quita scripts y formularios previos).\n\n```sh\ncurl https://doculisto.mx/v1/templates \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\" \\\n  -F file=@contrato.pdf -F name=\"Contrato de arrendamiento\"\n```\n\nConsulta `GET /v1/templates/{id}` hasta que `latest_version.status` sea `draft`.\n\n**2. Coloca roles y campos, y publica.** Lo más cómodo es el editor web (*Plantillas*), que hace lo mismo que `PUT /v1/templates/{id}/draft`. Las posiciones son fracciones de la página, con origen arriba a la izquierda. Cada rol necesita exactamente un campo de firma.\n\n```sh\ncurl -X POST https://doculisto.mx/v1/templates/tpl_…/publish \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\"\n```\n\nLa respuesta incluye `variables`: lo que tendrás que enviar al crear cada sobre.\n\n**3. Crea el sobre.** Con `send: true`, doculisto avisa a quien firma en cuanto el documento está listo.\n\n```sh\ncurl https://doculisto.mx/v1/envelopes \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n    \"template_id\": \"tpl_…\",\n    \"external_ref\": \"contrato-2026-118\",\n    \"variables\": {\n      \"tenant_name\": \"Daniel Ortega Ruiz\",\n      \"property_address\": \"Av. Universidad 214, depto. 3, Querétaro, Qro.\",\n      \"monthly_rent\": 14500,\n      \"start_date\": \"2026-11-01\"\n    },\n    \"recipients\": [\n      { \"role\": \"tenant\", \"name\": \"Daniel Ortega Ruiz\", \"email\": \"daniel@example.com\", \"delivery\": \"email\" },\n      { \"role\": \"landlord\", \"name\": \"Inmobiliaria Los Arcos\", \"email\": \"contratos@example.com\", \"delivery\": \"email\" }\n    ],\n    \"send\": true\n  }'\n```\n\nCada destinatario trae su `signing_url`. Con `\"delivery\": \"email\"` doculisto se lo manda por correo; con `\"none\"` lo entregas tú (o integras la firma en tu app, ver *Firma integrada*). El enlace es personal: trátalo como una contraseña.\n\n**4. Espera a que se selle.** Consulta `GET /v1/envelopes/{id}`. El estado avanza `preparing` → `ready` → `signing` → `completed` → `sealed`. Cuando está `sealed`, descarga el PDF final y el certificado:\n\n```sh\ncurl -o firmado.pdf     \"https://doculisto.mx/v1/envelopes/env_…/document\"\ncurl -o certificado.pdf \"https://doculisto.mx/v1/envelopes/env_…/document?kind=certificate\"\n```\n\n(Ambos con el encabezado `Authorization`.) Para encontrar un sobre por tu propio identificador usa `GET /v1/envelopes?external_ref=contrato-2026-118`.\n\n## Orden de firma\n\nLos roles tienen `sign_order`. Firman primero los de número menor; los que comparten número firman en paralelo. En un contrato, por ejemplo, el arrendatario y el fiador firman a la vez (`1`) y el arrendador al final (`2`). `is_current_turn` indica a quién le toca.\n\n## Verificación de quien firma\n\nCada rol define cómo se verifica a quien abre su enlace (`auth`): solo con el enlace (`link`) o, además, con un código de 6 dígitos que llega por correo (`email_otp`). SMS y WhatsApp llegarán más adelante.\n\n\n# Firma integrada\n\nMuestra la página de firma dentro de tu propia app con el componente `<doculisto-sign>`: un elemento HTML estándar, sin dependencias, que funciona con cualquier framework. La firma ocurre en un iframe servido por doculisto, así que el texto de consentimiento, la captura de la firma y la evidencia siguen bajo control de doculisto.\n\n## 1. Autoriza el origen de tu app\n\nSolo los orígenes autorizados pueden mostrar la página de firma (HTTPS, salvo `localhost`):\n\n```sh\ncurl -X PUT https://doculisto.mx/v1/settings/embed-origins \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{ \"origins\": [\"https://portal.tuempresa.mx\"] }'\n```\n\n## 2. Pide un token desde tu servidor\n\nCuando la persona ya inició sesión en tu app, tu **backend** pide un token para su rol en el sobre. `client_user_ref` es tu identificador de esa persona y queda en la evidencia, junto con el hecho de que tu sistema la autenticó.\n\n```sh\ncurl -X POST https://doculisto.mx/v1/envelopes/env_…/recipients/tenant/embed \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{ \"client_user_ref\": \"usuario-881\" }'\n```\n\nEl token debe abrirse en los siguientes 10 minutos; una vez abierto, sirve durante una hora. Pide uno nuevo cada vez que muestres la firma.\n\n## 3. Muéstralo en la página\n\n```html\n<script type=\"module\" src=\"https://doculisto.mx/embed/v1.js\"></script>\n\n<doculisto-sign token=\"emb_…\" accent=\"#0a7d4f\"></doculisto-sign>\n\n<script>\n  const firma = document.querySelector(\"doculisto-sign\");\n  firma.addEventListener(\"doculisto:ready\", (e) => console.log(e.detail));    // { envelope_id, can_sign, blocked_reason }\n  firma.addEventListener(\"doculisto:signed\", (e) => console.log(e.detail));   // { envelope_id, role }\n  firma.addEventListener(\"doculisto:declined\", (e) => console.log(e.detail)); // { envelope_id, role }\n  firma.addEventListener(\"doculisto:error\", (e) => console.log(e.detail));    // { code, message }\n</script>\n```\n\n- `accent`: color de los botones, en hexadecimal.\n- El elemento ajusta su altura al contenido.\n- En React 19 basta con `<doculisto-sign token={token} />`; con versiones anteriores, agrega los listeners con un `ref`.\n\n`doculisto:signed` te avisa en el navegador, pero confirma siempre desde tu servidor con `GET /v1/envelopes/{id}` antes de dar algo por firmado.\n\n\n# Firma por API\n\nCuando tu sistema recoge la firma por su cuenta (por ejemplo, en tu app móvil), envíala con `POST /v1/envelopes/{id}/recipients/{role}/sign`. Necesita una clave con el permiso `envelopes:sign`.\n\ndoculisto no vio a la persona firmar, así que tu sistema declara cómo la autenticó (`proof.attestation`). Esa declaración queda en la evidencia, atribuida a tu clave, y el certificado indica que la firma llegó por API.\n\n```sh\ncurl https://doculisto.mx/v1/envelopes/env_…/recipients/tenant/sign \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n    \"fields\": { \"phone\": \"442 000 0000\", \"emergency_contact\": \"Laura Ruiz, 442 111 2222\", \"inventory\": true },\n    \"signature\": { \"type\": \"drawn\", \"strokes\": [[{ \"x\": 0.1, \"y\": 0.6, \"t\": 0 }, { \"x\": 0.4, \"y\": 0.2, \"t\": 30 }]] },\n    \"proof\": {\n      \"attestation\": {\n        \"ip\": \"203.0.113.10\",\n        \"user_agent\": \"MiApp/3.2 (iOS 18)\",\n        \"consented_at\": \"2026-10-08T15:30:00Z\",\n        \"auth_ref\": \"sesion:8f2c\"\n      }\n    }\n  }'\n```\n\n## El trazo de la firma\n\n`signature.strokes` es una lista de trazos; cada trazo, una lista de puntos. `x` e `y` son fracciones del recuadro de firma (de 0 a 1, origen arriba a la izquierda), `t` son milisegundos desde el primer punto y `p`, opcional, la presión del lápiz. Guarda los puntos tal como los capturaste: el ritmo y la presión también son evidencia.\n\n## Con código de verificación\n\nSi el rol tiene `\"api_signing_proof\": \"attestation_otp\"` (en el editor: *Firma por API → Tu sistema + código*), además de tu declaración hace falta un código que recibe quien firma:\n\n1. `POST /v1/envelopes/{id}/recipients/{role}/otp` envía el código y devuelve `challenge_id`.\n2. Pide el código a la persona en tu app.\n3. Incluye `\"otp\": { \"challenge_id\": \"otp_…\", \"code\": \"123456\" }` dentro de `proof` al firmar.\n\nUn código vence a los 10 minutos y admite 5 intentos; después, pide otro. Se pueden pedir hasta 3 códigos cada 15 minutos por destinatario.\n\n## Después de firmar\n\nLa respuesta es `202`: la firma se aplica al PDF en segundo plano. Cuando firma el último rol, el sobre pasa a `completed` y luego a `sealed`.\n\n\n# Documentos maestros\n\nPara documentos que una persona firma una vez y muchas otras firman cada una la suya: la directora firma el permiso de la excursión y cada familia firma su copia; la responsable de un estudio firma el consentimiento y cada participante el suyo.\n\n## En la plantilla\n\n- Marca el rol que firma una sola vez con `\"scope\": \"master\"` (en el editor: *Firma una sola vez*).\n- Marca cada variable como `\"scope\": \"shared\"` (igual en todas las copias, como la versión del protocolo) o `\"per_person\"` (distinta en cada copia, como el nombre de cada participante).\n\n## El flujo\n\n**1. Crea el maestro** con quien firma una vez y las variables compartidas:\n\n```sh\ncurl https://doculisto.mx/v1/masters \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n    \"template_id\": \"tpl_…\",\n    \"title\": \"Estudio de sueño · cohorte otoño 2026\",\n    \"variables\": { \"protocol_version\": \"2.1, 15/09/2026\" },\n    \"recipients\": [{ \"role\": \"study_lead\", \"name\": \"Dra. Elena Ríos Garza\", \"email\": \"elena.rios@example.edu\", \"delivery\": \"email\" }],\n    \"send\": true\n  }'\n```\n\nQuien firma el maestro usa los mismos caminos que en cualquier sobre: su enlace, la firma integrada o la firma por API, con el id del maestro.\n\n**2. Crea un sobre por persona**, hasta 1,000 por llamada, con las variables de cada una:\n\n```sh\ncurl https://doculisto.mx/v1/masters/env_…/envelopes \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\n    \"envelopes\": [\n      { \"external_ref\": \"participante-017\",\n        \"variables\": { \"participant_name\": \"Sofía Márquez León\", \"birth_date\": \"2004-03-18\" },\n        \"recipients\": [{ \"role\": \"participant\", \"name\": \"Sofía Márquez León\", \"email\": \"sofia@example.com\", \"delivery\": \"email\" }] }\n    ]\n  }'\n```\n\nPuedes crearlos antes o después de que se firme el maestro: los que se crean antes esperan (`waiting`) y salen en cuanto está firmado. Cada copia es el PDF del maestro tal cual, con su firma intacta, más los datos y la firma de esa persona.\n\n## Enlace público\n\nCuando no conoces de antemano la lista de personas (participantes de un estudio, inscripciones), activa un enlace público con `PUT /v1/masters/{id}/public-link`. Quien lo abre confirma su correo con un código, llena sus datos y firma su copia. Puedes limitar cuántas personas entran (`max_envelopes`) y hasta cuándo (`closes_at`). Necesita una plantilla con un solo rol que firma cada copia.\n\n`POST /v1/masters/{id}/close` deja de aceptar personas nuevas, por la API o por el enlace; `…/reopen` lo vuelve a abrir.\n\n\n# Verificación y evidencia\n\n## El PDF sellado\n\nCada firma se aplica al PDF como una firma digital PAdES, y al final doculisto lo certifica con el sello de la plataforma. Cualquier lector de PDF (Adobe Acrobat, por ejemplo) muestra las firmas y avisa si el documento cambió después de firmarse. Los campos firmados quedan bloqueados.\n\n## El certificado de auditoría\n\n`GET /v1/envelopes/{id}/document?kind=certificate` devuelve un PDF, también firmado, con quién firmó, en qué rol, cuándo y cómo se verificó a cada persona, las huellas (SHA-256) de los documentos y el último hash de la cadena de eventos.\n\n## La evidencia completa\n\n`GET /v1/envelopes/{id}/evidence` devuelve el registro de eventos del sobre (creado, enviado, abierto, verificado, firmado, sellado…). Cada evento incluye el hash del anterior, así que alterar o borrar uno rompe la cadena. También incluye la evidencia de cada firma: el método, la declaración de tu sistema o los códigos verificados, y la huella de los trazos.\n\nGuarda `documents.final_sha256` en tu sistema: con esa huella puedes demostrar más adelante que un PDF es exactamente el que se selló.\n\n\n# Webhooks\n\nEn vez de consultar cada sobre hasta que cambie, registra una URL de tu servidor y doculisto le envía un `POST` firmado cada vez que algo pasa: alguien abrió el documento, firmó, lo rechazó, o el PDF sellado ya se puede descargar.\n\n## 1. Registra tu endpoint\n\n```sh\ncurl -X POST https://doculisto.mx/v1/webhooks \\\n  -H \"Authorization: Bearer $DOCULISTO_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{ \"url\": \"https://api.tuempresa.mx/doculisto/eventos\", \"events\": [\"envelope.sealed\", \"envelope.declined\", \"recipient.signed\"] }'\n```\n\nLa respuesta incluye `secret` (`whsec_…`). Guárdalo en tu servidor: solo se muestra esta vez. Con `\"events\": [\"*\"]` recibes todos los tipos, también los que se agreguen después. Cada organización puede tener hasta 10 webhooks, y el sandbox tiene los suyos.\n\nPrueba la conexión con `POST /v1/webhooks/{id}/test`: envía un evento `webhook.test` en ese momento y te devuelve lo que contestó tu endpoint.\n\n## 2. Qué recibes\n\n```json\n{\n  \"type\": \"envelope.sealed\",\n  \"timestamp\": \"2026-10-13T17:04:12.381Z\",\n  \"environment\": \"production\",\n  \"data\": {\n    \"envelope\": {\n      \"id\": \"env_7k2m9q4x1c8v3b6n0d5f\",\n      \"kind\": \"standard\",\n      \"master_id\": null,\n      \"title\": \"Contrato de arrendamiento\",\n      \"status\": \"sealed\",\n      \"external_ref\": \"contrato-2291\",\n      \"metadata\": {}\n    },\n    \"documents\": { \"final_sha256\": \"9f2c…\", \"certificate_sha256\": \"4be1…\" }\n  }\n}\n```\n\nLos eventos `recipient.*` incluyen `data.recipient` (rol, nombre, correo y estado), y `recipient.declined` incluye `data.reason`. `data.envelope` es el sobre tal como quedó justo después del evento. Para el detalle completo, consulta `GET /v1/envelopes/{id}`.\n\n| Evento | Cuándo |\n|---|---|\n| `envelope.created` | Se creó un sobre o un maestro, por la API o porque alguien se unió con un enlace público |\n| `envelope.sent` | Empezó la firma: se avisó a los primeros firmantes |\n| `envelope.completed` | Todos firmaron; el documento final se está sellando |\n| `envelope.sealed` | El PDF firmado y el certificado de auditoría están listos para descargar |\n| `envelope.declined` | Un firmante rechazó; el sobre ya no se firmará |\n| `envelope.voided` | Se anuló el sobre |\n| `envelope.failed` | El documento no se pudo preparar o firmar |\n| `recipient.viewed` | Un firmante abrió el documento por primera vez |\n| `recipient.signed` | Un firmante firmó |\n| `recipient.declined` | Un firmante rechazó, con su motivo |\n| `master.opened` | Firmaron el maestro: ya se pueden firmar sus copias |\n| `master.closed` | El maestro dejó de aceptar sobres nuevos |\n| `master.reopened` | El maestro vuelve a aceptar sobres nuevos |\n\nPara descargar los documentos, espera `envelope.sealed`, no `envelope.completed`.\n\n## 3. Verifica la firma\n\nCada entrega trae tres encabezados, según [Standard Webhooks](https://www.standardwebhooks.com):\n\n- `webhook-id`: el id de la entrega (`msg_…`). Es el mismo en cada reintento: úsalo para no procesar dos veces lo mismo.\n- `webhook-timestamp`: cuándo se envió, en segundos Unix. Rechaza los que tengan más de 5 minutos.\n- `webhook-signature`: `v1,` seguido del HMAC-SHA256 en base64 de `{webhook-id}.{webhook-timestamp}.{cuerpo}`. La llave es la parte del secreto después de `whsec_`, decodificada de base64.\n\nLas librerías de Standard Webhooks (`npm i standardwebhooks`, `pip install standardwebhooks` y otras) lo hacen por ti:\n\n```js\nimport { Webhook } from \"standardwebhooks\";\n\nconst wh = new Webhook(process.env.DOCULISTO_WEBHOOK_SECRET);\n\napp.post(\"/doculisto/eventos\", express.raw({ type: \"application/json\" }), (req, res) => {\n  const event = wh.verify(req.body, req.headers); // lanza un error si la firma no coincide\n  // …guarda event y responde rápido\n  res.sendStatus(204);\n});\n```\n\nVerifica con el cuerpo tal como llegó, antes de convertirlo a JSON: cualquier cambio de espacios u orden rompe la firma.\n\n## 4. Responde rápido\n\nResponde con un estado 2xx en menos de 10 segundos; si tienes trabajo largo, encólalo y responde. Cualquier otra respuesta, una redirección o no contestar a tiempo cuenta como fallo, y doculisto reintenta a los 5 segundos, 5 minutos, 30 minutos, 2 horas, 5 horas y dos veces más a las 10 horas: 8 intentos en unas 27 horas.\n\n- Los eventos pueden llegar más de una vez y en distinto orden. Ignora los `webhook-id` que ya procesaste y, si el orden te importa, compara `timestamp` o consulta el sobre.\n- `GET /v1/webhooks/{id}/deliveries` muestra las entregas recientes con lo que contestó tu servidor. `POST …/deliveries/{delivery_id}/retry` reenvía una.\n- `PATCH /v1/webhooks/{id}` con `\"enabled\": false` lo pausa: no se generan eventos nuevos mientras tanto.\n\n## 5. Cambia el secreto\n\n`POST /v1/webhooks/{id}/rotate-secret` crea un secreto nuevo. Durante 24 horas cada entrega va firmada con los dos (`webhook-signature` trae ambas firmas separadas por un espacio), así que puedes actualizar tu servidor sin perder eventos.\n\nLos webhooks requieren el permiso `settings:write`. La URL debe ser HTTPS y pública: doculisto no envía a direcciones privadas ni a `localhost`. Para probar en tu máquina, usa un túnel como `cloudflared` o `ngrok`.\n\n\n# Errores\n\nLos errores siguen el formato *problem details* (RFC 9457), con `Content-Type: application/problem+json`:\n\n```json\n{\n  \"type\": \"https://doculisto.mx/problems/validation_failed\",\n  \"title\": \"validation failed\",\n  \"status\": 422,\n  \"code\": \"validation_failed\",\n  \"detail\": \"The request is invalid\",\n  \"errors\": { \"recipients.0.email\": \"Invalid email address\" }\n}\n```\n\nDecide con `code`, que no cambia; `detail` es un texto para personas y puede cambiar.\n\n| Estado | `code` | Qué pasó |\n|---|---|---|\n| 400 | `invalid_json`, `invalid_form` | El cuerpo no es JSON o formulario válido |\n| 401 | `unauthorized` | Falta la clave, está mal escrita, fue revocada, o es `fk_test_` para producción (o al revés) |\n| 402 | `no_credits` | Tu organización no tiene créditos para documentos nuevos; compra un paquete. Sigue pudiendo consultar y firmar los que ya creó |\n| 403 | `forbidden` | La clave no tiene el permiso que hace falta |\n| 403 | `production_key_required` | Importar plantillas del sandbox requiere la clave de producción (`fk_live_`) |\n| 403 | `sandbox_limit_reached` | La organización sandbox ya creó sus 10 documentos; escríbenos para una clave de producción |\n| 404 | `not_found` | No existe en tu organización |\n| 409 | `invalid_state`, `not_ready`, `template_not_published`… | No se puede en el estado actual |\n| 409 | `too_many_webhooks`, `webhook_disabled` | Ya hay 10 webhooks, o el webhook está pausado y no puede reenviar |\n| 409 | `no_linked_sandbox`, `nothing_to_import` | La organización no viene de un sandbox, o la plantilla del sandbox aún no tiene versión que copiar |\n| 410 | `code_expired` | El código venció; pide otro |\n| 413 | `file_too_large` | El PDF pasa de 25 MB |\n| 422 | `validation_failed`, `not_a_pdf`, `otp_required` | La petición no es válida; `errors` indica cada campo |\n| 422 | `sandbox_recipient_not_allowed` | Una clave sandbox solo envía a quien la pidió; `errors` indica qué destinatario |\n| 429 | `too_many_attempts`, `too_many_requests` | Demasiados intentos o códigos; espera unos minutos |\n\n## Permisos\n\n| Permiso | Permite |\n|---|---|\n| `templates:read` | Ver plantillas y sus PDF |\n| `templates:write` | Subir, editar y publicar plantillas |\n| `envelopes:read` | Ver sobres, maestros, documentos y evidencia |\n| `envelopes:write` | Crear, enviar y anular sobres y maestros; tokens de firma integrada |\n| `envelopes:sign` | Firmar por API y enviar códigos |\n| `settings:write` | Cambiar la configuración de la organización y administrar webhooks |\n","contact":{"name":"Bekind Software","url":"https://bekind.software"}},"servers":[{"url":"https://doculisto.mx","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Templates","description":"Upload PDFs, place fields and signers, publish."},{"name":"Envelopes","description":"A document sent to specific people to sign, created from a published template."},{"name":"Signing","description":"Embed the signing page in your app, or sign through the API."},{"name":"Masters","description":"Documents signed once and copied for each person: consent forms, permission slips."},{"name":"Webhooks","description":"Signed notifications to your server when envelopes change. Every delivery's body is a `WebhookEvent`. Event types:\n\n- `envelope.created`: An envelope or master was created, by the API or by someone joining through a public link\n- `envelope.sent`: Signing started: the first signers were notified\n- `envelope.completed`: Everyone signed; the final document is being sealed\n- `envelope.sealed`: The signed PDF and the audit certificate are ready to download\n- `envelope.declined`: A signer declined; the envelope will not be signed\n- `envelope.voided`: The envelope was voided\n- `envelope.failed`: The document could not be prepared or signed\n- `recipient.viewed`: A signer opened the document for the first time\n- `recipient.signed`: A signer signed\n- `recipient.declined`: A signer declined, with their reason\n- `master.opened`: The master's signers finished: its copies can be signed\n- `master.closed`: The master stopped accepting new envelopes\n- `master.reopened`: The master accepts new envelopes again"},{"name":"Settings","description":"Organisation settings."}],"paths":{"/v1/templates":{"get":{"operationId":"listTemplates","tags":["Templates"],"summary":"List templates","description":"The 100 most recent templates, newest first.\n\nPermission: `templates:read`.","responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"uploadAPdf","tags":["Templates"],"summary":"Upload a PDF","description":"Creates a template from a PDF. The document is checked and normalised in the background (scripts and existing form fields are removed): poll the template until `latest_version.status` is `draft`, then set roles and fields with `PUT /v1/templates/{id}/draft`.\n\nPermission: `templates:write`.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The PDF, up to 25 MB"},"name":{"type":"string","maxLength":200,"description":"Defaults to the file name"}}}}}},"responses":{"202":{"description":"Template created; the PDF is being processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/v1/templates/{id}":{"get":{"operationId":"getATemplate","tags":["Templates"],"summary":"Get a template","description":"Includes the latest version and `variables`: what to send when creating an envelope from it.\n\nPermission: `templates:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Template id (`tpl_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/templates/{id}/document":{"get":{"operationId":"downloadTheTemplatePdf","tags":["Templates"],"summary":"Download the template PDF","description":"The normalised PDF of the latest version, which field positions refer to.\n\nPermission: `templates:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Template id (`tpl_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/templates/{id}/draft":{"put":{"operationId":"setRolesAndFields","tags":["Templates"],"summary":"Set roles and fields","description":"Replaces the draft's roles and fields. Each role needs exactly one signature field. If the latest version is published, this starts a new draft; envelopes keep using the published version until you publish again.\n\nPermission: `templates:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Template id (`tpl_…`)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDraft"},"example":{"roles":[{"key":"tenant","label":"Arrendatario","sign_order":1},{"key":"landlord","label":"Arrendador","sign_order":2}],"fields":[{"key":"monthly_rent","type":"number","filled_by":"api","label":"Renta mensual","rect":{"page":0,"x":0.12,"y":0.3,"w":0.2,"h":0.03}},{"key":"signature","type":"signature","filled_by":"signer","role":"tenant","rect":{"page":1,"x":0.12,"y":0.4,"w":0.3,"h":0.07}},{"key":"signature","type":"signature","filled_by":"signer","role":"landlord","rect":{"page":1,"x":0.55,"y":0.4,"w":0.3,"h":0.07}}]}}}},"responses":{"200":{"description":"The template with the updated draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/v1/templates/{id}/publish":{"post":{"operationId":"publishTheDraft","tags":["Templates"],"summary":"Publish the draft","description":"Freezes the draft as the version new envelopes are created from.\n\nPermission: `templates:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Template id (`tpl_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The published template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/sandbox/templates":{"get":{"operationId":"listSandboxTemplates","tags":["Templates"],"summary":"List sandbox templates","description":"For an organization promoted from a sandbox, with a production key: the sandbox's templates that can be imported, and whether each is already imported and up to date. `409 no_linked_sandbox` if the organization did not come from a sandbox; `403 production_key_required` with a sandbox key.\n\nPermission: `templates:read`.","responses":{"200":{"description":"Sandbox templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxTemplateList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/templates/import":{"post":{"operationId":"importATemplateFromTheSandbox","tags":["Templates"],"summary":"Import a template from the sandbox","description":"Copies one sandbox template into production, with a production key: the PDF, roles, fields and variables of its published version, and its newer draft if there is one. Importing the same template again adds the changes as new versions of the same production template, so its id does not change. Envelopes are never copied.\n\nPermission: `templates:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportTemplate"},"example":{"sandbox_template_id":"tpl_7k2m9q4x1c8v3b6n0d5f"}}}},"responses":{"200":{"description":"The production template and what changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateImport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/v1/envelopes":{"post":{"operationId":"createAnEnvelope","tags":["Envelopes"],"summary":"Create an envelope","description":"Creates a document to sign from a published template, with one recipient per role. The document is prepared in the background (status `preparing`, then `ready`). With `send: true` signing starts as soon as it is ready; otherwise call `POST /v1/envelopes/{id}/send`. The response includes each recipient's `signing_url`.\n\nPermission: `envelopes:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnvelope"},"example":{"template_id":"tpl_8m2kq4x7v1d9c3r6b5n0","title":"Arrendamiento · Av. Universidad 214, depto. 3","external_ref":"contrato-2026-118","variables":{"landlord_name":"Inmobiliaria Los Arcos, S.A. de C.V.","tenant_name":"Daniel Ortega Ruiz","guarantor_name":"Laura Ruiz Méndez","property_address":"Av. Universidad 214, depto. 3, Querétaro, Qro.","monthly_rent":14500,"deposit":14500,"start_date":"2026-11-01","term_months":12},"recipients":[{"role":"tenant","name":"Daniel Ortega Ruiz","email":"daniel@example.com","delivery":"email"},{"role":"guarantor","name":"Laura Ruiz Méndez","email":"laura@example.com","delivery":"email"},{"role":"landlord","name":"Inmobiliaria Los Arcos","email":"contratos@example.com","delivery":"email"}],"send":true}}}},"responses":{"201":{"description":"Envelope created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/NoCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}},"get":{"operationId":"listEnvelopes","tags":["Envelopes"],"summary":"List envelopes","description":"The 100 most recent envelopes, newest first.\n\nPermission: `envelopes:read`.","parameters":[{"name":"external_ref","in":"query","required":false,"description":"Only envelopes with this `external_ref`","schema":{"type":"string"}}],"responses":{"200":{"description":"Envelopes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/envelopes/{id}":{"get":{"operationId":"getAnEnvelope","tags":["Envelopes"],"summary":"Get an envelope","description":"Permission: `envelopes:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Envelope id (`env_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/envelopes/{id}/send":{"post":{"operationId":"startSigning","tags":["Envelopes"],"summary":"Start signing","description":"Notifies the first signers. If the document is still being prepared, signing starts as soon as it is ready.\n\nPermission: `envelopes:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Envelope id (`env_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/envelopes/{id}/void":{"post":{"operationId":"voidAnEnvelope","tags":["Envelopes"],"summary":"Void an envelope","description":"Cancels an envelope that is not finished. Voiding a master also voids its envelopes that are waiting for it.\n\nPermission: `envelopes:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Envelope id (`env_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The voided envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/envelopes/{id}/document":{"get":{"operationId":"downloadAPdf","tags":["Envelopes"],"summary":"Download a PDF","description":"`final`: the sealed document with every signature (the default once sealed). `current`: the document as signed so far. `prepared`: before anyone signed. `certificate`: the signed audit certificate.\n\nPermission: `envelopes:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Envelope id (`env_…`)","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"Which document","schema":{"type":"string","enum":["final","current","prepared","certificate"]}}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/envelopes/{id}/evidence":{"get":{"operationId":"getTheEvidence","tags":["Envelopes"],"summary":"Get the evidence","description":"The hash-chained event log and each signature's evidence: method, attestation, codes and fingerprints of the stroke data.\n\nPermission: `envelopes:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Envelope id (`env_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"Evidence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evidence"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/envelopes/{id}/recipients/{role}/embed":{"post":{"operationId":"createAnEmbedToken","tags":["Signing"],"summary":"Create an embed token","description":"A token for showing the signing page inside your app with `<doculisto-sign token=\"…\">`. Open it within 10 minutes; it then works for 60. The signature is recorded as verified by your login, with `client_user_ref`. Call it from your backend, never the browser. Your app's origin must be allowed first (`PUT /v1/settings/embed-origins`).\n\nPermission: `envelopes:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Envelope id (`env_…`)","schema":{"type":"string"}},{"name":"role","in":"path","required":true,"description":"The recipient's role key from the template, e.g. `tenant`","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmbedToken"},"example":{"client_user_ref":"user-881"}}}},"responses":{"201":{"description":"Embed token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedToken"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/v1/envelopes/{id}/recipients/{role}/sign":{"post":{"operationId":"signThroughTheApi","tags":["Signing"],"summary":"Sign through the API","description":"Signs on the recipient's behalf when your system collected the signature, for example in your own app. `proof.attestation` records how you authenticated the signer. If the role's `api_signing_proof` is `attestation_otp`, first send the signer a code with `POST …/otp` and include it in `proof.otp`.\n\nPermission: `envelopes:sign`.","parameters":[{"name":"id","in":"path","required":true,"description":"Envelope id (`env_…`)","schema":{"type":"string"}},{"name":"role","in":"path","required":true,"description":"The recipient's role key from the template, e.g. `tenant`","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSignRequest"},"example":{"fields":{"phone":"442 000 0000","emergency_contact":"Laura Ruiz, 442 111 2222","inventory":true},"signature":{"type":"drawn","strokes":[[{"x":0.1,"y":0.6,"t":0},{"x":0.4,"y":0.2,"t":30},{"x":0.8,"y":0.7,"t":60}]]},"proof":{"attestation":{"ip":"203.0.113.10","user_agent":"Mozilla/5.0 …","consented_at":"2026-10-08T15:30:00Z","auth_ref":"session:8f2c"}}}}}},"responses":{"202":{"description":"Signature accepted; it is applied to the PDF in the background","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/Gone"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyAttempts"}}}},"/v1/envelopes/{id}/recipients/{role}/otp":{"post":{"operationId":"sendTheSignerACode","tags":["Signing"],"summary":"Send the signer a code","description":"For roles that require `attestation_otp`: sends the signer a 6-digit code to include in `POST …/sign`.\n\nPermission: `envelopes:sign`.","parameters":[{"name":"id","in":"path","required":true,"description":"Envelope id (`env_…`)","schema":{"type":"string"}},{"name":"role","in":"path","required":true,"description":"The recipient's role key from the template, e.g. `tenant`","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestOtp"}}}},"responses":{"202":{"description":"Code sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpChallenge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/v1/masters":{"post":{"operationId":"createAMaster","tags":["Masters"],"summary":"Create a master","description":"A master is signed once by the template's `master` roles (a principal, a research lead); then each person gets their own envelope that already carries that signature. Send `recipients` for the master roles and the `shared` variables. Its signers use the envelope endpoints with the master's id.\n\nPermission: `envelopes:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMaster"},"example":{"template_id":"tpl_8m2kq4x7v1d9c3r6b5n0","title":"Estudio de sueño · cohorte otoño 2026","variables":{"protocol_version":"2.1, 15/09/2026"},"recipients":[{"role":"study_lead","name":"Dra. Elena Ríos Garza","email":"elena.rios@example.edu","delivery":"email"}],"send":true}}}},"responses":{"201":{"description":"Master created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Master"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}},"get":{"operationId":"listMasters","tags":["Masters"],"summary":"List masters","description":"Permission: `envelopes:read`.","responses":{"200":{"description":"Masters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/masters/{id}":{"get":{"operationId":"getAMaster","tags":["Masters"],"summary":"Get a master","description":"Permission: `envelopes:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Master id (`env_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The master","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Master"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/masters/{id}/envelopes":{"post":{"operationId":"createEnvelopesFromAMaster","tags":["Masters"],"summary":"Create envelopes from a master","description":"One envelope per person, up to 1,000 per call, each with the per-person variables and its own recipients. Envelopes created before the master is signed wait for it.\n\nPermission: `envelopes:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Master id (`env_…`)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMasterEnvelopes"},"example":{"envelopes":[{"external_ref":"participante-017","variables":{"participant_name":"Sofía Márquez León","birth_date":"2004-03-18"},"recipients":[{"role":"participant","name":"Sofía Márquez León","email":"sofia@example.com","delivery":"email"}]}]}}}},"responses":{"201":{"description":"Envelopes created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedEnvelopes"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/NoCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}},"get":{"operationId":"listAMastersEnvelopes","tags":["Masters"],"summary":"List a master's envelopes","description":"Up to 1,000, newest first, with each person's variables and signing status.\n\nPermission: `envelopes:read`.","parameters":[{"name":"id","in":"path","required":true,"description":"Master id (`env_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"Envelopes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterEnvelopeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/masters/{id}/close":{"post":{"operationId":"closeAMaster","tags":["Masters"],"summary":"Close a master","description":"Stops creating new envelopes from the master, including from its public link. Existing envelopes are unaffected.\n\nPermission: `envelopes:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Master id (`env_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The master","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Master"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/masters/{id}/reopen":{"post":{"operationId":"reopenAMaster","tags":["Masters"],"summary":"Reopen a master","description":"Permission: `envelopes:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Master id (`env_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The master","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Master"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/masters/{id}/public-link":{"put":{"operationId":"turnThePublicLinkOnOrOff","tags":["Masters"],"summary":"Turn the public link on or off","description":"A link anyone can open to join: they confirm their email with a code, fill in the per-person variables and sign their own copy. Needs a template with exactly one role that signs each copy.\n\nPermission: `envelopes:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Master id (`env_…`)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicLinkSettings"},"example":{"enabled":true,"max_envelopes":40,"closes_at":"2026-11-10T23:59:00Z"}}}},"responses":{"200":{"description":"The master, with `public_link`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Master"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/v1/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhooks","description":"Permission: `settings:write`.","responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createAWebhook","tags":["Webhooks"],"summary":"Create a webhook","description":"Sends a signed `POST` to `url` for each event of the types in `events`. The response includes the `secret` for verifying them; it is shown only here. Up to 10 per organization (`409 too_many_webhooks`).\n\nPermission: `settings:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhook"},"example":{"url":"https://api.example.com/doculisto/events","events":["envelope.sealed","envelope.declined","recipient.signed"],"description":"Producción"}}}},"responses":{"201":{"description":"Webhook created, with its secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecret"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/v1/webhooks/{id}":{"get":{"operationId":"getAWebhook","tags":["Webhooks"],"summary":"Get a webhook","description":"Permission: `settings:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`whk_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateAWebhook","tags":["Webhooks"],"summary":"Update a webhook","description":"Changes only what you send. `enabled: false` pauses it.\n\nPermission: `settings:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`whk_…`)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhook"},"example":{"events":["*"]}}}},"responses":{"200":{"description":"The webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"}}},"delete":{"operationId":"deleteAWebhook","tags":["Webhooks"],"summary":"Delete a webhook","description":"Deletes it and its delivery history. Events still pending are not sent.\n\nPermission: `settings:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`whk_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedWebhook"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/webhooks/{id}/rotate-secret":{"post":{"operationId":"rotateTheSecret","tags":["Webhooks"],"summary":"Rotate the secret","description":"Creates a new secret and returns it. For 24 hours deliveries are signed with both, so `webhook-signature` carries two signatures and either one verifies.\n\nPermission: `settings:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`whk_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The webhook, with its new secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecret"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/webhooks/{id}/test":{"post":{"operationId":"sendATestEvent","tags":["Webhooks"],"summary":"Send a test event","description":"Sends a `webhook.test` event now and returns what your endpoint answered, in `last_status` and `last_error`. It is not retried.\n\nPermission: `settings:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`whk_…`)","schema":{"type":"string"}}],"responses":{"200":{"description":"The test delivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/webhooks/{id}/deliveries":{"get":{"operationId":"listDeliveries","tags":["Webhooks"],"summary":"List deliveries","description":"The 100 most recent deliveries, newest first, with each one's payload and last attempt.\n\nPermission: `settings:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`whk_…`)","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only deliveries in this state","schema":{"type":"string","enum":["pending","delivered","failed"]}}],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/webhooks/{id}/deliveries/{delivery_id}/retry":{"post":{"operationId":"retryADelivery","tags":["Webhooks"],"summary":"Retry a delivery","description":"Sends a delivered or failed delivery once more, with the same `webhook-id`. `409 webhook_disabled` if the webhook is disabled.\n\nPermission: `settings:write`.","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id (`whk_…`)","schema":{"type":"string"}},{"name":"delivery_id","in":"path","required":true,"description":"Delivery id (`msg_…`), the `webhook-id` it was sent with","schema":{"type":"string"}}],"responses":{"202":{"description":"The delivery, queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/organization":{"get":{"operationId":"getTheOrganization","tags":["Settings"],"summary":"Get the organization","description":"The organization the key belongs to: its name, whether it is a `sandbox` or `production`, how many documents it has created (and may create, in a sandbox), and its credits. Any valid key can read it.","responses":{"200":{"description":"The organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/settings/embed-origins":{"get":{"operationId":"listEmbedOrigins","tags":["Settings"],"summary":"List embed origins","description":"The origins allowed to embed the signing page.","responses":{"200":{"description":"Origins","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedOriginList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"operationId":"setEmbedOrigins","tags":["Settings"],"summary":"Set embed origins","description":"Replaces the origins allowed to embed the signing page (HTTPS, except `localhost`).\n\nPermission: `settings:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedOrigins"},"example":{"origins":["https://portal.example.com"]}}}},"responses":{"200":{"description":"Origins","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedOriginList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"fk_…","description":"Your organisation's API key: `Authorization: Bearer fk_…`. Keep it on your server."}},"schemas":{"TemplateDraft":{"type":"object","properties":{"roles":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,47}$","description":"Used as `role` in recipients and in URLs, e.g. `parent`"},"label":{"type":"string","minLength":1,"maxLength":80,"description":"Shown to people, e.g. \"Madre, padre o tutor\""},"sign_order":{"default":1,"description":"Lower numbers sign first; roles with the same number sign in parallel","type":"integer","minimum":1,"maximum":20},"auth":{"default":["link"],"description":"Verification methods accepted on the signing page (any one is enough).","minItems":1,"type":"array","items":{"type":"string","enum":["link","email_otp","sms_otp","whatsapp_otp","sso"]}},"api_signing_proof":{"default":"attestation","description":"What a client must prove when signing for this role through the API.","type":"string","enum":["attestation","attestation_otp"]},"scope":{"default":"envelope","description":"`master`: signs once, on the master document, before anyone else; every envelope created from that master carries the signature. `envelope` (default): signs each envelope.","type":"string","enum":["envelope","master"]}},"required":["key","label"]}},"fields":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,47}$","description":"Variables: the key in `variables`. Signer fields: the key in `fields`, unique per role."},"type":{"type":"string","enum":["signature","text","date","number","checkbox","radio","dropdown"]},"filled_by":{"type":"string","enum":["api","signer"],"description":"`api` = a variable filled when the envelope is created; `signer` = filled while signing."},"role":{"description":"Required for signer fields; ignored for api fields.","type":"string","pattern":"^[a-z][a-z0-9_]{0,47}$"},"label":{"description":"Shown to signers next to the field","type":"string","maxLength":120},"scope":{"description":"For api-filled variables used with masters: `shared` values are drawn into the master before it is signed; `per_person` values are filled into each copy afterwards. Individual envelopes draw both. Default `shared`.","type":"string","enum":["shared","per_person"]},"required":{"default":true,"type":"boolean"},"options":{"description":"Choices, for radio and dropdown fields","minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"align":{"description":"How the value sits across the box: `left` (default), `center`, `right` or `justify`","type":"string","enum":["left","center","right","justify"]},"valign":{"description":"Where the value sits in a tall box: `top`, `middle` (default) or `bottom`","type":"string","enum":["top","middle","bottom"]},"rect":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"maximum":9007199254740991},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1}},"required":["page","x","y","w","h"]}},"required":["key","type","filled_by","rect"]}}},"required":["roles","fields"]},"CreateEnvelope":{"type":"object","properties":{"template_id":{"type":"string","pattern":"^tpl_.*"},"title":{"description":"Defaults to the template name","type":"string","minLength":1,"maxLength":200},"locale":{"default":"es","description":"Language of the signing page, emails and certificate","type":"string","enum":["es","en"]},"external_ref":{"description":"Your own id for this envelope; filter with `GET /v1/envelopes?external_ref=`","type":"string","maxLength":200},"metadata":{"description":"Your own key–value data, returned as is","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","maxLength":500}},"variables":{"default":{},"description":"Values for the template's variables, by key (see `variables` on the template)","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"recipients":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/components/schemas/RecipientInput"},"description":"One per template role"},"send":{"default":false,"description":"Deliver links to the first signers as soon as the document is prepared.","type":"boolean"},"expires_at":{"description":"After this, the envelope can no longer be signed","type":"string","format":"date-time"}},"required":["template_id","recipients"]},"RecipientInput":{"type":"object","properties":{"role":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,47}$","description":"A role key from the template"},"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","format":"email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{7,14}$"},"auth":{"description":"Narrows the template's accepted methods for this recipient.","minItems":1,"type":"array","items":{"type":"string","enum":["link","email_otp","sms_otp","whatsapp_otp","sso"]}},"delivery":{"default":"none","description":"How doculisto delivers the signing link. `none`: you deliver `signing_url` yourself or embed signing. Only `email` and `none` are available today.","type":"string","enum":["email","sms","whatsapp","none"]}},"required":["role","name"]},"CreateEmbedToken":{"type":"object","properties":{"client_user_ref":{"description":"The signer's id in the client's own system, recorded as evidence.","type":"string","minLength":1,"maxLength":200}}},"ApiSignRequest":{"type":"object","properties":{"fields":{"default":{},"description":"Values for this role's fields, by key","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"signature":{"type":"object","properties":{"type":{"type":"string","const":"drawn"},"strokes":{"minItems":1,"maxItems":200,"type":"array","items":{"minItems":1,"maxItems":5000,"type":"array","items":{"type":"object","properties":{"x":{"type":"number","minimum":0,"maximum":1,"description":"Fractions of the signature box, top-left origin."},"y":{"type":"number","minimum":0,"maximum":1},"t":{"type":"number","minimum":0,"description":"Milliseconds since the first point of the signature."},"p":{"description":"Pen pressure 0–1 when the device reports it.","type":"number","minimum":0,"maximum":1}},"required":["x","y","t"]}}}},"required":["type","strokes"]},"proof":{"type":"object","properties":{"attestation":{"type":"object","properties":{"ip":{"type":"string","minLength":1,"maxLength":100,"description":"The signer's IP address, as your system saw it"},"user_agent":{"type":"string","minLength":1,"maxLength":1000,"description":"The signer's browser or app"},"consented_at":{"type":"string","format":"date-time","description":"When the signer agreed to sign electronically"},"auth_ref":{"type":"string","minLength":1,"maxLength":200,"description":"How your system authenticated the signer, e.g. a session or user id"}},"required":["ip","user_agent","consented_at","auth_ref"],"description":"Your system's statement of who signed and how they were authenticated; recorded as evidence"},"otp":{"description":"Required when the role's `api_signing_proof` is `attestation_otp`: the code the signer received","type":"object","properties":{"challenge_id":{"type":"string"},"code":{"type":"string","pattern":"^\\d{6}$"}},"required":["challenge_id","code"]}},"required":["attestation"]}},"required":["signature","proof"]},"RequestOtp":{"type":"object","properties":{"channel":{"default":"email","description":"Only `email` is available today","type":"string","enum":["email","sms","whatsapp"]}}},"CreateMaster":{"type":"object","properties":{"template_id":{"type":"string","pattern":"^tpl_.*"},"title":{"type":"string","minLength":1,"maxLength":200},"locale":{"default":"es","type":"string","enum":["es","en"]},"external_ref":{"type":"string","maxLength":200},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","maxLength":500}},"variables":{"default":{},"description":"Values for the template's shared variables.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"recipients":{"minItems":1,"maxItems":5,"type":"array","items":{"$ref":"#/components/schemas/RecipientInput"},"description":"The people who sign once: one per master-scoped role."},"send":{"default":false,"type":"boolean"}},"required":["template_id","recipients"]},"CreateMasterEnvelopes":{"type":"object","properties":{"envelopes":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"external_ref":{"type":"string","maxLength":200},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","maxLength":500}},"variables":{"default":{},"description":"Values for the template's per-person variables.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"recipients":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/components/schemas/RecipientInput"},"description":"One per envelope-scoped role."},"expires_at":{"type":"string","format":"date-time"}},"required":["recipients"]}},"send":{"default":true,"description":"Deliver links as soon as each envelope is ready (after the master is signed).","type":"boolean"}},"required":["envelopes"]},"PublicLinkSettings":{"type":"object","properties":{"enabled":{"type":"boolean"},"max_envelopes":{"description":"Stop accepting new people after this many envelopes from the link.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"closes_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["enabled"]},"EmbedOrigins":{"type":"object","properties":{"origins":{"maxItems":20,"type":"array","items":{"type":"string"}}},"required":["origins"]},"ImportTemplate":{"type":"object","properties":{"sandbox_template_id":{"type":"string","pattern":"^tpl_.*"}},"required":["sandbox_template_id"]},"CreateWebhook":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"description":"Where to POST events. HTTPS; plain HTTP and private addresses only from a local doculisto."},"events":{"minItems":1,"type":"array","items":{"anyOf":[{"type":"string","enum":["envelope.created","envelope.sent","envelope.completed","envelope.sealed","envelope.declined","envelope.voided","envelope.failed","recipient.viewed","recipient.signed","recipient.declined","master.opened","master.closed","master.reopened"]},{"type":"string","const":"*"}]},"description":"Event types to send, or `[\"*\"]` for all of them, including types added later"},"description":{"type":"string","maxLength":200}},"required":["url","events"]},"UpdateWebhook":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"description":"Where to POST events. HTTPS; plain HTTP and private addresses only from a local doculisto."},"events":{"minItems":1,"type":"array","items":{"anyOf":[{"type":"string","enum":["envelope.created","envelope.sent","envelope.completed","envelope.sealed","envelope.declined","envelope.voided","envelope.failed","recipient.viewed","recipient.signed","recipient.declined","master.opened","master.closed","master.reopened"]},{"type":"string","const":"*"}]},"description":"Event types to send, or `[\"*\"]` for all of them, including types added later"},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"enabled":{"description":"A disabled webhook gets no new events; those already pending are sent if it is enabled again","type":"boolean"}}},"Template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"current_version_id":{"description":"The published version envelopes are created from; null until the first publish","type":["string","null"]},"latest_version":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["ingesting","draft","published","failed"],"description":"`ingesting` while the PDF is checked and normalised; then `draft` until published. `failed` if the PDF could not be processed."},"pages":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0},"rotate":{"anyOf":[{"type":"number","const":0},{"type":"number","const":90},{"type":"number","const":180},{"type":"number","const":270}]}},"required":["width","height","rotate"],"additionalProperties":false}},{"type":"null"}],"description":"Page sizes in PDF points; null while ingesting"},"roles":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,47}$","description":"Used as `role` in recipients and in URLs, e.g. `parent`"},"label":{"type":"string","minLength":1,"maxLength":80,"description":"Shown to people, e.g. \"Madre, padre o tutor\""},"sign_order":{"default":1,"description":"Lower numbers sign first; roles with the same number sign in parallel","type":"integer","minimum":1,"maximum":20},"auth":{"default":["link"],"description":"Verification methods accepted on the signing page (any one is enough).","minItems":1,"type":"array","items":{"type":"string","enum":["link","email_otp","sms_otp","whatsapp_otp","sso"]}},"api_signing_proof":{"default":"attestation","description":"What a client must prove when signing for this role through the API.","type":"string","enum":["attestation","attestation_otp"]},"scope":{"default":"envelope","description":"`master`: signs once, on the master document, before anyone else; every envelope created from that master carries the signature. `envelope` (default): signs each envelope.","type":"string","enum":["envelope","master"]}},"required":["key","label","sign_order","auth","api_signing_proof","scope"],"additionalProperties":false}},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,47}$","description":"Variables: the key in `variables`. Signer fields: the key in `fields`, unique per role."},"type":{"type":"string","enum":["signature","text","date","number","checkbox","radio","dropdown"]},"filled_by":{"type":"string","enum":["api","signer"],"description":"`api` = a variable filled when the envelope is created; `signer` = filled while signing."},"role":{"description":"Required for signer fields; ignored for api fields.","type":"string","pattern":"^[a-z][a-z0-9_]{0,47}$"},"label":{"description":"Shown to signers next to the field","type":"string","maxLength":120},"scope":{"description":"For api-filled variables used with masters: `shared` values are drawn into the master before it is signed; `per_person` values are filled into each copy afterwards. Individual envelopes draw both. Default `shared`.","type":"string","enum":["shared","per_person"]},"required":{"default":true,"type":"boolean"},"options":{"description":"Choices, for radio and dropdown fields","minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"align":{"description":"How the value sits across the box: `left` (default), `center`, `right` or `justify`","type":"string","enum":["left","center","right","justify"]},"valign":{"description":"Where the value sits in a tall box: `top`, `middle` (default) or `bottom`","type":"string","enum":["top","middle","bottom"]},"rect":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"maximum":9007199254740991},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1}},"required":["page","x","y","w","h"],"additionalProperties":false}},"required":["key","type","filled_by","required","rect"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"},"description":"What was removed or changed while normalising the PDF (scripts, existing form fields…)"},"error":{"type":["string","null"]},"source_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","version","status","pages","roles","fields","warnings","error","source_sha256","published_at"],"additionalProperties":false},"variables":{"description":"What to send as `variables` when creating an envelope","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string","enum":["signature","text","date","number","checkbox","radio","dropdown"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"label":{"type":"string"},"scope":{"type":"string","enum":["shared","per_person"]}},"required":["key","type","required","scope"],"additionalProperties":false}},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","current_version_id","created_at"],"additionalProperties":false},"TemplateList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}},"required":["data"],"additionalProperties":false},"Envelope":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["standard","master","child"],"description":"`child` envelopes were created from a master and carry its signature"},"environment":{"type":"string","enum":["sandbox","production"],"description":"`sandbox` documents carry a watermark and have no legal validity"},"master_id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["preparing","ready","signing","completed","sealed","failed","voided","expired","declined","waiting","open","closed"]},"locale":{"type":"string","enum":["es","en"]},"external_ref":{"type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"template_version_id":{"type":"string"},"documents":{"type":"object","properties":{"prepared_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"current_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"final_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"certificate_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]}},"required":["prepared_sha256","current_sha256","final_sha256","certificate_sha256"],"additionalProperties":false},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"sign_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","notified","viewed","verified","signed","declined"]},"is_current_turn":{"type":"boolean","description":"True while the envelope is waiting for this recipient's signature"},"signed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signing_url":{"description":"The recipient's personal signing link. Returned when the envelope is created; treat it as a secret.","type":"string","format":"uri"}},"required":["id","role","name","email","phone","sign_order","status","is_current_turn","signed_at"],"additionalProperties":false}},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"signer_values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Values each signer filled in, by role"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"sealed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","kind","environment","title","status","locale","external_ref","metadata","template_version_id","documents","recipients","variables","signer_values","created_at","completed_at","sealed_at","expires_at"],"additionalProperties":false},"EnvelopeList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["preparing","ready","signing","completed","sealed","failed","voided","expired","declined","waiting","open","closed"]},"external_ref":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","title","status","external_ref","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"Evidence":{"type":"object","properties":{"envelope_id":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"type":{"type":"string","description":"e.g. `envelope.created`, `recipient.viewed`, `recipient.signed`, `envelope.sealed`"},"actor":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"at":{"type":"string","format":"date-time"},"prev_hash":{"type":["string","null"]},"hash":{"type":"string","description":"SHA-256 over this event and `prev_hash`: changing any event breaks the chain"}},"required":["seq","type","actor","data","at","prev_hash","hash"],"additionalProperties":false}},"signatures":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"name":{"type":"string"},"method":{"type":"string","enum":["link","email_otp","sms_otp","whatsapp_otp","sso","api_attestation","api_attestation_otp"]},"strokes_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},"evidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"signed_blob":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["role","name","method","strokes_sha256","evidence","signed_blob","created_at"],"additionalProperties":false}},"certificate_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"final_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]}},"required":["envelope_id","events","signatures","certificate_sha256","final_sha256"],"additionalProperties":false},"EmbedToken":{"type":"object","properties":{"token":{"type":"string","description":"Pass to `<doculisto-sign token=\"…\">`. Open it within 10 minutes; it then works for 60. One recipient only."},"expires_at":{"type":"string","format":"date-time"},"allowed_origins":{"type":"array","items":{"type":"string"}}},"required":["token","expires_at","allowed_origins"],"additionalProperties":false},"OtpChallenge":{"type":"object","properties":{"challenge_id":{"type":"string"},"channel":{"type":"string","enum":["email","sms","whatsapp"]},"sent_to":{"type":"string","description":"Masked address the code went to, e.g. `a•••@example.com`"},"expires_at":{"type":"string","format":"date-time"}},"required":["challenge_id","channel","sent_to","expires_at"],"additionalProperties":false},"Master":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["standard","master","child"],"description":"`child` envelopes were created from a master and carry its signature"},"environment":{"type":"string","enum":["sandbox","production"],"description":"`sandbox` documents carry a watermark and have no legal validity"},"master_id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["preparing","ready","signing","completed","sealed","failed","voided","expired","declined","waiting","open","closed"]},"locale":{"type":"string","enum":["es","en"]},"external_ref":{"type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"template_version_id":{"type":"string"},"documents":{"type":"object","properties":{"prepared_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"current_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"final_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"certificate_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]}},"required":["prepared_sha256","current_sha256","final_sha256","certificate_sha256"],"additionalProperties":false},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"sign_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","notified","viewed","verified","signed","declined"]},"is_current_turn":{"type":"boolean","description":"True while the envelope is waiting for this recipient's signature"},"signed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signing_url":{"description":"The recipient's personal signing link. Returned when the envelope is created; treat it as a secret.","type":"string","format":"uri"}},"required":["id","role","name","email","phone","sign_order","status","is_current_turn","signed_at"],"additionalProperties":false}},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"signer_values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Values each signer filled in, by role"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"sealed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"roles":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"scope":{"type":"string","enum":["envelope","master"]},"sign_order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["key","label","scope","sign_order"],"additionalProperties":false}},"per_person_fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string","enum":["signature","text","date","number","checkbox","radio","dropdown"]},"label":{"type":"string"},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}}},"required":["key","type","required"],"additionalProperties":false}},"supports_public_link":{"type":"boolean"}},"required":["id","name","roles","per_person_fields","supports_public_link"],"additionalProperties":false},"public_link":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"url":{"type":"string","format":"uri"},"max_envelopes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"closes_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["enabled","url","max_envelopes","closes_at"],"additionalProperties":false},{"type":"null"}]},"signed_master_sha256":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the stored file, hex"},{"type":"null"}]},"envelopes":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"by_status":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["total","by_status"],"additionalProperties":false}},"required":["id","kind","environment","title","status","locale","external_ref","metadata","template_version_id","documents","recipients","variables","signer_values","created_at","completed_at","sealed_at","expires_at","template","public_link","signed_master_sha256","envelopes"],"additionalProperties":false},"MasterList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["preparing","ready","signing","completed","sealed","failed","voided","expired","declined","waiting","open","closed"]},"external_ref":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"template_name":{"type":"string"},"envelopes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sealed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"public_link":{"type":"boolean"}},"required":["id","title","status","external_ref","created_at","template_name","envelopes","sealed","public_link"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"CreatedEnvelopes":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Envelope"}}},"required":["data"],"additionalProperties":false},"MasterEnvelopeList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["preparing","ready","signing","completed","sealed","failed","voided","expired","declined","waiting","open","closed"]},"external_ref":{"type":["string","null"]},"source":{"type":"string","enum":["api","public_link"]},"created_at":{"type":"string","format":"date-time"},"sealed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"recipients":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"name":{"type":"string"},"email":{"type":["string","null"]},"status":{"type":"string","enum":["pending","notified","viewed","verified","signed","declined"]},"signed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signing_url":{"type":"string","format":"uri"}},"required":["role","name","email","status","signed_at"],"additionalProperties":false}}},"required":["id","status","external_ref","source","created_at","sealed_at","variables","recipients"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"EmbedOriginList":{"type":"object","properties":{"origins":{"type":"array","items":{"type":"string"}}},"required":["origins"],"additionalProperties":false},"Problem":{"type":"object","properties":{"type":{"type":"string","description":"URL identifying the problem type"},"title":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string","description":"Stable identifier to branch on, e.g. `validation_failed` or `invalid_state`"},"detail":{"type":"string","description":"Human-readable explanation, in English"},"errors":{"description":"For `validation_failed`: one message per invalid path, e.g. `recipients.0.email`","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["type","title","status","code","detail"],"additionalProperties":false},"SandboxTemplateList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The template's id in the sandbox; send it as `sandbox_template_id`"},"name":{"type":"string"},"status":{"type":"string","enum":["published","draft"],"description":"`draft` if it was never published in the sandbox: it is imported as a draft"},"imported":{"anyOf":[{"type":"object","properties":{"template_id":{"type":"string","description":"The production template it was imported as"},"up_to_date":{"type":"boolean","description":"false if the sandbox template changed since the last import"}},"required":["template_id","up_to_date"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","status","imported"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"TemplateImport":{"type":"object","properties":{"result":{"type":"string","enum":["created","updated","unchanged"],"description":"`created` on the first import; `updated` when the sandbox changed and new versions were added; `unchanged` when there was nothing new"},"template":{"$ref":"#/components/schemas/Template"}},"required":["result","template"],"additionalProperties":false},"Organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"environment":{"type":"string","enum":["sandbox","production"],"description":"`sandbox` documents carry a watermark and have no legal validity"},"documents":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Envelopes of any kind created so far"},"limit":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"How many it may create; null for no limit"}},"required":["used","limit"],"additionalProperties":false},"credits":{"anyOf":[{"type":"object","properties":{"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credits available for new documents. Below zero only if documents from a public link were completed with none left"},"in_progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credits held by documents not finished yet; returned if they are voided, declined or fail"}},"required":["balance","in_progress"],"additionalProperties":false},{"type":"null"}],"description":"Prepaid documents: one credit per document signed by everyone. null for sandboxes and organizations that don't use credits"}},"required":["id","name","environment","documents","credits"],"additionalProperties":false},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","url","description","events","enabled","created_at","updated_at"],"additionalProperties":false},"WebhookWithSecret":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"`whsec_…`: verifies `webhook-signature`. Shown only now; rotate it if it is lost"}},"required":["id","url","description","events","enabled","created_at","updated_at","secret"],"additionalProperties":false},"WebhookList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["data"],"additionalProperties":false},"DeletedWebhook":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","description":"`msg_…`, sent as `webhook-id`. The same on every attempt: use it to ignore repeats"},"type":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"],"description":"`failed` once every retry failed; retry it by hand with `POST …/retry`"},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"next_attempt_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_attempt_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_status":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Your endpoint's HTTP status on the last attempt"},"last_error":{"type":["string","null"]},"last_duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"payload":{"description":"The body sent, a WebhookEvent"}},"required":["id","type","status","attempts","next_attempt_at","last_attempt_at","last_status","last_error","last_duration_ms","delivered_at","created_at","payload"],"additionalProperties":false},"WebhookDeliveryList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}},"required":["data"],"additionalProperties":false},"WebhookEvent":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","enum":["envelope.created","envelope.sent","envelope.completed","envelope.sealed","envelope.declined","envelope.voided","envelope.failed","recipient.viewed","recipient.signed","recipient.declined","master.opened","master.closed","master.reopened"]},{"type":"string","const":"webhook.test"}]},"timestamp":{"type":"string","format":"date-time","description":"When it happened"},"environment":{"type":"string","enum":["sandbox","production"]},"data":{"type":"object","properties":{"envelope":{"description":"The envelope or master as it was right after the event","type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["standard","master","child"]},"master_id":{"type":["string","null"]},"title":{"type":"string"},"status":{"type":"string","enum":["preparing","ready","signing","completed","sealed","failed","voided","expired","declined","waiting","open","closed"]},"external_ref":{"type":["string","null"]},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["id","kind","master_id","title","status","external_ref","metadata"],"additionalProperties":false},"recipient":{"description":"For `recipient.*` events","type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"name":{"type":"string"},"email":{"type":["string","null"]},"status":{"type":"string","enum":["pending","notified","viewed","verified","signed","declined"]}},"required":["id","role","name","email","status"],"additionalProperties":false},"reason":{"description":"For `recipient.declined`: what the signer wrote, if anything","type":["string","null"]},"documents":{"description":"For `envelope.sealed`: fingerprints of the files to download","type":"object","properties":{"final_sha256":{"type":"string"},"certificate_sha256":{"type":"string"}},"required":["final_sha256","certificate_sha256"],"additionalProperties":false},"message":{"description":"For `webhook.test`","type":"string"}},"additionalProperties":false}},"required":["type","timestamp","environment","data"],"additionalProperties":false}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NoCredits":{"description":"`no_credits`: the organization has no credits left for new documents","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"The API key lacks the permission this needs","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"Not found in your organisation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Not possible in the current state, e.g. `invalid_state` or `not_ready`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Gone":{"description":"The code expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooLarge":{"description":"The file is too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ValidationFailed":{"description":"The request is invalid; `errors` lists each invalid path","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyAttempts":{"description":"Too many wrong codes","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}