Automation: Agendamentos

Endpoints da WebApiAlcance para gerenciar agendamentos de automação - registros que programam a execução recorrente de uma automação para um cliente, definindo o tipo de automação, o cliente-alvo, o usuário executor e a antecedência (lead time) com que a próxima execução deve ser disparada. Cobrem criação, listagem geral, detalhamento por ID, atualização parcial e exclusão.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/agendamento-automation

Escopos necessários

agendamento_automation:read - listagem e detalhamento por ID
agendamento_automation:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /agendamento-automation vira o recurso agendamento_automation (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /agendamento-automation/`

Cria um novo agendamento de automação, programando a execução recorrente de uma automação para um cliente. O tipo de automação, o cliente-alvo e o usuário executor são obrigatórios.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (AgendamentoAutomationCreate): automation_type, customer_id e executor_user_id (obrigatórios); lead_time_days (opcional, default 5), status (opcional, default "ATIVO"), extra (opcional) e next_run_at (opcional).

Request

{
  "automation_type": "certidao_negativa",
  "customer_id": 128,
  "executor_user_id": 7,
  "lead_time_days": 5,
  "status": "ATIVO",
  "next_run_at": "2026-07-10T09:00:00"
}

Response 201 Created

{
  "success": true,
  "message": "Agendamento criado com sucesso",
  "data": {
    "id": 42,
    "automation_type": "certidao_negativa",
    "customer_id": 128,
    "executor_user_id": 7,
    "lead_time_days": 5,
    "status": "ATIVO",
    "extra": null,
    "next_run_at": "2026-07-10T09:00:00",
    "last_run_at": null,
    "last_worker_id": null,
    "created_at": "2026-07-03T14:22:11",
    "updated_at": "2026-07-03T14:22:11"
  }
}

Quando já existe um agendamento conflitante (mesma automação/cliente), a rota retorna 409 Conflict com o detail da regra de negócio. Escopo: agendamento_automation:write

`GET /agendamento-automation/`

Lista todos os agendamentos de automação cadastrados. Quando não há nenhum, retorna o envelope de erro { "success": false, "message": "Nenhum agendamento encontrado.", "details": [] }.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Agendamentos recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "automation_type": "certidao_negativa",
      "customer_id": 128,
      "executor_user_id": 7,
      "lead_time_days": 5,
      "status": "ATIVO",
      "extra": null,
      "next_run_at": "2026-07-10T09:00:00",
      "last_run_at": null,
      "last_worker_id": null,
      "created_at": "2026-07-03T14:22:11",
      "updated_at": "2026-07-03T14:22:11"
    }
  ]
}

Escopo: agendamento_automation:read

`GET /agendamento-automation/{schedule_id}`

Detalha um agendamento pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail: "Agendamento não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`schedule_id`	`int`	path	sim	ID interno do agendamento

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Agendamento encontrado!",
  "data": {
    "id": 42,
    "automation_type": "certidao_negativa",
    "customer_id": 128,
    "executor_user_id": 7,
    "lead_time_days": 5,
    "status": "ATIVO",
    "extra": null,
    "next_run_at": "2026-07-10T09:00:00",
    "last_run_at": null,
    "last_worker_id": null,
    "created_at": "2026-07-03T14:22:11",
    "updated_at": "2026-07-03T14:22:11"
  }
}

Escopo: agendamento_automation:read

`PUT /agendamento-automation/{schedule_id}`

Atualiza um agendamento existente. O body é um AgendamentoAutomationUpdate com campos parciais - somente o que vier preenchido é alterado. Quando o ID não existe, retorna 404 Not Found com detail: "Agendamento não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`schedule_id`	`int`	path	sim	ID do agendamento

Request (AgendamentoAutomationUpdate - todos os campos opcionais)

{
  "lead_time_days": 7,
  "status": "INATIVO",
  "next_run_at": "2026-08-01T09:00:00"
}

Response 200 OK

{
  "success": true,
  "message": "Agendamento atualizado!",
  "data": {
    "id": 42,
    "automation_type": "certidao_negativa",
    "customer_id": 128,
    "executor_user_id": 7,
    "lead_time_days": 7,
    "status": "INATIVO",
    "extra": null,
    "next_run_at": "2026-08-01T09:00:00",
    "last_run_at": null,
    "last_worker_id": null,
    "created_at": "2026-07-03T14:22:11",
    "updated_at": "2026-07-03T16:05:44"
  }
}

Escopo: agendamento_automation:write

`DELETE /agendamento-automation/{schedule_id}`

Remove um agendamento de automação pelo ID. Quando o ID não existe, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`schedule_id`	`int`	path	sim	ID do agendamento

Request

Sem corpo de requisição.

Response 204 No Content

Exclusão bem-sucedida, sem corpo de resposta.

Escopo: agendamento_automation:write

Schemas

`AgendamentoAutomationCreate`

Campo	Tipo	Obrigatório	Observações
`automation_type`	`str`	sim	Tipo da automação a ser executada.
`customer_id`	`int`	sim	ID do cliente-alvo do agendamento.
`executor_user_id`	`int`	sim	ID do usuário que executa a automação.
`lead_time_days`	`int`	não	Antecedência (em dias) para disparar a execução. Default `5`.
`status`	`str`	não	Situação do agendamento. Default `"ATIVO"`.
`extra`	`dict[str, Any]`	não	Metadados adicionais livres. Default `null`.
`next_run_at`	`datetime`	não	Data/hora da próxima execução programada. Default `null`.

`AgendamentoAutomationUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados.

Campo	Tipo	Observações
`lead_time_days`	`int`	Nova antecedência (em dias) para a execução.
`status`	`str`	Nova situação do agendamento.
`next_run_at`	`datetime`	Nova data/hora da próxima execução.
`extra`	`dict[str, Any]`	Novos metadados adicionais.

`AgendamentoAutomationRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do agendamento.
`automation_type`	`str`	Tipo da automação.
`customer_id`	`int`	Cliente-alvo.
`executor_user_id`	`int`	Usuário executor.
`lead_time_days`	`int`	Antecedência (em dias) para disparar a execução.
`status`	`str`	Situação (`"ATIVO"` por padrão).
`extra`	`dict[str, Any]`	Metadados adicionais (`null` quando não informado).
`next_run_at`	`datetime`	Próxima execução programada (`null` quando não definida).
`last_run_at`	`datetime`	Última execução realizada (`null` se nunca executou).
`last_worker_id`	`int`	ID do último worker que executou o agendamento (`null` se nenhum).
`created_at`	`datetime`	Data/hora de criação do registro.
`updated_at`	`datetime`	Data/hora da última atualização.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Na criação, um conflito de regra de negócio (ex.: agendamento duplicado) resulta em 409 Conflict.
Os campos last_run_at e last_worker_id são preenchidos pela plataforma após cada execução, relacionando o agendamento ao worker que o processou - veja Worker Automation.