Agregar clave Pix

Este endpoint permite registrar una nueva clave Pix (correo electrónico, CPF, CNPJ, teléfono o aleatoria) para su cliente final.

---

Endpoint

• Método: POST

URL del endpoint

https://api.xgateglobal.com/pix/customer/CLIENT_ID/key

Importante

El campo CLIENT_ID hace referencia al ID del cliente; si aún no lo ha creado, puede hacerlo desde la página de crear clientes.

---

Prueba de integración

Utilice el formulario a continuación para simular el registro de una clave Pix real.

➕

Probar: Añadir Clave Pix

1. Sus Credenciales

Correo electrónico

Contraseña

---

2. ¿Qué cliente recibirá la clave?

ID de Cliente

¿No tienes un cliente? Haz clic aquí para crear

---

3. Datos de la Nueva Clave

Tipo de ClaveE-mailCPFCNPJTeléfonoClave Aleatoria

Valor de la Clave

---

Solicitud

Encabezados obligatorios

Encabezado	Valor	Descripción
Authorization	Bearer <tu_token>	Token de autenticación JWT.

Parámetros de URL

Parámetro	Tipo	Obligatorio	Descripción
CLIENT_ID	string	Sí	El _id del cliente al que desea agregar la clave Pix.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
key	string	Sí	El valor de la clave Pix (por ejemplo: your@email.com, +551199...).
type	string	Sí	El tipo de clave. Valores aceptados: EMAIL, CPF, CNPJ, PHONE, RANDOM.

---

Respuestas

Éxito (201 Created)

La clave se registró correctamente y ya está lista para su uso.

{
  "message": "Chave Pix adicionada com sucesso",
  "key": {
    "key": "444***********",
    "type": "CPF",
    "_id": "696c604456f8***********"
  }
}

Errores comunes

Estado	Mensaje	Posible causa
400	Bad Request	La clave Pix proporcionada no es válida.
401	Unauthorized	• Token inválido o vencido. • Encabezado inválido o faltante. • IP no permitido.
404	Not Found	• La clave Pix ya está registrada. • La clave Pix no corresponde a un CPF válido. • Cliente no encontrado.
500	Internal Server Error	Error interno del servidor. Contacte con soporte.

Cómo usar

El propósito principal de agregar claves Pix es permitir que el usuario realice un retiro (Withdraw) utilizando la clave recién creada.

La respuesta de este endpoint proporciona inmediatamente el objeto completo de la clave, que es necesario para construir la carga útil del retiro.

Flujo de integración

1. Registrar la clave: Llame a este endpoint (POST /pix/customer/CLIENT_ID/key).
2. Capturar: La API devolverá los datos de la clave creada. Guarde este objeto.
3. Enviar: Debe pasar el objeto completo recibido dentro de la propiedad pixKey en la carga útil del retiro.

Advertencia de formato

No envíe datos de clave Pix incompletos. La carga útil del retiro espera el objeto JSON completo que contiene key, type y _id.

Ejemplo práctico

1. Lo que recibe al crear una clave Pix:

{
    "message": "Chave Pix adicionada com sucesso",
    "key": {
      "key": "+5512**********",
      "type": "PHONE",
      "_id": "68fa5d5400**********"
    }
}

2. Cómo enviarla en el retiro (POST /withdraw):

Tomará el objeto anterior e lo insertará dentro de pixKey:

{
    "amount": 0.2,
    "customerId": "68e7b8****************",
    "currency": {
        "_id": "67339fa800****************",
        "name": "BRL",
        "type": "PIX",
        "symbol": "R$",
        "createdDate": "2024-11-12T18:34:16.289Z",
        "updatedDate": "2024-11-12T18:34:16.289Z",
        "__v": 0
    },
    "pixKey": {
        "key": "+5512**********",
        "type": "PHONE",
        "_id": "68fa5d5400**********"
    }
}

Cada campo de este JSON se explica en la página de retiros.

---

Integración

Node.js

El ejemplo de integración utiliza la librería Axios en Node.js.

Instalando Axios:

npm install axios

Ejemplo en JavaScript:

const axios = require("axios");

(async () => {
const email = "your_email@domain.com";
const password = "**********";
const customerId = "12************";
const key = "+55***********";
const type = "PHONE";

try {
    const url_api = "https://api.xgateglobal.com"
    const login = await axios.post(`${url_api}/auth/token`, { email, password });
    const { data } = await axios.post(`${url_api}/pix/customer/${customerId}/key`, {
        key,
        type
    }, {
        headers: {
            "Authorization": `Bearer ${login.data.token}`
        }
    });
    console.log(data); // Respuesta
} catch (error) {
    console.log(error.response.data.message) // Error
}
})()

Python

El ejemplo de integración utiliza la librería requests.

Instalando requests:

pip install requests

Ejemplo en Python:

import requests

email = "your_email@domain.com"
password = "**********"
customer_id = "12************"
key = "+55***********"
type_ = "PHONE"

try:
url_api = "https://api.xgateglobal.com"

# Autenticación para obtener el token
login_response = requests.post(f"{url_api}/auth/token", json={"email": email, "password": password})
login_response.raise_for_status()
token = login_response.json().get("token")

# Solicitud con autenticación
headers = {"Authorization": f"Bearer {token}"}
payload = {"key": key, "type": type_}
response = requests.post(f"{url_api}/pix/customer/{customer_id}/key", json=payload, headers=headers)
response.raise_for_status()

print(response.json())  # Respuesta
except requests.exceptions.RequestException as error:
try:
    print(error.response.json().get("message"))  # Error
except AttributeError:
    print("Error al procesar la solicitud.")

PHP

Ejemplo de cómo agregar una clave Pix utilizando cURL nativo de PHP.

$email = "your_email@domain.com";
$password = "**********";
$customerId = "12************";
$key = "+55***********";
$type = "PHONE";

$url_api = "https://api.xgateglobal.com";

try {
// Autenticación para obtener el token
$login_response = file_get_contents("$url_api/auth/token", false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n",
        'content' => json_encode(['email' => $email, 'password' => $password])
    ]
]));

$login_data = json_decode($login_response, true);
$token = $login_data['token'] ?? '';

// Solicitud con autenticación
$options = [
    'http' => [
        'method' => 'POST',
        'header' => "Authorization: Bearer $token\r\nContent-Type: application/json\r\n",
        'content' => json_encode(['key' => $key, 'type' => $type])
    ]
];

$response = file_get_contents("$url_api/pix/customer/$customerId/key", false, stream_context_create($options));

echo $response; // Respuesta
} catch (Exception $error) {
echo "Error al procesar la solicitud.";
}