Smart: Saldo de Glosas Reapresentáveis

Endpoints da WebApiAlcance para o CRUD de saldos de glosas reapresentáveis consumido pelo produto Smart. Cada registro representa o valor de uma NFS-e glosada pelo convênio que ainda pode ser reapresentado: o valor original, o quanto já foi reapresentado, as glosas acatadas em cada rodada e o saldo remanescente. 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": "1.52", não "saldo": 1.52. Faça a conversão explícita (Number(...)/parseFloat) no consumidor.

Base path

/api/v1/smart-saldo-glosas-reapresentaveis

Escopos necessários

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

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

Lista os saldos de glosas reapresentáveis, 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 glosas reapresentáveis recuperados com sucesso",
  "data": [
    {
      "id": 5501,
      "cnpj": "12345678000199",
      "cfg_emp": "HOSP01",
      "mns_nfs_tipo": "NFSE",
      "mns_nfs_serie": "1",
      "mns_nfs_numero": 4521,
      "emp_cod": 10,
      "emp_raz_soc": "ACME SERVICOS MEDICOS LTDA",
      "emp_cgc": "12345678000199",
      "mns_vlr": "45.00",
      "nfs_dt_emis": "2026-01-10T00:00:00",
      "reapresentado": "20.00",
      "glosa_acatada_1": "18.48",
      "glosa_acatada_2": "5.00",
      "saldo": "1.52",
      "gcc_descr": "GLOSAS CONVENIO",
      "data_hora_criacao": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: smart_saldo_glosas_reapresentaveis:read

`GET /smart-saldo-glosas-reapresentaveis/{smart_saldo_id}`

Busca um saldo de glosa reapresentável pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_saldo_id`	`int`	path	sim	ID do saldo de glosa reapresentável.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Saldo de glosa reapresentável recuperado com sucesso",
  "data": {
    "id": 5501,
    "cnpj": "12345678000199",
    "saldo": "1.52",
    "...": "demais campos como em SmartSaldoGlosasReapresentaveisRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Saldo de glosa reapresentável não encontrado."}. Escopo: smart_saldo_glosas_reapresentaveis:read

`POST /smart-saldo-glosas-reapresentaveis/`

Cria um novo saldo de glosa reapresentável.

Parâmetros

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

Request

{
  "cnpj": "12.345.678/0001-99",
  "cfg_emp": "HOSP01",
  "mns_nfs_tipo": "NFSE",
  "mns_nfs_serie": "1",
  "mns_nfs_numero": 4521,
  "emp_cod": 10,
  "emp_raz_soc": "ACME SERVICOS MEDICOS LTDA",
  "emp_cgc": "12345678000199",
  "mns_vlr": 45.00,
  "nfs_dt_emis": "2026-01-10T00:00:00",
  "reapresentado": 20.00,
  "glosa_acatada_1": 18.48,
  "glosa_acatada_2": 5.00,
  "saldo": 1.52,
  "gcc_descr": "GLOSAS CONVENIO"
}

Response 201 Created

{
  "status": "success",
  "message": "Saldo de glosa reapresentável criado com sucesso",
  "data": {
    "id": 5501,
    "cnpj": "12345678000199",
    "saldo": "1.52",
    "...": "demais campos como em SmartSaldoGlosasReapresentaveisRead"
  }
}

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

`PUT /smart-saldo-glosas-reapresentaveis/{smart_saldo_id}`

Atualiza um saldo de glosa reapresentável 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 glosa reapresentável.

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

Request

{
  "reapresentado": 21.52,
  "saldo": 0.00
}

Response 200 OK

{
  "status": "success",
  "message": "Saldo de glosa reapresentável atualizado com sucesso",
  "data": {
    "id": 5501,
    "cnpj": "12345678000199",
    "reapresentado": "21.52",
    "saldo": "0.00",
    "...": "demais campos como em SmartSaldoGlosasReapresentaveisRead"
  }
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Saldo de glosa reapresentável não encontrado."}. Escopo: smart_saldo_glosas_reapresentaveis:write

`DELETE /smart-saldo-glosas-reapresentaveis/{smart_saldo_id}`

Remove um saldo de glosa reapresentável.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`smart_saldo_id`	`int`	path	sim	ID do saldo de glosa reapresentável.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Saldo de glosa reapresentável removido com sucesso",
  "data": null
}

Quando o ID não existe, retorna 404 Not Found com {"message": "Saldo de glosa reapresentável não encontrado."}. Escopo: smart_saldo_glosas_reapresentaveis:write

Schemas

`SmartSaldoGlosasReapresentaveisCreate`

Corpo do POST /smart-saldo-glosas-reapresentaveis/. 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. 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.
`mns_nfs_tipo`	`str`	Máx. 20 caracteres. Tipo da NFS-e glosada.
`mns_nfs_serie`	`str`	Máx. 20 caracteres. Série da NFS-e glosada.
`mns_nfs_numero`	`int`	Número da NFS-e glosada.
`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.
`mns_vlr`	`Decimal`	Valor original glosado.
`nfs_dt_emis`	`datetime`	Data/hora de emissão da NFS-e glosada.
`reapresentado`	`Decimal`	Valor já reapresentado ao convênio.
`glosa_acatada_1`	`Decimal`	Valor de glosa acatada na 1ª rodada de reapresentação.
`glosa_acatada_2`	`Decimal`	Valor de glosa acatada na 2ª rodada de reapresentação.
`saldo`	`Decimal`	Saldo remanescente ainda reapresentável.
`gcc_descr`	`str`	Máx. 300 caracteres. Descrição do grupo/centro de custo.

`SmartSaldoGlosasReapresentaveisUpdate`

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

`SmartSaldoGlosasReapresentaveisRead`

Retornado nas listagens e nas respostas de criação/atualização. Estende SmartSaldoGlosasReapresentaveisCreate 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 (mns_vlr, reapresentado, glosa_acatada_1, glosa_acatada_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).
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-glosas-reapresentaveis/ 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.