Início › Desenvolvedores › Tarefas e aprovações

Tarefas e aprovações

Uma tarefa é assíncrona: o pedido volta na hora com o id, e o resultado chega quando o agente termina.

Pedir

{
  "input": "Envie o lembrete de vencimento da fatura 4821",
  "context": {"cliente": "4821", "valor": 1290.00, "vencimento": "2026-11-10"},
  "external_ref": "erp-4821"
}

• input: o pedido em texto, até 8.000 caracteres.
• context: objeto JSON opcional, até 16 KB.
• external_ref: o seu identificador, devolvido na tarefa e nos eventos (até 200 caracteres).
• Cabeçalho Idempotency-Key (até 120 caracteres): repetir a mesma chave devolve a mesma tarefa com 200, em vez de criar outra. Use em toda criação.

Status

Status	Significa
pending_approval	Espera alguém da empresa aprovar.
queued	Na fila para começar.
running	O agente está trabalhando.
completed	Concluída; o resultado está em /result.
failed	O agente não concluiu; error explica em palavras simples.
cancelled	Cancelada pela integração.
rejected	A empresa recusou.
expired	Ninguém aprovou em 7 dias.

Acompanhar

O melhor caminho são os webhooks. Sem eles, consulte GET /tasks/{id} a cada poucos segundos e, quando terminar, GET /tasks/{id}/result. GET /tasks lista as tarefas da integração (filtros status, agent_id, since; paginação com before).

Cancelar

POST /tasks/{id}/cancel vale para pending_approval, queued e running. Uma tarefa já terminada responde 409 task_finished.

Aprovação

• É uma opção da integração: vem desligada nas integrações de testes e ligada nas de produção. A empresa muda no painel.
• Quem aprova recebe e-mail e vê a tarefa em Workforce › Aprovações; pode recusar com motivo.
• Sem decisão em 7 dias, a tarefa expira. Recusada, expirada ou cancelada antes de começar, ela não conta na cota.

Mais do portal

Comece aqui: Visão geral · Primeiros passos

Guias: Autenticação · Conceitos · Tarefas e aprovações · Webhooks · Erros · Limites e cota · Ambiente de testes · MCP do Workforce

Referência: Referência da API · Exemplos de código · Versões e mudanças

Dados públicos: API pública do catálogo · MCP do catálogo público