Contratos de principio a fin
La vida de un contrato en la API, paso a paso: de la plantilla a los documentos firmados. Aquí está el qué y el porqué de cada paso. Los parámetros, respuestas y errores de cada endpoint están en la Referencia API: cada paso enlaza al suyo.
Dos caminos
- Paso a paso (v1). Creas un borrador, lo configuras, rellenas participantes y variables, añades anexos y lo envías. Es el camino de esta guía y el que da control sobre cada detalle.
- Una sola llamada (v2). POST
/api/v2/create/contractcrea el contrato y lo envía a firmar en la misma petición. Útil cuando la plantilla ya está configurada en la app: ver API v2.
Si es tu primera integración, haz antes el Quickstart: es esta misma guía en versión mínima.
1. Elige la plantilla
Todo contrato parte de una plantilla: aporta los participantes, sus variables y la configuración por
defecto. Las plantillas se diseñan en la app de TRATO y cada entorno tiene las suyas, así que el
templateId de Stage no sirve en Producción.
GET /api/list/templates devuelve las plantillas de tu cuenta con su templateId.
2. Crea el borrador
POST /api/create/contract crea el contrato en borrador y devuelve su contractid: guárdalo,
todas las llamadas siguientes lo usan. Hay dos orígenes:
source: "template": el texto del contrato es el de la plantilla.source: "document": el texto es un PDF o Word que envías en Base64. La plantilla sigue siendo obligatoria porque aporta los participantes y la configuración.
Los Word se convierten a PDF en el servidor y pueden cambiar fuentes, márgenes o el número de páginas. Si el formato importa, envía directamente el PDF.
3. Configura el contrato
POST /api/contract/configuration/{contractId} cambia la configuración del borrador. Envía solo los campos que
quieras cambiar; el resto se queda como en la plantilla. Las decisiones habituales:
| Qué decides | Campo |
|---|---|
| Tipo de firma: electrónica, avanzada (e.firma), en papel, externa | signatureType |
| Canal de las notificaciones: correo, SMS, WhatsApp o ninguno | notificationType |
| Idioma del contrato y de las notificaciones | language |
| Constancia NOM-151 en el documento firmado | stampNom |
| Vigencia del contrato | expiryUndefined, expiryStartDate, expiryEndDate |
| Tu identificador del contrato, para cruzarlo con tu sistema | externalId |
| URL que recibe los eventos de este contrato | webhook |
4. Participantes y variables
GET /api/contract/variables/{contractId} devuelve los participantes del contrato (participantid) y las
variables de cada uno por su nombre de API (apiName). Con esos identificadores:
- POST
/api/contract/participant/{contractId}/{participantId}rellena los datos de cada participante: nombre, correo, teléfono y requisitos de firma. - POST
/api/contract/variables/{contractId}/{participantId}da valor a sus variables.
Las variables son de tres tipos. El tipo viene en la respuesta de GET /api/contract/variables/{contractId}:
- Texto, número o sí/no: el valor tal cual.
- Imagen (
type: "image"): la imagen PNG o JPG en Base64. - Tabla dinámica (
type: "dynamictable"): un objeto{ headers, rows }, donde cada fila es{ cols: [...] }. Para que la tabla no aparezca en el contrato, envía un objeto vacío ({}).
cURL
curl -X POST https://enterprise-stage.api.trato.io/api/contract/variables/{contractId}/{participantId} \
-H "apikey: $TRATO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rfc": "GALA800101XXX", "productos": {"headers": ["Concepto", "Cantidad"], "rows": [{"cols": ["Laptop", "2"]}]}}'
5. Anexos
Los anexos son documentos que acompañan al contrato. Se añaden mientras el contrato está en borrador:
- POST
/api/contract/attachments/{contractId}: un anexo del contrato, con su archivo. - POST
/api/contract/attachments/{contractId}/{participantId}: un anexo que se pide a un participante (por ejemplo, su identificación). Conrequiredno puede firmar sin subirlo. - POST
/api/contracts/{contractId}/confidential-attachments: un anexo que solo ven el dueño y los usuarios autorizados.
6. Envía a firmar
POST /api/contract/send/{contractId} comprueba que el contrato está completo y lo envía a los participantes. Si
falta algo, responde con el detalle y no envía nada. Opciones útiles:
onlyValidate: solo comprueba, sin enviar. Sirve para validar antes de un envío masivo.showSignLinks: la respuesta trae el enlace de firma de cada participante, para integrarlo en tu propio flujo. ConsendNotifications: false, TRATO no les escribe.
Con el contrato ya enviado:
- GET
/api/contract/pending/{contractId}recuerda la firma a quien aún no ha firmado. - POST
/api/contracts/{contractId}/participants/{participantId}/change-emailcambia el firmante o sus datos de contacto, si aún no ha firmado. - POST
/api/sign-url/renewgenera un enlace de firma nuevo a partir de uno caducado. - POST
/api/contracts/{contractId}/spectatorsañade observadores: personas que siguen el contrato sin firmarlo.
7. Sigue el estado
La forma recomendada es no preguntar: configura un webhook y TRATO te avisará cuando alguien firme, cuando firmen todos o cuando el contrato se finalice o elimine.
Para consultar bajo demanda, GET /api/contract/status/{contractId} devuelve el estado de un contrato y
GET /api/list/contracts lista tus contratos. Los estados son:
| Estado | Significado |
|---|---|
"" | Borrador |
SENT_TO_FILL / SENT_TO_VALIDATE / NEGOTIATION | Pasos previos a la firma, si la plantilla los tiene |
SENT_TO_SIGN | Enviado, pendiente de firmas |
RECEIVED_SIGNED | Firmado por todos |
FINALIZED | Finalizado |
CANCELED | Cancelado |
PHYSICAL_SIGNATURE / EXTERNAL_SIGNATURE | Firmado fuera de TRATO |
8. Descarga los documentos
Con el contrato firmado, GET /api/contract/documents/{contractId} devuelve el PDF firmado (contrato, anexos y
document trail) y, si lo configuraste, la constancia NOM-151. GET /api/contracts/{contractId}/package
descarga todo en un ZIP.
9. Cierra el contrato
- POST
/api/contract/finalize/{contractId}: marca como finalizado un contrato firmado. - DELETE
/api/contract/cancel/{contractId}: cancela un contrato que aún no está firmado. - POST
/api/contract/archive/{contractId}: lo archiva.
Para guardar tus propios datos en el contrato (número de expediente, centro de coste…) usa
POST /api/contracts/{contractId}/customproperties.
API v2: una sola llamada
POST /api/v2/create/contract hace los pasos 2 a 6 en una sola petición: crea el contrato desde
la plantilla con sus participantes y variables y lo envía a firmar. Usa la configuración de la
plantilla, así que conviene dejarla preparada en la app. Si la plantilla pide consulta al buró de
crédito o e.firma, los datos del participante (RFC, domicilio, fecha de nacimiento) son obligatorios.