Smart: Saldo de Clientes Particulares

Endpoints da WebApiAlcance para o CRUD de saldos de clientes particulares consumido pelo produto Smart. Cada registro representa um movimento (recebimento/débito) de um cliente particular, com a forma de pagamento, o valor e a referência ao documento (nfx_numero) de origem. Os endpoints cobrem listagem com filtro por CNPJ e paginação, consulta por ID, 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.

Campo `valor` sai como string

O campo valor deste domínio é Decimal no schema (não float), para preservar a precisão do valor gravado no banco. O Pydantic serializa Decimal como string em JSON: por exemplo, "valor": "250.75", não "valor": 250.75. Faça a conversão explícita (Number(...)/parseFloat) no consumidor.

Base path

/api/v1/smart-saldo-clientes-particulares

Escopos necessários

smart_saldo_clientes_particulares:read - listagem e consulta por ID
smart_saldo_clientes_particulares:write - criação, atualização e exclusão

O escopo é derivado do prefixo público da rota: /smart-saldo-clientes-particulares vira o recurso smart_saldo_clientes_particulares (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/PATCH/DELETE).

Endpoints

`GET /smart-saldo-clientes-particulares/`

Lista os saldos de clientes particulares, com filtro opcional por CNPJ e paginação. Lista vazia é um estado válido - o retorno normal é 200 OK com data: [], não um erro.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cnpj`	`str`	query	não	Filtra os registros pelo CNPJ informado.
`limit`	`int`	query	não	Itens por página. Entre 1 e 500. Padrão `100`.
`offset`	`int`	query	não	Deslocamento de paginação. Padrão `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Saldos de clientes particulares recuperados com sucesso",
  "data": [
    {
      "id": 2101,
      "cnpj": "12345678000199",
      "cfg_emp": "HOSP01",
      "rdi_mte_serie": "1",
      "rdi_mte_seq": 5502,
      "valor": "250.75",
      "rdi_forma_pag": "PIX",
      "gcc_descr": "PARTICULARES",
      "str_nome": "MARIA DA SILVA SANTOS",
      "mte_tipo": "REC",
      "mte_dthr": "2026-01-10T14:30:00",
      "v_dt": "2026-01-10T00:00:00",
      "nfx_numero": "8821",
      "data_hora_criacao": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: smart_saldo_clientes_particulares:read

`GET /smart-saldo-clientes-particulares/{smart_saldo_id}`

Busca um saldo de cliente particular pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_saldo_id`	`int`	path	sim	ID do saldo de cliente particular.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Saldo de cliente particular recuperado com sucesso",
  "data": {
    "id": 2101,
    "cnpj": "12345678000199",
    "valor": "250.75",
    "...": "demais campos como em SmartSaldoClientesParticularesRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Saldo de cliente particular não encontrado."}. Escopo: smart_saldo_clientes_particulares:read

`POST /smart-saldo-clientes-particulares/`

Cria um novo saldo de cliente particular.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O corpo é o schema SmartSaldoClientesParticularesCreate.

Request

{
  "cnpj": "12.345.678/0001-99",
  "cfg_emp": "HOSP01",
  "rdi_mte_serie": "1",
  "rdi_mte_seq": 5502,
  "valor": 250.75,
  "rdi_forma_pag": "PIX",
  "gcc_descr": "PARTICULARES",
  "str_nome": "MARIA DA SILVA SANTOS",
  "mte_tipo": "REC",
  "mte_dthr": "2026-01-10T14:30:00",
  "v_dt": "2026-01-10T00:00:00",
  "nfx_numero": "8821"
}

Response 201 Created

{
  "status": "success",
  "message": "Saldo de cliente particular criado com sucesso",
  "data": {
    "id": 2101,
    "cnpj": "12345678000199",
    "valor": "250.75",
    "...": "demais campos como em SmartSaldoClientesParticularesRead"
  }
}

Em falha inesperada ao persistir, retorna 500 Internal Server Error com {"message": "Não foi possível criar o saldo de cliente particular."}. Escopo: smart_saldo_clientes_particulares:write

`PUT /smart-saldo-clientes-particulares/{smart_saldo_id}`

Atualiza um saldo de cliente particular existente. O cnpj não é editável por este endpoint - o schema de atualização não o inclui.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_saldo_id`	`int`	path	sim	ID do saldo de cliente particular.

O corpo é o schema SmartSaldoClientesParticularesUpdate, com todos os campos opcionais.

Request

{
  "valor": 260.00,
  "rdi_forma_pag": "CARTAO"
}

Response 200 OK

{
  "status": "success",
  "message": "Saldo de cliente particular atualizado com sucesso",
  "data": {
    "id": 2101,
    "cnpj": "12345678000199",
    "valor": "260.00",
    "rdi_forma_pag": "CARTAO",
    "...": "demais campos como em SmartSaldoClientesParticularesRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Saldo de cliente particular não encontrado."}. Escopo: smart_saldo_clientes_particulares:write

`DELETE /smart-saldo-clientes-particulares/{smart_saldo_id}`

Remove um saldo de cliente particular.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_saldo_id`	`int`	path	sim	ID do saldo de cliente particular.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Saldo de cliente particular removido com sucesso",
  "data": null
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Saldo de cliente particular não encontrado."}. Escopo: smart_saldo_clientes_particulares:write

Schemas

`SmartSaldoClientesParticularesCreate`

Corpo do POST /smart-saldo-clientes-particulares/. Todos os campos são opcionais no schema (nenhum é obrigatório para o Pydantic aceitar o payload), mas cnpj é a chave prática de identificação do cliente.

Campo	Tipo	Observações
`cnpj`	`str`	Máx. 30 caracteres.
`cfg_emp`	`str`	Máx. 300 caracteres. Código/config da empresa de origem.
`rdi_mte_serie`	`str`	Máx. 20 caracteres. Série do documento de movimento.
`rdi_mte_seq`	`int`	Sequencial do movimento.
`valor`	`Decimal`	Valor do movimento.
`rdi_forma_pag`	`str`	Máx. 20 caracteres. Forma de pagamento.
`gcc_descr`	`str`	Máx. 300 caracteres. Descrição do grupo/centro de custo.
`str_nome`	`str`	Máx. 300 caracteres. Nome do cliente particular.
`mte_tipo`	`str`	Máx. 20 caracteres. Tipo do movimento (ex.: recebimento, débito).
`mte_dthr`	`datetime`	Data/hora do movimento.
`v_dt`	`datetime`	Data de referência do movimento.
`nfx_numero`	`str`	Máx. 20 caracteres. Número do documento de origem.

`SmartSaldoClientesParticularesUpdate`

Corpo do PUT /smart-saldo-clientes-particulares/{smart_saldo_id}. Mesmos campos de SmartSaldoClientesParticularesCreate, exceto cnpj - trocar o CNPJ dono do registro não é permitido por este endpoint. Todos os campos são opcionais.

`SmartSaldoClientesParticularesRead`

Retornado nas listagens e nas respostas de criação/atualização. Estende SmartSaldoClientesParticularesCreate com:

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`data_hora_criacao`	`datetime`	Data/hora de criação do registro.

Notas

Toda resposta segue o envelope { status: "success", message, data }.
O campo valor é Decimal e trafega como string em JSON, tanto na entrada (aceita número ou string) quanto na saída (sempre string).
Erros de negócio manualmente sinalizados pela rota (404 Not Found, 500 Internal Server Error) seguem o formato { "message": "..." } - não usam o campo detail.
Erros de validação de schema (tipo/formato inválido no payload) seguem o padrão do FastAPI: 422 Unprocessable Entity com { "detail": [...] }.
GET /smart-saldo-clientes-particulares/ sempre retorna 200 OK; lista vazia (data: []) é estado normal, não um erro.
O filtro ?cnpj= aceita o CNPJ com ou sem máscara; internamente é normalizado antes da consulta.