Customer QSA

Endpoints da WebApiAlcance para gerenciar o Quadro de Sócios e Administradores (QSA) vinculado a cada cliente da Alcance Contabilidade. Cada registro representa um sócio ou administrador de um cliente (pessoa jurídica), com dados como nome, CPF/CNPJ, qualificação, situação cadastral e participação no capital. Cobrem registro, listagem geral, listagem por cliente, detalhamento por ID, atualização, exclusão e importação automática de sócios a partir de PDFs de Situação Fiscal (SITFIS).

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-qsa

Escopos necessários

customer_qsa:read - listagem geral, listagem por cliente e detalhamento
customer_qsa:write - registro, atualização, exclusão e importação de sócios

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

Endpoints

`POST /customer-qsa/`

Registra um novo sócio no QSA de um cliente. Retorna 200 OK (e não 201 Created) ao criar o registro.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CustomerQsaCreate): cliente_id e nome são obrigatórios; cpfecnpj, qualificacao, situacao_cadastral, capital_social e capital_votante são opcionais.

Request

{
  "cliente_id": 1234,
  "nome": "JOÃO DA SILVA",
  "cpfecnpj": "123.456.789-00",
  "qualificacao": "Sócio-Administrador",
  "situacao_cadastral": "Ativa",
  "capital_social": "100000.00",
  "capital_votante": "100.00"
}

Response 200 OK

{
  "success": true,
  "message": "Socio registrado com sucesso!",
  "data": {
    "id": 42,
    "cliente_id": 1234,
    "cpfecnpj": "123.456.789-00",
    "nome": "JOÃO DA SILVA",
    "qualificacao": "Sócio-Administrador",
    "situacao_cadastral": "Ativa",
    "capital_social": "100000.00",
    "capital_votante": "100.00"
  }
}

Escopo: customer_qsa:write

`GET /customer-qsa/`

Lista todos os sócios cadastrados no sistema. Lista vazia é um estado válido - retorna 200 OK com data: [].

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": "Socios listados com sucesso!",
  "data": [
    {
      "id": 42,
      "cliente_id": 1234,
      "cpfecnpj": "123.456.789-00",
      "nome": "JOÃO DA SILVA",
      "qualificacao": "Sócio-Administrador",
      "situacao_cadastral": "Ativa",
      "capital_social": "100000.00",
      "capital_votante": "100.00"
    },
    {
      "id": 43,
      "cliente_id": 1234,
      "cpfecnpj": "987.654.321-00",
      "nome": "MARIA SOUZA",
      "qualificacao": "Sócia",
      "situacao_cadastral": "Ativa",
      "capital_social": "50000.00",
      "capital_votante": "0.00"
    }
  ]
}

Escopo: customer_qsa:read

`GET /customer-qsa/cliente/{cliente_id}`

Lista todos os sócios vinculados a um cliente específico. Retorna 200 OK com data: [] quando o cliente não tem sócios cadastrados.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cliente_id`	`int`	path	sim	ID interno do cliente (Customer)

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Socios do cliente listados com sucesso!",
  "data": [
    {
      "id": 42,
      "cliente_id": 1234,
      "cpfecnpj": "123.456.789-00",
      "nome": "JOÃO DA SILVA",
      "qualificacao": "Sócio-Administrador",
      "situacao_cadastral": "Ativa",
      "capital_social": "100000.00",
      "capital_votante": "100.00"
    }
  ]
}

Escopo: customer_qsa:read

`GET /customer-qsa/{qsa_id}`

Detalha um sócio pelo ID inteiro do registro de QSA. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`qsa_id`	`int`	path	sim	ID interno do registro de QSA

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Sócio encontrado!",
  "data": {
    "id": 42,
    "cliente_id": 1234,
    "cpfecnpj": "123.456.789-00",
    "nome": "JOÃO DA SILVA",
    "qualificacao": "Sócio-Administrador",
    "situacao_cadastral": "Ativa",
    "capital_social": "100000.00",
    "capital_votante": "100.00"
  }
}

Escopo: customer_qsa:read

`PUT /customer-qsa/{qsa_id}`

Atualiza um registro de sócio existente. O body é um CustomerQsaUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`qsa_id`	`int`	path	sim	ID do registro de QSA

Request (CustomerQsaUpdate - todos os campos opcionais)

{
  "qualificacao": "Sócio-Gerente",
  "capital_votante": "60.00"
}

Response 200 OK

{
  "success": true,
  "message": "Socio atualizado com sucesso!",
  "data": {
    "id": 42,
    "cliente_id": 1234,
    "cpfecnpj": "123.456.789-00",
    "nome": "JOÃO DA SILVA",
    "qualificacao": "Sócio-Gerente",
    "situacao_cadastral": "Ativa",
    "capital_social": "100000.00",
    "capital_votante": "60.00"
  }
}

Escopo: customer_qsa:write

`DELETE /customer-qsa/{qsa_id}`

Remove um registro de sócio do QSA pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`qsa_id`	`int`	path	sim	ID do registro de QSA

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Socio removido com sucesso!",
  "data": null
}

Escopo: customer_qsa:write

`POST /customer-qsa/importar-socios`

Importa sócios automaticamente a partir de um ou mais PDFs de Situação Fiscal (SITFIS). O endpoint recebe os arquivos via multipart/form-data, extrai o quadro societário de cada PDF e persiste os registros no QSA do cliente correspondente.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os arquivos vão no corpo multipart/form-data.

Parâmetro	Tipo	Local	Obrigatório	Descrição
`pdfs`	`List[UploadFile]`	form-data (`File`)	sim	PDFs de Situação Fiscal (SITFIS). Repita o campo para múltiplos arquivos.

Request

Envie os arquivos como multipart/form-data, repetindo o campo pdfs para cada PDF:

POST /api/v1/customer-qsa/importar-socios
Content-Type: multipart/form-data
 
pdfs=@sitfis-cliente-a.pdf
pdfs=@sitfis-cliente-b.pdf

Response 200 OK

{
  "success": true,
  "message": "2 arquivo(s) processado(s).",
  "data": {}
}

Em caso de falha no processamento, retorna o envelope de erro { success: false, message: "Erro ao importar socios.", details: [...] }.

Escopo: customer_qsa:write

Schemas

`CustomerQsaCreate`

Campo	Tipo	Obrigatório	Observações
`cliente_id`	`int`	sim	ID do cliente (Customer) ao qual o sócio pertence.
`nome`	`str`	sim	Nome do sócio ou administrador.
`cpfecnpj`	`str`	não	CPF ou CNPJ do sócio. Default `null`.
`qualificacao`	`str`	não	Qualificação (ex.: `Sócio-Administrador`). Default `null`.
`situacao_cadastral`	`str`	não	Situação cadastral do sócio. Default `null`.
`capital_social`	`str`	não	Valor do capital social. Default `null`.
`capital_votante`	`str`	não	Percentual/valor do capital votante. Default `null`.

`CustomerQsaUpdate`

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

Campo	Tipo	Observações
`cpfecnpj`	`str`	Novo CPF/CNPJ do sócio.
`nome`	`str`	Novo nome.
`qualificacao`	`str`	Nova qualificação.
`situacao_cadastral`	`str`	Nova situação cadastral.
`capital_social`	`str`	Novo capital social.
`capital_votante`	`str`	Novo capital votante.

`CustomerQsaRead`

Estende CustomerQsaBase adicionando o id. Serializa a partir do model (from_attributes = True).

Campo	Tipo	Notas
`id`	`int`	Identificador do registro de QSA.
`cliente_id`	`int`	Cliente (Customer) ao qual o sócio pertence.
`nome`	`str`	Nome do sócio ou administrador.
`cpfecnpj`	`str`	CPF/CNPJ do sócio (pode ser `null`).
`qualificacao`	`str`	Qualificação do sócio (pode ser `null`).
`situacao_cadastral`	`str`	Situação cadastral (pode ser `null`).
`capital_social`	`str`	Capital social (pode ser `null`).
`capital_votante`	`str`	Capital votante (pode ser `null`).

Notas

Ordem de rotas no FastAPI

GET /customer-qsa/cliente/{cliente_id} é declarado antes da rota dinâmica GET /customer-qsa/{qsa_id}, então cliente é resolvido como segmento estático (e não interpretado como um qsa_id).

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O POST /customer-qsa/ retorna 200 OK (e não 201 Created) ao registrar um novo sócio.
A importação via SITFIS (POST /customer-qsa/importar-socios) usa multipart/form-data e aceita múltiplos PDFs em uma única chamada; a mensagem de retorno informa a quantidade de arquivos processados.
Relaciona-se com Customers - cada registro de QSA referencia um cliente pelo campo cliente_id.