Copy page

Conceptos de Zaroz Cloud v2

Suscripciones y facturación

Presupuesta y después compra

POST /checkout/quote calcula el precio de una compra y no escribe nada. Usa la misma resolución, ubicación, descuento e impuestos que POST /checkout, así que el total que presupuestas es el que se te factura. Un código se valida pero no se canjea.

curl

Code
# same body as /checkout, minus name and slug: writes nothing
curl -sS -X POST "$ZAROZ_API/checkout/quote" -H "$AUTH" -H "Content-Type: application/json" -d '{
  "product_id": "<product uuid>", "plan_id": 3, "region_id": "<region uuid>",
  "organization_id": "<org uuid>", "discount_code": "WELCOME10"
}'
# then, to buy: the same body plus "name" and "slug" on POST /checkout

TypeScript

Code
const body = { product_id: PRODUCT, plan_id: 3, region_id: REGION, organization_id: ORG, discount_code: "WELCOME10" };
const quote = await call("POST", "/checkout/quote", body);
console.log(quote.body.total_cents, quote.body.due_now_cents, quote.body.cadence_label);
const bought = await call("POST", "/checkout", { ...body, name: "My API", slug: "my-api" });
console.log(bought.body.subscription.id, bought.body.invoice.id);

Python

Code
body = {"product_id": PRODUCT, "plan_id": 3, "region_id": REGION, "organization_id": ORG, "discount_code": "WELCOME10"}
_, quote = call("POST", "/checkout/quote", body)
print(quote["total_cents"], quote["due_now_cents"], quote["cadence_label"])
_, bought = call("POST", "/checkout", {**body, "name": "My API", "slug": "my-api"})
print(bought["subscription"]["id"], bought["invoice"]["id"])

El presupuesto responde lines, subtotal_cents, tax, total_cents (por ciclo de facturación), due_now_cents (lo que pagas hoy, que no siempre es el total: una cuota de alta, un periodo prepagado o un primer periodo prorrateado lo cambian), cadence_label y los resources que se valoraron. Si indicas puertos públicos, metered_estimate muestra lo que puede costar mantenerlos.

POST /checkout crea una suscripción pendiente y la factura de alta. Paga la factura por las rutas de pago de facturas existentes; cuando se paga, el servicio se aprovisiona. Necesitas Owner o Admin en la organización indicada por organization_id; sin ella la compra se factura a tu organización personal.

Renovación y cancelación

Una suscripción se renueva al final de cada periodo. Hay dos cosas distintas que puedes pedir:

• PUT /subscriptions/{id}/renewal {auto_renew}: parar o reanudar la próxima factura. El servicio sigue en marcha.
• PUT /subscriptions/{id}/cancellation: programar el fin del propio servicio.

curl

Code
curl -sS -X PUT "$ZAROZ_API/subscriptions/<subscription uuid>/renewal" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"auto_renew": false}'   # stops the NEXT invoice, not the service

TypeScript

Code
await call("PUT", `/subscriptions/${SUB}/renewal`, { auto_renew: false });   // not a cancellation

Python

Code
call("PUT", f"/subscriptions/{SUB}/renewal", {"auto_renew": False})   # not a cancellation

Cambiar el tamaño es un presupuesto y una confirmación: POST /subscriptions/{id}/resize/quote y después POST /subscriptions/{id}/resize. Un cambio de plan tiene la misma forma en /resize/plan-change.

Cómo se facturan las unidades

El plan de un Workload incluye un número de unidades (included_units). Las que superan ese número son unidades extra.

• Una unidad extra se factura por hora mientras tiene un pod, más un cargo mínimo por arranque de 5 minutos. El vaivén nunca es gratis.
• Qué unidades están "incluidas" se decide al crear un pod, según su número de ranura. Una unidad controlada por código que se detiene libera su ranura, así que las ranuras incluidas son siempre las primeras que corren.
• Una unidad detenida no cuesta nada. Una unidad caliente se factura como cualquier unidad en marcha, porque ocupa CPU y memoria.
• Los puertos públicos se facturan por las horas que se mantienen.
• Eventos, webhooks y principales de servicio están incluidos sin coste.

Controlas el peor caso con límites: el max_units de la política, el límite de unidades de tu organización (50 por defecto), la tasa de arranques (600 por hora por defecto) y un spend_cap_cents mensual para las unidades extra. POST .../units/policy/quote muestra el peor caso de una política antes de guardarla. Cuando se alcanza un tope o un límite, las llamadas que arrancarían un pod se rechazan con un código estable (mira Errores de la API de Units); un límite nunca detiene unidades en marcha.

Un ejemplo con números:

Montaje	Cálculo	Resultado
1 unidad incluida, 3 unidades calientes todo el mes	3 unidades extra × 720 h × la tarifa horaria extra	el máximo que puede costar el buffer caliente en un mes de 30 días
un trabajo que dura 40 s, 100 trabajos al día	100 arranques × el mínimo de 5 minutos	se facturan 500 minutos de unidad, no 67
una parcela detenida entre visitas	0 mientras está detenida	pagas solo mientras hay jugadores

La tarifa horaria es el precio del plan; léela del presupuesto.