> ## Documentation Index
> Fetch the complete documentation index at: https://api.contractia.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 📝 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
```bash theme={null}
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 theme={null}
{
"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
}
```
```json theme={null}
5868
```
#### Siguiente paso:
* Agregar participantes a una tarea [➜](/platform/crear)