Criar Carnê
curl --request POST \
--url https://garu.com.br/api/v1/installment-plans \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"productId": "<string>",
"customerId": 123,
"installments": 123,
"firstDueDate": "<string>",
"affiliateId": 123
}
'import requests
url = "https://garu.com.br/api/v1/installment-plans"
payload = {
"productId": "<string>",
"customerId": 123,
"installments": 123,
"firstDueDate": "<string>",
"affiliateId": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
productId: '<string>',
customerId: 123,
installments: 123,
firstDueDate: '<string>',
affiliateId: 123
})
};
fetch('https://garu.com.br/api/v1/installment-plans', 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://garu.com.br/api/v1/installment-plans",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'productId' => '<string>',
'customerId' => 123,
'installments' => 123,
'firstDueDate' => '<string>',
'affiliateId' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://garu.com.br/api/v1/installment-plans"
payload := strings.NewReader("{\n \"productId\": \"<string>\",\n \"customerId\": 123,\n \"installments\": 123,\n \"firstDueDate\": \"<string>\",\n \"affiliateId\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://garu.com.br/api/v1/installment-plans")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"productId\": \"<string>\",\n \"customerId\": 123,\n \"installments\": 123,\n \"firstDueDate\": \"<string>\",\n \"affiliateId\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://garu.com.br/api/v1/installment-plans")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"productId\": \"<string>\",\n \"customerId\": 123,\n \"installments\": 123,\n \"firstDueDate\": \"<string>\",\n \"affiliateId\": 123\n}"
response = http.request(request)
puts response.read_bodyBoleto Parcelado (Carnê)
Criar Carnê
Venda um produto em até 12 boletos mensais
POST
/
api
/
v1
/
installment-plans
Criar Carnê
curl --request POST \
--url https://garu.com.br/api/v1/installment-plans \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"productId": "<string>",
"customerId": 123,
"installments": 123,
"firstDueDate": "<string>",
"affiliateId": 123
}
'import requests
url = "https://garu.com.br/api/v1/installment-plans"
payload = {
"productId": "<string>",
"customerId": 123,
"installments": 123,
"firstDueDate": "<string>",
"affiliateId": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
productId: '<string>',
customerId: 123,
installments: 123,
firstDueDate: '<string>',
affiliateId: 123
})
};
fetch('https://garu.com.br/api/v1/installment-plans', 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://garu.com.br/api/v1/installment-plans",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'productId' => '<string>',
'customerId' => 123,
'installments' => 123,
'firstDueDate' => '<string>',
'affiliateId' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://garu.com.br/api/v1/installment-plans"
payload := strings.NewReader("{\n \"productId\": \"<string>\",\n \"customerId\": 123,\n \"installments\": 123,\n \"firstDueDate\": \"<string>\",\n \"affiliateId\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://garu.com.br/api/v1/installment-plans")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"productId\": \"<string>\",\n \"customerId\": 123,\n \"installments\": 123,\n \"firstDueDate\": \"<string>\",\n \"affiliateId\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://garu.com.br/api/v1/installment-plans")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"productId\": \"<string>\",\n \"customerId\": 123,\n \"installments\": 123,\n \"firstDueDate\": \"<string>\",\n \"affiliateId\": 123\n}"
response = http.request(request)
puts response.read_bodyVisão Geral
Cria um carnê e registra apenas o primeiro boleto. As parcelas seguintes são emitidas mês a mês, e a venda só se torna real quando a parcela 1 compensa.Carnê é crédito concedido por você, não parcelamento de cartão. Ninguém garante um boleto: se o comprador parar na parcela 4, você fica com 4 parcelas. Leia o guia do carnê antes de ativar.
Envie sempre
X-Idempotency-Key. Esta chamada registra um boleto de verdade no banco — uma retentativa sem a chave coloca dois códigos de barras pagáveis na mão do mesmo comprador. A mesma chave devolve o carnê original por 24h.Exemplo de Requisição
curl -X POST https://garu.com.br/api/v1/installment-plans \
-H "Authorization: Bearer sk_live_sua_chave" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: 6c4c2a1e-4c2b-4f1c-9a8d-1b2e3f4a5b6c" \
-d '{
"productId": "40381e8e-6ee7-4b8e-9393-766a6e2109d2",
"customerId": 4821,
"installments": 12
}'
import { Garu } from '@garuhq/node';
const garu = new Garu({ apiKey: process.env.GARU_API_KEY });
const carne = await garu.installmentPlans.create({
productId: '40381e8e-6ee7-4b8e-9393-766a6e2109d2',
customerId: 4821,
installments: 12
});
console.log(carne.totalScheduled); // 1560
console.log(carne.installmentAmount); // 130
import os, uuid, requests
r = requests.post(
"https://garu.com.br/api/v1/installment-plans",
headers={
"Authorization": f"Bearer {os.environ['GARU_API_KEY']}",
"X-Idempotency-Key": str(uuid.uuid4()),
},
json={
"productId": "40381e8e-6ee7-4b8e-9393-766a6e2109d2",
"customerId": 4821,
"installments": 12,
},
)
print(r.json()["totalScheduled"]) # 1560
Parâmetros
string
required
UUID do produto. O produto precisa ter carnê habilitado.
number
required
ID numérico do cliente. Clientes já têm um
uuid público (veja Clientes), mas este endpoint ainda linka pelo id numérico interno — obtenha-o via POST /api/customers (API interna) ou no dashboard.number
required
Número de parcelas, de 2 a 12. Uma parcela só não é carnê. O teto da plataforma é 12 e o vendedor pode definir um menor por produto.
string
Vencimento da parcela 1 em
YYYY-MM-DD. Padrão: hoje. Deve cair nos próximos 90 dias. As demais parcelas caem no mesmo dia dos meses seguintes, calculadas a partir dessa âncora — por isso um carnê ancorado em 31/01 não “escorrega” depois de fevereiro.number
Afiliado que fez a venda. Fixado no momento da venda: todas as parcelas seguintes herdam ele, então omitir aqui significa não pagar comissão nenhuma no carnê inteiro. Precisa ter afiliação ativa neste produto — caso contrário a chamada é recusada, em vez de descartar a atribuição em silêncio.
Resposta
{
"uuid": "e5d0d8fe-0000-4000-8000-000000000001",
"status": "pending_activation",
"installments": 12,
"installmentsPaid": 0,
"baseValue": 1200,
"fator": 1.3,
"installmentAmount": 130,
"totalScheduled": 1560,
"totalCollected": 0,
"firstDueDate": "2026-09-05",
"installmentsDetail": [
{
"number": 1,
"amount": 130,
"dueDate": "2026-09-05",
"status": "scheduled",
"boleto": { "barcodeLine": "50990...", "pdfUrl": "https://garu.com.br/..." },
"reissueCount": 0
}
]
}
Só a parcela 1 aparece com boleto. As demais ainda não existem como slip pagável — elas são criadas quando a parcela 1 compensa.
Erros
| Código | Quando |
|---|---|
400 | Produto não aceita carnê, número de parcelas fora de 2..12, ou afiliado sem afiliação ativa |
404 | Produto não encontrado nesta conta |
409 | Um carnê idêntico acabou de ser criado para este cliente |
Was this page helpful?
⌘I