Tareas

Pendientes de seguimiento para el equipo, opcionalmente ligados a una cotización.

Qué ofrece la API

La API de tareas tiene un solo método: POST /api/v1/tareas, para crear una tarea. No hay endpoints para listar, editar, completar ni borrar tareas por API; eso se hace desde la app. Para enterarte de cambios, escucha los eventos task.created y task.completed con webhooks o consúltalos en el historial de eventos.

Crear una Tarea

POST /api/v1/tareas crea una tarea en la bandeja del equipo. Requiere una llave con permiso de escritura (en una llave restringida, write sobre el recurso tareas) y acepta Idempotency-Key.

Campo	Obligatorio	Detalle
`titulo`	Sí	Texto de la tarea. Se guardan los primeros 200 caracteres; el resto se descarta sin error.
`due_date`	No	Fecha límite en formato `YYYY-MM-DD`.
`cotizacion_id`	No	UUID de una cotización de tu organización para ligar la tarea.
`factura_id`	No	UUID de una factura de tu organización (el `id` de `/api/v1/facturas`) para ligar la tarea. Puede ir junto con `cotizacion_id`.

Cualquier otro campo del cuerpo (por ejemplo asignado_a, prioridad o notas) se ignora sin error: por API no se asignan responsable, prioridad ni notas.

curl -X POST "https://cordhq.app/api/v1/tareas" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: seguimiento-cot-00104" \
     -d '{
       "titulo": "Llamar a Stark Industries por COT-00104",
       "due_date": "2026-09-20",
       "cotizacion_id": "2a9d8e4f-6b1c-4d7a-9e3f-5c8b1a2d4e6f"
     }'

{ "data": { "id": "7c1e0b4a-3f2d-4e8c-9a6b-5d1f0e2c3b4a" } }

La tarea nace sin responsable y con prioridad normal. En la app se le asigna responsable, prioridad y notas desde Tareas; mientras no tenga responsable, el recordatorio por correo de la mañana le llega al dueño de la cuenta.

Con una llave de prueba (sk_test_) la tarea se crea en el entorno de prueba, que no manda recordatorios.

Cada tarea nueva emite el evento task.created, con cotizacion_id y factura_id (o null). También lo emiten las tareas que Cord crea solo (contracargo y reembolso SPEI). Cuando alguien la marca como hecha en la app se emite task.completed.

Errores posibles

Código	Cuándo
`invalid_request` (400)	Falta `titulo` (o viene vacío), o `due_date` no es una fecha real en formato `YYYY-MM-DD` (por ejemplo, `2026-02-30` se rechaza).
`not_found` (404)	`cotizacion_id` o `factura_id` no es un UUID, o no es una cotización o factura de tu organización. El mensaje sale en el idioma de tu cuenta.
`invalid_json` (400)	El cuerpo no es JSON válido.
`insufficient_scope` / `insufficient_permissions` (403)	La llave es de solo lectura, o es una llave restringida sin `write` en `tareas`.

El resto de los códigos comunes están en Manejo de Errores.