Registrar Cliente
curl --request POST \
--url https://garu.com.br/api/v1/customers \
--header 'Authorization: <authorization>' \
--header 'Content-Type: <content-type>' \
--data '
{
"name": "<string>",
"email": "<string>",
"document": "<string>",
"phone": "<string>",
"personType": "<string>",
"zipCode": "<string>",
"street": "<string>",
"number": "<string>",
"complement": "<string>",
"neighborhood": "<string>",
"city": "<string>",
"state": "<string>"
}
'import requests
url = "https://garu.com.br/api/v1/customers"
payload = {
"name": "<string>",
"email": "<string>",
"document": "<string>",
"phone": "<string>",
"personType": "<string>",
"zipCode": "<string>",
"street": "<string>",
"number": "<string>",
"complement": "<string>",
"neighborhood": "<string>",
"city": "<string>",
"state": "<string>"
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
body: JSON.stringify({
name: '<string>',
email: '<string>',
document: '<string>',
phone: '<string>',
personType: '<string>',
zipCode: '<string>',
street: '<string>',
number: '<string>',
complement: '<string>',
neighborhood: '<string>',
city: '<string>',
state: '<string>'
})
};
fetch('https://garu.com.br/api/v1/customers', 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/customers",
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([
'name' => '<string>',
'email' => '<string>',
'document' => '<string>',
'phone' => '<string>',
'personType' => '<string>',
'zipCode' => '<string>',
'street' => '<string>',
'number' => '<string>',
'complement' => '<string>',
'neighborhood' => '<string>',
'city' => '<string>',
'state' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: <content-type>"
],
]);
$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/customers"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"document\": \"<string>\",\n \"phone\": \"<string>\",\n \"personType\": \"<string>\",\n \"zipCode\": \"<string>\",\n \"street\": \"<string>\",\n \"number\": \"<string>\",\n \"complement\": \"<string>\",\n \"neighborhood\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "<content-type>")
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/customers")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.body("{\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"document\": \"<string>\",\n \"phone\": \"<string>\",\n \"personType\": \"<string>\",\n \"zipCode\": \"<string>\",\n \"street\": \"<string>\",\n \"number\": \"<string>\",\n \"complement\": \"<string>\",\n \"neighborhood\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://garu.com.br/api/v1/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"document\": \"<string>\",\n \"phone\": \"<string>\",\n \"personType\": \"<string>\",\n \"zipCode\": \"<string>\",\n \"street\": \"<string>\",\n \"number\": \"<string>\",\n \"complement\": \"<string>\",\n \"neighborhood\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyClientes
Registrar Cliente
Cadastre um cliente para o seller autenticado, com dedup automática por CPF/CNPJ
POST
/
api
/
v1
/
customers
Registrar Cliente
curl --request POST \
--url https://garu.com.br/api/v1/customers \
--header 'Authorization: <authorization>' \
--header 'Content-Type: <content-type>' \
--data '
{
"name": "<string>",
"email": "<string>",
"document": "<string>",
"phone": "<string>",
"personType": "<string>",
"zipCode": "<string>",
"street": "<string>",
"number": "<string>",
"complement": "<string>",
"neighborhood": "<string>",
"city": "<string>",
"state": "<string>"
}
'import requests
url = "https://garu.com.br/api/v1/customers"
payload = {
"name": "<string>",
"email": "<string>",
"document": "<string>",
"phone": "<string>",
"personType": "<string>",
"zipCode": "<string>",
"street": "<string>",
"number": "<string>",
"complement": "<string>",
"neighborhood": "<string>",
"city": "<string>",
"state": "<string>"
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
body: JSON.stringify({
name: '<string>',
email: '<string>',
document: '<string>',
phone: '<string>',
personType: '<string>',
zipCode: '<string>',
street: '<string>',
number: '<string>',
complement: '<string>',
neighborhood: '<string>',
city: '<string>',
state: '<string>'
})
};
fetch('https://garu.com.br/api/v1/customers', 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/customers",
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([
'name' => '<string>',
'email' => '<string>',
'document' => '<string>',
'phone' => '<string>',
'personType' => '<string>',
'zipCode' => '<string>',
'street' => '<string>',
'number' => '<string>',
'complement' => '<string>',
'neighborhood' => '<string>',
'city' => '<string>',
'state' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: <content-type>"
],
]);
$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/customers"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"document\": \"<string>\",\n \"phone\": \"<string>\",\n \"personType\": \"<string>\",\n \"zipCode\": \"<string>\",\n \"street\": \"<string>\",\n \"number\": \"<string>\",\n \"complement\": \"<string>\",\n \"neighborhood\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "<content-type>")
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/customers")
.header("Authorization", "<authorization>")
.header("Content-Type", "<content-type>")
.body("{\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"document\": \"<string>\",\n \"phone\": \"<string>\",\n \"personType\": \"<string>\",\n \"zipCode\": \"<string>\",\n \"street\": \"<string>\",\n \"number\": \"<string>\",\n \"complement\": \"<string>\",\n \"neighborhood\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://garu.com.br/api/v1/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"document\": \"<string>\",\n \"phone\": \"<string>\",\n \"personType\": \"<string>\",\n \"zipCode\": \"<string>\",\n \"street\": \"<string>\",\n \"number\": \"<string>\",\n \"complement\": \"<string>\",\n \"neighborhood\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyVisão Geral
Registra um cliente para a conta autenticada. Se já existir um cliente global com o mesmodocument (CPF ou CNPJ) — vinculado a outro seller — a Garu não cria um registro duplicado: reaproveita o cliente global e cria (ou atualiza) o seu próprio perfil vinculado a ele.
Dedup por documento, não por e-mail. Dois sellers podem cadastrar o mesmo CPF com e-mails diferentes; cada um enxerga seu próprio perfil (nome, e-mail, telefone) para esse cliente, sem vazar dados do outro seller.
Headers
string
required
Sua chave de API (
Bearer sk_live_...)string
required
application/jsonstring
Opcional. Chave única para reenviar a requisição com segurança sem criar um cliente duplicado. A mesma chave devolve o cliente originalmente criado/casado por 24h, por vendedor.
Request Body
string
required
Nome completo
string
required
E-mail válido
string
required
CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números
string
required
Telefone com DDD, 10 ou 11 dígitos, apenas números
string
required
fisica ou juridicastring
CEP com 8 dígitos, sem hífen
string
Logradouro
string
Número do endereço
string
Complemento
string
Bairro
string
Cidade
string
Sigla do estado, 2 letras maiúsculas (ex:
SP)Exemplo de Requisição
curl -X POST https://garu.com.br/api/v1/customers \
-H "Authorization: Bearer sk_live_sua_chave_api" \
-H "Content-Type: application/json" \
-d '{
"name": "Maria Silva",
"email": "maria@exemplo.com.br",
"document": "12345678909",
"phone": "11987654321",
"personType": "fisica"
}'
const response = await fetch('https://garu.com.br/api/v1/customers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GARU_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Maria Silva',
email: 'maria@exemplo.com.br',
document: '12345678909',
phone: '11987654321',
personType: 'fisica'
})
});
const customer = await response.json();
console.log(customer.uuid);
import os
import requests
response = requests.post(
"https://garu.com.br/api/v1/customers",
headers={
"Authorization": f"Bearer {os.environ['GARU_API_KEY']}",
"Content-Type": "application/json",
},
json={
"name": "Maria Silva",
"email": "maria@exemplo.com.br",
"document": "12345678909",
"phone": "11987654321",
"personType": "fisica",
},
)
customer = response.json()
print(customer["uuid"])
Resposta de Sucesso (201 Created)
{
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Maria Silva",
"email": "maria@exemplo.com.br",
"phone": "11987654321",
"document": "12345678909",
"personType": "fisica",
"zipCode": null,
"street": null,
"number": null,
"complement": null,
"neighborhood": null,
"city": null,
"state": null,
"billingEmail": "maria@exemplo.com.br",
"hasBillingEmailOverride": false,
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
}
billingEmail é o e-mail resolvido para envios de cobrança: billingEmailOverride (se definido) → e-mail deste perfil → e-mail global do cliente. Veja Definir e-mail de cobrança.Erros
| Código | Quando acontece |
|---|---|
400 | Dados inválidos (documento, telefone, e-mail) |
401 | Chave de API ausente ou inválida |
Próximos passos
- Cobranças agendadas — agende PIX/Boleto para uma data futura para este cliente.
- Boleto parcelado — venda em carnê para este cliente.
Was this page helpful?
⌘I