Juros e Descontos sob Compromisso

Endpoints da WebApiAlcance para gerenciar registros de juros e descontos sob compromisso financeiro - parametrizações de multa, desconto e juros aplicadas a compromissos de pagamento originados do Klingo ERP. Cobrem criação, listagem com filtros por empresa e CNPJ (com paginação), detalhamento por ID, atualização parcial 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.

Base path

/api/v1/juros-descontos-compromisso

Escopos necessários

juros_descontos_compromisso:read - listagem e detalhamento
juros_descontos_compromisso:write - criação, atualização e exclusão

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

Endpoints

`POST /juros-descontos-compromisso/`

Cria um novo registro de juros e descontos sob compromisso vinculado a um compromisso de pagamento do Klingo ERP.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (JurosDescontosCompromissoCreate); todos os campos são opcionais.

Request

{
  "cnpj": "12345678000199",
  "cfg_emp": "EMP_001",
  "emp_cod": 1001,
  "emp_raz_soc": "ACME SERVICOS LTDA",
  "cpg_serie": 1,
  "cpg_num": 5567,
  "ipg_parc": 3,
  "multa_baixa": 2,
  "desconto_baixa": 0,
  "desconto_compromisso": 5,
  "multa_compromisso": 2,
  "ipg_bcp_serie": 1,
  "ipg_bcp_num": 8890,
  "gcc_descr": 12
}

Response 201 Created

{
  "success": true,
  "message": "Registro de juros e descontos sob compromisso criado com sucesso",
  "data": {
    "id": 42,
    "cnpj": "12345678000199",
    "cfg_emp": "EMP_001",
    "emp_cod": 1001,
    "emp_raz_soc": "ACME SERVICOS LTDA",
    "cpg_serie": 1,
    "cpg_num": 5567,
    "ipg_parc": 3,
    "multa_baixa": 2,
    "desconto_baixa": 0,
    "desconto_compromisso": 5,
    "multa_compromisso": 2,
    "ipg_bcp_serie": 1,
    "ipg_bcp_num": 8890,
    "gcc_descr": 12,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Em caso de dados inválidos, retorna 422 Unprocessable Entity com o detail do erro de validação. Escopo: juros_descontos_compromisso:write

`GET /juros-descontos-compromisso/`

Lista os registros cadastrados, com filtros opcionais por empresa e CNPJ e paginação por limit/offset. Quando não há registros, retorna o envelope de erro (success: false), não um array vazio.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`cfg_emp`	`str`	query	não	Filtra pela empresa (`cfg_emp`).
`cnpj`	`str`	query	não	Filtra pelo CNPJ.
`limit`	`int 1..500`	query	não	Itens por página (default `100`).
`offset`	`int >= 0`	query	não	Deslocamento de paginação (default `0`).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registros de juros e descontos sob compromisso recuperados com sucesso",
  "data": [
    { "id": 42, "cnpj": "12345678000199", "cfg_emp": "EMP_001", "data_hora_criacao": "2026-07-03T10:15:00" },
    { "id": 43, "cnpj": "98765432000155", "cfg_emp": "EMP_002", "data_hora_criacao": "2026-07-03T11:20:00" }
  ]
}

Quando não há registros, retorna { "success": false, "message": "Nenhum registro de juros e descontos sob compromisso encontrado.", "details": [] }. Escopo: juros_descontos_compromisso:read

`GET /juros-descontos-compromisso/{juros_id}`

Detalha um registro pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com o detail do erro.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro de juros e descontos sob compromisso recuperado com sucesso",
  "data": {
    "id": 42,
    "cnpj": "12345678000199",
    "cfg_emp": "EMP_001",
    "emp_cod": 1001,
    "emp_raz_soc": "ACME SERVICOS LTDA",
    "cpg_serie": 1,
    "cpg_num": 5567,
    "ipg_parc": 3,
    "multa_baixa": 2,
    "desconto_baixa": 0,
    "desconto_compromisso": 5,
    "multa_compromisso": 2,
    "ipg_bcp_serie": 1,
    "ipg_bcp_num": 8890,
    "gcc_descr": 12,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Escopo: juros_descontos_compromisso:read

`PUT /juros-descontos-compromisso/{juros_id}`

Atualiza um registro existente. O body é um JurosDescontosCompromissoUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos cnpj e cfg_emp são imutáveis e não aparecem no schema (proteção contra mass-assignment).

Parâmetros

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

Request (JurosDescontosCompromissoUpdate - todos os campos opcionais)

{
  "multa_compromisso": 3,
  "desconto_compromisso": 4
}

Response 200 OK

{
  "success": true,
  "message": "Registro de juros e descontos sob compromisso atualizado com sucesso",
  "data": {
    "id": 42,
    "cnpj": "12345678000199",
    "cfg_emp": "EMP_001",
    "emp_cod": 1001,
    "emp_raz_soc": "ACME SERVICOS LTDA",
    "cpg_serie": 1,
    "cpg_num": 5567,
    "ipg_parc": 3,
    "multa_baixa": 2,
    "desconto_baixa": 0,
    "desconto_compromisso": 4,
    "multa_compromisso": 3,
    "ipg_bcp_serie": 1,
    "ipg_bcp_num": 8890,
    "gcc_descr": 12,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Registro inexistente retorna 404 Not Found; dados inválidos retornam 422 Unprocessable Entity. Escopo: juros_descontos_compromisso:write

`DELETE /juros-descontos-compromisso/{juros_id}`

Remove um registro pelo ID. Registro inexistente retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro de juros e descontos sob compromisso removido com sucesso",
  "data": null
}

Escopo: juros_descontos_compromisso:write

Schemas

`JurosDescontosCompromissoCreate`

Todos os campos são opcionais.

Campo	Tipo	Obrigatório	Observações
`cnpj`	`str`	não	CNPJ da empresa. Máx. 30 caracteres.
`cfg_emp`	`str`	não	Identificador de configuração da empresa. Máx. 300.
`emp_cod`	`int`	não	Código da empresa.
`emp_raz_soc`	`str`	não	Razão social da empresa. Máx. 300 caracteres.
`cpg_serie`	`int`	não	Série do compromisso de pagamento.
`cpg_num`	`int`	não	Número do compromisso de pagamento.
`ipg_parc`	`int`	não	Parcela do item de pagamento.
`multa_baixa`	`int`	não	Multa aplicada na baixa.
`desconto_baixa`	`int`	não	Desconto aplicado na baixa.
`desconto_compromisso`	`int`	não	Desconto aplicado sob compromisso.
`multa_compromisso`	`int`	não	Multa aplicada sob compromisso.
`ipg_bcp_serie`	`int`	não	Série do banco/compromisso de pagamento.
`ipg_bcp_num`	`int`	não	Número do banco/compromisso de pagamento.
`gcc_descr`	`int`	não	Referência de descrição do grupo/conta contábil.

`JurosDescontosCompromissoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Os campos cnpj e cfg_emp não estão presentes neste schema - são imutáveis via PUT (guarda contra mass-assignment).

Campo	Tipo	Observações
`emp_cod`	`int`	Código da empresa.
`emp_raz_soc`	`str`	Razão social da empresa. Máx. 300 caracteres.
`cpg_serie`	`int`	Série do compromisso de pagamento.
`cpg_num`	`int`	Número do compromisso de pagamento.
`ipg_parc`	`int`	Parcela do item de pagamento.
`multa_baixa`	`int`	Multa aplicada na baixa.
`desconto_baixa`	`int`	Desconto aplicado na baixa.
`desconto_compromisso`	`int`	Desconto aplicado sob compromisso.
`multa_compromisso`	`int`	Multa aplicada sob compromisso.
`ipg_bcp_serie`	`int`	Série do banco/compromisso de pagamento.
`ipg_bcp_num`	`int`	Número do banco/compromisso de pagamento.
`gcc_descr`	`int`	Referência de descrição do grupo/conta contábil.

`JurosDescontosCompromissoRead`

Estende os campos de JurosDescontosCompromissoCreate com os campos de leitura abaixo.

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`data_hora_criacao`	`datetime`	Data e hora de criação (ISO 8601).

Os demais campos (cnpj, cfg_emp, emp_cod, emp_raz_soc, cpg_serie, cpg_num, ipg_parc, multa_baixa, desconto_baixa, desconto_compromisso, multa_compromisso, ipg_bcp_serie, ipg_bcp_num, gcc_descr) são herdados de JurosDescontosCompromissoBase e também retornam na leitura.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
GET /juros-descontos-compromisso/ retorna envelope de erro (success: false) quando não há registros - não um array vazio. Trate esse caso no cliente.
Os campos cnpj e cfg_emp são imutáveis via PUT - para corrigi-los, exclua e recrie o registro.
Os dados originam-se do Klingo ERP e representam parametrizações de juros, multas e descontos vinculadas a compromissos de pagamento.