Worker Automation
Acompanhamento das execuções assíncronas da plataforma Alcance - listagem, estatísticas, status de task, cancelamento e novo envio.
Base path
Todos os endpoints abaixo estão prefixados por:
/api/v1/worker-automation
Escopos
A API Key deve conter os escopos recurso:acao apropriados:
| Escopo | Quando é necessário |
|---|---|
worker_automation:read | Listagens, detalhes, stats, dashboard, status de task. |
worker_automation:write | cancel e retry. |
As operações cancel e retry exigem autenticação e o escopo worker_automation:write.
Estados de uma task
Para o fluxo de acompanhamento, veja Tarefas assíncronas.
| Estado | Significado |
|---|---|
PENDING | Task aceita, aguardando execução. |
STARTED | Execução iniciada. |
SUCCESS | Execução concluída sem erros. result contém o payload. |
FAILURE | Execução falhou. erro traz a mensagem resumida. |
RETRY | Task falhou e será executada novamente. |
REVOKED | Cancelada manualmente via cancel. |
Endpoints
GET /worker-automation/
Lista paginada de workers com filtros opcionais. Cada item vem enriquecido com client_name (razão social do cliente) e display_name (nome amigável da automação).
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
status | str | query | não | Filtra por estado do worker (ex.: AGENDADO, EXECUTANDO, FALHA). |
automation_type | str | query | não | Filtra pelo tipo de automação (chave do catálogo de automações). |
date_from | datetime | query | não | Data/hora inicial do intervalo de criação. |
date_to | datetime | query | não | Data/hora final do intervalo de criação. |
page | int | query | não | Página (≥ 1, default 1). |
per_page | int | query | não | Itens por página (1 a 100, default 20). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Workers recuperados com sucesso",
"data": {
"items": [
{
"id": 812,
"task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
"cliente_id": 1024,
"usuario_id": 42,
"path_file": null,
"status": "EXECUTANDO",
"data_inicio": "2026-07-08T09:15:00-03:00",
"data_fim": null,
"mensagem_erro": null,
"automation_type": "certidao_trabalhista",
"priority": 0,
"retry_count": 0,
"progress": 45,
"metadata_json": null,
"display_name": "Certidão Trabalhista (CNDT)",
"client_name": "Comércio de Alimentos Ltda"
}
],
"total": 137,
"page": 1,
"per_page": 20,
"pages": 7
}
}Escopo: worker_automation:read
GET /worker-automation/stats
Dashboard de estatísticas agregadas - total geral e contagens por status. Ideal para alimentar contadores e gráficos do gerenciador.
Parâmetros de query
Todos opcionais. Sem nenhum deles, o resultado cobre a tabela inteira.
| Parâmetro | Tipo | Observações |
|---|---|---|
data_inicio | date | Início do período (AAAA-MM-DD, horário de Brasília). |
data_fim | date | Fim do período, inclusive. |
automation_type | str | Restringe a um tipo de automação. |
Quando data_inicio e data_fim vêm juntos, data_inicio posterior a data_fim ou janela acima de 366 dias retorna 422.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Estatisticas recuperadas com sucesso",
"data": {
"total": 1342,
"by_status": {
"AGENDADO": 18,
"EXECUTANDO": 5,
"CONCLUIDO": 1290,
"FALHA": 22,
"CANCELADO": 7
}
}
}Escopo: worker_automation:read
GET /worker-automation/timeseries
Série temporal de execuções por status, agregada por dia ou por mês. A série é contígua: dias ou meses sem execução vêm com zero, nunca omitidos.
Parâmetros de query
| Parâmetro | Tipo | Obrigatório | Observações |
|---|---|---|---|
data_inicio | date | sim | Início do período (AAAA-MM-DD, horário de Brasília). |
data_fim | date | sim | Fim do período, inclusive. |
group_by | str | não | dia (default) ou mes. Outro valor retorna 422. |
automation_type | str | não | Filtra um tipo de automação. |
cliente_id | int | não | > 0. Filtra um cliente. |
usuario_id | int | não | > 0. Filtra um usuário. |
data_inicio posterior a data_fim ou janela acima de 366 dias retorna 422.
Request
GET /api/v1/worker-automation/timeseries?data_inicio=2026-08-01&data_fim=2026-08-03&group_by=diaResponse 200 OK
{
"status": "success",
"message": "Serie temporal gerada com sucesso",
"data": {
"group_by": "dia",
"data_inicio": "2026-08-01",
"data_fim": "2026-08-03",
"labels": ["2026-08-01", "2026-08-02", "2026-08-03"],
"total": [120, 0, 98],
"sucesso": [110, 0, 90],
"erro": [6, 0, 5],
"pendencia": [2, 0, 1],
"cancelado": [2, 0, 2],
"outros": [0, 0, 0]
}
}Os arrays são paralelos (labels[i] descreve o mesmo período que total[i], sucesso[i] etc.) e têm sempre o mesmo tamanho. Os rótulos são AAAA-MM-DD (dia) ou AAAA-MM (mes). Baldes de status:
| Campo | Status contados |
|---|---|
sucesso | CONCLUIDO |
erro | FALHA |
pendencia | AGENDADO, EXECUTANDO |
cancelado | CANCELADO |
outros | Qualquer outro status. total = soma dos cinco baldes. |
Escopo: worker_automation:read
GET /worker-automation/stats-by-automation
Ranking por tipo de automação, com contagens por status e taxa de sucesso.
Parâmetros de query
Todos opcionais. Sem período, cobre o histórico completo.
| Parâmetro | Tipo | Observações |
|---|---|---|
data_inicio | date | Início do período (AAAA-MM-DD, horário de Brasília). |
data_fim | date | Fim do período, inclusive. |
cliente_id | int | > 0. Restringe a um cliente. |
usuario_id | int | > 0. Restringe a um usuário. |
data_inicio posterior a data_fim ou janela acima de 366 dias retorna 422.
Request
GET /api/v1/worker-automation/stats-by-automation?data_inicio=2026-08-01&data_fim=2026-08-31Response 200 OK
{
"status": "success",
"message": "Ranking por automacao gerado com sucesso",
"data": {
"itens": [
{
"automation_type": "certidao_trabalhista",
"display_name": "Certidão Trabalhista",
"total": 120,
"sucesso": 110,
"erro": 6,
"pendencia": 2,
"cancelado": 2,
"outros": 0,
"taxa_sucesso": 94.83
}
],
"total_geral": 120
}
}taxa_sucesso = sucesso / (sucesso + erro) * 100, com 2 casas. pendencia e cancelado ficam fora do denominador; sem desfechos terminais a taxa é 0.0.
Escopo: worker_automation:read
GET /worker-automation/active
Lista os workers atualmente com status EXECUTANDO, já enriquecidos com client_name e display_name. Retorna a lista completa, sem paginação.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Workers ativos recuperados com sucesso",
"data": [
{
"id": 812,
"task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
"cliente_id": 1024,
"usuario_id": 42,
"status": "EXECUTANDO",
"data_inicio": "2026-07-08T09:15:00-03:00",
"data_fim": null,
"automation_type": "certidao_trabalhista",
"priority": 0,
"progress": 45,
"display_name": "Certidão Trabalhista (CNDT)",
"client_name": "Comércio de Alimentos Ltda"
}
]
}Escopo: worker_automation:read
GET /worker-automation/queued
Lista os workers com status AGENDADO, ordenados por prioridade e paginados. A paginação segue o contrato items + total + page + per_page + pages.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
page | int | query | não | Página (≥ 1, default 1). |
per_page | int | query | não | Itens por página (1 a 100, default 10). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Workers na fila recuperados com sucesso",
"data": {
"items": [
{
"id": 845,
"task_id": null,
"cliente_id": 1099,
"usuario_id": 42,
"status": "AGENDADO",
"automation_type": "simples_nacional",
"priority": 0,
"progress": 0,
"display_name": "Simples Nacional",
"client_name": "Transportadora Horizonte ME"
}
],
"total": 18,
"page": 1,
"per_page": 10,
"pages": 2
}
}Escopo: worker_automation:read
GET /worker-automation/search-automations
Busca inteligente de automações no catálogo de automações com fuzzy matching. Sem q, retorna todas as automações agrupadas por categoria e em lista plana. Com q, retorna apenas os resultados com score ≥ 60, ordenados do mais relevante para o menos.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
q | str | query | não | Texto de busca. Vazio retorna todas as automações agrupadas. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "2 automacao(oes) encontrada(s)",
"data": {
"results": [
{
"key": "certidao_trabalhista",
"display_name": "Certidão Trabalhista (CNDT)",
"category": "Certidões",
"requires_selenium": true,
"score": 100
}
]
}
}Escopo: worker_automation:read
GET /worker-automation/status/{task_id}
Consulta o estado atual de uma task pelo task_id (UUID). É o endpoint que alimenta o tool MCP consultar_status_task - o LLM usa esta rota para acompanhar tasks longas (CNDs, scrapers) sem bloquear o chat.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
task_id | str | path | sim | UUID da task a ser consultada. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Status da task recuperado com sucesso",
"data": {
"task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
"status": "SUCCESS",
"result": "{'certidao_id': 1234, 'url_pdf': '/api/v1/certidao-negativa/1234/pdf'}"
}
}Em estados não terminais (PENDING, STARTED, RETRY), result vem como null.
Escopo: worker_automation:read
GET /worker-automation/dashboard
Dashboard agregado - reúne stats, active e queued em uma única requisição. Cada seção pode vir vazia quando não há dados.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Dashboard recuperado com sucesso",
"data": {
"stats": {
"total": 1342,
"by_status": { "AGENDADO": 18, "EXECUTANDO": 5, "CONCLUIDO": 1290 }
},
"summary": {
"total_active": 5,
"total_pending": 18,
"total_completed_today": 87,
"total_errors_today": 3
},
"active": [],
"queued": { "items": [], "total": 18, "page": 1, "per_page": 10, "pages": 2 },
"history": []
}
}O payload contém as seções: stats (contagens agregadas), summary (totais do dia), active (workers EXECUTANDO, cap de 50), queued (primeira página de AGENDADO, 10 itens) e history (últimos 20 workers em estado terminal CONCLUIDO, FALHA, CANCELADO).
Escopo: worker_automation:read
GET /worker-automation/{worker_id}
Detalhe completo de um worker pelo ID interno (int). Inclui client_name, display_name, timestamps e mensagem de erro quando aplicável. Quando não encontrado, retorna erro com a mensagem "Worker nao encontrado.".
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
worker_id | int | path | sim | ID interno do worker. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Worker encontrado com sucesso",
"data": {
"id": 812,
"task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
"cliente_id": 1024,
"usuario_id": 42,
"path_file": null,
"status": "EXECUTANDO",
"data_inicio": "2026-07-08T09:15:00-03:00",
"data_fim": null,
"mensagem_erro": null,
"automation_type": "certidao_trabalhista",
"priority": 0,
"retry_count": 0,
"progress": 45,
"metadata_json": null,
"display_name": "Certidão Trabalhista (CNDT)",
"client_name": "Comércio de Alimentos Ltda"
}
}Escopo: worker_automation:read
POST /worker-automation/{worker_id}/cancel
Cancela a task e atualiza o status para CANCELADO. Exige apenas o escopo worker_automation:write.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
worker_id | int | path | sim | ID do worker a ser cancelado. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Task cancelada com sucesso",
"data": {
"id": 812,
"task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
"cliente_id": 1024,
"usuario_id": 42,
"status": "CANCELADO",
"data_inicio": "2026-07-08T09:15:00-03:00",
"data_fim": "2026-07-08T09:31:00-03:00",
"automation_type": "certidao_trabalhista",
"priority": 0,
"retry_count": 0,
"progress": 45
}
}Escopo: worker_automation:write
POST /worker-automation/{worker_id}/retry
Re-enfileira um worker em estado FALHA ou CANCELADO. Resolve o nome real da task pelo catálogo de automações, cria uma nova task assíncrona e devolve o worker atualizado com status AGENDADO e retry_count incrementado. Exige apenas o escopo worker_automation:write.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
worker_id | int | path | sim | ID do worker a ser re-enfileirado. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Task re-enfileirada com sucesso",
"data": {
"id": 812,
"task_id": "b7e2d4a1-3c8f-4a6b-9d0e-1f2a3b4c5d6e",
"cliente_id": 1024,
"usuario_id": 42,
"status": "AGENDADO",
"data_inicio": null,
"data_fim": null,
"mensagem_erro": null,
"automation_type": "certidao_trabalhista",
"priority": 0,
"retry_count": 1,
"progress": 0
}
}Worker de cliente inativo retorna 409 no envelope de erro: { "status": "error", "message": "Cliente inativo: automações bloqueadas.", "details": null }.
Escopo: worker_automation:write
Operações administrativas (acesso restrito)
Uso interno do escritório
As rotas desta seção são de uso interno e operam sobre a fila de processamento como um todo. Várias são destrutivas e irreversíveis. Não as exponha a clientes de IA nem as chame sem confirmação humana explícita.
GET /worker-automation/queue-live-status
Estado em tempo real de cada fila, com as tasks ativas e pendentes, a carga (load_percent) e um summary com os totais do dia.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Status das filas recuperado com sucesso",
"data": {
"queues": [
{
"queue_name": "<fila>",
"workers_count": 2,
"active_tasks": [],
"pending_tasks": [],
"active_count": 1,
"pending_count": 4,
"capacity": 2,
"load_percent": 50.0
}
],
"summary": {
"total_active": 5,
"total_pending": 18,
"total_completed_today": 87,
"total_errors_today": 3
}
}
}Escopo: worker_automation:read
GET /worker-automation/broker-status
Snapshot do serviço de mensageria que alimenta a fila de processamento: disponibilidade e quantidade de mensagens pendentes em cada fila.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "<mensagem de confirmação>",
"data": {
"available": true,
"queues": {
"<fila>": 4
}
}
}Escopo: worker_automation:read
GET /worker-automation/workers-inspect
Diagnóstico direto dos processos que executam as tasks (em execução, reservadas, agendadas e resposta de verificação), com timeout curto. Quando o serviço de mensageria não responde, available vem false e as seções vêm vazias.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "<mensagem de confirmação>",
"data": {
"active": {},
"reserved": {},
"scheduled": {},
"stats": {},
"ping": {},
"available": true
}
}Escopo: worker_automation:read
POST /worker-automation/{worker_id}/move
Migra o worker para outra fila, revogando a task antiga e reagendando-a na fila de destino. O target_queue é validado contra as filas conhecidas.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
worker_id | int | path | sim | ID do worker a ser migrado. |
O corpo segue o schema WorkerMoveQueue: target_queue (obrigatório).
Request
{
"target_queue": "<fila>"
}Response 200 OK
{
"status": "success",
"message": "Worker migrado de fila com sucesso",
"data": {
"id": 812,
"task_id": "c9f3e5b2-4d7a-4b8c-a1e2-3f4b5c6d7e8f",
"cliente_id": 1024,
"usuario_id": 42,
"status": "AGENDADO",
"automation_type": "certidao_trabalhista",
"queue": "<fila>",
"priority": 0,
"retry_count": 0,
"progress": 0
}
}Worker de cliente inativo retorna 409 no mesmo envelope de erro do retry.
Escopo: worker_automation:write
POST /worker-automation/{worker_id}/reorder
Altera a prioridade de execução do worker. Quanto menor o número, mais cedo é processado.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
worker_id | int | path | sim | ID do worker a ser reordenado. |
O corpo segue o schema WorkerReorder: new_priority (obrigatório).
Request
{
"new_priority": 1
}Response 200 OK
{
"status": "success",
"message": "Prioridade alterada com sucesso",
"data": {
"id": 845,
"task_id": null,
"cliente_id": 1099,
"usuario_id": 42,
"status": "AGENDADO",
"automation_type": "simples_nacional",
"queue": "<fila>",
"priority": 1,
"retry_count": 0,
"progress": 0
}
}Escopo: worker_automation:write
POST /worker-automation/clear-queue
Operação destrutiva. Cancela em massa os workers conforme o parâmetro scope. Cada worker é marcado como CANCELADO e tem a task revogada, com interrupção forçada dos que estão em execução.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
scope | str | query | não | queued (apenas AGENDADO), running (apenas EXECUTANDO) ou all (ambos, default all). |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "18 worker(s) cancelado(s) com sucesso",
"data": {
"cancelled": 18,
"scope": "all"
}
}Um scope fora dos valores aceitos retorna 422 com { "detail": [...] }.
Escopo: worker_automation:write
Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
clear-queue é irreversível
Cancela em massa todos os workers no escopo informado e não há "desfazer". Nunca chame esta rota sem confirmação humana explícita.
POST /worker-automation/broker/purge-queue/{queue_name}
Operação destrutiva. Apaga a fila no serviço de mensageria, descartando todas as mensagens ainda não entregues. Tasks já em execução continuam. Exige ?confirm=true.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
queue_name | str | path | sim | Nome da fila a purgar. Fila desconhecida retorna erro. |
confirm | bool | query | sim | Confirmação obrigatória. Sem confirm=true a operação é recusada. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "<mensagem de confirmação>",
"data": {
"queue_name": "<fila>",
"<chaves_removidas>": 2
}
}<chaves_removidas> é a contagem de itens removidos da fila.
Escopo: worker_automation:write
Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
DELETE /worker-automation/cleanup-no-client
Operação destrutiva. Remove do banco os workers AGENDADO/EXECUTANDO sem cliente válido, revogando a task antes de excluir.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "3 worker(s) sem cliente removido(s) do banco",
"data": {
"deleted": 3
}
}Escopo: worker_automation:write
Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
POST /worker-automation/sync-orphans
Detecta workers AGENDADO/EXECUTANDO cuja task se perdeu (sem task_id, ou antigos e ainda sem andamento) e os marca como CANCELADO. Útil após uma interrupção do serviço de mensageria.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "2 worker(s) orfao(s) detectado(s) e cancelado(s)",
"data": {
"orphans_found": 2,
"total_checked": 23
}
}Escopo: worker_automation:write
Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
Schemas
Schema típico de task status
Resposta de GET /worker-automation/status/{task_id}:
{
"status": "success",
"message": "Status da task recuperado com sucesso",
"data": {
"task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
"state": "SUCCESS",
"result": {
"certidao_id": 1234,
"url_pdf": "/api/v1/certidao-negativa/1234/pdf",
"tempo_execucao_s": 47.2
}
}
}Em estados não terminais (PENDING, STARTED, RETRY), result pode vir como null ou conter metadados parciais. Em FAILURE, o campo erro traz a mensagem resumida.