User Acessorias Config

Endpoints da WebApiAlcance para gerenciar a configuração por usuário das credenciais de integração com o Acessórias - o vínculo entre um usuário interno (usuario_id) e o par de credenciais (login/senha) usado para autenticar na plataforma Acessórias. Cobrem listagem geral, detalhamento por ID, busca pela configuração de um usuário, criação, atualização 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/user-acessorias

Escopos necessários

user_acessorias:read - listagem, detalhamento por ID e busca por usuário
user_acessorias:write - criação, atualização e exclusão

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

Endpoints

`GET /user-acessorias/`

Lista todas as configurações de Acessórias cadastradas. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhuma configuração encontrada.".

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": "Configurações recuperadas com sucesso",
  "data": [
    { "id": 1, "usuario_id": 7, "login": "operador.alcance", "senha": "..." },
    { "id": 2, "usuario_id": 12, "login": "financeiro.alcance", "senha": "..." }
  ]
}

Escopo: user_acessorias:read

`GET /user-acessorias/{config_id}`

Detalha uma configuração pelo ID inteiro. Quando não encontrada, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID interno da configuração

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração encontrada com sucesso",
  "data": {
    "id": 1,
    "usuario_id": 7,
    "login": "operador.alcance",
    "senha": "..."
  }
}

Escopo: user_acessorias:read

`POST /user-acessorias/`

Cria uma nova configuração de Acessórias para um usuário.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (UserAcessoriasConfigCreate): usuario_id, login e senha, todos obrigatórios.

Request

{
  "usuario_id": 7,
  "login": "operador.alcance",
  "senha": "s3nh4-acessorias"
}

Response 201 Created

{
  "success": true,
  "message": "Configuração criada com sucesso",
  "data": {
    "id": 3,
    "usuario_id": 7,
    "login": "operador.alcance",
    "senha": "..."
  }
}

Em caso de erro de validação/regra de negócio, retorna o envelope de erro (success: false). Escopo: user_acessorias:write

`PUT /user-acessorias/{config_id}`

Atualiza uma configuração existente. O body (UserAcessoriasConfigUpdate) tem a mesma estrutura do create - usuario_id, login e senha.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da configuração

Request

{
  "usuario_id": 7,
  "login": "operador.alcance",
  "senha": "nova-s3nh4-acessorias"
}

Response 200 OK

{
  "success": true,
  "message": "Configuração atualizada com sucesso",
  "data": {
    "id": 1,
    "usuario_id": 7,
    "login": "operador.alcance",
    "senha": "..."
  }
}

Escopo: user_acessorias:write

`DELETE /user-acessorias/{config_id}`

Remove uma configuração pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`config_id`	`int`	path	sim	ID da configuração

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração deletada com sucesso",
  "data": null
}

Escopo: user_acessorias:write

`GET /user-acessorias/user/{user_id}`

Busca a configuração de Acessórias pelo ID do usuário (usuario_id), e não pelo ID da configuração. Quando não há configuração para o usuário, retorna o envelope de erro com a mensagem "Configuração não encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	path	sim	ID do usuário interno

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Configuração encontrada com sucesso",
  "data": {
    "id": 1,
    "usuario_id": 7,
    "login": "operador.alcance",
    "senha": "..."
  }
}

Escopo: user_acessorias:read

Schemas

`UserAcessoriasConfigCreate`

Herda de UserAcessoriasConfigBase. Todos os campos são obrigatórios.

Campo	Tipo	Obrigatório	Observações
`usuario_id`	`int`	sim	ID do usuário interno dono da configuração.
`login`	`str`	sim	Login usado para autenticar na plataforma Acessórias.
`senha`	`str`	sim	Senha de acesso ao Acessórias. Campo sensível.

`UserAcessoriasConfigUpdate`

Estrutura idêntica ao UserAcessoriasConfigCreate - herda de UserAcessoriasConfigBase com os mesmos campos usuario_id, login e senha.

`UserAcessoriasConfigResponse`

Campo	Tipo	Notas
`id`	`int`	Identificador da configuração.
`usuario_id`	`int`	Usuário interno dono da configuração.
`login`	`str`	Login de acesso ao Acessórias.
`senha`	`str`	Senha de acesso ao Acessórias. Sensível.

Campo sensível: senha

O campo senha armazena a credencial de acesso à plataforma Acessórias. Na fonte atual, o schema UserAcessoriasConfigResponse inclui senha no payload de leitura - ou seja, a senha é retornada nas respostas de GET, POST e PUT. Trate esse dado com cuidado: não exponha estes endpoints a clientes IA via gateway MCP e restrinja o escopo user_acessorias:read a integrações estritamente confiáveis. Se a senha não precisa ser devolvida na leitura, considere remover o campo do schema de resposta.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
A rota estática GET /user-acessorias/user/{user_id} (dois segmentos) não conflita com a rota dinâmica GET /user-acessorias/{config_id} (um segmento), pois casam padrões de caminho distintos.
GET /user-acessorias/user/{user_id} filtra por usuario_id; já GET /user-acessorias/{config_id} filtra pela chave primária id da configuração.