📝 Crear nueva tarea

Una tarea es el elemento central del flujo de firma en Contractia. Cada tarea contiene:

📄 Uno o más documentos a firmar.
👥 Uno o más participantes, representados como “participaciones”, que incluyen la información de cada firmante/validador y sus requisitos.

Las tareas evolucionan a través de diferentes estados, reflejando su progreso desde la creación hasta su finalización.

📌 Estados posibles de una Tarea

Estado	Descripción
Borrador	La tarea fue creada pero aún no fue iniciada. Se puede seguir editando.
En progreso	La tarea fue iniciada y está en proceso de firma/validación.
Archivada	La tarea fue finalizada y almacenada.
Concluida	Todos los firmantes y validadores completaron exitosamente sus pasos.
Rechazada	Al menos uno de los firmantes o validadores rechazó la tarea.
Cancelada	La tarea fue cancelada antes de completarse.
Vencida	La fecha de expiración fue alcanzada sin que se completara la tarea.

POST ➜ /v2/tareas

https://api.contractia.app/v2/tareas Crea una nueva tarea en estado Borrador, sobre la cual se podrá seguir trabajando (agregar documentos, participantes, configuraciones) hasta que sea iniciada. Una vez iniciada, la tarea avanzará por los estados definidos según el progreso de firma. Si no se especifica referencia, asunto o body, se utilizará un texto por defecto.

🧾 Parámetros del cuerpo (JSON)

Campo	Tipo	Descripción
`referencia`	string	Nombre o etiqueta identificadora de la tarea. Opcional.
`secuencial`	boolean	`true`: los participantes son notificados en orden. `false`: se notifica a todos en simultáneo.
`notificacion_tarea`	objeto	Contenido del correo que recibirán los participantes.
`notificacion_tarea.asunto`	string	Asunto del email de notificación.
`notificacion_tarea.body`	string	Cuerpo del email.
`remitente`	objeto	Personalización del remitente del email.
`remitente.remitente_nombre`	string	Nombre del remitente. Opcional.
`remitente.remitente_email`	string	Email del remitente. Opcional.
`expiration_date`	datetime (YYYY-MM-DD)	Fecha límite para completar la tarea. Después de esta fecha, quedará como Vencida.
`webhook`	objeto o null	Si se configura, se enviarán notificaciones ante cambios.
`webhook.enabled`	boolean	Habilita/deshabilita el envío de webhooks.
`webhook.url`	string	URL destino para los webhooks.
`reminder`	objeto o null	Configuración de recordatorios automáticos.
`reminder.frequency`	int	Frecuencia de envío.
`reminder.unit`	string	Unidad de la frecuencia: `"hours"` o `"days"`.
`external_task_detail_link`	boolean	`true`: los participantes reciben el link al detalle de tarea externo en el email. `false`: no se envía el link en el mail. Debe estar configurado el envío en el email template
`merge_documents`	boolean	`true`: Todos los documentos se unirán para ser uno solo. `false`: Los documentos seguirán siendo independientes. * Requerido en `false` para usar “Asignar documentos a participantes y Campos dinámicos”.

🔁 Respuestas posibles

Código	Descripción
`200 OK`	La tarea fue creada correctamente. Devuelve el `id` de la tarea.
`400 Bad Request`	Error en la solicitud: `"Lo sentimos, ocurrió un error creando la tarea"`
`403 Forbidden`	`"No tiene permisos"` o `"Acceso denegado"`
`500 Internal Server Error`	`"Ocurrió un error creando la tarea"`

💻 Ejemplo de implementación

cURL
JSON
Response

curl --location --request POST 'https://api.contractia.app/v2/tareas' \
--header 'Authorization: Bearer {{api_key}}' \
--header 'user_id: {{user_id}}' \
--header 'Content-Type: application/json' \
--data '{
  "referencia": "Afiliación 12345",
  "secuencial": false,
  "submission_id": "",
  "notificacion_tarea": {
    "asunto": "Formulario de afiliación",
    "body": "Buenas tardes, adjuntamos el documento para gestionar la afiliación."
  },
  "remitente": {
    "remitente_nombre": "",
    "remitente_email": ""
  },
  "expiration_date": "2024-08-25"
}'

{
  "referencia": "Afiliación 12345",
  "secuencial": false,
  "submission_id": "",
  "notificacion_tarea": {
    "asunto": "Formulario de afiliación",
    "body": "Buenas tardes, adjuntamos el documento para gestionar la afiliación."
  },
  "remitente": {
    "remitente_nombre": "",
    "remitente_email": ""
  },
  "expiration_date": "2026-02-25",
  "webhook": {
    "enabled": false,
    "url": "string"
  },
  "reminder": {
    "frequency": 1,
    "unit": "days"
  },
  "merge_documents": true,
  "load_data_sequential": false,
  "external_task_detail_link": true
}

Configuración requerida: Si planeas usar el endpoint de Asignar documentos a participantes, asegúrate de enviar el parámetro merge_documents en false al crear la tarea. Si este parámetro está en true, el endpoint de asignación devolverá error 400.

💡 Configuración de recordatorios (`reminder`)

Podés definir el parámetro reminder en dos niveles distintos según la necesidad de tu flujo:

1. A nivel de Tarea (`POST /v2/tareas`) — Configuración global

Cuándo usarlo: Si todos los participantes del documento deben recibir los recordatorios con la misma frecuencia y condiciones.
Ventaja: Simplifica la integración al definir la regla una sola vez para toda la tarea, sin necesidad de repetirla en cada participante.

2. A nivel de Participante (`POST /v2/participaciones`) — Configuración individual

Cuándo usarlo: Si necesitás una regla personalizada para un participante en particular (por ejemplo, enviar avisos diarios a un firmante pero no a un validador).
Jerarquía: Este parámetro prevalece y pisa la configuración de reminder definida a nivel de tarea para ese participante específico.

Jerarquía de aplicación: Reminder de Participante > Reminder de Tarea
Si definís ambos, el sistema aplicará la regla del participante e ignorará la regla global de la tarea para ese usuario.

Siguiente paso:

Agregar participantes a una tarea ➜

Servicios de la API

Webhooks

📌 Estados posibles de una Tarea

POST ➜ /v2/tareas

🧾 Parámetros del cuerpo (JSON)

🔁 Respuestas posibles

💻 Ejemplo de implementación

💡 Configuración de recordatorios (`reminder`)

1. A nivel de Tarea (`POST /v2/tareas`) — Configuración global

2. A nivel de Participante (`POST /v2/participaciones`) — Configuración individual

Siguiente paso:

​📌 Estados posibles de una Tarea

​POST ➜ /v2/tareas

​🧾 Parámetros del cuerpo (JSON)

​🔁 Respuestas posibles

​💻 Ejemplo de implementación

​💡 Configuración de recordatorios (reminder)

​1. A nivel de Tarea (POST /v2/tareas) — Configuración global

​2. A nivel de Participante (POST /v2/participaciones) — Configuración individual

​Siguiente paso:

📌 Estados posibles de una Tarea

POST ➜ /v2/tareas

🧾 Parámetros del cuerpo (JSON)

🔁 Respuestas posibles

💻 Ejemplo de implementación

💡 Configuración de recordatorios (`reminder`)

1. A nivel de Tarea (`POST /v2/tareas`) — Configuración global

2. A nivel de Participante (`POST /v2/participaciones`) — Configuración individual

Siguiente paso: