Tarefas

Pendências de acompanhamento para a equipe, opcionalmente vinculadas a um orçamento.

O que a API oferece

A API de tarefas tem um único método: POST /api/v1/tareas, para criar uma tarefa. Não há endpoints para listar, editar, concluir nem excluir tarefas pela API; isso é feito no app. Para saber das alterações, escute os eventos task.created e task.completed com webhooks ou consulte-os no histórico de eventos.

Criar uma tarefa

POST /api/v1/tareas cria uma tarefa na caixa de entrada da equipe. Exige uma chave com permissão de escrita (em uma chave restrita, write sobre o recurso tareas) e aceita Idempotency-Key.

Campo	Obrigatório	Detalhe
`titulo`	Sim	Texto da tarefa. Os primeiros 200 caracteres são armazenados; o restante é descartado sem erro.
`due_date`	Não	Prazo no formato `YYYY-MM-DD`.
`cotizacion_id`	Não	UUID de um orçamento da sua organização para vincular a tarefa.
`factura_id`	Não	UUID de uma fatura da sua organização (o `id` de `/api/v1/facturas`) para vincular a tarefa. Pode ir junto com `cotizacion_id`.

Qualquer outro campo do corpo (por exemplo, asignado_a, prioridad ou notas) é ignorado sem erro: pela API, não se atribuem responsável, prioridade nem observações.

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

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

A tarefa nasce sem responsável e com prioridade normal. No app, o responsável, a prioridade e as observações são definidos em Tarefas; enquanto ela não tiver responsável, o lembrete por e-mail da manhã vai para o proprietário da conta.

Com uma chave de teste (sk_test_), a tarefa é criada no ambiente de teste, que não envia lembretes.

Cada tarefa nova emite o evento task.created, com cotizacion_id e factura_id (ou null). As tarefas que o Cord cria sozinho (contestação e reembolso SPEI) também o emitem. Quando alguém a marca como concluída no app, é emitido task.completed.

Erros possíveis

Código	Quando
`invalid_request` (400)	Falta `titulo` (ou ele vem vazio), ou `due_date` não é uma data real no formato `YYYY-MM-DD` (por exemplo, `2026-02-30` é rejeitada).
`not_found` (404)	`cotizacion_id` ou `factura_id` não é um UUID, ou não é um orçamento ou uma fatura da sua organização. A mensagem sai no idioma da sua conta.
`invalid_json` (400)	O corpo não é um JSON válido.
`insufficient_scope` / `insufficient_permissions` (403)	A chave é somente leitura, ou é uma chave restrita sem `write` em `tareas`.

Os demais códigos comuns estão em Tratamento de erros.