> ## 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.
# Configurar Juro Adicional
> Define o juro adicional de parcelamento que você cobra do comprador, de 2x a 12x. A chamada substitui a tabela inteira e passa a valer no próximo pagamento.
#### Escopo
```bash theme={null}
write payments
```
**Esta chamada muda o que o comprador paga.**
O juro adicional é somado ao valor da compra quando o comprador escolhe parcelar. Subir de `5%` para `10%` em 12x significa que, a partir da próxima venda parcelada em 12x, **o comprador paga a mais** — não é um ajuste de relatório nem de exibição.
Não há confirmação em duas etapas e não há desfazer: o valor anterior **não é guardado em lugar nenhum**. [Leia a tabela atual](/api-reference/installment-interest/retrieve) e guarde-a antes de escrever, se quiser poder voltar atrás.
## O que é este endpoint?
É a escrita da tabela consultada em [Consultar Juro Adicional](/api-reference/installment-interest/retrieve): o juro que **você** cobra do comprador por parcelar, por cima do juro-base da Cakto que sai em [`GET /public_api/fees/`](/api-reference/fees/retrieve).
Vale de **2x a 12x** — não existe juro adicional em 1x — e se aplica a **cartão de crédito**, **cartão com 3DS**, **Google Pay** e **Apple Pay**.
A operação escreve **sempre a conta dona do token**. Não existe parâmetro de produtor: não há como configurar a tabela de outra conta.
***
## Quando a mudança passa a valer
O corpo devolvido é a tabela como ficou gravada, no mesmo formato do `GET`. Não é um eco do que você mandou: se algo foi normalizado, é ali que aparece.
A tabela de parcelas que o comprador vê é atualizada na hora em que você grava. Não há espera de propagação.
O juro cobrado fica registrado no pedido. Mudar a tabela **não** altera venda passada, não gera cobrança complementar e não gera devolução.
**Checkout em voo: quem já está com a página aberta vê um valor e paga outro.**
A tabela exibida é lida quando o checkout **carrega**. O juro efetivamente cobrado é calculado no **momento do pagamento**. Um comprador que abriu o checkout antes da sua alteração continua vendo a tabela antiga até recarregar a página — mas, se ele finalizar depois, é a tabela **nova** que entra na cobrança.
A diferença sai do bolso do comprador e só aparece na fatura dele. Na prática:
* **Evite mexer em horário de pico.** A janela de risco é o tempo entre carregar o checkout e finalizar a compra.
* **Prefira reduzir a aumentar durante o dia.** Cobrar menos do que foi exibido não gera reclamação; o contrário gera.
* **Mudou para mais? Espere alguns minutos** antes de considerar a alteração "no ar" para quem já estava navegando.
***
## Corpo da requisição
A tabela inteira. **Substitui** a configuração anterior: parcela que não estiver nesta lista fica sem juro adicional, e uma lista vazia (`[]`) zera todas.
Mande apenas as faixas que quer cobrar — não é preciso repetir as 11.
Número de parcelas. Aceita apenas de `2` a `12`. Cada número pode aparecer uma única vez na lista.
Juro adicional em pontos percentuais (`1.5` = 1,5%), com no máximo duas casas decimais. `null` remove o juro dessa parcela.
Se o juro adicional deve passar a ser cobrado. Omitido, vale `true` — quem envia uma tabela quer cobrá-la.
Envie `false` para guardar a tabela **sem cobrar**: os percentuais são preservados e voltam a valer com um `true`.
### O que é aceito
| Campo | Faixa aceita | Recusa |
| -------------------- | ----------------------------------------------- | --------------------------------------- |
| `installments` | inteiro de `2` a `12` | `1`, `0`, `13`, `18`, negativos → `400` |
| `interestPercentage` | número não negativo, no máximo 2 casas decimais | `-1`, `1.234` → `400` |
| `installments[]` | cada número de parcelas **uma única vez** | faixa repetida → `400` |
| `active` | `true` ou `false` | — |
**Não há teto de negócio.** O quanto de juro cobrar é decisão sua, e esta API aceita a mesma faixa que o painel aceita — nada que você consegue configurar pela tela é recusado aqui.
O que existe é um limite técnico: acima de `99999999.99` o valor não cabe no campo e a chamada volta `400`. **Confira o que você envia**: um `1000` digitado no lugar de `10.00` é aceito, e multiplica por onze o que o comprador paga na parcela.
***
## Substituição, não mesclagem
O corpo descreve a tabela **inteira**, não um remendo. Se hoje você cobra em 6x e em 12x e manda só a linha de 6x, a de 12x é apagada.
É de propósito: sem isso, remover um juro pela API seria impossível — não haveria como dizer "essa faixa não existe mais".
O caminho seguro é sempre o mesmo: [leia a tabela](/api-reference/installment-interest/retrieve), altere o que precisa em memória, e mande o conjunto completo de volta.
`{"installments": []}` remove o juro adicional de todas as faixas. A conta continua existindo e `active` continua valendo o que você mandou — só não há mais percentual nenhum para aplicar.
Há duas formas de parar de cobrar, e elas não são equivalentes:
* **`active: false`** com a tabela cheia — para de cobrar e **guarda** os percentuais. Religar depois é um `PUT` com `active: true`.
* **`installments: []`** — apaga os percentuais. Voltar exige redigitar tudo.
Para uma pausa (promoção, campanha, teste), use `active: false`.
**Para religar, mande `active` explicitamente.** Se a sua tabela está desligada e você envia um `PUT` **sem** o campo `active`, a chamada volta `409` em vez de reativar.
O motivo: `active` omitido vale `true`, então a chamada silenciosamente voltaria a cobrar do seu comprador — e "corrigir um percentual" não é a mesma intenção que "voltar a cobrar". Envie `active: true` para religar junto com os novos percentuais, ou `active: false` para alterá-los mantendo a cobrança desligada.
Enquanto a tabela está vigente, ou quando nunca existiu, não há ambiguidade e omitir `active` continua valendo `true`.
Mandar o mesmo corpo duas vezes deixa a conta exatamente no mesmo estado. Não existe recurso que possa ser criado em duplicidade aqui.
Por isso a operação **não lê** o header `X-Idempotency-Key` — ele é ignorado, como em todo endpoint fora de [Criar Cobrança](/conceitos/idempotencia). Se um `503` interromper a chamada, repita à vontade.
***
## Resposta
`200` devolve a tabela como ficou gravada, no mesmo formato de [Consultar Juro Adicional](/api-reference/installment-interest/retrieve): `active` mais as 11 faixas de 2x a 12x, com `null` nas que ficaram sem juro.
```json theme={null}
{
"active": true,
"installments": [
{ "installments": 2, "interestPercentage": 1.5 },
{ "installments": 3, "interestPercentage": 2.5 },
{ "installments": 4, "interestPercentage": null },
{ "installments": 5, "interestPercentage": null },
{ "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 }
]
}
```
**Confira a resposta em vez de assumir.** Ela é a leitura do que ficou gravado, não a repetição do que você enviou — é onde uma faixa apagada por omissão aparece.
***
## Respostas de erro
| Código | Quando ocorre | Corpo de exemplo |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | Faixa fora de 2..12, percentual negativo, mais de duas casas decimais, ou faixa repetida. | `{ "installments": [ { "installments": ["1x não aceita juro adicional de parcelamento. Use um valor entre 2 e 12."] } ] }` |
| `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 `write`. Leitura exige `read`; escrita exige `write`. | `{ "detail": "Você não tem permissão para executar esta ação." }` |
| `409` | Conta sem cadastro de recebimento concluído, recurso não habilitado para a conta, **ou** `PUT` sem `active` sobre uma tabela desligada. | `{ "detail": "Conta ainda não habilitada para recebimento. Conclua o cadastro no painel da Cakto para poder configurar o juro adicional de parcelamento." }` |
| `429` | Limite de requisições excedido. Veja [Limites de Requisição](/conceitos/rate-limits). | `{ "detail": "Request was throttled. Expected available in 42 seconds." }` |
| `503` | Falha temporária ao gravar a configuração. | `{ "detail": "Não foi possível salvar o juro adicional agora. Tente novamente em instantes." }` |
### Como ler o `400`
Os erros por campo vêm em `installments`, **na mesma posição do item que você enviou** — o terceiro item da sua lista gera o terceiro elemento do array de erros. O erro de faixa repetida é da lista inteira e vem como texto direto:
```json theme={null}
{
"installments": ["Cada número de parcelas pode aparecer uma única vez. Repetidos: 6x."]
}
```
**`409` e `503` pedem reações opostas — não trate os dois como "deu erro, tenta de novo".**
`409` tem três motivos, e o `detail` diz qual: a conta ainda não concluiu o cadastro de recebimento, o recurso não está habilitado para ela, ou você mandou um `PUT` sem `active` sobre uma tabela desligada. **Nenhum dos três se resolve repetindo a chamada** — o primeiro se resolve no [Painel Cakto](https://app.cakto.com.br/dashboard), o segundo com o [suporte](mailto:infoprodutores@cakto.com.br), e o terceiro reenviando com `active` explícito.
`503` é transitório: repita com backoff. A operação é idempotente, então repetir não tem custo. Se persistir, é incidente do nosso lado.
Um `400` também pode chegar com `detail` em vez de `installments`, quando a recusa vem do serviço interno de taxas. É problema do corpo enviado: repetir igual não vai passar.
***
## Exemplo de requisição
```bash cURL theme={null}
curl -X PUT 'https://api.cakto.com.br/public_api/installment-interest/' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...' \
-H 'Content-Type: application/json' \
-d '{
"active": true,
"installments": [
{ "installments": 2, "interestPercentage": 1.5 },
{ "installments": 6, "interestPercentage": 5.5 },
{ "installments": 12, "interestPercentage": 10 }
]
}'
```
```python Python theme={null}
import requests
BASE = "https://api.cakto.com.br/public_api/installment-interest/"
HEADERS = {"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."}
# 1. Leia a tabela atual -- o PUT substitui tudo, então nunca escreva às cegas.
atual = requests.get(BASE, headers=HEADERS, timeout=30).json()
tabela = {
linha["installments"]: linha["interestPercentage"]
for linha in atual["installments"]
if linha["interestPercentage"] is not None
}
# 2. Altere só o que precisa.
tabela[12] = 10.0
# 3. Mande o conjunto completo de volta.
resposta = requests.put(
BASE,
headers=HEADERS,
json={
"active": True,
"installments": [
{"installments": n, "interestPercentage": p} for n, p in sorted(tabela.items())
],
},
timeout=30,
)
resposta.raise_for_status()
print(resposta.json())
```
```javascript Node.js theme={null}
const BASE = "https://api.cakto.com.br/public_api/installment-interest/";
const headers = {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn...",
"Content-Type": "application/json",
};
// 1. Leia a tabela atual -- o PUT substitui tudo.
const atual = await fetch(BASE, { headers }).then((r) => r.json());
const tabela = new Map(
atual.installments
.filter((l) => l.interestPercentage !== null)
.map((l) => [l.installments, l.interestPercentage]),
);
// 2. Altere só o que precisa.
tabela.set(12, 10.0);
// 3. Mande o conjunto completo de volta.
const resposta = await fetch(BASE, {
method: "PUT",
headers,
body: JSON.stringify({
active: true,
installments: [...tabela.entries()]
.sort((a, b) => a[0] - b[0])
.map(([installments, interestPercentage]) => ({ installments, interestPercentage })),
}),
});
if (!resposta.ok) throw new Error(`Cakto API error ${resposta.status}`);
console.log(await resposta.json());
```
### Pausar sem apagar
```bash theme={null}
curl -X PUT 'https://api.cakto.com.br/public_api/installment-interest/' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...' \
-H 'Content-Type: application/json' \
-d '{ "active": false, "installments": [
{ "installments": 2, "interestPercentage": 1.5 },
{ "installments": 6, "interestPercentage": 5.5 },
{ "installments": 12, "interestPercentage": 10 }
] }'
```
`{"active": false, "installments": []}` **não** é o mesmo que a chamada acima: ele desliga **e apaga**. Para religar depois, você teria que redigitar a tabela.
***
## Boas práticas
* **Leia, altere, escreva.** Nunca monte o corpo do zero a partir de uma tabela que você acha que está lá.
* **Guarde a tabela anterior** antes de gravar. Não há histórico do lado da Cakto: o valor que você substituir não é recuperável.
* **Prefira `active: false` a `installments: []`** quando o objetivo é pausar.
* **Não escreva em laço.** Esta configuração muda raramente e cada escrita chega ao comprador. Se você está gravando várias vezes por dia, provavelmente o que você quer é [medir o resultado](/api-reference/installment-interest/earnings), não reconfigurar.
* **Depois de mudar para mais, confira o efeito no ganho** em [Ganhos com Juro de Parcelamento](/api-reference/installment-interest/earnings) — juro alto derruba conversão no parcelado, e o total pode cair mesmo com o percentual maior.
## OpenAPI
````yaml PUT /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/:
put:
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_update
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentInterestUpdateRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/InstallmentInterestUpdateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/InstallmentInterestUpdateRequest'
required: true
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
description: >-
A tabela como ficou depois da escrita, no mesmo formato do `GET`. A
operação substitui a configuração inteira e pode ser repetida:
mandar o mesmo corpo de novo deixa a conta no mesmo estado.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentInterestUpdate400'
examples:
ParcelaForaDaFaixa:
value:
installments:
- installments:
- >-
1x não aceita juro adicional de parcelamento. Use um
valor entre 2 e 12.
PercentualNegativo:
value:
installments:
- interestPercentage:
- >-
Certifque-se de que este valor seja maior ou igual a
0.
summary: Não há teto de negócio no percentual; negativo é recusado.
PercentualNaoCabeNoCampo:
value:
installments:
- interestPercentage:
- >-
Certifique-se de que não haja mais de 10 dígitos no
total.
summary: Limite técnico do campo (99999999.99), não regra de negócio.
ParcelaRepetida:
value:
installments:
- >-
Cada número de parcelas pode aparecer uma única vez.
Repetidos: 6x.
description: >-
Corpo inválido. Os erros por campo vêm em `installments`, na mesma
posição do item enviado; `detail` aparece quando a recusa vem do
serviço interno de taxas.
'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`.
'409':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
ContaSemRecebimento:
value:
detail: >-
Conta ainda não habilitada para recebimento. Conclua o
cadastro no painel da Cakto para poder configurar o juro
adicional de parcelamento.
RecursoNaoHabilitado:
value:
detail: >-
O juro adicional de parcelamento não está habilitado para
esta conta. Fale com o suporte da Cakto.
description: >-
O pedido está correto, mas o estado da conta impede a escrita: falta
concluir o cadastro de recebimento, ou o recurso não está habilitado
para a conta. Nos dois casos repetir a chamada não resolve — leia o
`detail` para saber qual é.
'503':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
EscritaIndisponivel:
value:
detail: >-
Não foi possível salvar o juro adicional agora. Tente
novamente em instantes.
description: >-
Falha ao falar com o serviço interno que guarda a configuração. É
transitório na maioria dos casos e a chamada pode ser repetida com
backoff — ela é idempotente. A resposta nunca repassa o corpo do
erro interno.
security:
- OAuth Token: []
components:
schemas:
InstallmentInterestUpdateRequest:
type: object
properties:
active:
type: boolean
default: true
description: >-
Se o juro adicional deve passar a ser cobrado. Omitido, vale `true`
— quem envia uma tabela quer cobrá-la. Envie `false` para guardar a
tabela sem cobrar; os percentuais são preservados e voltam a valer
com um `true`.
installments:
type: array
items:
$ref: '#/components/schemas/InstallmentInterestRateInput'
description: >-
A tabela inteira. **Substitui** a configuração anterior: parcela que
não estiver nesta lista fica sem juro adicional, e uma lista vazia
zera todas. Mande apenas as faixas que quer cobrar; não é preciso
repetir as 11.
required:
- installments
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
InstallmentInterestUpdate400:
type: object
properties:
detail:
type: string
installments: {}
UnauthenticatedError:
type: object
properties:
detail:
type: string
InstallmentInterestRateInput:
type: object
properties:
installments:
type: integer
description: Número de parcelas, de 2 a 12.
interestPercentage:
type: number
example: 1.5
nullable: true
description: >-
Juro adicional em pontos percentuais (`1.5` = 1,5%), com no máximo
duas casas decimais. Não há teto de negócio — o percentual é decisão
sua, e a mesma faixa aceita no painel é aceita aqui. `null` remove o
juro dessa parcela.
maximum: 99999999.99
minimum: 0
required:
- installments
- interestPercentage
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).
````