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/contract crea 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.

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é decidesCampo
Tipo de firma: electrónica, avanzada (e.firma), en papel, externasignatureType
Canal de las notificaciones: correo, SMS, WhatsApp o ningunonotificationType
Idioma del contrato y de las notificacioneslanguage
Constancia NOM-151 en el documento firmadostampNom
Vigencia del contratoexpiryUndefined, expiryStartDate, expiryEndDate
Tu identificador del contrato, para cruzarlo con tu sistemaexternalId
URL que recibe los eventos de este contratowebhook

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:

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:

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. Con sendNotifications: false, TRATO no les escribe.

Con el contrato ya enviado:

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:

EstadoSignificado
""Borrador
SENT_TO_FILL / SENT_TO_VALIDATE / NEGOTIATIONPasos previos a la firma, si la plantilla los tiene
SENT_TO_SIGNEnviado, pendiente de firmas
RECEIVED_SIGNEDFirmado por todos
FINALIZEDFinalizado
CANCELEDCancelado
PHYSICAL_SIGNATURE / EXTERNAL_SIGNATUREFirmado 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

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.