Customer Ata

Endpoints da WebApiAlcance para gerenciar as atas do cliente - o registro de uma ata de assembleia/reunião societária vinculada a um cliente da Alcance Contabilidade. Cada ata pertence a um cliente (id_cliente), pode estar vinculada a um sócio do quadro societário (id_customer_qsa), carrega um valor financeiro (com um saldo computado a partir dos lançamentos de lucro que a consomem) e percorre um ciclo de vida por status. Os endpoints cobrem criação, listagem das atas do usuário autenticado, listagem por cliente, detalhamento por ID, 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/customer-ata

Escopos necessários

customer_ata:read - listagem por usuário, listagem por cliente e detalhamento
customer_ata:write - criação, atualização e exclusão

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

Endpoints

`POST /customer-ata/`

Cria uma nova ata vinculada a um cliente. O usuário autenticado é registrado como criador da ata (id_usuario_created) - o campo não vem no corpo da requisição.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CustomerAtaCreate): id_cliente (obrigatório), valor (obrigatório), id_customer_qsa, data_validade, status, valor_contabil e observacao (opcionais).

Request

{
  "id_cliente": 1,
  "id_customer_qsa": 10,
  "data_validade": "2026-12-31",
  "status": "ativo",
  "valor": "1234.56",
  "valor_contabil": "1000.00",
  "observacao": "Ata de assembleia ordinária."
}

Response 201 Created

{
  "success": true,
  "message": "Ata criada com sucesso!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_customer_qsa": 10,
    "data_validade": "2026-12-31",
    "status": "ativo",
    "valor": "1234.56",
    "valor_contabil": "1000.00",
    "observacao": "Ata de assembleia ordinária.",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T14:30:00",
    "saldo": "1234.56"
  }
}

Cliente ou sócio vinculado inexistente retorna 404 Not Found; validações de negócio (ex.: valor negativo) retornam 422 Unprocessable Entity. Escopo: customer_ata:write

`GET /customer-ata/by-user`

Lista todas as atas do usuário autenticado, com filtro e paginação opcionais. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma ata encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`status`	`str`	query	não	Filtro por status da ata. Ex.: `ativo`.
`page`	`int`	query	não	Página 1-based (`>= 1`).
`per_page`	`int`	query	não	Itens por página (1 a 500).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Atas recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_cliente": 1,
      "id_customer_qsa": 10,
      "data_validade": "2026-12-31",
      "status": "ativo",
      "valor": "1234.56",
      "valor_contabil": "1000.00",
      "observacao": "Ata de assembleia ordinária.",
      "id_usuario_created": 42,
      "data_hora_criacao": "2026-07-03T14:30:00",
      "saldo": "1234.56"
    }
  ]
}

Escopo: customer_ata:read

`GET /customer-ata/by-customer/{customer_id}`

Lista as atas de um cliente específico, opcionalmente filtradas por status e paginadas. É o caso de uso primário do front. Quando o cliente não existe, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`customer_id`	`int`	path	sim	ID do cliente (`customer.id`).
`status`	`str`	query	não	Filtro por status da ata. Ex.: `ativo`.
`page`	`int`	query	não	Página 1-based (`>= 1`).
`per_page`	`int`	query	não	Itens por página (1 a 500).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Atas recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_cliente": 1,
      "id_customer_qsa": 10,
      "data_validade": "2026-12-31",
      "status": "ativo",
      "valor": "1234.56",
      "valor_contabil": "1000.00",
      "observacao": "Ata de assembleia ordinária.",
      "id_usuario_created": 42,
      "data_hora_criacao": "2026-07-03T14:30:00",
      "saldo": "1234.56"
    }
  ]
}

Escopo: customer_ata:read

`GET /customer-ata/{ata_id}`

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

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Ata encontrada!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_customer_qsa": 10,
    "data_validade": "2026-12-31",
    "status": "ativo",
    "valor": "1234.56",
    "valor_contabil": "1000.00",
    "observacao": "Ata de assembleia ordinária.",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T14:30:00",
    "saldo": "1234.56"
  }
}

Escopo: customer_ata:read

`PUT /customer-ata/{ata_id}`

Atualiza uma ata existente. O body é um CustomerAtaUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos id, id_usuario_created, id_cliente e data_hora_criacao são imutáveis e não aparecem no schema (proteção contra mass-assignment).

Parâmetros

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

Request (CustomerAtaUpdate - todos os campos opcionais)

{
  "status": "suspenso",
  "valor": "2000.00",
  "observacao": "Ata revisada em assembleia extraordinária."
}

Response 200 OK

{
  "success": true,
  "message": "Ata atualizada!",
  "data": {
    "id": 1,
    "id_cliente": 1,
    "id_customer_qsa": 10,
    "data_validade": "2026-12-31",
    "status": "suspenso",
    "valor": "2000.00",
    "valor_contabil": "1000.00",
    "observacao": "Ata revisada em assembleia extraordinária.",
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T14:30:00",
    "saldo": "2000.00"
  }
}

Escopo: customer_ata:write

`DELETE /customer-ata/{ata_id}`

Remove uma ata pelo ID. Quando não encontrada, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Ata removida!",
  "data": null
}

Escopo: customer_ata:write

Schemas

`CustomerAtaCreate`

Herda todos os campos de CustomerAtaBase. id_usuario_created é derivado do usuário autenticado e não vem no payload.

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	ID do cliente (customer.id) ao qual a ata pertence.
`id_customer_qsa`	`int`	não	ID do sócio do quadro societário (customer_qsa.id).
`data_validade`	`date`	não	Data de validade da ata (sem hora). Ex.: `2026-12-31`.
`status`	`str`	não	Ciclo de vida. Valores: `ativo`, `inativo`, `suspenso`, `cancelado`. Default `ativo`.
`valor`	`Decimal`	sim	Valor associado à ata, não-negativo. Compatível com `Numeric(15,2)`.
`valor_contabil`	`Decimal`	não	Valor para fins contábeis, se diferente de `valor`. Não-negativo.
`observacao`	`str`	não	Observação livre. Máximo 200 caracteres.

`CustomerAtaUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Campos imutáveis (id, id_usuario_created, id_cliente, data_hora_criacao) não aparecem aqui.

Campo	Tipo	Observações
`id_customer_qsa`	`int`	Reatribui o vínculo opcional ao sócio.
`data_validade`	`date`	Nova data de validade.
`status`	`str`	Novo status (`ativo`, `inativo`, `suspenso`, `cancelado`).
`valor`	`Decimal`	Novo valor, não-negativo.
`valor_contabil`	`Decimal`	Novo valor contábil, não-negativo.
`observacao`	`str`	Nova observação. Máximo 200 caracteres.

`CustomerAtaRead`

Herda CustomerAtaBase e adiciona os campos gerenciados (identificador, dono e timestamp) mais o saldo computado.

Campo	Tipo	Notas
`id`	`int`	ID da ata.
`id_cliente`	`int`	Cliente ao qual a ata pertence.
`id_customer_qsa`	`int`	Sócio vinculado (opcional).
`data_validade`	`date`	Data de validade (opcional).
`status`	`str`	Status atual (`ativo`, `inativo`, `suspenso`, `cancelado`).
`valor`	`Decimal`	Valor associado à ata.
`valor_contabil`	`Decimal`	Valor contábil (opcional).
`observacao`	`str`	Observação livre (opcional).
`id_usuario_created`	`int`	Usuário que criou a ata (multi-tenant).
`data_hora_criacao`	`datetime`	Timestamp de criação (server-side).
`saldo`	`Decimal`	Saldo disponível = `valor` − Σ(`valor_ata_utilizada` dos lançamentos de lucro vinculados).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
As rotas estáticas GET /by-user e GET /by-customer/{customer_id} são declaradas antes da rota dinâmica GET /{ata_id}, para que o FastAPI as resolva corretamente (e não interprete by-user como um ata_id).
O campo valor deve ser não-negativo e menor que 10.000.000.000.000 (compatível com Numeric(15,2) do banco); o mesmo vale para valor_contabil.
O saldo é computado no service a partir dos lançamentos de lucro que consomem a ata - não é informado no payload de criação/atualização.