Cómo pedir nombres de dominio con la API

¿Gestionas muchos nombres de dominio? ¿O los vendes a tus propios clientes? Entonces puedes pedirlos a través de la API de Site.es. Tu script paga desde tu cartera y el pedido empieza al instante.

Con la API puedes registrar, transferir, renovar y restaurar nombres de dominio. Cada llamada es un pedido para un nombre de dominio. ¿Quieres pedir alojamiento web? Lee cómo pedir paquetes con la API. ¿Es la primera vez que usas nuestra API? Entonces lee primero cómo empezar a usar la API.

Qué necesitas

Una clave API. Créala en tu panel de control, en Ajustes, en la pestaña Claves API. Marca solo los permisos que necesitas, en Endpoints de API:

• domains.order.create: pedir nombres de dominio (registrar, transferir, renovar y restaurar).
• domains.view: consultar los ID de tus nombres de dominio y el precio de un nombre de dominio premium.
• contacts.required_info: solo si envías datos adicionales del titular del dominio con un pedido.

Dinero en tu cartera. Los pedidos a través de la API siempre se pagan desde tu cartera online. El saldo tiene que cubrir todo el pedido, IVA incluido.

Los pedidos solo funcionan con una clave API. En el navegador, simplemente usas el carrito.

Cómo funciona un pedido

Envías una solicitud POST a la API. Pon tu clave API en la cabecera X-API-Key y los datos del pedido en formato JSON en el cuerpo. Por ejemplo, para registrar un nombre de dominio:

POST https://backend.site.es/v2/domain_names/register
X-API-Key: your API key
Content-Type: application/json

En el cuerpo envías como mínimo domain_name, por ejemplo example.nl. Después ocurre esto:

• El mismo precio. Pagas lo mismo que si haces el pedido en nuestra web.
• Si algo no está bien, no se cobra nada. Recibes un código de error que dice por qué.
• Pruébalo primero. Envía dry_run: true. La respuesta muestra el precio, el IVA y si el saldo de tu cartera es suficiente. No se pide ni se cobra nada.
• Iniciamos el pedido en un minuto, más o menos. A partir de ahí, sigue el mismo camino que cualquier otro pedido, con los mismos correos.
• Aparece en tu factura mensual, marcado como «Via API». Eso también ocurre cuando la facturación mensual está desactivada.

La documentación de la API enumera todos los campos y da ejemplos de cada solicitud y de cada respuesta.

Registrar o transferir un nombre de dominio

POST https://backend.site.es/v2/domain_names/register
POST https://backend.site.es/v2/domain_names/transfer

Puedes enviar estos campos:

• domain_name (obligatorio): el nombre de dominio completo, como example.nl.
• auth_key (solo transferencias): la clave de transferencia de tu proveedor actual. Lee cómo solicitar la clave de transferencia.
• order_period: de 1 a 5 periodos. Por defecto es 1. Un periodo es el plazo de registro más corto de la extensión, normalmente 1 año.
• contact_id: el contacto que pasa a ser el titular del dominio. Si no lo envías, usamos tu contacto predeterminado.
• name_servers: una lista de 2 a 8 servidores DNS. Si no la envías, el nombre de dominio recibe tus servidores DNS por defecto.
• privacy_protection: true oculta al titular del dominio en el WHOIS, si la extensión lo permite.
• expected_price: el precio en céntimos, sin IVA, que aceptas. Lo necesitas para los nombres de dominio premium.
• dry_run: true solo comprueba el pedido y calcula su precio.

¿No sabes si el nombre de dominio sigue libre? Compruébalo primero. Para esto no necesitas una clave API:

GET https://backend.site.es/v2/domain_names/check_availability?domain_name=example.nl

¿La respuesta dice premium: true? Entonces consulta su precio con GET /v2/domain_names/premium_quote. Envía ese precio como expected_price con tu pedido.

La transferencia en sí puede tardar unos días. ¿Ha fallado? Entonces lee qué hacer si la transferencia de tu dominio ha fallado.

Renovar o restaurar un nombre de dominio

POST https://backend.site.es/v2/domain_names/6731/renew
POST https://backend.site.es/v2/domain_names/6731/restore

Aquí, 6731 es el ID del nombre de dominio. Lo encuentras con GET /v2/domain_names. En el cuerpo puedes enviar order_period, expected_price y dry_run.

• Renovar: para un nombre de dominio activo. Un nombre de dominio premium solo se puede renovar en el último año antes de que expire.
• Restaurar: para un nombre de dominio que ha expirado, siempre que siga en su periodo de restauración. Ese periodo varía según la extensión.

La respuesta

¿Se ha realizado el pedido? Entonces recibes su order_id, con order_status paid. También recibes los precios en céntimos: amount_excluding_vat_in_cents, vat_amount_in_cents y total_including_vat_in_cents. En payment, wallet_balance_in_cents muestra lo que queda en tu cartera.

Sigue el pedido con su ID:

GET https://backend.site.es/v2/orders/5925

Cada línea del pedido tiene un estado: unprocessed, processing, processed, awaiting_required_info, transfer_failed, failed o cancelled.

Nunca pagues dos veces

A veces la conexión se corta justo después de enviar un pedido. ¿Se ha realizado o no? Para ir sobre seguro, envía una cabecera Idempotency-Key con cada pedido. Es un código único de hasta 255 caracteres, como un UUID.

¿Vuelves a enviar el mismo pedido con la misma clave? Entonces recibes otra vez la primera respuesta, y nunca se te cobra dos veces. Si usas la clave para otro pedido, recibes el error ORDER_005.

¿El titular del dominio necesita datos adicionales?

Algunas extensiones, como .es e .it, piden datos adicionales del titular del dominio. Un número de identificación, por ejemplo. ¿El contacto todavía no está preparado para la extensión? Entonces el pedido se detiene con ORDER_003 y el motivo contact_required_info. No se cobra nada. La respuesta enumera en required_info los campos que todavía faltan.

Puedes enviar esos datos con el pedido, como required_info. O preparar antes el contacto. Lee cómo crear un contacto y prepararlo con la API.

Códigos de error

Con cualquier error, no se cobra nada. Estos son los más habituales:

• ORDER_001: el saldo de tu cartera es demasiado bajo. En top_up, la respuesta indica el importe que tienes que añadir y un enlace para recargar tu cartera.
• ORDER_002: el precio no coincide con tu expected_price. La respuesta incluye el precio actual.
• ORDER_003: este pedido no es posible. El campo reason dice por qué.
• ORDER_004: tu cuenta no puede pagar desde la cartera.
• ORDER_005: ya has usado esta Idempotency-Key para otro pedido.
• DOMAIN_NOT_AVAILABLE: el nombre de dominio está ocupado (registro), no está registrado (transferencia) o ya está con nosotros.
• REG_001: no hemos podido conectar con el registro de la extensión. Vuelve a intentarlo un poco más tarde.

Conviene saberlo

• No hay entorno de pruebas. Cada pedido es real. Así que prueba primero con dry_run.
• ¿Un registro está esperando datos del titular o ha fallado una transferencia? Entonces puedes cancelar esa línea con PATCH /v2/domain_name_orders/22455/cancel. Aquí, 22455 es el ID de la línea del pedido. Tu clave API necesita domains.order.cancel. Te devolvemos el dinero a tu cartera.

¿Necesitas ayuda? Contacta con nosotros por WhatsApp, Telegram o correo electrónico.