Créditos y saldos
Cómo funcionan los créditos de Piloterr y cómo recargar tu saldo.
Cada llamada facturable descuenta créditos de tu espacio de trabajo. El panel Uso del panel de control, en Configuración → Suscripción, muestra tres saldos. El endpoint de uso de la API informa una autonomía combinada para que puedas alertar desde el código sin analizar cada compartimento.
Uso
Período actual38,400
10,000
3,780
Suscripción
Pro · se renueva el día 1
Los tres saldos
| Saldo | Qué es | Reinicio |
|---|---|---|
| Cuota de suscripción | Llamadas API incluidas en tu plan | Sí: al inicio de cada periodo de facturación (desde Stripe si está disponible; si no, el mes calendario). La cuota no usada no se acumula. |
| Pack API puntual | Cuota API adicional de una compra única | Nunca: se consume hasta agotarse, de un periodo a otro |
| Créditos pay-as-you-go | Un libro mayor aparte, usado solo cuando la cuota de suscripción y los packs API están vacíos | Nunca: los créditos permanecen hasta gastarse |
En el panel esas tres barras aparecen en Configuración → Suscripción → Uso (y en el panel Uso de API de la barra lateral). En el endpoint de uso (/v2/usage), el objeto subscription es la cuota API combinada (suscripción + packs restantes). El pay-as-you-go está en credits. El remaining de nivel superior es la suma de ambos.
Orden de consumo
Primero la cuota de suscripción
Las llamadas facturables llenan la asignación del plan del periodo actual.
Después los packs API puntuales
Cuando se agota la asignación del periodo, se consume a continuación la cuota restante de los packs. Los packs se imputan en orden de compra.
Después los créditos pay-as-you-go
Solo si la cuota API combinada no puede cubrir el coste del endpoint debitamos el libro pay-as-you-go.
Si no, la llamada se rechaza
La API devuelve 402 con Payment required, y la petición no se ejecuta.
Qué se factura
| Resultado | Créditos |
|---|---|
200 o 201 (respuesta facturable correcta / aceptada) | Sí: el coste en créditos del endpoint |
404 | Normalmente sí, salvo que ese endpoint marque el 404 como gratuito (indicado en la Biblioteca y en la página del endpoint) |
401, 402, 400, 5xx y la mayoría del resto de errores | No, y cualquier reserva pay-as-you-go se libera |
| Endpoints por fila con 0 resultados | Gratis |
| Endpoints por fila con N resultados | N × el coste por fila — todo o nada (saldo insuficiente → 402 antes de devolver ninguna fila) |
/v2/usage y URL de estado de jobs | Siempre gratis: sin comprobación de cuota |
Cada endpoint declara su coste en la Biblioteca (y en la Referencia de la API): N créditos por llamada o por fila. El saldo se comprueba antes de que empiece el trabajo, así que un job nunca se acepta sin los créditos para pagarlo. Consultar el estado de un job nunca cuesta créditos.
Comprar más capacidad
Abre los ajustes de suscripción
Ve a Configuración → Suscripción y haz clic en Ver todos los planes (o abre https://app.piloterr.com/pricing).
Elige un pack puntual
Según el producto, un pack suma a la cuota API (pack API puntual) o al libro pay-as-you-go. Por sí solo nunca cambia tu plan. Los packs más grandes suelen costar menos por crédito.
Confirma el pago
La capacidad está disponible en cuanto el pago se confirma, y se envía una factura por correo a la dirección de facturación.
Los packs comprados también aparecen en Configuración → Suscripción → Packs puntuales. Para rellenar automáticamente cuando baje el saldo combinado, consulta Recarga automática.
Dónde consultar el historial
| Pantalla | Qué muestra |
|---|---|
| Configuración → Suscripción → Uso | Restante / usado en vivo de los tres saldos del periodo actual |
| Registros API | Cada petición con estado, duración y créditos cobrados, incluido el uso de suscripción y packs |
| Configuración → Créditos | El libro pay-as-you-go únicamente: abonos (recompensas, algunos tipos de pack, recarga automática) y gastos ocurridos tras agotar la cuota API. Filtra por miembro o por tipo. |
Endpoint de uso (/v2/usage) | Instantánea legible por máquina: remaining, subscription, credits, renewal_date — gratis de llamar |
Si Configuración → Créditos parece vacío mientras Analytics muestra tráfico, es lo esperado: el consumo de suscripción y packs nunca aparece en esa página. Usa Registros API o las barras de Uso en su lugar.
Cuando ves 402
| Mensaje | Significado | Qué hacer |
|---|---|---|
Payment required | No queda cuota de suscripción, packs ni pay-as-you-go para el coste de esta llamada | Compra un pack, sube de plan o activa la recarga automática |
You have open invoices: … | Una factura impagada está bloqueando la cuenta | Págalo en Configuración → Facturas: el saldo solo no basta |
Insufficient credits: X required, Y available | Un endpoint por fila devolvería más filas de las que puedes pagar | Recarga o acota la petición para que vuelvan menos filas |
FAQ
- ¿Se acumula la cuota del plan no usada? No. El compartimento de suscripción se reinicia en cada periodo de facturación.
- ¿Caducan los packs puntuales a fin de mes? No. Permanecen hasta consumirse.
- ¿Todas las claves comparten los mismos saldos? Sí: la cuota es del espacio de trabajo.
- ¿Consultar el uso cuesta créditos? No.
/v2/usagey las rutas de estado de jobs son gratis. - ¿Por qué Uso en el panel está separado y
/usage.subscriptioncombinado? Para que un solo númeroremainingbaste para las alertas; abre el panel cuando necesites el desglose en tres.