Conceptos de facturación de la API

Ciclos de facturación

Un servicio se factura con uno de cinco ciclos. MONTHLY, QUARTERLY, SEMI_ANNUALLY y ANNUALLY son periodos de 1, 3, 6 y 12 meses, pagados por adelantado: cada nuevo periodo se factura anticipadamente y vence en la fecha nextRenewal de la suscripción.

Los cargos por uso se acumulan durante el mes natural UTC y aparecen en una factura el día 1 del mes siguiente: el uso de octubre se factura el 1 de noviembre. Esa factura incluye los cargos de servicio HOURLY y los excesos de tráfico aplicables, y vence siete días después de emitirse. El cargo base de un periodo prepagado se factura por adelantado; sus excesos de tráfico aplicables se facturan después.

Cada plan indica los precios de sus ciclos en pricing.rates, un objeto cuyas claves son los ciclos. Cada tarifa tiene tres campos:

Unidades monetarias

Todos los importes son números enteros en la divisa de su registro o del registro que los contiene, y el nombre del campo indica la escala. Un nombre terminado en Millicents cuenta milésimas de céntimo, así que 150000 es 1,50. Los demás campos monetarios cuentan céntimos: 12999 es 129,99.

Las milésimas de céntimo permiten conservar la fracción de céntimo de una tarifa por hora, mientras que un precio por periodo siempre es un número entero de céntimos. Un pedido solo contiene su precio. Los impuestos, descuentos e importe pendiente aparecen en su factura.

La divisa es un código ISO 4217 enviado como currency en pricing del plan, pedidos, suscripciones y sus elementos, facturas y sus transacciones, el saldo de crédito y sus entradas, y el resumen de uso. Los planes tienen precios en dólares estadounidenses que se convierten a la divisa de facturación de la organización, que no puede cambiar una vez que la organización tiene un pedido, factura, suscripción o entrada de crédito.

Contratar servicios

La forma de comprar un servidor o bloque de IP nuevo depende de su ciclo de facturación:

Crear pedido requiere cycle y acepta los cinco valores. Las dos llamadas de un solo elemento son atajos para un pedido por hora de un elemento: aceptan sus campos en el nivel superior del cuerpo, sin type ni cycle, crean el mismo pedido y ejecutan las mismas comprobaciones. Las tres aceptan Idempotency-Key (Idempotencia).

La facturación por hora necesita un derecho de uso que una organización nueva no tiene. Por ahora se concede previa solicitud mediante soporte en la consola. Obtener derechos lo muestra como billing.isUsageBased y un pedido por hora o atajo enviado sin él responde 422 USAGE_BILLING_DISABLED.

Elementos del pedido

items contiene una entrada por servidor o bloque de IP, ya que un elemento no tiene campo de cantidad. Cada entrada indica su clase en type, BAREMETAL o IP_BLOCK exactamente con esas mayúsculas; cualquier otra cosa, o la ausencia de type, se rechaza con 400 VALIDATION_ERROR. Todos los elementos indican un plan y un centro de datos:

• plan es el id del plan. Un plan bare metal también acepta su slug, que nunca cambia; un plan de bloque de IP no.
• datacenter es el id del centro de datos o su code, como ams1.

Listar planes bare metal y Listar planes de bloques de IP devuelven el id de cada plan, el slug de un plan bare metal y una entrada availability por centro de datos con su id, su code y la quantity disponible.

Un elemento BAREMETAL también acepta las direcciones y ajustes de arranque del nuevo servidor:

Con bootMode PXE y un script, el servidor arranca una vez con ese script tras su aprovisionamiento (Scripts iPXE personalizados). El sistema operativo no forma parte del pedido: se elige al desplegar el servidor.

El /30 y el /120 están incluidos en el precio del plan. Un bloque IPv4 mayor, con longitud de 24 a 29, añade una línea IPv4 /<length> a las lines del elemento de pedido y a la factura, cuyo precio es la diferencia entre el plan de bloque de IP IPv4 de esa longitud y el de /30.

El IPv6 contratado con IPv4 se omite si el centro de datos no tiene espacio IPv6 y el servidor arranca sin él; si se contrata solo, hace que falle el elemento. Un servidor con ambas longitudes null no recibe red ni dirección y no puede desplegarse hasta que conectes tu propia red y le asignes una IPv4 principal (Redes). En caso contrario, sus prefijos están en una red de acceso a Internet creada para ese servidor y se facturan en su propia suscripción, por lo que un elemento BAREMETAL no tiene campo de red.

Un elemento IP_BLOCK acepta networkId, la red a la que se añade el bloque. Una red inexistente o de otra organización responde 404 ENTITY_NOT_FOUND. Listar redes virtuales del servicio da las redes de un servidor con sus ID, así que un bloque para la red de un servidor nuevo se contrata una vez que existe ese servidor.

promoCode es opcional. Su descuento se aplica a la primera factura de un pedido por periodo; las renovaciones y los pedidos por hora no tienen descuento y un código vacío cuenta como ninguno.

El pedido se comprueba al crearlo y un rechazo es 422. OFFERING_NOT_AVAILABLE llega como el propio código. Los demás rechazos son detalles en VALIDATION_FAILED sobre el campo indicado, que en los atajos no lleva el prefijo items[<i>].:

Pagar un pedido por periodo

La respuesta de un pedido por periodo contiene data.order, cuyo status es UNPAID, y data.invoiceId. La factura vence el día de su emisión. Factura cada servidor al priceMillicents del plan para el ciclo, cualquier prefijo IPv4 con coste en una línea propia, los impuestos de la dirección de facturación de la organización y el descuento promocional. Una organización sin dirección de facturación recibe 422 BILLING_ADDRESS_REQUIRED después de guardar el pedido; establece la dirección en la consola y envía la misma petición con la misma Idempotency-Key para emitir la factura del pedido guardado.

Nada paga esta factura por ti. Las facturas de renovación y uso se cobran en su fecha de vencimiento, primero del crédito de cuenta y después de la tarjeta predeterminada, pero la primera factura de un pedido espera hasta que un pago la cubra. Desde un script, Pagar factura con providerType ACCOUNT_CREDIT la paga con el crédito de la organización, como en la Guía rápida.

Un pedido que queda sin pagar se cancela en un plazo de 24 horas. Hasta entonces no reserva un servidor: se comprueban las existencias al crear el pedido y de nuevo al aprovisionar el pedido pagado.

Cuando la factura muestra PAID, el aprovisionamiento se ejecuta en segundo plano. Cada elemento recibe su propia suscripción con el ciclo del pedido y Obtener pedido muestra el resultado: el elemento pasa de PENDING a COMPLETED, su provisionedId contiene el ID del nuevo servidor (el del bloque nuevo en un elemento IP_BLOCK) y el pedido pasa de UNPAID a COMPLETE. Listar facturas da el orderId de cada factura de pedido.

Un elemento que no puede aprovisionarse muestra FAILED; por ejemplo, un servidor cuyo plan se agota entre el pedido y el pago. El pedido muestra FAILED cuando termina el aprovisionamiento con al menos un elemento fallido, aunque los demás se hayan completado. El pedido no indica por qué falló un elemento, nada lo reintenta automáticamente, una factura pagada sigue pagada y nada se reembolsa automáticamente, así que contacta con soporte e indica el id del pedido.

Peticiones por hora

El id de la respuesta de un atajo es el ID del nuevo servidor o bloque. Crear pedido con HOURLY responde con invoiceId null, las subscriptions abiertas y provisionedItems: una entrada por elemento con su orderItemId, su provisionedId e isProvisioned, además de un errorMessage si isProvisioned es false.

Una petición en la que no se pudo aprovisionar nada responde 409 PROVISIONING_FAILED y el pedido creado se conserva con status FAILED. Con varios elementos, un pedido puede tener éxito parcial; la respuesta es entonces 201 y sus provisionedItems muestran cuáles arrancaron. Volver a enviar la petición con la misma Idempotency-Key no crea otro pedido. Responde 200, con isReplayed true en Crear pedido, devuelve lo aprovisionado por la primera petición y reintenta los elementos fallidos.

Suscripciones

Cada servicio facturado pertenece a una suscripción que conserva su cycle, status, lastRenewal y nextRenewal, un terminatedAt cuando termina y los items que factura, incluidos los finalizados. La suscripción de un servidor contiene el servidor y un elemento IP_BLOCK por cada familia de direcciones con la que se contrató. El provisionedId de un elemento es el ID del servidor o bloque que factura, y su subtotalMillicents es su precio por ciclo o por hora en HOURLY. Sus details contienen includedEgressGb para un servidor (null si es ilimitado) o ipVersion y prefixLength para un bloque.

Obtener suscripción del servicio y Obtener suscripción del bloque de IP devuelven la suscripción que factura un servidor o bloque. El status de una suscripción es ACTIVE, CANCELLATION_REQUESTED o CANCELLED.

Cancelar suscripción responde 204. Desde ese momento, la suscripción no emite facturas de renovación y una por hora deja de acumular uso. Lo que sucede después depende de lo que facture:

• Un servidor bare metal se elimina. Muestra state DELETING mientras se apaga y desmantela (Eliminar un servicio) y la suscripción muestra CANCELLATION_REQUESTED hasta que desaparecen el servidor y sus bloques de direcciones, y después CANCELLED.
• Un bloque de IP contratado por separado se libera inmediatamente y su suscripción pasa directamente a CANCELLED.
• Un servidor en la nube, o una suscripción sin elementos activos, llega a nuestro equipo de soporte como ticket para revisión manual. La suscripción muestra CANCELLATION_REQUESTED hasta que terminan.

Eliminar servicio bare metal en el único servidor de una suscripción inicia la misma cancelación y Eliminar bloque de IP hace lo mismo para un bloque contratado por separado. Un bloque incluido con un servidor se rechaza con 422 BUNDLED_ITEM_CANCELLATION_BLOCKED: elimina el servidor y el bloque se libera después.

Repetir la solicitud mientras la cancelación está pendiente responde de nuevo 204. Un rechazo es 422 y solo SUBSCRIPTION_CANCELLATION_INCOMPLETE sucede después de un cambio parcial:

Facturas

Listar facturas acepta unpaidOnly=true para las que siguen abiertas: UNPAID, PARTIAL y OVERDUE. El status de una factura es uno de esos tres, PAID, COLLECTIONS, CANCELLED o REFUNDED, y su type es STANDARD o, para recargar crédito, CREDIT_PURCHASE. Descargar PDF de factura devuelve el propio PDF en lugar de JSON.

Pagar factura acepta un cuerpo JSON cuyo providerType es ACCOUNT_CREDIT o STRIPE; MANUAL, también enumerado, se rechaza con 400. Responde 200 con el status del pago (PENDING, SUCCEEDED, FAILED o CANCELLED), el transactionId registrado en la factura, un clientSecret y un declineCode.

• ACCOUNT_CREDIT paga con el crédito de la organización, que es como paga un script con una clave. Toma el saldo disponible hasta el importe pendiente, así que un saldo menor que la factura la deja PARTIAL con el pago SUCCEEDED.
• STRIPE con el methodId de una tarjeta guardada carga el pago a esa tarjeta.
• STRIPE sin methodId inicia un pago con tarjeta que se completa en un formulario de tarjeta.

Un pago con tarjeta que necesita al titular, sea una tarjeta nueva o una guardada que pide 3-D Secure, responde PENDING con un clientSecret. Stripe.js lo completa en un navegador con nuestra clave publicable, que la API no proporciona, y Confirmar pago de factura registra después el resultado a partir de providerType STRIPE y el providerTransactionId dado por Stripe. Por tanto, los pagos con tarjeta se realizan en la consola.

Un pago rechazado es 422 cuyo data contiene la misma vista de pago:

declineCode solo se establece ante un rechazo de tarjeta, por ejemplo INSUFFICIENT_FUNDS o EXPIRED_CARD. Un rechazo genérico muestra GENERIC_DECLINE, igual que una tarjeta marcada por la red como fraudulenta, perdida o robada; un rechazo que la plataforma no reconoce muestra UNKNOWN.

Uso del periodo actual

Obtener uso actual abarca los servicios por hora del periodo de facturación en curso, con importes en céntimos:

• periodStart y periodEnd delimitan el periodo.
• accruedAmount es lo acumulado por esos servicios: las horas facturables de cada uno a su tarifa por hora, menos cualquier descuento del elemento, más el tráfico que supera la cuota del plan.
• estimatedAmount proyecta las horas hasta periodEnd, contando los servicios en ejecución como si continuaran hasta entonces y los finalizados por lo acumulado. El tráfico cuenta según lo medido hasta ahora.
• activeServiceCount y terminatedServiceCount cuentan los servicios de esos importes.
• isPartial es true si no se pudo leer parte del uso y los importes omiten esa parte.

Crédito de cuenta

Obtener saldo de crédito devuelve el creditBalance de la organización y los importes mínimo y máximo que acepta una compra, minPurchaseAmount y maxPurchaseAmount, todos en céntimos. Comprar crédito acepta un amount en céntimos y responde 201 con una factura CREDIT_PURCHASE; un importe fuera de los límites produce 422 VALIDATION_FAILED con un detalle CREDIT_AMOUNT_INVALID sobre amount. Esa factura no tiene impuestos, nunca se cobra automáticamente y se paga con tarjeta en la consola. El crédito se añade cuando se paga.

El saldo es la suma de un registro contable. Listar entradas de crédito lo pagina de más reciente a más antiguo y Obtener entrada de crédito lee una entrada: su amount en céntimos, type, description, createdAt y, si interviene una factura, invoiceId. Una compra de crédito pagada añade una ADDITION y el crédito gastado en una factura es un INVOICE_PAYMENT negativo. Los demás tipos son PROMOTION, MANUAL_ADJUSTMENT para crédito que añade o retira nuestro equipo y REFUND para crédito devuelto cuando se revierte un pago con crédito.

Métodos de pago

Las tarjetas se añaden en la consola mediante Stripe, así que el número de tarjeta nunca pasa por esta API. Añadir tarjeta no acepta cuerpo y responde 201 con provider STRIPE y el clientSecret de la configuración de Stripe del formulario de tarjeta de la consola, que Stripe.js completa en un navegador igual que un pago con tarjeta. Sin dirección de facturación en la organización, la primera configuración de tarjeta responde 422 BILLING_ADDRESS_REQUIRED.

Establecer método de pago predeterminado responde 204 y hace que una tarjeta guardada sea la que recibe los cargos de renovación y uso. Eliminar método de pago responde 204 y elimina una tarjeta de la organización y de Stripe. Ninguna llamada enumera las tarjetas guardadas: sus ID están en el registro de organización, que solo lee una sesión de consola, así que una clave no puede encontrar el ID que aceptan estas dos llamadas y methodId de Pagar factura.