Skip to main content
GET
cURL

Escopo

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: Em produto sem coprodutor nem afiliado, os dois são iguais. Assim que existe alguém dividindo receita, eles se separam — e é aí que mora o erro que este endpoint existe para evitar.
A operação lê sempre a conta dona do token. Não existe parâmetro de produtor.

O rateio, em um exemplo

O juro não é todo seu. Ele é dividido entre os comissionados do pedido, exatamente como o valor da venda.Somar o juro dos pedidos e chamar de ganho — o cálculo “óbvio” — superestima o ganho de quem divide receita. O número é plausível, vem sozinho, e ninguém percebe até conferir com o extrato.
Uma venda de R1.000,00parceladaem12xcom10 1.000,00** parcelada em 12x com **10%** de juro adicional gera **R 100,00 de juro cobrado do comprador. O que acontece com esses R$ 100,00 depende de quem participa da venda: O charged é o mesmo nos quatro casos porque ele é o juro do pedido, não a sua fatia dele. O que muda é o earned.
A última linha não é 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.
Em pedidos antigos, criados por um caminho de comissionamento legado com afiliado, o rateio gravado pode somar mais de 100% do juro do pedido. Nesses pedidos o 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

Não existe “consultar tudo”. Omitindo 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.
Acima disso a resposta é 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.
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.
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

Só pedidos pagos. Pedido recusado, expirado ou aguardando pagamento não entra — nem em charged, nem em earned, nem na contagem orders.
O total de um período passado pode mudar.Não existe registro de reversão: um pedido reembolsado, com chargeback ou em disputa simplesmente sai do total do período em que foi vendido. O agosto que você consultou em setembro pode não ser o mesmo agosto se consultar em outubro.Se você armazenar o valor, trate-o como um retrato daquele momento e reconcilie, em vez de tratá-lo como fechado.

Resposta

Dinheiro vem como string decimal ("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

Nesse mês o comprador pagou R1.000,00dejuroadicional;R 1.000,00 de juro adicional; R 700,00 ficaram com esta conta e R$ 300,00 foram para coprodutores e afiliados.
Ele traz o número de parcelas dos pedidos que existiram na janela. Faixa que você configurou mas ninguém usou não aparece; e um pedido antigo com um número de parcelas fora de 2..12 aparece como está.Para saber o que está configurado hoje, use Consultar Juro Adicional — esta consulta é sobre o passado.
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.
Somando 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

O 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


Boas práticas

  • Use earned para “quanto eu ganhei” e charged para conferir com o extrato. Trocar os dois é o erro clássico aqui, e ele só aparece na conciliação.
  • Nunca some charged entre parceiros. O mesmo pedido aparece com o mesmo charged para cada comissionado; somar conta o juro várias vezes. Entre parceiros, some earned.
  • Leia o startDate/endDate da 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 earned não subiu depois de você aumentar o percentual em Configurar Juro Adicional, provavelmente a conversão no parcelado caiu — byInstallments mostra em qual faixa.

Authorizations

Authorization
string
header
required

Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.

Query Parameters

currency
enum<string>
default:BRL

Moeda dos pedidos considerados. Uma consulta responde sobre uma moeda só — somar moedas diferentes produziria um número que não existe.

  • BRL - Real
  • EUR - Euro
  • MXN - Peso Mexicano
  • PEN - Sol Peruano
  • USD - Dólar
  • CLP - Peso Chileno
  • COP - Peso Colombiano
  • ARS - Peso Argentino
  • BOB - Boliviano
  • UYU - Peso Uruguayo
Available options:
BRL,
EUR,
MXN,
PEN,
USD,
CLP,
COP,
ARS,
BOB,
UYU
Minimum string length: 1
endDate
string<date>

Fim 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.

startDate
string<date>

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.

currency
string
required

Moeda dos pedidos considerados.

startDate
string<date-time>
required

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.

endDate
string<date-time>
required

Fim da janela efetivamente aplicada.

charged
string<decimal>
required

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.

Example:

"2.49"

earned
string<decimal>
required

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.

Example:

"2.49"

orders
integer
required

Quantidade de pedidos pagos com juro adicional na janela.

byInstallments
object[]
required

O mesmo total, recortado por número de parcelas do pedido.

byPaymentMethod
object[]
required

O mesmo total, recortado por método de pagamento do pedido.