WAPI – Manual

En este artículo aprenderá:

• Cómo funciona WAPI
  • Servicios compatibles
  • Restricciones de solicitudes
  • Solicitudes síncronas y asíncronas
  • Códigos de respuesta
• Cómo activar WAPI en el panel de administración de WEDOS Global
• Cómo integrar WAPI en su sistema
• Peticiones básicas para probar las funciones de WAPI
• Resolución de problemas habituales
• Preguntas frecuentes

---

WEDOS API (WAPI)

La API de WEDOS, abreviada WAPI, sirve para gestionar los servicios de WEDOS directamente desde su sistema mediante solicitudes y respuestas.

• La comunicación es o bien síncrono (una respuesta se procesa normalmente en cuestión de segundos tras recibir la solicitud) o asíncrono (algunas respuestas pueden tardar más tiempo; el proceso se supervisa mediante notificaciones).
• Los datos se transmiten mediante el HTTPS protocolo por el POST método en el parámetro de la solicitud; la codificación de datos es UTF-8.
• Entre los formatos admitidos se incluyen tanto XML y JSON.

Servicios compatibles

Actualmente WAPI admite los siguientes servicios de WEDOS Global:

• Miembros de WEDOS Global
• WEDOS Protection
• WEDOS DNS y NSSET

Además, puede acceder a los servicios de registrador de dominios de WEDOS:

• Dominios
• Contactos del dominio
• Cuenta de crédito

Restricciones de WAPI

Para evitar un uso indebido, WAPI aplica las siguientes restricciones:

• Una cuenta de usuario puede enviar un máximo de 1000 solicitudes por hora. Se aplica a todos los tipos de solicitudes. Al alcanzar este límite, WAPI rechaza las siguientes solicitudes hasta que expire el tiempo de espera.
• Una cuenta de usuario puede realizar un máximo de 100 consultas de disponibilidad de dominios por hora. Se aplica a las solicitudes domain-check, domain-create y domain-transfer-check.
• Solicitudes no válidas repetidas (fallo de autorización, acceso desde una dirección IP no autorizada, entrada incorrecta, parámetros faltantes o incorrectos, comandos desconocidos, comandos que resulten en cualquier error, o cualquier solicitud que exceda otras restricciones) hará que la dirección IP se bloquee durante 1 minuto por cada solicitud no válida que supere las 10. Con cada solicitud no válida adicional, el sistema aumenta el tiempo de bloqueo.

Solicitudes síncronas y asíncronas

La mayoría de las solicitudes ejecutadas mediante WAPI son síncronas: usted envía la solicitud y normalmente obtiene el resultado en unos segundos.

Algunas solicitudes son asíncronas: su procesamiento puede tardar mucho tiempo (incluso horas o días). En esos casos, WAPI no devuelve el resultado final, sino solo la información de que la solicitud se ha recibido. Después, el sistema le envía información sobre el progreso y el resultado final en forma de notificaciones.

Códigos de respuesta

Los códigos de respuesta indican el estado de una respuesta de WAPI. Algunos códigos son específicos de cada solicitud y se encuentran en la documentación de WAPI correspondiente; la lista siguiente se aplica a todas las solicitudes.

• 1000 = OK
• 2000 = Error al analizar la solicitud
• 2001 = Solicitud no válida – falta un parámetro obligatorio: user
• 2002 = Solicitud no válida – falta un parámetro obligatorio: auth
• 2003 = Solicitud no válida – falta un parámetro obligatorio: command
• 2004 = Solicitud no válida – solo se permite un elemento data
• 2005 = Solicitud no válida – el parámetro clTRID es demasiado largo
• 2006 = Límite de solicitudes superado
• 2007 = Solicitud no válida – tamaño máximo de solicitud superado
• 2008 = Solicitud no válida – la solicitud es demasiado compleja
• 2009 = Solicitud no válida – la solicitud está vacía
• 2010 = Comando desconocido
• 2011 = Comando desactivado
• 2050 = Error de autenticación
• 2051 = Acceso no permitido desde esta dirección IP
• 2052 = Dirección IP bloqueada temporalmente por demasiadas solicitudes fallidas
• 2100 = Falta un parámetro obligatorio
• 2101 = Los parámetros no coinciden
• 2102 = Solicitud no válida – la codificación de los datos de entrada no coincide
• 4000 = Error interno
• 4001 = Excepción interna
• 5000 = Error fatal
• 5001 = Error interno de autenticación
• 5003 = Fuera de servicio

---

Activar WAPI

Antes de poder empezar a usar WAPI, debe activarlo. Siga estos pasos:

1. Inicie sesión en el Panel de administración de WEDOS Global ⧉.
2. En la barra izquierda, seleccione WAPI.
3. En el Configuración de WAPI formulario, introduzca lo siguiente y confirme con el Establecer botón:
   • IP permitidas: Una lista de direcciones IP separadas por comas (IPv4 e IPv6) desde las que su sistema se conecta a WAPI.
   • Modo de notificación: Un método para recibir notificaciones sobre el progreso de las solicitudes asíncronas.
   • Protocolo preferido: Esta configuración solo se aplica a las notificaciones del sistema. Las respuestas utilizan el mismo formato que las solicitudes.
4. En el Configuración de la contraseña formulario, introduzca la contraseña de WAPI (dos veces para confirmarla) y haga clic en el Establecer botón.

La configuración surtirá efecto en un plazo de 30 minutos.

---

Integre WAPI en su sistema

Para integrar WAPI en su sistema una vez activado, debe:

• Preparar un script para conectarse a la API
• Enviar una solicitud
• Recibir y procesar una respuesta
• Recibir y procesar una notificación

Conectarse a WAPI

Para conectar su sistema a WAPI necesitará:

• Su correo electrónico de inicio de sesión de WEDOS y su contraseña de WAPI
• La URL de WAPI (depende del formato):
  • XML:https://api.wedos.com/wapi/xml
  • JSON:https://api.wedos.com/wapi/json

WAPI utiliza una única cadena de autenticación, que es un hash SHA-1 de una cadena compuesta por el nombre de usuario, el hash SHA-1 de la contraseña de WAPI y la hora actual (00-23). La zona horaria es Europe/Prague (UTC+1 CET, o UTC+2 CET con ajuste de horario de verano). Vea el código siguiente para un ejemplo concreto.

La siguiente plantilla muestra la conexión a WAPI mediante un script PHP:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'your@login.tld'; 
$wpass = 'your-WAPI-password'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'request name',
  'data' => ['request data'],
  'clTRID' => 'request identifier',
  'test' => '1 (if you only want to test the request)'
  ]
];

$post = json_encode($input);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_TIMEOUT,60);
curl_setopt($ch,CURLOPT_POST,true);
curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . urlencode($post));
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
curl_close($ch);
?>

Solicitud WAPI

Una solicitud WAPI consta de los siguientes datos:

• test: Indicador de modo de prueba, opcional. Si incluye en la solicitud un elemento test con el valor 1, WAPI solo comprobará el comando, pero no realizará ningún cambio en el sistema.
• user: El inicio de sesión (correo electrónico) de su cuenta de cliente de WEDOS, obligatorio.
• auth: Cadena de autorización, obligatoria. Es el hash SHA-1 de una cadena formada por el nombre de usuario, el hash SHA-1 de la contraseña de WAPI y la hora actual (00-23). La zona horaria es Europe/Prague (UTC+1 CET, o UTC+2 CET con el ajuste de horario de verano). Vea el código siguiente para un ejemplo concreto.
• comando: La solicitud WAPI propiamente dicha. Obligatorio.
• clTRID: ID de la solicitud, opcional. Puede indicar en este elemento cualquier cadena como identificador que WAPI devolverá en la respuesta.
• datos: La parte de datos de la solicitud. Opcional.

A continuación se muestra una plantilla de solicitud JSON:

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "auth-string",
    "command": "request-name",
    "data":
    {
      request data
    }
    "clTRID": "request-id (optional)",
  }
}

Respuesta WAPI

La respuesta consta de los siguientes datos:

• código: El valor de retorno de la solicitud correspondiente. Encontrará más información sobre estos códigos en el Códigos de respuesta sección y la documentación del comando concreto.
• result: Descripción del código de retorno.
• timestamp: Hora de ejecución del comando en formato UNIX.
• clTRID: Identificador de la solicitud del cliente.
• svTRID: Identificador de la solicitud del servidor.
• comando: Solicitud WAPI.
• datos: Datos devueltos. Ninguno si la solicitud falla.
• test: Se incluye en las respuestas a solicitudes de prueba.

A continuación se muestra una plantilla de respuesta JSON:

{
  "response": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "request-name"
  }
}

Notificaciones

Las peticiones asíncronas no se pueden ejecutar de inmediato. Puede supervisar el progreso y el resultado de esas operaciones mediante notificaciones. Las peticiones síncronas no utilizan notificaciones.

Si WAPI no puede completar la operación de inmediato, devuelve Request pending (1001) en la respuesta. Una vez completada la operación (para acciones más complejas con varios pasos), crea una notificación similar a una respuesta clásica. Puede asociar la notificación con la solicitud correspondiente mediante los parámetros clTRID o svTRID.

Los datos de las notificaciones siempre están codificados en UTF-8.

Puede recibir notificaciones de las siguientes maneras (según la configuración):

• Uso de la cola POLL.
• Enviar a la dirección de correo indicada.
• Mediante el protocolo HTTP (o HTTPS) a la dirección URL que usted indique, utilizando el método POST en el parámetro de la solicitud. Se considera un éxito una respuesta HTTP con código de retorno 200. Si la entrega falla, el sistema intentará entregar la notificación de nuevo a intervalos de varios minutos.

A continuación se muestra una plantilla de notificación JSON:

{
  "notify": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "svTRID": "server request id",
    "command": "request-name",
    "ID": "numerical id"
  }
}

---

Peticiones básicas

Las peticiones básicas incluyen ping, ping-async, y comandos para trabajar con la cola POLL poll-req y poll-ack.

ping

El ping se usa para probar el funcionamiento de WAPI, por ejemplo, las credenciales de acceso, la dirección IP o el código.

Los valores de retorno son:

• 1000 – OK

Plantilla de solicitud JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "clTRID": "user request id"
  }
}

Plantilla de respuesta JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

ping-async

El ping-async prueba el funcionamiento de las notificaciones de WAPI.

Los valores de retorno son:

• 1000 – OK
• 1001 – Esperando la solicitud

Plantilla de solicitud JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping-async",
    "clTRID": "user request id"
  }
}

Plantilla de respuesta JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async"
  }
}

Plantilla de notificación JSON:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async",
    "id": "poll queue id",
    "data": {
      "round": "attempt number",
      "time": "time",
      "done": 1
    }
  }
}

poll-req y poll-ack

Puede recibir notificaciones de la cola POLL combinando poll-req y poll-ack comandos:

1. Utilice el poll-req comando para descargar la notificación disponible más antigua.
2. Con el poll-ack comando, marque la notificación como leída y ponga a disposición las más recientes hasta agotar la cola.

Los valores de retorno para poll-req son:

• 1000 – notificación recibida
• 1003 – no hay notificaciones sin leer en la cola
• 2150 – notificaciones de la cola poll desactivadas para esta cuenta

JSON poll-req plantilla de la solicitud:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-req",
    "clTRID": "user request id"
  }
}

JSON poll-req plantilla de respuesta (notificación disponible):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF time",
        "clTRID": "request user id",
        "svTRID": "request server id",
        "command": "request name",
        "id": "poll queue id"
      }
    }
  }
}

JSON poll-req plantilla de respuesta (cola de notificaciones vacía):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req"
  }
}

Incluya los siguientes parámetros en el poll-ack solicitud:

• id – ID de la notificación poll actual

Los valores de retorno para poll-ack son:

• 1002 – notificación marcada como leída
• 2151 – notificación no encontrada

JSON poll-ack solicitud:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-ack",
    "clTRID": "user request id",
    "data": {
      "id": “poll notification id”
    }
  }
}

JSON poll-ack respuesta:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-ack"
  }
}

---

Resolución de problemas habituales

Los problemas habituales con WAPI son:

• No autenticar las peticiones

---

FAQ