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:

EscopoQuando é necessário
worker_automation:readListagens, detalhes, stats, dashboard, status de task.
worker_automation:writecancel 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.

EstadoSignificado
PENDINGTask aceita, aguardando execução.
STARTEDExecução iniciada.
SUCCESSExecução concluída sem erros. result contém o payload.
FAILUREExecução falhou. erro traz a mensagem resumida.
RETRYTask falhou e será executada novamente.
REVOKEDCancelada 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âmetroTipoLocalObrigatórioDescrição
statusstrquerynãoFiltra por estado do worker (ex.: AGENDADO, EXECUTANDO, FALHA).
automation_typestrquerynãoFiltra pelo tipo de automação (chave do catálogo de automações).
date_fromdatetimequerynãoData/hora inicial do intervalo de criação.
date_todatetimequerynãoData/hora final do intervalo de criação.
pageintquerynãoPágina (≥ 1, default 1).
per_pageintquerynãoItens 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âmetroTipoObservações
data_iniciodateInício do período (AAAA-MM-DD, horário de Brasília).
data_fimdateFim do período, inclusive.
automation_typestrRestringe 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âmetroTipoObrigatórioObservações
data_iniciodatesimInício do período (AAAA-MM-DD, horário de Brasília).
data_fimdatesimFim do período, inclusive.
group_bystrnãodia (default) ou mes. Outro valor retorna 422.
automation_typestrnãoFiltra um tipo de automação.
cliente_idintnão> 0. Filtra um cliente.
usuario_idintnã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=dia

Response 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:

CampoStatus contados
sucessoCONCLUIDO
erroFALHA
pendenciaAGENDADO, EXECUTANDO
canceladoCANCELADO
outrosQualquer 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âmetroTipoObservações
data_iniciodateInício do período (AAAA-MM-DD, horário de Brasília).
data_fimdateFim do período, inclusive.
cliente_idint> 0. Restringe a um cliente.
usuario_idint> 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-31

Response 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âmetroTipoLocalObrigatórioDescrição
pageintquerynãoPágina (≥ 1, default 1).
per_pageintquerynãoItens 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âmetroTipoLocalObrigatórioDescrição
qstrquerynãoTexto 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âmetroTipoLocalObrigatórioDescrição
task_idstrpathsimUUID 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âmetroTipoLocalObrigatórioDescrição
worker_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
worker_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
worker_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
worker_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
worker_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
scopestrquerynãoqueued (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âmetroTipoLocalObrigatórioDescrição
queue_namestrpathsimNome da fila a purgar. Fila desconhecida retorna erro.
confirmboolquerysimConfirmaçã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.