Guía rápida de la API

Crear una clave de API

En la consola en la nube, abre los ajustes de tu organización y elige Create an API Key en Manage API Keys. La consola muestra la clave una sola vez, al crearla, así que cópiala antes de cerrar el diálogo.

Todas las peticiones de la documentación la muestran como <api-key> en la cabecera Authorization: Bearer. Pon tu clave en su lugar y los valores que devuelve cada paso en lugar de los demás valores <...> y {serviceId}.

Elegir un plan y un centro de datos

Enumera los planes bare metal:

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/plans \
  --header 'Authorization: Bearer <api-key>'

La lista está paginada, con 25 planes por página salvo que pageSize solicite más, hasta 1000. Cada plan de data incluye su id y slug, su hardware en specs y dos campos que determinan el pedido:

• availability tiene una entrada por centro de datos, con su code (como ams1), su city y facility y la quantity disponible allí.
• pricing da la currency y, en rates, una entrada por ciclo de facturación en el que se vende el plan. El priceMillicents de una entrada es el precio de un periodo de ese ciclo y effectiveMonthlyMillicents el mismo precio por mes, ambos en milésimas de céntimo (Dinero).

Elige un plan y un centro de datos cuya quantity sea mayor que cero y conserva el slug del plan y el code del centro de datos. Para empezar por una ubicación, Listar regiones indica todos los centros de datos donde puedes contratar, con su code, ciudad e instalación.

Contratar el servidor

Crea un pedido del plan en ese centro de datos con el ciclo de facturación que vayas a pagar:

curl --request POST \
  --url https://api.serverside.com/v1/billing/orders \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cycle": "MONTHLY",
  "items": [
    {
      "type": "BAREMETAL",
      "plan": "<plan-slug>",
      "datacenter": "<datacenter-code>",
      "name": "<hostname>"
    }
  ]
}
'

plan y datacenter aceptan ID además del slug y el código. name es opcional, de 2 a 64 caracteres, y el despliegue lo convierte en el nombre de host del sistema operativo, así que un nombre como web1.example.com establece ambos.

cycle es obligatorio y acepta HOURLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY o ANNUALLY. Lo que sucede después depende del que elijas:

• Un periodo (MONTHLY a ANNUALLY): el pedido se guarda con una factura y aún no se aprovisiona nada. La respuesta es 201; conserva data.order.id y data.invoiceId para el paso siguiente.
• HOURLY: el servidor se aprovisiona dentro de la petición y no se emite factura. data.provisionedItems[0].provisionedId es el ID del servidor, el {serviceId} de los dos últimos pasos, así que pasa a elegir un sistema operativo. La facturación por hora necesita que billing.isUsageBased sea true en Obtener derechos, algo que una organización nueva no tiene; por ahora se concede previa solicitud mediante soporte en la consola, y sin ello el pedido responde 422 USAGE_BILLING_DISABLED.

El servidor recibe un IPv4 /30 y un IPv6 /120, ambos incluidos en el precio del plan; IPv6 se omite si el centro de datos no tiene espacio IPv6 disponible. Facturación explica cómo usar un prefijo IPv4 mayor y omitir una familia.

La cabecera Idempotency-Key es opcional. Genera un valor por pedido y vuelve a enviar el mismo si reintentas tras agotar el tiempo de espera, para que el reintento devuelva el primer pedido en lugar de crear otro; Idempotencia contiene las reglas.

Pagar la factura

Un servidor contratado por un periodo se aprovisiona cuando su factura se paga íntegramente y nada paga automáticamente la factura de un pedido. Un pedido que queda sin pagar se cancela en un plazo de 24 horas. Desde un script, Pagar factura la liquida con crédito de cuenta:

curl --request POST \
  --url https://api.serverside.com/v1/billing/invoices/{invoiceId}/pay \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "providerType": "ACCOUNT_CREDIT"
}
'

El pago toma el saldo de crédito disponible hasta el importe pendiente y muestra status SUCCEEDED. Un saldo insuficiente deja parte de la factura pendiente y el servidor espera el resto; obtén la factura y lee amountDue, en céntimos. Sin crédito, la llamada responde 422 PAYMENT_FAILED.

providerType STRIPE con el ID de una tarjeta guardada en methodId carga el pago a esa tarjeta. La API solo enumera las tarjetas guardadas en los ajustes de la organización, que requieren una sesión de consola, así que una clave no tiene una llamada para obtener ese ID. Sin methodId, STRIPE inicia un pago que debe confirmar un navegador (Facturación).

Después obtén el pedido aproximadamente cada 20 segundos hasta que su elemento en items muestre status COMPLETED:

curl --request GET \
  --url https://api.serverside.com/v1/billing/orders/{orderId} \
  --header 'Authorization: Bearer <api-key>'

El propio pedido muestra UNPAID hasta que se ha ejecutado el aprovisionamiento y después COMPLETE. El provisionedId del elemento es el ID del nuevo servidor, el {serviceId} que requieren todas las llamadas posteriores. Un elemento que muestre FAILED no se recuperará solo: el pedido también muestra FAILED y soporte necesita el id del pedido para completarlo.

Elegir un sistema operativo

Enumera las imágenes compatibles con el nuevo servidor:

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/deploy/images \
  --header 'Authorization: Bearer <api-key>'

Cada imagen tiene un id, un name, un slug como ubuntu-24.04, una platform (LINUX o WINDOWS), el defaultUser que crea y los raidVariants que admite.

Desplegarlo

Inicia el despliegue. image acepta el id de la imagen o su slug y sshKeyIds acepta ID de Listar claves SSH.

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/deploy \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": "<image-id>",
  "sshKeyIds": [
    "<ssh-key-id>"
  ],
  "raidVariant": "RAID1"
}
'

Un despliegue Linux necesita una forma de iniciar sesión: una clave SSH, una password o tu propio cloudInit. Uno de Windows necesita una password. username toma por defecto el defaultUser de la imagen; en Linux, username y password se aplican junto con las claves y un usuario indicado ahí recibe sudo sin contraseña. raidVariant toma por defecto NONE y cualquier otro valor debe estar entre los que enumera la imagen.

La respuesta es 201 con la operación en curso, de type DEPLOYMENT. Obtén el estado del servicio para seguirla:

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/status \
  --header 'Authorization: Bearer <api-key>'

operation contiene el despliegue en curso con su progress y lastProgressMessage, y lastOperation.state muestra COMPLETED o FAILED cuando termina. Un despliegue solo comienza si el state del servicio es ACTIVE; si sigue ejecutándose otra operación, la API responde 409 y el código OPERATION_IN_PROGRESS. Cuando muestre COMPLETED, inicia sesión en la primaryIpv4 que devuelve Obtener servicio bare metal.