Permitir IP de retiro en la subcuenta

Este endpoint permite registrar automáticamente el primer IP autorizado para realizar solicitudes de retiro en una subcuenta recién creada.

Regla de uso único

Esta ruta fue diseñada exclusivamente para la configuración inicial de la subcuenta. Solo permite guardar el primer IP. Si la subcuenta ya tiene un IP de retiro configurado, la API devolverá un error y los nuevos IP deberán agregarse desde el panel.

Atención: retiro vs saldo

El IP habilitado por este endpoint tiene permiso exclusivo para crear retiros. No otorga acceso a las rutas de consulta de saldo. La habilitación de IP para consulta de saldo tiene una configuración separada.

---

Endpoint

• Método: POST

URL del endpoint

https://api.xgateglobal.com/withdraw/allowed-ip/subaccount

---

Solicitud

Encabezados obligatorios

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

Cuerpo de la solicitud

Parámetro	Tipo	Validación	Descripción
ip	string	Obligatorio	La dirección IP (IPv4 o IPv6) de su servidor que tendrá permiso para disparar retiros en esta subcuenta.

Ejemplo de payload

{
    "ip": "8.8.8.8"
}

---

Respuestas

Éxito (200 OK)

La dirección IP se registró en la lista de permisos y ya puede solicitar retiros.

{
    "message": "Primer IP habilitado para solicitud de retiro registrado con éxito"
}

Errores comunes

Como se trata de una ruta de uso único, las validaciones de reglas de negocio suelen devolver un estado 400.

Estado	Mensaje	Motivo probable
400	Bad Request	• Esta funcionalidad no está disponible para su cuenta: esta ruta solo está disponible para registrar el primer IP de una subcuenta. La cuenta que realiza la solicitud no es una subcuenta válida para este flujo. • Esta funcionalidad solo permite habilitar el primer IP de retiro de su cuenta: cuando ya se ha registrado un primer IP. La subcuenta ya tiene un IP registrado y la ruta solo funciona cuando la lista está vacía.
401	Unauthorized	• Token inválido o caducado. • Encabezado inválido o no proporcionado. • IP de la solicitud no permitido.
500	Internal Server Error	Error interno del servidor. Contacte con soporte.

---

Cómo usar

Casos de uso comunes

1. Automatización de configuración (onboarding): Así como con los webhooks, inmediatamente después de crear la subcuenta vía API para un nuevo cliente, su sistema puede iniciar sesión en esa nueva subcuenta y registrar la IP fija de su servidor financiero. Esto garantiza que la subcuenta nazca lista y segura para procesar retiros automáticamente, sin necesidad de intervención manual de su equipo de soporte.

---

Integración

A continuación se muestra un ejemplo simple de cómo implementar esta llamada con Node.js. Recuerde usar las credenciales de la subcuenta para obtener el token de autorización.

Node.js

El ejemplo de integración utiliza la biblioteca Axios para realizar la solicitud HTTP.

Instalando Axios:

npm install axios

Ejemplo en JavaScript:

const axios = require("axios");

(async () => {
    // ATENCIÓN: use el correo electrónico y la contraseña de la SUBCUENTA para generar el token de esta acción
    const emailSubcuenta = "admin@subcuenta.com";
    const passwordSubcuenta = "••••••";

    try {
        const url_api = "https://api.xgateglobal.com";
        
        // 1. Obtener el token de autenticación de la subcuenta
        const login = await axios.post(`${url_api}/auth/token`, { 
            email: emailSubcuenta, 
            password: passwordSubcuenta 
        });
        
        // 2. Configurar el primer IP permitido para retiro
        const ipData = {
            ip: "8.8.8.8"
        };

        const { data } = await axios.post(`${url_api}/withdraw/allowed-ip/subaccount`, ipData, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`,
                "Content-Type": "application/json"
            }
        });
        
        console.log("Respuesta:", data); 
        // Esperado: { message: 'Primer IP habilitado para solicitud de retiro registrado con éxito' }

    } catch (error) {
        console.error("Error al registrar IP:", error.response ? JSON.stringify(error.response.data, null, 2) : error.message);
    }
})();