Smart: Saldo de Fornecedores

Endpoints da WebApiAlcance para o CRUD de saldos de fornecedores consumido pelo produto Smart. Cada registro representa uma parcela de um contas a pagar (cpg) a um fornecedor/credor, com o valor da parcela, os tributos retidos na fonte, descontos, multas e o valor adiantado. 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, "ipg_valor": "985.00", não "ipg_valor": 985.0. Faça a conversão explícita (Number(...)/parseFloat) no consumidor.

Base path

/api/v1/smart-saldo-fornecedores

Escopos necessários

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

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

Lista os saldos de fornecedores, 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 fornecedores recuperados com sucesso",
  "data": [
    {
      "id": 4401,
      "cnpj": "12345678000199",
      "cfg_emp": "HOSP01",
      "gcc_descr": "FORNECEDORES DIVERSOS",
      "emp_cgc": "98765432000188",
      "cpg_serie": "1",
      "cpg_num": 7712,
      "cpg_doc": "NF-7712",
      "cpg_credor": "DISTRIBUIDORA HOSPITALAR LTDA",
      "cpg_dt_doc_emiss": "2026-01-05T00:00:00",
      "ipg_dt_pgto": null,
      "ipg_parc": 1,
      "ipg_valor": "985.00",
      "ipg_iss": "0.00",
      "ipg_irrf": "14.78",
      "ipg_inss": "0.00",
      "ipg_pcc_valor": "0.00",
      "ipg_desconto": "0.00",
      "ipg_multa": "0.00",
      "ipg_desp_aces": "0.00",
      "ipg_valor_adiantado": "0.00",
      "total_parc": 1,
      "query_1": null,
      "cpg_obs": null,
      "ipg_dt_vcto": "2026-02-05T00:00:00",
      "data_hora_criacao": "2026-01-15T10:00:00"
    }
  ]
}

Escopo: smart_saldo_fornecedores:read

`GET /smart-saldo-fornecedores/{smart_saldo_id}`

Busca um saldo de fornecedor pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Saldo de fornecedor recuperado com sucesso",
  "data": {
    "id": 4401,
    "cnpj": "12345678000199",
    "ipg_valor": "985.00",
    "...": "demais campos como em SmartSaldoFornecedoresRead"
  }
}

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

`POST /smart-saldo-fornecedores/`

Cria um novo saldo de fornecedor.

Parâmetros

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

Request

{
  "cnpj": "12.345.678/0001-99",
  "cfg_emp": "HOSP01",
  "gcc_descr": "FORNECEDORES DIVERSOS",
  "emp_cgc": "98765432000188",
  "cpg_serie": "1",
  "cpg_num": 7712,
  "cpg_doc": "NF-7712",
  "cpg_credor": "DISTRIBUIDORA HOSPITALAR LTDA",
  "cpg_dt_doc_emiss": "2026-01-05T00:00:00",
  "ipg_parc": 1,
  "ipg_valor": 985.00,
  "ipg_irrf": 14.78,
  "total_parc": 1,
  "ipg_dt_vcto": "2026-02-05T00:00:00"
}

Response 201 Created

{
  "status": "success",
  "message": "Saldo de fornecedor criado com sucesso",
  "data": {
    "id": 4401,
    "cnpj": "12345678000199",
    "ipg_valor": "985.00",
    "...": "demais campos como em SmartSaldoFornecedoresRead"
  }
}

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

`PUT /smart-saldo-fornecedores/{smart_saldo_id}`

Atualiza um saldo de fornecedor 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 fornecedor.

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

Request

{
  "ipg_dt_pgto": "2026-02-05T09:00:00",
  "ipg_valor": 985.00
}

Response 200 OK

{
  "status": "success",
  "message": "Saldo de fornecedor atualizado com sucesso",
  "data": {
    "id": 4401,
    "cnpj": "12345678000199",
    "ipg_dt_pgto": "2026-02-05T09:00:00",
    "ipg_valor": "985.00",
    "...": "demais campos como em SmartSaldoFornecedoresRead"
  }
}

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

`DELETE /smart-saldo-fornecedores/{smart_saldo_id}`

Remove um saldo de fornecedor.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

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

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

Schemas

`SmartSaldoFornecedoresCreate`

Corpo do POST /smart-saldo-fornecedores/. 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.
`gcc_descr`	`str`	Máx. 300 caracteres. Descrição do grupo/centro de custo.
`emp_cgc`	`str`	Máx. 30 caracteres. CNPJ da empresa pagadora.
`cpg_serie`	`str`	Máx. 20 caracteres. Série do contas a pagar.
`cpg_num`	`int`	Número do contas a pagar.
`cpg_doc`	`str`	Máx. 20 caracteres. Número do documento (nota/boleto).
`cpg_credor`	`str`	Máx. 300 caracteres. Nome do fornecedor/credor.
`cpg_dt_doc_emiss`	`datetime`	Data de emissão do documento.
`ipg_dt_pgto`	`datetime`	Data efetiva do pagamento da parcela.
`ipg_parc`	`int`	Número da parcela.
`ipg_valor`	`Decimal`	Valor da parcela.
`ipg_iss`	`Decimal`	Valor de ISS retido na parcela.
`ipg_irrf`	`Decimal`	Valor de IRRF retido na parcela.
`ipg_inss`	`Decimal`	Valor de INSS retido na parcela.
`ipg_pcc_valor`	`Decimal`	Valor de PCC retido na parcela.
`ipg_desconto`	`Decimal`	Valor de desconto aplicado à parcela.
`ipg_multa`	`Decimal`	Valor de multa aplicado à parcela.
`ipg_desp_aces`	`Decimal`	Valor de despesas acessórias.
`ipg_valor_adiantado`	`Decimal`	Valor pago antecipadamente para a parcela.
`total_parc`	`int`	Total de parcelas do documento.
`query_1`	`str`	Máx. 20 caracteres. Campo auxiliar de origem.
`cpg_obs`	`str`	Máx. 300 caracteres. Observação livre.
`ipg_dt_vcto`	`datetime`	Data de vencimento da parcela.

`SmartSaldoFornecedoresUpdate`

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

`SmartSaldoFornecedoresRead`

Retornado nas listagens e nas respostas de criação/atualização. Estende SmartSaldoFornecedoresCreate 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 (ipg_valor, ipg_iss, ipg_irrf, ipg_inss, ipg_pcc_valor, ipg_desconto, ipg_multa, ipg_desp_aces, ipg_valor_adiantado) 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-fornecedores/ 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.