📝 Crear nueva tarea

Crea una nueva tarea de firma en Contractia con documentos, participantes y estados, incluyendo ejemplos de request, response e integración.

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”.

🔁 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

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"
}'

JSON

{
  "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": 5,
    "unit": "hours"
  },
  "merge_documents": true,
  "load_data_sequential": false,
  "external_task_detail_link": true
}

Response

5868

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.

Siguiente paso:

• Agregar participantes a una tarea ➜