> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Consultar Juro Adicional
> Consulte o juro adicional de parcelamento que você cobra do comprador, de 2x a 12x, e se ele está sendo cobrado hoje. É o juro que você define por cima do juro-base da Cakto.
#### Escopo
```bash theme={null}
read payments
```
## O que é este endpoint?
Quando o comprador parcela no cartão, **dois juros diferentes** entram na mesma parcela:
| Quem define | Onde consultar | O que é |
| ----------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| A **Cakto** | [`GET /public_api/fees/`](/api-reference/fees/retrieve), em `creditCardInstallments` | O juro-base do parcelamento, de 1x a 18x. |
| **Você** | **este endpoint**, de 2x a 12x | O juro adicional que você decide cobrar do comprador por cima daquele. |
Este endpoint devolve **o seu**: a tabela de percentuais por número de parcelas e o campo `active`, que diz se ela está sendo aplicada hoje. É a versão consultável por API do que você configura no painel.
A operação lê **sempre a conta dona do token**. Não existe parâmetro de produtor: não há como consultar a tabela de outra conta, e mandar um identificador na query não muda o resultado.
**Não existe juro adicional em 1x.** A faixa vai de `2` a `12`, e é assim nos dois lados: o painel não oferece 1x e a API recusa (`400`). Se você monta um simulador que vai de 1x a 18x, some o juro adicional só a partir de 2x — e só até 12x.
***
## Para que serve
Some este juro ao juro-base de [`GET /public_api/fees/`](/api-reference/fees/retrieve) para exibir, na sua interface, exatamente o que o comprador vai ver no checkout da Cakto.
Leia antes de mexer. `active: false` com percentuais preenchidos é uma tabela guardada e desligada — situação fácil de confundir com "não configurado".
Como o [`PUT`](/api-reference/installment-interest/update) substitui a tabela inteira, ler primeiro é o que evita apagar uma faixa por omissão.
Quando o comprador pergunta por que a parcela ficou acima do preço dividido, a diferença sai daqui e do juro-base da Cakto.
***
## Como ler os valores
Com `active: false`, **nada é somado ao valor do comprador** — mesmo que `installments` venha cheio de percentuais.
Desligar preserva a tabela em vez de apagá-la, para que religar não exija redigitar. Isso significa que uma resposta com `active: false` e `interestPercentage: 5.5` é perfeitamente normal: é uma configuração guardada, inativa.
**Cruze sempre os dois campos** antes de calcular o valor de uma parcela. Ler só `interestPercentage` faz você exibir um juro que a Cakto não está cobrando.
`interestPercentage: null` quer dizer **"não há juro adicional configurado nessa parcela"**. `0` quer dizer **"configurado como 0%"**. Na conta do comprador os dois dão o mesmo resultado, mas na hora de escrever eles são diferentes: um `PUT` com `null` remove a faixa, um `PUT` com `0` grava zero.
São **sempre as 11 faixas**, de `2` a `12`, mesmo que só uma esteja configurada e mesmo na conta que nunca configurou nada. A lista não encolhe conforme o preenchimento.
Pode iterar sem medo de ela mudar de tamanho entre chamadas, e pode indexar por `installments` sem checar se a chave existe.
`1.5` significa **1,5%**, e não 0,015. É a mesma convenção de todo percentual no contrato, incluindo o `percentage` e o `interestPercentage` de [`GET /public_api/fees/`](/api-reference/fees/retrieve).
O valor chega como **número** JSON (`1.5`), não como string. Em linguagens onde isso importa, converta para decimal antes de fazer aritmética financeira.
Os dois juros incidem sobre a mesma venda parcelada e se somam em pontos percentuais:
```
juro_total(n) = fees.creditCardInstallments[n].interestPercentage
+ (active ? installment-interest[n].interestPercentage ?? 0 : 0)
```
De 13x a 18x só existe o juro-base da Cakto — sua tabela não chega lá. Em 1x, idem.
O mesmo percentual se aplica a **cartão de crédito**, **cartão com 3DS**, **Google Pay** e **Apple Pay**. Não há tabela por método: é uma tabela só, por número de parcelas.
Métodos sem parcelamento — Pix, boleto — não têm juro adicional nenhum.
***
## Resposta
`boolean` — se o juro adicional está sendo cobrado hoje. `false` numa conta que nunca configurou nada, e também numa conta que configurou e desligou.
* `installments` — número de parcelas, de 2 a 12
* `interestPercentage` — juro adicional dessa faixa, em pontos percentuais, ou `null`
### Exemplo de resposta
```json theme={null}
{
"active": true,
"installments": [
{ "installments": 2, "interestPercentage": 1.5 },
{ "installments": 3, "interestPercentage": 2.5 },
{ "installments": 4, "interestPercentage": 3.5 },
{ "installments": 5, "interestPercentage": 4.5 },
{ "installments": 6, "interestPercentage": 5.5 },
{ "installments": 7, "interestPercentage": null },
{ "installments": 8, "interestPercentage": null },
{ "installments": 9, "interestPercentage": null },
{ "installments": 10, "interestPercentage": null },
{ "installments": 11, "interestPercentage": null },
{ "installments": 12, "interestPercentage": 10.0 }
]
}
```
Nesse exemplo o produtor cobra juro adicional de 2x a 6x e em 12x. De 7x a 11x não há juro adicional — o comprador paga só o juro-base da Cakto.
***
## Respostas de erro
| Código | Quando ocorre | Corpo de exemplo |
| ------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `401` | Token ausente, inválido ou expirado. | `{ "detail": "As credenciais de autenticação não foram fornecidas." }` |
| `403` | Chave de API sem o escopo `payments`, ou sem `read`. | `{ "detail": "Você não tem permissão para executar esta ação." }` |
| `429` | Limite de requisições excedido. Veja [Limites de Requisição](/conceitos/rate-limits). | `{ "detail": "Request was throttled. Expected available in 42 seconds." }` |
**Esta leitura não tem `409`**, e a diferença para [`GET /public_api/fees/`](/api-reference/fees/retrieve) é proposital.
Lá, uma conta sem cadastro de recebimento concluído responde `409` porque devolver "sem taxas" faria você calcular líquido = bruto: seria erro de dinheiro. Aqui, "você não cobra juro adicional nenhum" **é a resposta verdadeira** para essa conta, e não induz erro de cálculo nenhum. Ela vem como `200` com `active: false` e a tabela toda em `null`.
O `409` existe só na [escrita](/api-reference/installment-interest/update), onde é acionável de verdade: sem cadastro concluído não há onde gravar.
***
## Exemplo de requisição
```bash cURL theme={null}
curl -X GET 'https://api.cakto.com.br/public_api/installment-interest/' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...'
```
```python Python theme={null}
import requests
HEADERS = {"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."}
adicional = requests.get(
"https://api.cakto.com.br/public_api/installment-interest/",
headers=HEADERS,
timeout=30,
).json()
base = requests.get(
"https://api.cakto.com.br/public_api/fees/",
headers=HEADERS,
timeout=30,
).json()
juro_base = {
linha["installments"]: linha["interestPercentage"]
for linha in base["creditCardInstallments"]
}
juro_seu = {
linha["installments"]: linha["interestPercentage"]
for linha in adicional["installments"]
}
preco = 197.00
for parcelas in range(1, 19):
extra = juro_seu.get(parcelas) or 0 if adicional["active"] else 0
total_juro = (juro_base.get(parcelas) or 0) + extra
com_juro = preco * (1 + total_juro / 100)
print(f"{parcelas}x de R$ {com_juro / parcelas:.2f} (total R$ {com_juro:.2f})")
```
```javascript Node.js theme={null}
const headers = { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." };
const [adicional, base] = await Promise.all([
fetch("https://api.cakto.com.br/public_api/installment-interest/", { headers }).then((r) => r.json()),
fetch("https://api.cakto.com.br/public_api/fees/", { headers }).then((r) => r.json()),
]);
const juroBase = new Map(base.creditCardInstallments.map((l) => [l.installments, l.interestPercentage]));
const juroSeu = new Map(adicional.installments.map((l) => [l.installments, l.interestPercentage]));
const preco = 197.0;
for (let parcelas = 1; parcelas <= 18; parcelas++) {
const extra = adicional.active ? juroSeu.get(parcelas) ?? 0 : 0;
const totalJuro = (juroBase.get(parcelas) ?? 0) + extra;
const comJuro = preco * (1 + totalJuro / 100);
console.log(`${parcelas}x de R$ ${(comJuro / parcelas).toFixed(2)}`);
}
```
***
## Boas práticas
* **Consulte uma vez e guarde.** Sua tabela muda quando você mesmo a muda, e nunca sozinha. Chamar a cada carregamento de página gasta seu limite de requisições sem trazer informação nova.
* **Sempre cruze `active` com `interestPercentage`.** É o erro mais fácil de cometer aqui, e ele aparece na tela do comprador.
* **Trate `null` explicitamente** antes de qualquer conta, em vez de deixar a linguagem convertê-lo para zero em silêncio.
* **Leia antes de escrever.** O [`PUT`](/api-reference/installment-interest/update) substitui a tabela inteira: parcela que você não mandar fica sem juro.
* **Para saber quanto esse juro já rendeu**, use [Ganhos com Juro de Parcelamento](/api-reference/installment-interest/earnings) — o percentual configurado não diz nada sobre o que foi efetivamente cobrado nem sobre quanto ficou com você.
## OpenAPI
````yaml GET /public_api/installment-interest/
openapi: 3.0.3
info:
title: Cakto API
version: 1.0.0
description: Documentação da API pública do Cakto.
servers:
- url: https://api.cakto.com.br
description: Cakto API
security: []
paths:
/public_api/installment-interest/:
get:
tags:
- installment-interest
description: >-
Juro adicional de parcelamento que você cobra do comprador.
É o juro que **você** define por cima do juro-base da Cakto (o de
`GET /public_api/fees/`) quando o comprador escolhe parcelar. Vale de 2x
a 12x — não
existe juro adicional em 1x — e se aplica a todos os métodos com
parcelamento:
cartão de crédito, cartão 3DS, Google Pay e Apple Pay.
A operação sempre lê e escreve a conta dona do token: não recebe
identificador de
produtor e não há como configurar a tabela de outra conta.
Percentuais vêm em pontos percentuais (`1.5` = 1,5%) e `null` significa
"sem juro
adicional nessa parcela", nunca zero. O campo `active` é o que decide se
algo é
cobrado: com `active: false` a tabela continua guardada e nada é somado
ao comprador.
O `PUT` **substitui a tabela inteira** e é seguro repetir — mandar o
mesmo corpo duas
vezes deixa a conta no mesmo estado. Por isso a operação não lê o header
`X-Idempotency-Key`: não há nada que possa ser criado em duplicidade.
operationId: installment_interest_retrieve
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentInterestConfig'
examples:
Sucesso:
value:
active: true
installments:
- installments: 2
interestPercentage: 1.5
- installments: 3
interestPercentage: 2.5
- installments: 4
interestPercentage: 3.5
- installments: 5
interestPercentage: 4.5
- installments: 6
interestPercentage: 5.5
- installments: 7
interestPercentage: null
- installments: 8
interestPercentage: null
- installments: 9
interestPercentage: null
- installments: 10
interestPercentage: null
- installments: 11
interestPercentage: null
- installments: 12
interestPercentage: 10
SemJuroConfigurado:
value:
active: false
installments:
- installments: 2
interestPercentage: null
- installments: 3
interestPercentage: null
- installments: 4
interestPercentage: null
- installments: 5
interestPercentage: null
- installments: 6
interestPercentage: null
- installments: 7
interestPercentage: null
- installments: 8
interestPercentage: null
- installments: 9
interestPercentage: null
- installments: 10
interestPercentage: null
- installments: 11
interestPercentage: null
- installments: 12
interestPercentage: null
summary: Conta sem juro adicional, ou com a cobrança desligada.
description: >-
Juro adicional de parcelamento configurado na conta autenticada, de
2x a 12x. A conta que nunca configurou nada responde 200 com
`active: false` e todos os percentuais em `null` — nada é cobrado.
'401':
description: Request não autenticado devido à ausência ou invalidez do token.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedError'
examples:
Token ausente ou inválido:
$ref: '#/components/examples/UnauthenticatedErrorExample'
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
EscopoInsuficiente:
value:
detail: Você não tem permissão para executar esta ação.
description: >-
Chave de API sem o escopo `payments`, ou sem `write` na operação de
escrita. Leitura exige `payments` e `read`; escrita exige `payments`
e `write`.
security:
- OAuth Token: []
components:
schemas:
InstallmentInterestConfig:
type: object
properties:
active:
type: boolean
description: >-
Se o juro adicional está sendo cobrado hoje. Com `false` nada é
somado ao valor do comprador, mesmo que `installments` traga
percentuais: desligar preserva a tabela em vez de apagá-la, para que
religar não exija redigitar. Uma conta que nunca configurou juro
adicional também responde `false`.
installments:
type: array
items:
$ref: '#/components/schemas/InstallmentInterestRate'
description: >-
A tabela completa de 2x a 12x, sempre com as 11 faixas e sempre na
mesma ordem. Faixa sem juro configurado aparece com
`interestPercentage: null`.
required:
- active
- installments
UnauthenticatedError:
type: object
properties:
detail:
type: string
InstallmentInterestRate:
type: object
properties:
installments:
type: integer
description: Número de parcelas, de 2 a 12. Não existe juro adicional em 1x.
interestPercentage:
type: number
nullable: true
description: >-
Juro adicional que **você** cobra do comprador nesse número de
parcelas, em pontos percentuais (`1.5` = 1,5%). Soma-se ao juro-base
da Cakto, que está em `creditCardInstallments` de `GET
/public_api/fees/`. `null` significa que não há juro adicional
configurado para essa parcela — não confunda com `0`, que é
"configurado como zero". **Cruze sempre com `active`**: com `active:
false` estes percentuais continuam guardados e nada é cobrado.
required:
- installments
- interestPercentage
examples:
UnauthenticatedErrorExample:
summary: Token ausente ou inválido
description: Token ausente ou inválido
value:
detail: As credenciais de autenticação não foram fornecidas.
securitySchemes:
OAuth Token:
type: http
scheme: bearer
in: header
name: Authorization
description: >-
Token de autenticação do tipo `Bearer {access_token}`, onde
`{access_token}` é o token obtido no fluxo de
[autenticação](/authentication).
````