WAPI – Manual

En este artículo aprenderá:

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

---

API de WEDOS (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 síncrona (la respuesta se procesa normalmente a los pocos segundos de recibir la solicitud), o bien asíncrona (algunas respuestas pueden tardar más tiempo; el proceso se supervisa mediante notificaciones).
• Los datos se transmiten mediante el protocolo HTTPS con el método POST en el parámetro request; la codificación de los datos es UTF-8.
• Los formatos admitidos son 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 del registrador de dominios WEDOS:

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

Restricciones de WAPI

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

• Una cuenta de usuario puede enviar como máximo 1000 solicitudes por hora. Esto se aplica a todos los tipos de solicitudes. Cuando se alcanza este límite, WAPI rechaza las siguientes solicitudes hasta que expire el límite de tiempo.
• Una cuenta de usuario puede realizar como máximo 100 solicitudes de disponibilidad de dominio por hora. Esto se aplica a las solicitudes domain-check, domain-create y domain-transfer-check.
• Las solicitudes no válidas repetidas (fallo de autorización, acceso desde una dirección IP no autorizada, entrada incorrecta, parámetros ausentes o incorrectos, comandos desconocidos, comandos que terminan en error o cualquier solicitud que supere otras restricciones) provocan el bloqueo de la dirección IP durante 1 minuto por cada solicitud no válida que exceda de 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 tal caso, WAPI no devuelve el resultado final, sino solo la información sobre la recepción de la solicitud. 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 propios de una solicitud concreta y figuran 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 el parámetro obligatorio: user
• 2002 = Solicitud no válida – falta el parámetro obligatorio: auth
• 2003 = Solicitud no válida – falta el 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 la 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 deshabilitado
• 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 la administración de WEDOS Global ⧉.
2. En la barra izquierda, seleccione WAPI.
3. En el formulario Configuración de WAPI , introduzca los siguientes datos y confirme con el botón Definir :
   • Direcciones IP permitidas: Una lista de direcciones IP separadas por comas (tanto IPv4 como IPv6, admite la notación CIDR) desde las que su sistema se conecta a WAPI.
   • Modo de notificación: Un método de recepción de notificaciones sobre el progreso de las solicitudes asíncronas.
   • Protocolo preferido: Este ajuste se aplica únicamente a las notificaciones del sistema. Las respuestas utilizan el mismo formato que las solicitudes.
4. En el formulario Configuración de la contraseña , introduzca la contraseña de WAPI (dos veces para confirmarla) y haga clic en el botón Definir .

Los ajustes surtirán efecto en un plazo de 30 minutos.

---

Integrar 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 acceso a WEDOS y la contraseña de WAPI
• La URL de WAPI (según el 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 el ajuste del horario de verano). Consulte el código a continuación para ver 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 de WAPI

Una solicitud de WAPI se compone de los siguientes datos:

• prueba: Indicador del 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: Su identificador de acceso a la cuenta de cliente de WEDOS (correo electrónico), obligatorio.
• auth: Cadena de autorización, obligatoria. 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 el horario de verano). Vea el ejemplo de código más abajo.
• comando: La propia solicitud de WAPI. Obligatorio.
• clTRID: Identificador de la solicitud, opcional. En este elemento puede indicar cualquier cadena como identificador que WAPI devolverá en la respuesta.
• data: La parte de datos de la solicitud. Opcional.

Esta es una plantilla de solicitud JSON:

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

Respuesta de WAPI

La respuesta se compone de los siguientes datos:

• code: El valor de retorno de la solicitud dada. Encontrará más información sobre estos códigos en la sección Códigos de respuesta y en 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 de WAPI.
• data: Datos devueltos. Ninguno si la solicitud falla.
• prueba: Se incluye en las respuestas a las solicitudes de prueba.

Esta es 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 solicitudes asíncronas no se pueden ejecutar de inmediato. Puede supervisar el progreso y el resultado de estas operaciones mediante notificaciones. Las solicitudes 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 (en el caso de acciones más complejas compuestas por 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 las notificaciones de las siguientes maneras (según la configuración):

• Mediante la cola POLL.
• Envío a una dirección de correo electrónico especificada.
• A través del protocolo HTTP (o HTTPS) a la dirección URL indicada por usted mediante el método POST en el parámetro request. Una respuesta HTTP con el código de retorno 200 se considera un éxito. 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"
  }
}

---

Solicitudes básicas

Entre las solicitudes básicas se incluyen ping, ping-async, así como los comandos para trabajar con la cola POLL poll-req y poll-ack.

ping

La solicitud ping sirve para comprobar 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

La solicitud ping-async comprueba 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 :

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

Los valores de retorno de poll-req son:

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

JSON poll-req plantilla de 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 la solicitud poll-ack :

• id – identificador actual de la notificación poll

Los valores de retorno de poll-ack son:

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

JSON poll-ack :

{
  "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

Entre los problemas habituales con WAPI se incluyen:

• El fallo de autenticación de las solicitudes

---

FAQ