Automation: Acessorias

Endpoints da WebApiAlcance para automação de obrigações acessórias - disparam o login automático no portal Acessórias (e-Continuo) e as sincronizações de obrigações e de contatos/departamentos, executadas de forma assíncrona. A chamada não bloqueia: ela cria um registro de Worker, enfileira a task e retorna imediatamente com a confirmação de agendamento.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

Base path

/api/v1/automation/acessorias

Escopos necessários

Escopo derivado de automation

O recurso do escopo é derivado do 1º segmento após /api/v1/, que aqui é automation - não automation_acessorias. Portanto os escopos válidos são automation:read e automation:write. Esse mesmo par de escopos é compartilhado com Automation: Tax: uma API Key com automation:write habilita a escrita em ambos os domínios de automação.

  • automation:write - enfileirar automações (POST /automation/acessorias/login, /sync-obrigacoes e /sync-contatos-departamentos)
  • automation:read - consultas de leitura sob o recurso automation (quando existirem)

A ação é definida pelo método HTTP: read para GET, write para POST/PUT/DELETE.

Endpoints

POST /automation/acessorias/login

Enfileira o login automático no Acessórias (e-Continuo) para o usuário informado. A chamada busca o usuário por user_id, cria um registro Worker (status: "AGENDADO", automation_type: "login_acessorias"), dispara a task login_acessorias gravando o task_id retornado, registra a atividade e o log da automação, e responde imediatamente com o envelope de sucesso. Como a execução é assíncrona, acompanhe o andamento pelo Worker/task_id gerado - consulte Worker Automation para os endpoints de status de task (ex.: GET /worker-automation/status/{task_id}).

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário cujo login será automatizado. Precisa ser o do usuário autenticado, exceto para usuários com permissão adicional (demais recebem 403).

Request

Sem corpo de requisição - o user_id é enviado como parâmetro de query.

Response 200 OK

{
  "status": "success",
  "message": "Automação agendada com sucesso.",
  "data": null
}

Quando o usuário não é encontrado, a resposta foge do envelope padrão e retorna { "error": "Usuário não encontrado" }.

Escopo: automation:write

POST /automation/acessorias/sync-obrigacoes

Enfileira a sincronização de obrigações com a Acessórias para um período de prazos. Cria um Worker (automation_type: "sync_obrigacoes") em nome do usuário autenticado e responde com o worker_id.

Acompanhe e cancele pelo Worker Automation: GET /worker-automation/{id} (status, progress e o resumo em metadata_json) e POST /worker-automation/{id}/cancel.

Parâmetros

Sem parâmetros de rota ou query - os dados vão no corpo:

CampoTipoObrigatórioObservações
dt_inicialdatesimPrimeiro dia do período (prazo das obrigações), AAAA-MM-DD.
dt_finaldatesimÚltimo dia do período, inclusive. A janela tem no máximo 31 dias.

Request

{
  "dt_inicial": "2026-08-01",
  "dt_final": "2026-08-31"
}

Response 200 OK

{
  "status": "success",
  "message": "Sincronização de obrigações agendada com sucesso.",
  "data": { "worker_id": 4521 }
}

Erros

HTTPQuando
403Usuário sem permissão.
409Já existe uma sincronização de obrigações ou de contatos e departamentos AGENDADA/EXECUTANDO (cancele a travada por /cancel). A mensagem informa qual está em andamento.
422Corpo inválido: dt_inicial maior que dt_final ou janela maior que 31 dias.
429Limite de requisições excedido.
503Serviço de processamento indisponível: a sincronização não foi agendada.

Escopo: automation:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

POST /automation/acessorias/sync-contatos-departamentos

Enfileira a sincronização de contatos e departamentos com a Acessórias. Cria um Worker (automation_type: "sync_contatos_departamentos") em nome do usuário autenticado e responde com o worker_id. Acompanhamento e cancelamento são os mesmos da sincronização de obrigações.

Parâmetros

Sem parâmetros de rota, query ou corpo.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Sincronização de contatos e departamentos agendada com sucesso.",
  "data": { "worker_id": 4522 }
}

Erros

HTTPQuando
403Usuário sem permissão.
409Já existe uma sincronização de contatos e departamentos ou de obrigações AGENDADA/EXECUTANDO.
429Limite de requisições excedido.
503Serviço de processamento indisponível: a sincronização não foi agendada.

Escopo: automation:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

Notas

  • Toda resposta de sucesso segue o envelope { status, message, data }. No login, o caso de usuário inexistente foge do envelope padrão e retorna { "error": "Usuário não encontrado" }.
  • As duas sincronizações compartilham o limite da Acessórias: uma não começa enquanto a outra estiver agendada ou em execução (409).
  • Para estados da task (PENDING, STARTED, SUCCESS, FAILURE, RETRY, REVOKED) e monitoramento, veja Worker Automation e tasks assíncronas.
  • O login em si é feito por um scraper (e-Continuo). Falhas de credencial ou de acesso ao portal são registradas nos logs de automação, e o Worker correspondente reflete o resultado final da execução.
  • Os escopos automation:read / automation:write são compartilhados com Automation: Tax - ambos derivam do recurso automation.