Smart: Saldo de Clientes Convênio

Endpoints da WebApiAlcance para o CRUD de saldos de clientes convênio consumido pelo produto Smart. Cada registro é um snapshot do saldo de uma nota fiscal de serviço (NFS-e) faturada a um convênio: valor da nota, impostos, valor recebido, glosas e o saldo em aberto. 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.

Campos monetários saem como string

Os campos monetários deste domínio são 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, "saldo": "987.65", não "saldo": 987.65. Faça a conversão explícita (Number(...)/parseFloat) no consumidor.

Base path

/api/v1/smart-saldo-clientes-convenio

Escopos necessários

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

O escopo é derivado do prefixo público da rota: /smart-saldo-clientes-convenio vira o recurso smart_saldo_clientes_convenio (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-convenio/`

Lista os saldos de clientes convênio, 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 convênio recuperados com sucesso",
  "data": [
    {
      "id": 1201,
      "cnpj": "12345678000199",
      "cfg_emp": "HOSP01",
      "nfs_tipo": "NFSE",
      "nfs_serie": "1",
      "nfs_numero": 4521,
      "emp_cod": 10,
      "emp_raz_soc": "ACME SERVICOS MEDICOS LTDA",
      "emp_cgc": "12345678000199",
      "nfs_dt_emis": "2026-01-10T00:00:00",
      "ano": 2026,
      "nfs_valor": "3200.00",
      "gcc_descr": "CONVENIOS MEDICOS",
      "nfs_dt_vcto": "2026-02-10T00:00:00",
      "nfs_dt_envio": "2026-01-11T00:00:00",
      "impostos": "150.00",
      "recebido": "2000.00",
      "glosado": "50.00",
      "glosa_2": "0.00",
      "saldo": "1000.00",
      "data_hora_criacao": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: smart_saldo_clientes_convenio:read

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

Busca um saldo de cliente convênio pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Saldo de cliente convênio recuperado com sucesso",
  "data": {
    "id": 1201,
    "cnpj": "12345678000199",
    "saldo": "1000.00",
    "...": "demais campos como em SmartSaldoClientesConvenioRead"
  }
}

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

`POST /smart-saldo-clientes-convenio/`

Grava um saldo de cliente convênio. Esta rota é a borda de carga da planilha: a tabela é um snapshot identificado pela chave natural (cnpj, nfs_tipo, nfs_serie, nfs_numero) - reenviar a mesma chave atualiza a linha existente (mesmo id) em vez de criar outra. O status é 201 Created nos dois casos (criação ou atualização por upsert); o corpo devolve sempre o estado atual do recurso.

Parâmetros

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

Request

{
  "cnpj": "12.345.678/0001-99",
  "cfg_emp": "HOSP01",
  "nfs_tipo": "NFSE",
  "nfs_serie": "1",
  "nfs_numero": 4521,
  "emp_cod": 10,
  "emp_raz_soc": "ACME SERVICOS MEDICOS LTDA",
  "emp_cgc": "12345678000199",
  "nfs_dt_emis": "2026-01-10T00:00:00",
  "ano": 2026,
  "nfs_valor": 3200.00,
  "gcc_descr": "CONVENIOS MEDICOS",
  "nfs_dt_vcto": "2026-02-10T00:00:00",
  "nfs_dt_envio": "2026-01-11T00:00:00",
  "impostos": 150.00,
  "recebido": 2000.00,
  "glosado": 50.00,
  "glosa_2": 0.00,
  "saldo": 1000.00
}

Response 201 Created

{
  "status": "success",
  "message": "Saldo de cliente convênio criado com sucesso",
  "data": {
    "id": 1201,
    "cnpj": "12345678000199",
    "saldo": "1000.00",
    "...": "demais campos como em SmartSaldoClientesConvenioRead"
  }
}

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

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

Atualiza um saldo de cliente convênio existente. O cnpj não é editável por este endpoint. Os demais campos da chave natural (nfs_tipo, nfs_serie, nfs_numero) são editáveis, mas não podem colidir com a chave natural de outro registro já existente.

Parâmetros

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

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

Request

{
  "recebido": 2500.00,
  "saldo": 500.00
}

Response 200 OK

{
  "status": "success",
  "message": "Saldo de cliente convênio atualizado com sucesso",
  "data": {
    "id": 1201,
    "cnpj": "12345678000199",
    "recebido": "2500.00",
    "saldo": "500.00",
    "...": "demais campos como em SmartSaldoClientesConvenioRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Saldo de cliente convênio não encontrado."}. Quando a alteração faria a chave natural (nfs_tipo/nfs_serie/nfs_numero) colidir com outro registro já existente, retorna 409 Conflict com {"message": "..."} descrevendo o conflito. Escopo: smart_saldo_clientes_convenio:write

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

Remove um saldo de cliente convênio.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

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

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

Schemas

`SmartSaldoClientesConvenioCreate`

Corpo do POST /smart-saldo-clientes-convenio/. Todos os campos são opcionais no schema (nenhum é obrigatório para o Pydantic aceitar o payload). Na prática, cnpj, nfs_tipo, nfs_serie e nfs_numero formam a chave natural usada no upsert. Os campos monetários são Decimal.

Campo	Tipo	Observações
`cnpj`	`str`	Máx. 30 caracteres.
`cfg_emp`	`str`	Máx. 300 caracteres. Código/config da empresa de origem.
`nfs_tipo`	`str`	Máx. 20 caracteres. Parte da chave natural.
`nfs_serie`	`str`	Máx. 20 caracteres. Parte da chave natural.
`nfs_numero`	`int`	Parte da chave natural.
`emp_cod`	`int`	Código da empresa emissora no ERP.
`emp_raz_soc`	`str`	Máx. 300 caracteres. Razão social da empresa.
`emp_cgc`	`str`	Máx. 30 caracteres. CNPJ da empresa emissora.
`nfs_dt_emis`	`datetime`	Data/hora de emissão da NFS-e.
`ano`	`int`	Ano de referência.
`nfs_valor`	`Decimal`	Valor total da NFS-e.
`gcc_descr`	`str`	Máx. 300 caracteres. Descrição do grupo/centro de custo.
`nfs_dt_vcto`	`datetime`	Data de vencimento.
`nfs_dt_envio`	`datetime`	Data de envio ao convênio.
`impostos`	`Decimal`	Valor de impostos retidos.
`recebido`	`Decimal`	Valor já recebido do convênio.
`glosado`	`Decimal`	Valor glosado pelo convênio.
`glosa_2`	`Decimal`	Valor de glosa adicional/secundária.
`saldo`	`Decimal`	Saldo em aberto (valor - impostos - recebido - glosas).

`SmartSaldoClientesConvenioUpdate`

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

`SmartSaldoClientesConvenioRead`

Retornado nas listagens e nas respostas de criação/atualização. Estende SmartSaldoClientesConvenioCreate 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 }.
Os campos monetários (nfs_valor, impostos, recebido, glosado, glosa_2, saldo) são Decimal e trafegam como string em JSON, tanto na entrada (aceita número ou string) quanto na saída (sempre string).
POST /smart-saldo-clientes-convenio/ é um upsert por chave natural (cnpj, nfs_tipo, nfs_serie, nfs_numero): reenviar a mesma chave atualiza o registro existente em vez de duplicá-lo. O status permanece 201 Created em ambos os casos.
PUT /smart-saldo-clientes-convenio/{smart_saldo_id} pode retornar 409 Conflict quando a alteração da chave natural colidiria com outro registro já existente.
Erros de negócio manualmente sinalizados pela rota (404 Not Found, 409 Conflict, 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-convenio/ 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.