{
"info": {
"_postman_id": "9dfb2f67-2d25-4c42-9b1f-contratos",
"name": "Contratos API",
"description": "Colección para probar la API pública de Contratos. Rellena las variables baseUrl y apiKey antes de ejecutar.",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{apiKey}}",
"type": "string"
}
]
},
"variable": [
{
"key": "baseUrl",
"value": "http://localhost:3000",
"type": "string"
},
{
"key": "apiKey",
"value": "fo_RELLENA_TU_API_KEY",
"type": "string"
},
{
"key": "envelopeId",
"value": "",
"type": "string"
},
{
"key": "templateId",
"value": "",
"type": "string"
},
{
"key": "invoiceId",
"value": "",
"type": "string"
},
{
"key": "cursor",
"value": "",
"type": "string"
}
],
"item": [
{
"name": "Envelopes",
"item": [
{
"name": "List envelopes",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes?take=25&status=&cursor=",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes"],
"query": [
{ "key": "take", "value": "25" },
{ "key": "status", "value": "", "description": "Opcional: draft, sent, viewed, partiallySigned, completed, declined, voided, expired" },
{ "key": "cursor", "value": "", "description": "Opcional: id devuelto en nextCursor" },
{ "key": "externalRef", "value": "contrato:2026-001", "description": "Opcional: tu referencia del documento (coincidencia exacta)", "disabled": true }
]
}
},
"event": [
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
"const json = pm.response.json();",
"if (json.data && json.data[0]) pm.collectionVariables.set('envelopeId', json.data[0].id);",
"if (json.nextCursor) pm.collectionVariables.set('cursor', json.nextCursor);"
]
}
}
]
},
{
"name": "Create envelope multipart PDF",
"request": {
"method": "POST",
"header": [
{ "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Opcional: clave única de esta creación. Reenviar con la misma clave y los mismos datos devuelve el mismo documento (24 h). Pon un valor fijo para probar el reintento." }
],
"body": {
"mode": "formdata",
"formdata": [
{ "key": "subject", "value": "Contrato PDF API", "type": "text" },
{ "key": "message", "value": "Documento subido por API.", "type": "text" },
{ "key": "document", "type": "file", "src": [] },
{ "key": "recipients", "value": "[{\"name\":\"Cliente Uno\",\"email\":\"cliente1@example.com\",\"signingOrder\":1},{\"name\":\"Cliente Dos\",\"email\":\"cliente2@example.com\",\"signingOrder\":2}]", "type": "text" },
{ "key": "fields", "value": "[{\"recipientEmail\":\"cliente1@example.com\",\"page\":1,\"x\":64,\"y\":680,\"width\":240,\"height\":72},{\"recipientEmail\":\"cliente2@example.com\",\"page\":1,\"x\":64,\"y\":560,\"width\":240,\"height\":72}]", "type": "text" },
{ "key": "externalRef", "value": "contrato:2026-001", "type": "text", "description": "Opcional: tu referencia para buscarlo con GET /envelopes?externalRef=. Máx. 200 caracteres, no es única" },
{ "key": "metadata", "value": "{\"clienteId\":\"123\",\"tipo\":\"contrato\"}", "type": "text", "description": "Opcional: JSON de hasta 10 claves con valores de texto (máx. 500). Vuelve en los webhooks" },
{ "key": "send", "value": "true", "type": "text" },
{ "key": "embedded", "value": "false", "type": "text" },
{ "key": "isTest", "value": "true", "type": "text" }
]
},
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes"]
}
},
"event": [
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
"const json = pm.response.json();",
"if (json.id) pm.collectionVariables.set('envelopeId', json.id);"
]
}
}
]
},
{
"name": "Vista previa (PDF)",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "formdata",
"formdata": [
{ "key": "document", "type": "file", "src": [] },
{ "key": "recipients", "value": "[{\"name\":\"Cliente Uno\",\"email\":\"cliente1@example.com\"}]", "type": "text", "description": "Opcional: solo pone los nombres en los recuadros" },
{ "key": "fields", "value": "[{\"recipientIndex\":0,\"page\":1,\"x\":315,\"y\":680,\"width\":240,\"height\":72}]", "type": "text", "description": "Puntos PDF, origen arriba a la izquierda; recipientIndex desde 0" }
]
},
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/preview",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "preview"]
},
"description": "Devuelve el PDF con los recuadros de firma dibujados. No crea nada ni gasta firmas."
}
},
{
"name": "Vista previa (JSON)",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "formdata",
"formdata": [
{ "key": "document", "type": "file", "src": [] },
{ "key": "recipients", "value": "[{\"name\":\"Cliente Uno\",\"email\":\"cliente1@example.com\"}]", "type": "text", "description": "Opcional: solo pone los nombres en los recuadros" },
{ "key": "fields", "value": "[{\"recipientIndex\":0,\"page\":1,\"x\":315,\"y\":680,\"width\":240,\"height\":72}]", "type": "text", "description": "Puntos PDF, origen arriba a la izquierda; recipientIndex desde 0" }
]
},
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/preview?format=json",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "preview"],
"query": [{ "key": "format", "value": "json" }]
},
"description": "Devuelve { pageCount, pages, fields } con los campos tal como se usarían al crear."
}
},
{
"name": "Get envelope detail",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/{{envelopeId}}",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "{{envelopeId}}"]
}
}
},
{
"name": "Download envelope PDF inline",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/{{envelopeId}}/document",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "{{envelopeId}}", "document"]
}
}
},
{
"name": "Download envelope PDF attachment",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/{{envelopeId}}/document?download=1",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "{{envelopeId}}", "document"],
"query": [{ "key": "download", "value": "1" }]
}
}
},
{
"name": "Download certificate",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/{{envelopeId}}/certificate?download=1",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "{{envelopeId}}", "certificate"],
"query": [{ "key": "download", "value": "1" }]
}
}
},
{
"name": "Resend envelope",
"request": {
"method": "POST",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/{{envelopeId}}/resend",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "{{envelopeId}}", "resend"]
}
}
},
{
"name": "Resend envelope to a corrected email",
"request": {
"method": "POST",
"header": [
{ "key": "Content-Type", "value": "application/json" }
],
"body": {
"mode": "raw",
"raw": "{\n \"email\": \"email.corregido@example.com\"\n}",
"options": { "raw": { "language": "json" } }
},
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/{{envelopeId}}/resend",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "{{envelopeId}}", "resend"]
},
"description": "Cambia el email del firmante pendiente y le reenvía la invitación."
}
},
{
"name": "Nuevo enlace de firma",
"request": {
"method": "POST",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/{{envelopeId}}/signing-link",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "{{envelopeId}}", "signing-link"]
},
"description": "Anula el enlace del firmante pendiente y devuelve uno nuevo de 7 días (signingUrl, embedUrl, expiresAt) sin enviar email. Si estaba caducado, lo reabre. 409 si está completado, rechazado o cancelado."
}
},
{
"name": "Cancel envelope",
"request": {
"method": "POST",
"header": [
{ "key": "Content-Type", "value": "application/json" }
],
"body": {
"mode": "raw",
"raw": "{\n \"reason\": \"El cliente ha pedido cambios en el contrato\"\n}",
"options": { "raw": { "language": "json" } }
},
"url": {
"raw": "{{baseUrl}}/api/v1/envelopes/{{envelopeId}}/cancel",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "envelopes", "{{envelopeId}}", "cancel"]
},
"description": "Pasa el documento a voided, revoca sus enlaces de firma y avisa con el webhook envelope.voided. El cuerpo es opcional: reason (hasta 500 caracteres) es el motivo, que queda en la auditoría y llega en el webhook. Responde { id, status, voidedAt, reason }. 400 si el cuerpo no es JSON o reason no es válido, 404 si no existe, 409 si ya está completado, rechazado, cancelado o caducado."
}
}
]
},
{
"name": "Templates",
"item": [
{
"name": "List templates",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/templates",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "templates"],
"query": [
{ "key": "archived", "value": "include", "description": "Incluir también las plantillas archivadas", "disabled": true }
]
}
},
"event": [
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
"const json = pm.response.json();",
"pm.test('Lista de plantillas', () => pm.expect(json.data).to.be.an('array'));",
"if (json.data && json.data[0]) pm.collectionVariables.set('templateId', json.data[0].id);"
]
}
}
]
},
{
"name": "Get template",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/templates/{{templateId}}",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "templates", "{{templateId}}"]
},
"description": "Devuelve los campos (fields) que hay que enviar en data al crear un documento desde la plantilla, y su contenido: html, css y schema."
}
},
{
"name": "Create template",
"request": {
"method": "POST",
"header": [
{ "key": "Content-Type", "value": "application/json" }
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Presupuesto\",\n \"html\": \"Presupuesto para {{cliente}}
\",\n \"css\": \"h1 { color: #047857; }\",\n \"schema\": {\n \"fields\": { \"cliente\": { \"type\": \"string\", \"label\": \"Cliente\" } },\n \"fields_order\": [\"cliente\"]\n }\n}"
},
"url": {
"raw": "{{baseUrl}}/api/v1/templates",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "templates"]
},
"description": "Crea una plantilla: name y html obligatorios; css y schema (objeto) opcionales. Para importar, envía tal cual el JSON de Export template (si el nombre ya existe, se añade «(importada)»)."
}
},
{
"name": "Update template",
"request": {
"method": "PUT",
"header": [
{ "key": "Content-Type", "value": "application/json" }
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"Presupuesto 2027\",\n \"active\": true\n}"
},
"url": {
"raw": "{{baseUrl}}/api/v1/templates/{{templateId}}",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "templates", "{{templateId}}"]
},
"description": "Cambia solo los campos enviados: name, html, css, schema (null lo quita) y active (false archiva, true reactiva)."
}
},
{
"name": "Export template",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/templates/{{templateId}}/export",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "templates", "{{templateId}}", "export"]
},
"description": "Plantilla en el formato de fichero de Contratos (format, version, template). Se importa enviándola tal cual a Create template."
}
},
{
"name": "Create envelope from template",
"request": {
"method": "POST",
"header": [
{ "key": "Content-Type", "value": "application/json" },
{ "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true, "description": "Opcional: clave única de esta creación. Reenviar con la misma clave y los mismos datos devuelve el mismo documento (24 h). Pon un valor fijo para probar el reintento." }
],
"body": {
"mode": "raw",
"raw": "{\n \"subject\": \"Envio desde plantilla\",\n \"message\": \"Revisa y firma este documento.\",\n \"data\": {\n \"nombre_completo\": \"Maria Perez\",\n \"dni\": \"12345678Z\",\n \"fecha_firma\": \"2026-06-05\"\n },\n \"recipients\": [\n { \"name\": \"Maria Perez\", \"email\": \"maria@example.com\", \"signingOrder\": 1 }\n ],\n \"send\": true,\n \"embedded\": true,\n \"isTest\": true,\n \"externalRef\": \"presupuesto:2026-0042\",\n \"metadata\": { \"presupuestoId\": \"42\", \"tipo\": \"presupuesto\" }\n}",
"options": { "raw": { "language": "json" } }
},
"url": {
"raw": "{{baseUrl}}/api/v1/templates/{{templateId}}/envelopes",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "templates", "{{templateId}}", "envelopes"]
}
},
"event": [
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
"const json = pm.response.json();",
"if (json.id) pm.collectionVariables.set('envelopeId', json.id);"
]
}
}
]
}
]
},
{
"name": "Account",
"item": [
{
"name": "Get account",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/account",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "account"]
},
"description": "Modo prueba, plan y firmas disponibles de la organización de la clave API. Incluye creditsNextExpiry (próxima caducidad de créditos prepago, que valen 1 año desde la compra; null si no hay) y creditsExpiringNext (cuántos caducan ese día)."
}
},
{
"name": "Get QR logo",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/organization/qr-logo",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "organization", "qr-logo"]
},
"description": "PNG del logo del QR del link seguro, o 404 si no hay."
}
},
{
"name": "Upload QR logo",
"request": {
"method": "PUT",
"header": [],
"body": {
"mode": "formdata",
"formdata": [
{ "key": "logo", "type": "file", "src": [], "description": "PNG o JPG, máximo 300 KB" }
]
},
"url": {
"raw": "{{baseUrl}}/api/v1/organization/qr-logo",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "organization", "qr-logo"]
},
"description": "También acepta JSON { \"imageBase64\": \"...\" } o la imagen en el cuerpo."
}
},
{
"name": "Remove QR logo",
"request": {
"method": "DELETE",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/organization/qr-logo",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "organization", "qr-logo"]
}
}
},
{
"name": "Get embed origins",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/organization/embed-origins",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "organization", "embed-origins"]
},
"description": "Webs que pueden mostrar la página de firma en un iframe."
}
},
{
"name": "Set embed origins",
"request": {
"method": "PUT",
"header": [{ "key": "Content-Type", "value": "application/json" }],
"body": {
"mode": "raw",
"raw": "{\n \"origins\": [\"https://portal.empresa.com\"]\n}"
},
"url": {
"raw": "{{baseUrl}}/api/v1/organization/embed-origins",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "organization", "embed-origins"]
},
"description": "Sustituye la lista entera. [] la vacía: ninguna web externa podrá mostrar la firma."
}
}
]
},
{
"name": "Invoices",
"item": [
{
"name": "List invoices",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/invoices?from=&to=&status=&take=25&cursor=",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "invoices"],
"query": [
{ "key": "from", "value": "", "description": "Opcional YYYY-MM-DD" },
{ "key": "to", "value": "", "description": "Opcional YYYY-MM-DD" },
{ "key": "status", "value": "", "description": "Opcional: issued, paid, voided..." },
{ "key": "take", "value": "25" },
{ "key": "cursor", "value": "", "description": "Opcional: id devuelto en nextCursor" },
{ "key": "test", "value": "include", "description": "Facturas de prueba (Stripe en modo test): include (por defecto), exclude u only. Cada factura trae isTest.", "disabled": true }
]
}
},
"event": [
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
"const json = pm.response.json();",
"pm.test('Cada factura indica si es de prueba', () => (json.data || []).forEach((invoice) => pm.expect(invoice.isTest).to.be.a('boolean')));",
"if (json.data && json.data[0]) pm.collectionVariables.set('invoiceId', json.data[0].id);",
"if (json.nextCursor) pm.collectionVariables.set('cursor', json.nextCursor);"
]
}
}
]
},
{
"name": "Download invoice PDF",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/invoices/{{invoiceId}}/pdf",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "invoices", "{{invoiceId}}", "pdf"]
}
}
},
{
"name": "Download invoice XML/Xsig",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/invoices/{{invoiceId}}/xml",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "invoices", "{{invoiceId}}", "xml"]
}
}
},
{
"name": "Export invoices ZIP PDF/XML + CSV",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/invoices/export?from=&to=",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "invoices", "export"],
"query": [
{ "key": "from", "value": "", "description": "Opcional YYYY-MM-DD" },
{ "key": "to", "value": "", "description": "Opcional YYYY-MM-DD" },
{ "key": "test", "value": "include", "description": "Facturas de prueba: exclude (por defecto, no se mezclan con la contabilidad), include u only. Con include u only se añade la columna de prueba.", "disabled": true }
]
}
}
},
{
"name": "Export invoices CSV contabilidad",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/invoices/export?from=&to=&format=csv",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "invoices", "export"],
"query": [
{ "key": "from", "value": "", "description": "Opcional YYYY-MM-DD" },
{ "key": "to", "value": "", "description": "Opcional YYYY-MM-DD" },
{ "key": "format", "value": "csv" },
{ "key": "test", "value": "include", "description": "Facturas de prueba: exclude (por defecto, no se mezclan con la contabilidad), include u only. Con include u only se añade la columna factura_prueba.", "disabled": true }
]
}
}
}
]
},
{
"name": "Reports",
"item": [
{
"name": "Report summary",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/reports/summary?from=2026-09-01&to=2026-09-30&includeTest=false",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "reports", "summary"],
"query": [
{ "key": "from", "value": "2026-09-01", "description": "Obligatorio AAAA-MM-DD (hora de Madrid)" },
{ "key": "to", "value": "2026-09-30", "description": "Obligatorio AAAA-MM-DD, inclusivo. Máximo 366 días desde from" },
{ "key": "includeTest", "value": "false", "description": "Incluir documentos de prueba: true o false (por defecto)" },
{ "key": "groupBy", "value": "day", "description": "Opcional: day, week o month. Por defecto automático según la duración del periodo", "disabled": true },
{ "key": "source", "value": "all", "description": "Opcional: all (por defecto), uploaded, template o api", "disabled": true },
{ "key": "templateId", "value": "{{templateId}}", "description": "Opcional: solo los documentos de esa plantilla de la organización", "disabled": true }
]
},
"description": "Informe de documentos del periodo: totales por resultado, tasa de firma (fracción 0-1), mediana de horas hasta la firma, firmas gastadas, comparación con el periodo anterior y series por intervalo."
},
"event": [
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
"const json = pm.response.json();",
"pm.test('Devuelve totales y periodo anterior', () => {",
" pm.expect(json.totals).to.be.an('object');",
" pm.expect(json.previousRange).to.have.property('from');",
"});"
]
}
}
]
},
{
"name": "Report envelopes CSV",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/v1/reports/envelopes.csv?from=2026-09-01&to=2026-09-30&includeTest=false",
"host": ["{{baseUrl}}"],
"path": ["api", "v1", "reports", "envelopes.csv"],
"query": [
{ "key": "from", "value": "2026-09-01", "description": "Obligatorio AAAA-MM-DD (hora de Madrid)" },
{ "key": "to", "value": "2026-09-30", "description": "Obligatorio AAAA-MM-DD, inclusivo. Máximo 366 días desde from" },
{ "key": "includeTest", "value": "false", "description": "Incluir documentos de prueba: true o false (por defecto)" },
{ "key": "source", "value": "all", "description": "Opcional: all (por defecto), uploaded, template o api", "disabled": true },
{ "key": "templateId", "value": "{{templateId}}", "description": "Opcional: solo los documentos de esa plantilla de la organización", "disabled": true }
]
},
"description": "Un documento por fila (UTF-8 con BOM, separador ;), con los mismos filtros que el informe. Máximo 10.000 documentos; si hay más responde 400."
}
}
]
}
]
}