curl --request GET \
--url https://api.cakto.com.br/public_api/installment-interest/earnings/ \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.cakto.com.br/public_api/installment-interest/earnings/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.cakto.com.br/public_api/installment-interest/earnings/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cakto.com.br/public_api/installment-interest/earnings/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://api.cakto.com.br/public_api/installment-interest/earnings/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyHttpResponse<String> response = Unirest.get("https://api.cakto.com.br/public_api/installment-interest/earnings/")
.header("Authorization", "Bearer <token>")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.cakto.com.br/public_api/installment-interest/earnings/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);
Console.WriteLine("{0}", response.Content);
{
"currency": "BRL",
"startDate": "2026-08-01T00:00:00-03:00",
"endDate": "2026-08-31T23:59:59.999999-03:00",
"charged": "1000.00",
"earned": "700.00",
"orders": 42,
"byInstallments": [
{
"installments": 6,
"charged": "400.00",
"earned": "280.00",
"orders": 20
},
{
"installments": 12,
"charged": "600.00",
"earned": "420.00",
"orders": 22
}
],
"byPaymentMethod": [
{
"paymentMethod": "credit_card",
"charged": "900.00",
"earned": "630.00",
"orders": 38
},
{
"paymentMethod": "threeDs",
"charged": "100.00",
"earned": "70.00",
"orders": 4
}
]
}Ganhos com Juro de Parcelamento
Quanto de juro adicional de parcelamento foi cobrado do comprador num período e quanto disso ficou com você depois do rateio por comissão. São dois números diferentes.
curl --request GET \
--url https://api.cakto.com.br/public_api/installment-interest/earnings/ \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.cakto.com.br/public_api/installment-interest/earnings/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.cakto.com.br/public_api/installment-interest/earnings/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cakto.com.br/public_api/installment-interest/earnings/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}require 'uri'
require 'net/http'
url = URI("https://api.cakto.com.br/public_api/installment-interest/earnings/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyHttpResponse<String> response = Unirest.get("https://api.cakto.com.br/public_api/installment-interest/earnings/")
.header("Authorization", "Bearer <token>")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.cakto.com.br/public_api/installment-interest/earnings/");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);
Console.WriteLine("{0}", response.Content);
{
"currency": "BRL",
"startDate": "2026-08-01T00:00:00-03:00",
"endDate": "2026-08-31T23:59:59.999999-03:00",
"charged": "1000.00",
"earned": "700.00",
"orders": 42,
"byInstallments": [
{
"installments": 6,
"charged": "400.00",
"earned": "280.00",
"orders": 20
},
{
"installments": 12,
"charged": "600.00",
"earned": "420.00",
"orders": 22
}
],
"byPaymentMethod": [
{
"paymentMethod": "credit_card",
"charged": "900.00",
"earned": "630.00",
"orders": 38
},
{
"paymentMethod": "threeDs",
"charged": "100.00",
"earned": "70.00",
"orders": 4
}
]
}Escopo
read payments
O que é este endpoint?
O juro adicional é um percentual configurado. Este endpoint responde o que ele virou em dinheiro num período, e responde com dois números que não são o mesmo:| Campo | Responde | Bate com |
|---|---|---|
charged | Quanto de juro o comprador pagou nos seus pedidos. | O extrato da adquirente, o valor da fatura do comprador. |
earned | Quanto desse juro ficou com você depois do rateio por comissão. | O que entrou no seu saldo. |
O rateio, em um exemplo
| Cenário | charged | earned |
|---|---|---|
| Você sozinho | "100.00" | "100.00" |
| Coprodutor com 30% | "100.00" | "70.00" |
| Afiliado com 20% | "100.00" | "80.00" |
| Afiliado 20% + coprodutor 30% | "100.00" | "56.00" |
charged é o mesmo nos quatro casos porque ele é o juro do pedido, não a sua fatia dele. O que muda é o earned.
50.00 porque as comissões não se somam sobre o mesmo valor: a do coprodutor incide sobre o que sobra depois da do afiliado. Com afiliado a 20%, o coprodutor de 30% leva 30% dos 80% restantes — 24% — e sobram 56% para você. O juro segue exatamente essa divisão.charged é do pedido, e por isso ele aparece igual para todo mundo que participa da venda.No cenário do coprodutor a 30%, se ele consultar este endpoint com o token dele, vê charged: "100.00" e earned: "30.00" — o mesmo charged que você, porque é o mesmo pedido. Somar o charged de vários parceiros conta o mesmo juro várias vezes. Quem soma entre parceiros deve somar earned, nunca charged.Por que a Cakto publica os dois
Publicar sóearned faria você conferir com o extrato da adquirente e concluir que a API está errada — o extrato mostra o valor cobrado, que é o charged. Publicar só charged faria você contar como ganho um dinheiro que foi para outra pessoa.
Com os dois lado a lado, o rateio fica visível em vez de invisível, e charged - earned é exatamente o que foi para os seus parceiros no período.
Um caso raro em que earned aparece acima de charged
Um caso raro em que earned aparece acima de charged
earned sai acima do charged.É defeito de gravação daquele histórico, não do cálculo desta consulta — o número devolvido é o que está registrado. Se você encontrar isso em um período recente, fale com o suporte.A janela de consulta
Sem parâmetro, a resposta é dos últimos 30 dias
Sem parâmetro, a resposta é dos últimos 30 dias
startDate e endDate, a janela é dos últimos 30 dias terminando agora.Os campos startDate e endDate da resposta ecoam a janela que foi realmente aplicada — não a que você pediu. Confira esse eco antes de guardar o número, principalmente se você não mandou nenhuma das duas datas.O período não pode passar de 92 dias
O período não pode passar de 92 dias
400, com o tamanho da janela no detail. Não adianta repetir a mesma chamada: quebre em blocos menores e some os earned (nunca os charged, veja acima).O teto existe para que o custo da consulta escale com o período pedido, e não com o tamanho do seu histórico.As datas são inclusivas, no fuso de São Paulo
As datas são inclusivas, no fuso de São Paulo
startDate conta a partir de 00:00 do dia informado; endDate, até 23:59:59 do dia informado. Ambas em America/Sao_Paulo. O formato é YYYY-MM-DD.O corte é pela data de criação do pedido.Uma consulta responde sobre uma moeda só
Uma consulta responde sobre uma moeda só
currency tem padrão BRL. Somar moedas diferentes produziria um número que não existe, então não há resposta multimoeda: para vendas em outra moeda, consulte de novo com currency diferente.O que entra na conta
charged, nem em earned, nem na contagem orders.Resposta
"1000.00"), não como número. É o padrão do contrato para valores monetários: converta para o tipo decimal da sua linguagem antes de somar, em vez de acumular em ponto flutuante.Percentuais e contagens continuam sendo número — orders é integer, e interestPercentage, no endpoint de configuração, é number.Exemplo de resposta
{
"currency": "BRL",
"startDate": "2026-08-01T00:00:00-03:00",
"endDate": "2026-08-31T23:59:59.999999-03:00",
"charged": "1000.00",
"earned": "700.00",
"orders": 42,
"byInstallments": [
{ "installments": 6, "charged": "400.00", "earned": "280.00", "orders": 20 },
{ "installments": 12, "charged": "600.00", "earned": "420.00", "orders": 22 }
],
"byPaymentMethod": [
{ "paymentMethod": "credit_card", "charged": "900.00", "earned": "630.00", "orders": 38 },
{ "paymentMethod": "threeDs", "charged": "100.00", "earned": "70.00", "orders": 4 }
]
}
byInstallments reflete as vendas, não a sua tabela
byInstallments reflete as vendas, não a sua tabela
byPaymentMethod só traz métodos que parcelam
byPaymentMethod só traz métodos que parcelam
credit_card, threeDs, googlepay e applepay — o mesmo vocabulário de POST /public_api/payments/. Pix e boleto não parcelam, então não geram juro adicional e nunca aparecem aqui.A soma dos recortes bate com o total
A soma dos recortes bate com o total
charged de todos os itens de byInstallments você chega ao charged do topo, e o mesmo vale para byPaymentMethod e para earned.A contagem orders é a exceção: um pedido conta uma vez em cada recorte, mas o orders do topo conta pedidos distintos — os números coincidem porque um pedido tem um número de parcelas e um método só.Respostas de erro
| Código | Quando ocorre | Corpo de exemplo |
|---|---|---|
400 | Janela acima de 92 dias, janela invertida, data malformada ou moeda desconhecida. | { "detail": "Janela de 120 dias excede o máximo de 92 dias. Consulte por períodos menores." } |
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. | { "detail": "Request was throttled. Expected available in 42 seconds." } |
400 de janela vem em detail; o de formato de data ou moeda vem no nome do parâmetro (startDate, endDate, currency), como lista de mensagens. Em nenhum dos casos repetir a mesma chamada resolve — corrija o parâmetro.Exemplo de requisição
curl -X GET 'https://api.cakto.com.br/public_api/installment-interest/earnings/?startDate=2026-08-01&endDate=2026-08-31' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...'
from datetime import date, timedelta
from decimal import Decimal
import requests
BASE = "https://api.cakto.com.br/public_api/installment-interest/earnings/"
HEADERS = {"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."}
MAX_DIAS = 92
def ganhos(inicio: date, fim: date) -> dict:
resposta = requests.get(
BASE,
headers=HEADERS,
params={"startDate": inicio.isoformat(), "endDate": fim.isoformat()},
timeout=30,
)
resposta.raise_for_status()
return resposta.json()
# Um ano quebrado em blocos de 92 dias -- a janela tem teto.
inicio, fim = date(2026, 1, 1), date(2026, 12, 31)
cobrado = ganho = Decimal("0.00")
atual = inicio
while atual <= fim:
bloco_fim = min(atual + timedelta(days=MAX_DIAS - 1), fim)
dados = ganhos(atual, bloco_fim)
cobrado += Decimal(dados["charged"])
ganho += Decimal(dados["earned"])
atual = bloco_fim + timedelta(days=1)
print(f"Comprador pagou de juro: R$ {cobrado}")
print(f"Ficou com você: R$ {ganho}")
print(f"Foi para parceiros: R$ {cobrado - ganho}")
const BASE = "https://api.cakto.com.br/public_api/installment-interest/earnings/";
const headers = { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." };
const url = new URL(BASE);
url.searchParams.set("startDate", "2026-08-01");
url.searchParams.set("endDate", "2026-08-31");
const resposta = await fetch(url, { headers });
if (!resposta.ok) throw new Error(`Cakto API error ${resposta.status}`);
const dados = await resposta.json();
// A janela da resposta é a que valeu, não necessariamente a que foi pedida.
console.log(`Período aplicado: ${dados.startDate} a ${dados.endDate}`);
console.log(`Comprador pagou de juro: R$ ${dados.charged}`);
console.log(`Ficou com você: R$ ${dados.earned}`);
for (const linha of dados.byInstallments) {
console.log(`${linha.installments}x -> R$ ${linha.earned} em ${linha.orders} pedidos`);
}
Boas práticas
- Use
earnedpara “quanto eu ganhei” echargedpara conferir com o extrato. Trocar os dois é o erro clássico aqui, e ele só aparece na conciliação. - Nunca some
chargedentre parceiros. O mesmo pedido aparece com o mesmochargedpara cada comissionado; somar conta o juro várias vezes. Entre parceiros, someearned. - Leia o
startDate/endDateda resposta antes de rotular o número, sobretudo quando você não mandou as datas. - Quebre períodos longos em blocos de até 92 dias em vez de tentar de novo com o intervalo inteiro.
- Reconcilie o que você armazenar. Reembolso e chargeback retiram pedidos de um período já consultado.
- Compare com a tabela configurada. Se o
earnednão subiu depois de você aumentar o percentual em Configurar Juro Adicional, provavelmente a conversão no parcelado caiu —byInstallmentsmostra em qual faixa.
Authorizations
Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.
Query Parameters
Moeda dos pedidos considerados. Uma consulta responde sobre uma moeda só — somar moedas diferentes produziria um número que não existe.
BRL- RealEUR- EuroMXN- Peso MexicanoPEN- Sol PeruanoUSD- DólarCLP- Peso ChilenoCOP- Peso ColombianoARS- Peso ArgentinoBOB- BolivianoUYU- Peso Uruguayo
BRL, EUR, MXN, PEN, USD, CLP, COP, ARS, BOB, UYU 1Fim do período (YYYY-MM-DD), inclusive até 23:59:59. Omitido, vale agora. O período entre startDate e endDate não pode passar de 92 dias.
Início do período (YYYY-MM-DD), inclusive, a partir de 00:00 no fuso de São Paulo. Omitido, a janela é dos últimos 30 dias.
Response
Juro adicional cobrado e ganho na janela. charged é o que o comprador pagou; earned é a fatia que ficou com a conta autenticada depois do rateio por comissão. Só pedidos pagos entram, e o total de um período passado pode mudar se houver reembolso ou chargeback depois.
Moeda dos pedidos considerados.
Início da janela efetivamente aplicada, não a que foi pedida: sem startDate a consulta responde os últimos 30 dias, e este campo é onde isso fica visível.
Fim da janela efetivamente aplicada.
Juro adicional cobrado do comprador nos pedidos pagos da janela em que você é comissionado, como string decimal ("1000.00"). É o número que bate com o extrato da adquirente — e não é o seu ganho quando o produto tem coprodutor ou afiliado.
"2.49"
A fatia do juro que ficou com você depois do rateio por comissão, como string decimal. Em produto sem coprodutor nem afiliado é igual a charged; com coprodutor a 30%, é 70% dele. Este é o número de "quanto eu ganhei com juro". Em pedidos antigos de um caminho legado com afiliado, o rateio gravado pode passar de 100% e earned sair acima de charged.
"2.49"
Quantidade de pedidos pagos com juro adicional na janela.
O mesmo total, recortado por número de parcelas do pedido.
Show child attributes
Show child attributes
O mesmo total, recortado por método de pagamento do pedido.
Show child attributes
Show child attributes
Was this page helpful?