Criar cliente
curl --request POST \
--url https://api.uvvipay.com.br/v1/customers \
--header 'Content-Type: application/json' \
--header 'client-id: <api-key>' \
--header 'client-secret: <api-key>' \
--data '
{
"external_customer_id": "<string>",
"name": "<string>",
"email": "jsmith@example.com",
"phone": "<string>",
"document": {
"number": "12345678901"
}
}
'import requests
url = "https://api.uvvipay.com.br/v1/customers"
payload = {
"external_customer_id": "<string>",
"name": "<string>",
"email": "jsmith@example.com",
"phone": "<string>",
"document": { "number": "12345678901" }
}
headers = {
"client-id": "<api-key>",
"client-secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'client-id': '<api-key>',
'client-secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
external_customer_id: '<string>',
name: '<string>',
email: 'jsmith@example.com',
phone: '<string>',
document: {number: '12345678901'}
})
};
fetch('https://api.uvvipay.com.br/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://api.uvvipay.com.br/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([
'external_customer_id' => '<string>',
'name' => '<string>',
'email' => 'jsmith@example.com',
'phone' => '<string>',
'document' => [
'number' => '12345678901'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"client-id: <api-key>",
"client-secret: <api-key>"
],
]);
$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://api.uvvipay.com.br/v1/customers"
payload := strings.NewReader("{\n \"external_customer_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"phone\": \"<string>\",\n \"document\": {\n \"number\": \"12345678901\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("client-id", "<api-key>")
req.Header.Add("client-secret", "<api-key>")
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://api.uvvipay.com.br/v1/customers")
.header("client-id", "<api-key>")
.header("client-secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_customer_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"phone\": \"<string>\",\n \"document\": {\n \"number\": \"12345678901\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.uvvipay.com.br/v1/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["client-id"] = '<api-key>'
request["client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_customer_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"phone\": \"<string>\",\n \"document\": {\n \"number\": \"12345678901\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "550e8400-e29b-41d4-a716-446655440001",
"external_customer_id": "customer-ext-0001",
"name": "John Doe",
"email": "john@example.com"
}Clientes
Criar cliente
Cria um cliente ou reaproveita o cadastro existente.
POST
/
v1
/
customers
Criar cliente
curl --request POST \
--url https://api.uvvipay.com.br/v1/customers \
--header 'Content-Type: application/json' \
--header 'client-id: <api-key>' \
--header 'client-secret: <api-key>' \
--data '
{
"external_customer_id": "<string>",
"name": "<string>",
"email": "jsmith@example.com",
"phone": "<string>",
"document": {
"number": "12345678901"
}
}
'import requests
url = "https://api.uvvipay.com.br/v1/customers"
payload = {
"external_customer_id": "<string>",
"name": "<string>",
"email": "jsmith@example.com",
"phone": "<string>",
"document": { "number": "12345678901" }
}
headers = {
"client-id": "<api-key>",
"client-secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'client-id': '<api-key>',
'client-secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
external_customer_id: '<string>',
name: '<string>',
email: 'jsmith@example.com',
phone: '<string>',
document: {number: '12345678901'}
})
};
fetch('https://api.uvvipay.com.br/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://api.uvvipay.com.br/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([
'external_customer_id' => '<string>',
'name' => '<string>',
'email' => 'jsmith@example.com',
'phone' => '<string>',
'document' => [
'number' => '12345678901'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"client-id: <api-key>",
"client-secret: <api-key>"
],
]);
$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://api.uvvipay.com.br/v1/customers"
payload := strings.NewReader("{\n \"external_customer_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"phone\": \"<string>\",\n \"document\": {\n \"number\": \"12345678901\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("client-id", "<api-key>")
req.Header.Add("client-secret", "<api-key>")
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://api.uvvipay.com.br/v1/customers")
.header("client-id", "<api-key>")
.header("client-secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_customer_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"phone\": \"<string>\",\n \"document\": {\n \"number\": \"12345678901\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.uvvipay.com.br/v1/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["client-id"] = '<api-key>'
request["client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_customer_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"phone\": \"<string>\",\n \"document\": {\n \"number\": \"12345678901\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "550e8400-e29b-41d4-a716-446655440001",
"external_customer_id": "customer-ext-0001",
"name": "John Doe",
"email": "john@example.com"
}Cria o cadastro de um cliente. Guarde o
id da resposta.
Na hora de assinar, envie esse id em customer_id. Veja POST /v1/subscriptions.
Fluxo
- Envie
external_customer_id,name,email,phoneedocument. - Guarde o
idda resposta. - Crie a assinatura com
customer_idigual a esseid.
Cliente já cadastrado
Se oexternal_customer_id e os dados (nome, e-mail, telefone e documento) forem iguais, a API responde 200 e devolve o mesmo id.
Se os dados forem diferentes, a API responde 422 / UVV154640. O cadastro não muda.
Se o documento (número e tipo) já estiver em outro external_customer_id, a API responde 422 / UVV154718.
Endereço
O endereço é opcional. Você pode cadastrar o cliente sem o blocoaddress.
Se enviar address, preencha todos os campos: zip_code, street, street_number, neighborhood, city, state e country. Se faltar algum, a API responde 400.
NOTA: Pix Automático precisa de endereço completo. Sem ele, a criação da assinatura responde 422 / UVV154361.
A resposta não inclui documento, telefone nem endereço.
Erros comuns: 400 (body inválido), 401/403 (credenciais ou produto Recorrência), 422 (UVV154640, UVV154718), 429 (20 req/min).Headers
ID público da credencial do merchant
Secret da credencial do merchant
Body
application/json
Cadastro de cliente da recorrência. Não envie organization_id. Este endpoint não atualiza um cliente existente.
Identificador do cliente no seu sistema.
Nome do cliente.
Email do cliente.
Telefone do cliente (somente dígitos).
Documento do cliente.
Show child attributes
Show child attributes
Endereço do cliente. Opcional. Quando enviado, todos os campos são obrigatórios. Se o cliente for usado com pix_type: automatic no create de assinatura, envie o endereço completo aqui. Este endpoint não valida Pix Automático.
Show child attributes
Show child attributes