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 | La instancia a la que pertenece la entrada, y cuántos segundos cubre |
| 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 | Una liquidación de tiempo en ejecución |
charge_storage | Almacenamiento | Una liquidación de tiempo de disco detenido |
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:
meta.reason | Signo | Qué pasó |
|---|---|---|
refund | 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 | débito | Se presentó un contracargo y el dinero ya no está |
dispute_funds_withdrawn | débito | Se retiraron los fondos en una disputa que llegó primero como consulta, así que no se debitó nada al abrirse |
dispute_won | crédito | Usted ganó la disputa y el débito se revierte |
Una disputa 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. 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 abierta contra la organización. Una consulta, en la que el emisor está preguntando y no se ha movido dinero, congela la cuenta pero no 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.
La celda Detalle enlaza a la pestaña Facturación de esa instancia. Las recargas y los ajustes no tienen instancia y muestran un guion.
Como la liquidación se ejecuta aproximadamente una vez por minuto, una sola instancia produce alrededor de 60 filas por hora, y unas 1,440 al día. La lista está pensada para muestrearse y filtrarse, no para leerse de principio a fin: 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 de un minuto 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 se agrupan en UTC, así que una ejecución de última hora de la tarde al oeste de UTC cae en el punto del día siguiente.
- 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. Los cargos medidos llevan además un objeto meta que registra el inicio y el fin del período facturado y el número de segundos que cubre; un ajuste lleva el meta.reason de la tabla de arriba.
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 |
Esta es la fuente de datos del gráfico: cargos de GPU y de almacenamiento agrupados por día UTC, 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.