WAPI - Manual

En este artículo aprenderá:

WEDOS API (WAPI)

La API de WEDOS, abreviada WAPI, se utiliza para gestionar los servicios de WEDOS directamente desde su sistema a través de peticiones y respuestas.

  • La comunicación puede ser síncrona (la respuesta se procesa en cuestión de segundos tras la recepción de la solicitud) o asíncrona (algunas respuestas pueden tardar más tiempo; el proceso se controla mediante notificaciones).
  • Los datos se pasan a través del protocolo HTTPS mediante el método POST en el parámetro de solicitud; la codificación de los datos es UTF-8.
  • Los formatos admitidos son XML y JSON.

El uso de WAPI requiere una cuenta de crédito activa de la que el sistema deduce los pagos.

Servicios de apoyo

WAPI soporta actualmente los siguientes servicios WEDOS Global:

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

Restricciones WAPI

Para proteger contra el uso indebido, WAPI aplica las siguientes restricciones:

  • Una cuenta de usuario puede enviar un máximo de 1000 solicitudes por hora. Esto se aplica a todos los tipos de solicitudes. Cuando se alcanza este límite, WAPI rechaza más solicitudes hasta que expira el tiempo de espera.
  • Una cuenta de usuario puede realizar un máximo de 100 solicitudes de disponibilidad de dominio por hora. Esto se aplica a las solicitudes de comprobación de dominio, creación de dominio y comprobación de transferencia de dominio.
  • Las solicitudes invá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 dan lugar a cualquier error o cualquier solicitud que supere otras restricciones) provocarán el bloqueo de la dirección IP 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 peticiones que se ejecutan a través de WAPI son síncronas: envías la petición y normalmente obtienes el resultado en unos segundos.

Algunas peticiones son asíncronas: procesarlas puede llevar mucho tiempo (incluso horas o días). En estos casos, WAPI no devuelve el resultado final, sino sólo información sobre la recepción de la solicitud. El sistema le envía información sobre el progreso y el resultado final en forma de notificaciones.

Activar WAPI

Antes de activar WAPI, asegúrese de que dispone de una cuenta de crédito WEDOS activa.

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

  1. Inicie sesión en el panel de administración de WEDOS Global ⧉.
  2. En la barra de la izquierda, seleccione WAPI.
  3. En el Configuración WAPI introduzca lo siguiente y confirme con la tecla Establecer botón:
    • IPs permitidas: Una lista separada por comas de direcciones IP (tanto IPv4 como IPv6) desde las que su sistema se conecta a WAPI.
    • Método de notificación: Método para recibir notificaciones sobre el progreso de las peticiones asíncronas.
    • Protocolo preferido: Este ajuste sólo se aplica a las notificaciones del sistema. Las respuestas utilizan el mismo formato que las solicitudes.
  4. En el formulario Configuración de contraseña, introduzca la contraseña WAPI (dos veces para confirmarla) y pulse el botón Establecer.
Activar WAPI en el panel de administración global de WEDOS
Configuración de direcciones IP permitidas y una contraseña para WAPI en WEDOS Global
Configuración de direcciones IP permitidas y una contraseña para WAPI en WEDOS Global

Los ajustes surtirán efecto en 30 minutos.

Integre WAPI en su sistema

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

El siguiente texto asume que los datos se pasan en formato JSON. Para XML, actualice su código en consecuencia.

Conectarse a WAPI

Para conectar tu sistema a WAPI, necesitarás:

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

WAPI toma una única cadena de autenticación, que es un hash sha1 de una cadena compuesta por el nombre de usuario, el hash sha1 de la contraseña WAPI y la hora actual (00-23). La zona horaria es Europa/Praga (UTC+1 CET, o UTC+2 CET con ajuste DST). Consulte el código siguiente para ver un ejemplo concreto.

Utilice la contraseña WAPI para comunicarse con WAPI. La contraseña de la cuenta de cliente no funciona.

La siguiente plantilla demuestra la conexión a WAPI utilizando 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=' . $post);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>

Solicitud WAPI

Una solicitud WAPI consta de los siguientes datos:

  • test: Indicador de modo de prueba, opcional. Si incluye un elemento de prueba con valor 1 en la solicitud, WAPI sólo comprobará el comando, pero no realizará ningún cambio en el sistema.
  • usuario: El nombre de usuario de su cuenta de cliente WEDOS (correo electrónico), obligatorio.
  • auth: Cadena de autorización, obligatoria. Se trata de un hash sha1 de una cadena compuesta por el nombre de usuario, el hash sha1 de la contraseña WAPI y la hora actual (00-23). La zona horaria es Europa/Praga (UTC+1 CET, o UTC+2 CET con ajuste DST). Consulte el código siguiente para ver un ejemplo concreto.
  • comando: La solicitud WAPI real. Obligatorio.
  • clTRID: Identificador de la petición, opcional. Puede poner cualquier cadena en este elemento 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 para la petición dada. Puede encontrar más información sobre estos códigos en la documentación específica del comando.
  • resultado: 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 petición del servidor.
  • comando: Petición WAPI.
  • datos: Datos de retorno. Ninguno si la petición falla.
  • prueba: Incluido con las respuestas para las 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 pueden realizarse inmediatamente. Puede supervisar el progreso y el resultado de dichas operaciones mediante notificaciones. Las solicitudes síncronas no utilizan notificaciones.

Si WAPI no puede completar la operación inmediatamente, devuelve Request pending (1001) como respuesta. Una vez completada la operación (para acciones más complicadas de pasos individuales), crea una notificación similar a una respuesta clásica. Puede hacer coincidir la notificación con la solicitud correspondiente utilizando los parámetros clTRID o svTRID.

Los datos de notificación siempre se codifican en UTF-8.

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

  • Utilizar la cola POLL.
  • Enviar a la dirección de correo electrónico especificada.
  • A través del protocolo HTTP (o HTTPS) a la dirección URL especificada por usted utilizando el método POST en el parámetro de solicitud. Una respuesta HTTP con un código de retorno de 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"
  }
}

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

La solicitud ping se utiliza para probar la funcionalidad WAPI - por ejemplo, credenciales de acceso, dirección IP o 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 la funcionalidad de las notificaciones WAPI.

Los valores de retorno son:

  • 1000 - OK
  • 1001 - En espera de solicitud

Plantilla de solicitud JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "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"
  }
}

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 los comandos poll-req y poll-ack:

  1. Utilice el comando poll-req para descargar la notificación más antigua disponible.
  2. Con el comando poll-ack, marca la notificación como leída y pone a disposición otras nuevas hasta que se agote la cola.

Los valores de retorno de poll-req son:

  • 1000 - notificación recibida
  • 1003 - ninguna notificación no leída en cola
  • 2150 - notificaciones de cola de sondeo desactivadas 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 notificación 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 de poll-ack:

  • id - ID de la notificación de sondeo 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"
  }
}

Solución de problemas comunes

Los problemas más comunes con WAPI incluyen:

Fallo en la autenticación de la solicitud

Problema: No recibo respuestas ni a mis solicitudes.

Causa: Suele tratarse de un error de autenticación, sobre todo si persiste.

Solución: Compruebe el estado de WEDOS ⧉ para las interrupciones.

Asegúrese de que:

  • La dirección IP de su sistema figura entre las IP permitidas en el panel de administración (como se describe en el capítulo Activar WAPI ).
  • Su script utiliza la contraseña WAPI, y no su contraseña de acceso a WEDOS.
  • Tu script utiliza la zona horaria de Europa/Praga y la hora está sincronizada correctamente.

PREGUNTAS FRECUENTES

¿Puedo utilizar también otras solicitudes WAPI al activar WAPI a través de WEDOS Global?

Sí, independientemente del panel de administración que haya utilizado para activar WAPI, puede utilizar todas las solicitudes de su sistema.

¿Te ha resultado útil?

Gracias por sus comentarios.
Selectores genéricos
Sólo coincidencias exactas
Buscar en el título
Buscar en el contenido
Selectores de tipo de entrada
Artículo TOC
Examinar categorías