Cómo pedir paquetes con la API

¿Creas sitios web para tus clientes? Entonces puedes pedir su alojamiento web 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 pedir un paquete nuevo, renovar un paquete y restaurar un paquete. Cada llamada es un pedido para un paquete. ¿También quieres pedir nombres de dominio? Lee cómo pedir nombres de dominio 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:

• plans.order.create: pedir, renovar y restaurar paquetes.
• domains.view: consultar los ID de tus paquetes y de tus nombres de dominio.

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 pedir un paquete nuevo:

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

En el cuerpo envías como mínimo plan_name, por ejemplo starter. 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.

Pedir un paquete nuevo

POST https://backend.site.es/v2/plans/order

Puedes enviar estos campos:

• plan_name (obligatorio): el nombre del paquete en minúsculas, como starter o power.
• order_period: el número de años, de 1 a 5. Por defecto es 1.
• domain_name_ids: los ID de nombres de dominio que ya tienes con nosotros, para incluirlos en el paquete nuevo. Los encuentras con GET /v2/domain_names.
• external_domain_name_ids: los ID de nombres de dominio que están registrados en otro sitio, pero que has añadido a tu cuenta. Los encuentras con GET /v2/external_domain_names.
• expected_price: el precio en céntimos, sin IVA, que aceptas. ¿El precio es distinto? Entonces no realizamos el pedido.
• dry_run: true solo comprueba el pedido y calcula su precio.

Los nombres de dominio tienen que estar activos y no pueden estar ya en otro paquete. Además, cada paquete admite un número máximo de nombres de dominio. ¿Necesitas un nombre de dominio nuevo para el paquete? Pídelo primero y espera a que esté activo.

Renovar o restaurar un paquete

POST https://backend.site.es/v2/plans/91/renew
POST https://backend.site.es/v2/plans/91/restore

Aquí, 91 es el ID del paquete. Lo encuentras con GET /v2/plans. En el cuerpo puedes enviar order_period (en años), expected_price y dry_run.

• Renovar: para un paquete activo. Lee cómo funciona la renovación de un paquete.
• Restaurar: para un paquete que ha expirado o se ha cancelado, hasta 14 días después de que expirara.

¿Se está trasladando el paquete a otro usuario en este momento? Entonces no puedes renovarlo hasta que termine el traslado.

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/5926

Cada línea del pedido tiene un estado: unprocessed, processing, processed, 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.

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é. Por ejemplo: el paquete no admite tantos nombres de dominio, un nombre de dominio ya está en un paquete o el periodo de restauración ha terminado.
• ORDER_004: tu cuenta no puede pagar desde la cartera.
• ORDER_005: ya has usado esta Idempotency-Key para otro pedido.
• GENERAL_001: no existe ningún paquete con este nombre, o el ID del paquete no es tuyo.
• DOMAIN_NOT_FOUND: uno de los ID de nombre de dominio no es tuyo.

Conviene saberlo

• No hay entorno de pruebas. Cada pedido es real. Así que prueba primero con dry_run.

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