Transacciones y gasto
Cada crédito que entra o sale de una organización se escribe en un libro mayor de solo anexado. La página Facturación lo presenta de dos maneras: un gráfico para ver la forma de su gasto, y una tabla con las entradas exactas que hay detrás.
La lista de transacciones
La tabla se ordena de más reciente a más antigua y muestra 50 entradas a la vez; Cargar más obtiene la página siguiente.
| Columna | Qué contiene |
|---|---|
| Fecha | Cuándo se escribió la entrada, con precisión de segundos |
| Tipo | De qué clase de entrada se trata |
| Detalle | En un cargo, la instancia a la que pertenece y cuánto tiempo cubre; para las demás entradas, véase más abajo |
| Monto | El cambio con signo en el saldo, positivo para los créditos agregados |
| Saldo | El saldo inmediatamente después de esta entrada |
Tipos que verá:
| Tipo | Etiqueta en la consola | Qué lo produjo |
|---|---|---|
topup | Créditos agregados | Un pago de Stripe confirmado |
charge_gpu | Uso de GPU | Tiempo en ejecución, una fila por instancia y por hora de reloj |
charge_storage | Almacenamiento | Tiempo de disco detenido, una fila por instancia y por hora de reloj |
adjustment | Ajuste | Cualquier movimiento con signo del saldo que no sea una recarga ni uso medido — sobre todo devoluciones de Stripe, publicadas automáticamente. Véase más abajo |
Un adjustment no es solo una corrección manual. Los eventos de Stripe publican ajustes por su cuenta, y el meta.reason de la fila dice cuál. La columna Tipo muestra entonces el motivo en lugar de Ajuste:
meta.reason | Etiqueta en la consola | Signo | Qué pasó |
|---|---|---|---|
refund | Reembolso | débito | Se reembolsó un cargo. Solo se debita el importe que movió este evento, así que un segundo reembolso parcial no vuelve a tomar el primero |
dispute_opened | Disputa abierta | débito | Se presentó un contracargo y el dinero ya no está |
dispute_funds_withdrawn | Disputa — fondos retirados | débito | Se retiraron los fondos en una disputa que llegó primero como consulta, así que no se debitó nada al abrirse |
dispute_won | Disputa ganada | crédito | Usted ganó la disputa y su débito se revierte |
dispute_reinstated | Disputa — fondos devueltos en parte | crédito | Usted perdió la disputa, pero la red de tarjetas devolvió parte del dinero. Lo que vuelve se acredita una sola vez, y solo en la medida en que se había debitado: si un reembolso anterior ya había evitado que se debitara parte del pago, esa parte no se acredita una segunda vez |
dispute_capped | Disputa — ajustada al pago | crédito | Un reembolso del mismo pago llegó después de que se debitara la disputa, así que se devuelve parte de ese débito: un pago nunca se recupera dos veces |
staff_adjustment | Ajuste de soporte | cualquiera | El soporte de Superheat movió el saldo a mano. La celda Detalle muestra la nota que le escribieron |
Una disputa nunca recupera más de lo que le queda al pago: su importe (o el importe disputado, cuando el emisor de la tarjeta agrupa varios pagos en una sola disputa) menos los reembolsos ya registrados sobre él. Así, una recarga de $10 que se reembolsó en $4 y luego se disputó y se perdió cuesta $10 en total, llegue en el orden que llegue el reembolso y la disputa; nunca $14. Cuando un emisor sustituye una disputa por otra con el importe corregido, cada disputa se sigue por separado. Si la red de tarjetas devuelve parte de una disputa perdida en otra moneda, o sin decir cuánto, no se acredita nada automáticamente; se avisa al personal de Superheat para que lo revise.
Una disputa formal además congela la organización mientras está abierta: POST /v1/instances e iniciar una instancia detenida responden ambos 402 PAYMENTS_FROZEN, de modo que un contracargo no puede financiar tiempo de GPU. Como una instancia detenida no puede iniciarse mientras tanto, sus GPU también se liberan, y una detención pulsada durante la congelación las libera en el acto, en ambos casos donde la máquina lo permite: vea Mientras haya una disputa de pago abierta. Cerrar la disputa levanta la congelación gane quien gane —una derrota conserva su débito, y de ahí en adelante lo que lo limita es el saldo—, pero solo cuando no queda ninguna otra disputa formal abierta contra la organización. El personal de Superheat también puede levantar una congelación tras revisar la disputa. Una consulta, en la que el emisor está preguntando y no se ha movido dinero, ni congela la cuenta ni publica ninguna fila en el libro mayor: debitar por una pregunta que muchas veces no llega a nada le quitaría créditos a alguien que no ha hecho nada malo. Si la consulta escala a una disputa formal, la congelación y el débito llegan entonces. Cada disputa se debita como mucho una vez, y una disputa ganada devuelve exactamente lo que debitó.
En un cargo, la celda Detalle enlaza a la pestaña Facturación de esa instancia e indica el tiempo que cubre la fila, como 47m 0s. La fila de la hora que sigue en marcha lleva la marca en curso. Las recargas no tienen instancia y muestran en su lugar el método de pago (con Stripe). Una fila de reembolso o de disputa dice Reembolsado o Disputa de pago, un ajuste de soporte muestra la nota que escribió el soporte, y cualquier otro ajuste muestra un guion.
Una fila por instancia y por hora
Los cargos se siguen liquidando aproximadamente una vez por minuto, exactamente como describe Cómo funciona la facturación, pero ya no ocupan una fila cada uno. Cada instancia tiene una fila de cargo abierta para la hora de reloj en curso (UTC), y la liquidación de cada minuto se suma a ella: su importe y el tiempo que cubre crecen, y el saldo posterior baja, hasta que la fila se cierra. Una fila se cierra, y la siguiente liquidación abre otra, cuando:
- termina la hora de reloj;
- la instancia cambia de estado: detenerla, iniciarla o destruirla escribe una fila cerrada propia por el tiempo hasta ese momento;
- cambia la tarifa, o la instancia pasa a otra máquina;
- se escribe una recarga o un ajuste después de ella. El saldo de un pago nunca se reescribe, así que una fila nunca crece por encima de uno.
Así, una instancia que funciona todo el día produce unas 24 filas, no 1,440, y detenerla a mitad de una hora cierra antes la fila de esa hora. Para un total por instancia, abra la instancia y lea Gasto liquidado, y para un total día a día use el gráfico. Los montos por debajo del centavo se muestran con cuatro decimales, así que un cargo de almacenamiento pequeño se lee como algo parecido a $0.0007 en lugar de $0.00.
El gráfico de gasto
Gasto — últimos 30 días traza un punto por día, con el total de 30 días junto al encabezado. Al pasar el cursor sobre un punto se obtiene la cifra de ese día.
Lo que cuenta el gráfico:
- Solo los cargos de GPU y de almacenamiento. Las recargas y los ajustes quedan excluidos: esto es gasto, no flujo de caja.
- Los días son días naturales en la zona horaria de su navegador, así que una ejecución de última hora de la tarde cae en el día en que la ejecutó. La consola envía esa zona a la API, que agrupa los cargos según ella. Una fila de cargo cuenta en el día en que empezó su hora: en una zona horaria cuyo desfase no es una hora entera, como la de la India, hasta una hora de uso alrededor de la medianoche puede caer en el día vecino.
- Los días sin cargos se trazan como cero en lugar de omitirse, que es lo que da al gráfico sus tramos planos entre ráfagas de trabajo.
Los endpoints
Ambos endpoints leen el libro mayor de la organización actual. Envíe un token de portador: una sesión iniciada o una clave de API de organización shk_. Con una sesión, X-Org-Id selecciona la organización, y sin esa cabecera se usa la organización personal; una clave de API está fijada a su propia organización, y enviar un X-Org-Id de cualquier otra se rechaza con ORG_MISMATCH. Ninguno de los dos endpoints requiere ser administrador, así que un miembro o una clave de API pueden leerlos. Consulte Autenticación.
GET /v1/billing/transactions
curl "$SUPERHEAT_API/v1/billing/transactions?limit=100" \
-H "Authorization: Bearer $SUPERHEAT_TOKEN" \
-H "X-Org-Id: $ORG_ID"
| Parámetro | Rango | Predeterminado | Efecto |
|---|---|---|---|
limit | 1 a 200 | 50 | Entradas por página |
cursor | un id de entrada | — | Devuelve las entradas anteriores a este id |
instance_id | un id de instancia | — | Restringe la página a una sola instancia |
Las entradas vuelven de más reciente a más antigua en items, junto a un next_cursor. Pase ese valor como cursor para obtener la página siguiente; cuando vuelva como null, ha llegado al final del libro mayor.
Cada entrada lleva su id (que sirve además como cursor de paginación), su type, el instance_id al que pertenece o null si es una recarga o un ajuste, una marca de tiempo created_at, su monto con signo y el saldo que resultó de ella. Un ajuste lleva el meta.reason de la tabla de arriba, y reason lo repite en el nivel superior de la entrada (null en una entrada que no lo tiene).
Un cargo medido lleva un objeto meta con period_start, period_end, seconds (el tiempo que factura la fila), rate_micro_per_hour y settlements (cuántas liquidaciones por minuto suma; las filas escritas antes de las filas por hora no llevan este recuento y son una liquidación cada una). Su created_at es el momento en que se ejecutó su primera liquidación, y la fila solo acepta liquidaciones de esa misma hora de reloj. accruing es true en la fila a la que una instancia sigue sumando: hasta que se cierra, crecen su importe, meta.seconds, meta.period_end y meta.settlements, y el saldo posterior a ella, y a las filas de cargo que la siguen, baja en la misma cantidad. Todas las demás entradas son definitivas tal como se escriben. Si copia el libro mayor a otro sitio, vuelva a leer las filas que estaban accruing hasta que lleguen en false.
Para extraer los cargos de una sola instancia:
curl "$SUPERHEAT_API/v1/billing/transactions?instance_id=$INSTANCE_ID&limit=200" \
-H "Authorization: Bearer $SUPERHEAT_TOKEN" \
-H "X-Org-Id: $ORG_ID"
GET /v1/billing/spend-daily
curl "$SUPERHEAT_API/v1/billing/spend-daily?days=90" \
-H "Authorization: Bearer $SUPERHEAT_TOKEN" \
-H "X-Org-Id: $ORG_ID"
| Parámetro | Rango | Predeterminado | Efecto |
|---|---|---|---|
days | 1 a 90 | 30 | Hasta dónde agregar hacia atrás |
tz | un nombre de zona horaria IANA, como Europe/Berlin | UTC | En los días naturales de qué zona se agrupan los cargos. Un nombre que la API no conoce devuelve 422 INVALID_TIME_ZONE |
Esta es la fuente de datos del gráfico: cargos de GPU y de almacenamiento agrupados por día natural en tz, de más antiguo a más reciente, y cada entrada lleva una date y el total de ese día. Solo aparecen los días que tuvieron cargos, así que una semana tranquila no produce entradas en lugar de una sucesión de ceros; rellene los huecos usted mismo si está trazando una serie densa.