> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Facturación > Lea el catálogo de precios público, el uso mensual hasta la fecha, las facturas, los créditos y los pagos. El pago se realiza en la consola. Vea [Resource references](/es/reference-resolution) para los tipos de referencia aceptados, los ámbitos de búsqueda, las identidades canónicas y los filtros de lista exacta. La facturación responde lo que ha consumido y lo que se le ha cobrado. Es **global**: un punto final, una factura, sin segmento de región: ``` https://billing.basaltic.sh ``` Una factura cubre toda su organización. El uso de cada cuenta dentro de ella se acumula en una sola factura mensual, por lo que no hay `X-Account-Id` en estas llamadas, la organización que autenticó como es el alcance completo. **La API de facturación es de solo lectura, deliberadamente.** Cada operación aquí responde a una pregunta; ninguna de ellas mueve dinero. La liquidación de una factura, la adición o el cambio de un método de pago y la configuración de facturación son flujos de consola en [console.basaltic.sh](https://console.basaltic.sh) y no tienen equivalente en la API. Si estás buscando un endpoint para pagar una factura de forma programática, no hay uno. Público y no autenticado — todo el catálogo, idéntico para todos. Lo que se acumula ahora y lo que ya se ha facturado. Cómo se consumen las subvenciones y dónde aparecen en una factura. Días de reintento, vencimientos atrasados y lo que le puede costar el impago. ## El catálogo de precios público `GET /v1/prices` toma **No hay credenciales**. Like [Descubrimiento de la región](/es/regions), el catálogo de precios es público y no requiere una cuenta seleccionada. ```bash theme={null} curl https://billing.basaltic.sh/v1/prices?service=compute ``` ```json theme={null} { "prices": [ { "sku": "compute.instance.s1.medium", "service": "compute", "resource_type": "instance", "name": "s1.medium", "description": "2 vCPU, 4 GB RAM", "unit": "hour", "unit_price": "0.085", "currency": "BRL", "metadata": { "class": "shared", "vcpus": 2, "memory_gb": 4 } } ], "as_of": "2026-08-31T14:02:11Z" } ``` Es público porque no hay nada específico del inquilino en él. No hay tarifas a nivel de cuenta, descuentos o términos de uso comprometido en esta tabla: cada persona que llama recibe los mismos números, que es precisamente por qué es seguro publicar y útil leer. Existe para que una página de precios o un estimador de costos lea la tarifa que cobrará la facturación, en lugar de mantener su propia copia que se desplaza la próxima vez que algo se revaloriza. Como no requiere credenciales, el presupuesto se cuenta **por IP del cliente**: 100 solicitudes por minuto. Lea `X-RateLimit-Remaining` y `X-RateLimit-Reset` en lugar de codificar eso; en un `429`, espere `Retry-After` segundos, ya que volver a intentar temprano extiende la ventana. Las respuestas llevan `Cache-Control: public, max-age=300` — el catálogo cambia cuando algo se reprecia, no por petición, así que almacenarlo en caché durante cinco minutos no te cuesta nada. ### Filtros | Parámetro | Efecto | | - | - | | `service` | Solo SKU facturados por un servicio, p. ej. `compute` | | `resource_type` | Solo un tipo de recurso, p. ej. `instance` | | `sku` | Exactamente una SKU | | `family` | Solo SKUs cuyo `metadata.family` coincide con | | `at` | Leer el catálogo a partir de un instante de RFC 3339 en lugar de ahora | `family` es la forma en que se distinguen los productos administrados de los tipos de computación generales con los que comparten un `resource_type`: las réplicas de balanceador de carga y los nodos de clúster de base de datos se facturan como instancias, pero son su propia familia. `at` es lo que se usa para explicar una factura pasada: pase el `period_start` de la factura y obtendrá las tarifas que estaban en vigor entonces. `as_of` en la respuesta hace eco del instante en que las filas fueron seleccionadas, de modo que un cliente puede decir qué revisión del catálogo está teniendo. El dinero es una **cadena decimal**, nunca un número JSON, en todas partes de esta API. `"0.085"` sobrevive a un viaje de ida y vuelta a través del analizador JSON de cualquier lenguaje exactamente; un flotador no lo hace. La tarifa cotizada es la que se cobrará, por lo que no se puede permitir que se redondee de manera diferente en el camino de salida. No hay paginación en este extremo. El catálogo es la respuesta completa: un cliente que tuviera que paginarlo podría observar la mitad de una revisión y la mitad de la siguiente. ### Rendimiento adicional de volumen de bloque [Rendimiento del volumen aprovisionado](/es/storage/volumes#provisioning-more-performance) tiene precios separados por mes de IOPS y por mes de MiB/s en `resource_type=volume-performance`. Solo se cobra la asignación sostenida por encima de la asignación incluida de un volumen. Las tarifas se prorratean sobre el mes UTC real desde que se aplica un cambio, incluyendo el tiempo separado o detenido. Al volver a la configuración incluida o eliminar el volumen, se termina la asignación adicional. El uso de rendimiento aparece después de que se haya completado su hora UTC. ## Uso del mes hasta la fecha ```bash theme={null} GET /v1/usage ``` Devuelve el uso no facturado acumulado hasta la fecha en el mes actual **UTC**, con un desglose por SKU ordenado por costo: ```json theme={null} { "amount": "42.87", "period_start": "2026-08-01T00:00:00Z", "items": [ { "sku": "compute.instance.m1.small", "description": "m1.small", "quantity": "412.5", "unit": "hour", "amount": "26.8125" } ] } ``` La línea `amount` tiene cuatro decimales mientras que el total tiene dos. Eso no es inconsistencia — al principio de un mes una línea puede valer una fracción de un centavo, y redondearlo a dos dígitos lo convertiría en `0.00` y haría que pareciera que no se está acumulando nada. El total, y cada cifra en una factura, se mantiene en el dos del libro mayor. ## Facturas Se genera una factura el **1 de cada mes**, que cubre el mes calendario anterior UTC, una por organización. ```bash theme={null} GET /v1/invoices # one page, no line items GET /v1/invoices/{invoice_id} # the invoice with its line items ``` `period_start` es el primer día del mes de facturación y `period_end` es **exclusivo**, es decir, el primer día del mes siguiente. El uso que llega tarde de meses anteriores se traslada a la siguiente factura generada en lugar de reabrir una cerrada, por lo que los elementos de línea de una factura no siempre se limitan a su período etiquetado. La aritmética es `subtotal - credits_applied = total`. Las líneas de uso llevan `kind: "usage"`; las líneas de crédito llevan `kind: "credit"` y un `amount` negativo. `items` se rellena solo en el punto final de detalle. `GET /v1/invoices` devuelve los documentos de factura sin elementos de línea, porque una lista de facturas de un año con cada línea expandida es una respuesta grande que nadie pidió. ### Statuses | Estado | Significado | | - | - | | `open` | Emitido y no pagado. La recolección está en curso. | | `paid` | Settled. También cómo se lee una factura de cancelación — ver más abajo. | | `past_due` | El programa de reintentos se agotó sin recolectar. | | `uncollectible` | Se dio por vencido. | | `void` | Cancelado; no se debe nada. | `due_at` es igual a `issued_at`. Una factura vence cuando se emite, y el primer intento de cargo ocurre inmediatamente; los días siguientes son reintentos, no un período de gracia. **Las facturas pequeñas se cancelan en lugar de cobrarse.** Un total inferior a **1,00** en la moneda de la factura se cancela en la generación, y la factura dice `paid` sin que se haya intentado ningún pago. El costo de cobrar una cantidad de sub-unidad excede la cantidad. ### La declaración PDF ```bash theme={null} GET /v1/invoices/{invoice_id}/pdf ``` Se genera bajo demanda desde el estado actual de la factura, bajo la misma autorización que el documento de factura: no hay ningún archivo almacenado que se desvíe del estado que muestra. El campo `pdf_url` en una factura es la ruta a este punto final, no un enlace prefirmado que puede entregar a otra persona. ## Créditos ```bash theme={null} GET /v1/credits ``` Una concesión de crédito lleva la `amount` por la que fue emitida y el saldo `remaining`, más una `source` — `promo`, `coupon`, `adjustment` o `migration` — y un `expires_at` opcional. Las subvenciones se consumen en la generación de facturas, **la que caduca primero**, hasta que se cubre el subtotal. Cada porción consumida se convierte en su propia línea negativa en la factura y su propia entrada `credit_applied` en el libro mayor, por lo que siempre puede rastrear qué subvención pagó por qué. Los créditos se aplican automáticamente. No hay un punto final para aplicar uno a una factura en particular, ni para canjear un código: un código se canjea en la consola, que es lo que crea la concesión. ## Transacciones y pagos ```bash theme={null} GET /v1/transactions GET /v1/payments ``` `GET /v1/transactions` es el libro mayor: `payment`, `refund`, `adjustment`, `credit_grant` y `credit_applied` entradas. El `amount` de la transacción es **siempre positivo**. La dirección vive en el `type`, no en el signo. Sumando cantidades sin leer tipos te da un número que no significa nada. ### Referencias del libro mayor La `description` y la `reference` de una transacción son independientes y pueden ser `null`. `reference` reemplaza a `reference_type`: identifica la factura, pago o concesión de crédito relacionado con un CRN. El `crn` propio de la transacción identifica la entrada del libro mayor, no ese recurso relacionado. Las entradas manuales y las entradas sin un destino soportado devuelven `reference: null`. Por ejemplo, estas filas ilustrativas del libro mayor muestran los tres tipos de objetivos y una entrada sin un objetivo: ```json theme={null} { "transactions": [ { "crn": "crn:billing:::transaction/550e8400-e29b-41d4-a716-446655440010", "id": "550e8400-e29b-41d4-a716-446655440010", "type": "payment", "amount": "10.00", "description": "Invoice settlement", "reference": "crn:billing:::invoice/550e8400-e29b-41d4-a716-446655440000", "created_at": "2026-09-01T00:00:00Z" }, { "crn": "crn:billing:::transaction/550e8400-e29b-41d4-a716-446655440011", "id": "550e8400-e29b-41d4-a716-446655440011", "type": "refund", "amount": "10.00", "description": "Payment refund", "reference": "crn:billing:::payment/550e8400-e29b-41d4-a716-446655440000", "created_at": "2026-09-01T00:00:00Z" }, { "crn": "crn:billing:::transaction/550e8400-e29b-41d4-a716-446655440012", "id": "550e8400-e29b-41d4-a716-446655440012", "type": "credit_grant", "amount": "10.00", "description": "Promotional credit", "reference": "crn:billing:::credit/550e8400-e29b-41d4-a716-446655440000", "created_at": "2026-09-01T00:00:00Z" }, { "crn": "crn:billing:::transaction/550e8400-e29b-41d4-a716-446655440013", "id": "550e8400-e29b-41d4-a716-446655440013", "type": "adjustment", "amount": "10.00", "description": null, "reference": null, "created_at": "2026-09-01T00:00:00Z" } ], "meta": { "has_more": false } } ``` Siga el tipo en `reference`, en lugar de inferirlo de `type`: una liquidación de pago o una solicitud de crédito puede hacer referencia a una factura directamente. | Referencia tipo | Búsqueda exacta | | - | - | | `invoice` | `GET /v1/invoices?crn=crn:billing:::invoice/{id}` | | `payment` | `GET /v1/payments?crn=crn:billing:::payment/{id}` | | `credit` | `GET /v1/credits?crn=crn:billing:::credit/{id}` | Reemplaza `{id}` con el UUID de la referencia y codifica en URL el valor de la consulta `crn`. Estos filtros seleccionan el CRN propio del artículo de la colección. Por ejemplo, `GET /v1/transactions?crn=crn:billing:::transaction/{id}` selecciona una entrada de libro mayor; no encuentra todas las transacciones asociadas a una factura. Todas las búsquedas permanecen dentro de su organización autenticada. Una referencia válida pero no coincidente devuelve una colección vacía; las referencias malformadas devuelven `INVALID_INPUT`. Para obtener una referencia de pago, lea la `invoice` incrustada del pago correspondiente. Cuando esté presente, use `invoice.id` con `GET /v1/invoices/{invoice_id}` para leer sus elementos de línea. Cuando `invoice` es nulo, el estado del pago, el importe, el intento y las fechas permanecen disponibles. La resolución de pagos requiere `billing:ListPayments`; una búsqueda vacía o denegada no cambia la entrada del libro mayor ni su referencia. En la página de transacciones de la consola, **Description** y **Referencia** aparecen por separado, con `-` para los valores ausentes. Las referencias de factura abren los detalles de la factura. Haga clic en **Ver pago** para resolver una referencia de pago a su factura o detalles de pago. Los créditos y las referencias no reconocidas permanecen en el texto. ### Intentos de pago `GET /v1/payments` muestra los intentos de carga. Cada fila lleva `attempt`, un contador basado en 1 dentro del horario de cobro para su factura, y un `status` de `pending`, `processing`, `succeeded`, `failed` o `refunded`. Varias filas contra una factura es la forma normal de una secuencia de reintentos, no un signo de cargos duplicados. Cada pago incluye `invoice`, reemplazando el antiguo campo `invoice_id`. El objeto incrustado contiene los campos de la lista de facturas actuales, incluyendo `pdf_url`, sin `items`. Refleja la factura cuando se enumeran los pagos, no una instantánea del intento de cargo. Si la factura ha sido eliminada, `invoice` es explícitamente `null`; compruébelo antes de leer `invoice.id` u otros campos de factura. Por ejemplo, una respuesta con una factura disponible y una factura eliminada: ```json theme={null} { "payments": [ { "crn": "crn:billing:::payment/550e8400-e29b-41d4-a716-446655440001", "id": "550e8400-e29b-41d4-a716-446655440001", "invoice": { "crn": "crn:billing:::invoice/550e8400-e29b-41d4-a716-446655440000", "id": "550e8400-e29b-41d4-a716-446655440000", "invoice_number": "INV-2026-000042", "period_start": "2026-08-01", "period_end": "2026-09-01", "subtotal": "108.40", "credits_applied": "0.00", "total": "108.40", "currency": "BRL", "status": "paid", "issued_at": "2026-09-01T00:00:00Z", "due_at": "2026-09-01T00:00:00Z", "paid_at": "2026-09-01T00:01:00Z", "created_at": "2026-09-01T00:00:00Z", "pdf_url": "/v1/invoices/550e8400-e29b-41d4-a716-446655440000/pdf" }, "amount": "108.40", "status": "succeeded", "attempt": 1, "completed_at": "2026-09-01T00:01:00Z", "created_at": "2026-09-01T00:00:00Z" }, { "crn": "crn:billing:::payment/550e8400-e29b-41d4-a716-446655440002", "id": "550e8400-e29b-41d4-a716-446655440002", "invoice": null, "amount": "108.40", "status": "succeeded", "attempt": 1, "completed_at": "2026-09-01T00:01:00Z", "created_at": "2026-09-01T00:00:00Z" } ], "meta": { "has_more": false } } ``` ## Qué sucede con una factura impagada El cobro se realiza con un calendario fijo desde el momento de la emisión de la factura: ```mermaid theme={null} flowchart LR A["Day 0
issued
attempt 1"] --> B["Day 3
attempt 2"] B --> C["Day 5
attempt 3"] C --> D["past_due"] D --> E["Day 7
suspended"] E --> F["Day 15
terminated"] A -.paid.-> G["settled"] B -.paid.-> G C -.paid.-> G D -.paid.-> G ``` Si ninguno de los tres intentos se cobra, la factura se mueve a `past_due`. **El impago eventualmente le cuesta sus recursos.** Al día 7 la organización se suspende, al día 15 se termina y después se eliminan sus recursos. Cada paso vuelve a comprobar primero la factura, por lo que liquidarla en cualquier momento detiene la secuencia inmediatamente. Liquidar una factura `past_due` desde la consola. Ahí es donde también arreglas el método de pago que causó los rechazos, la API no tiene ruta a ninguno de los dos. ## Permisos | Acción y aventura | Punto final | | - | - | | `billing:GetCurrentUsage` | `GET /v1/usage` | | `billing:ListInvoices` | `GET /v1/invoices` | | `billing:GetInvoice` | `GET /v1/invoices/{id}` y su PDF | | `billing:ListCredits` | `GET /v1/credits` | | `billing:ListTransactions` | `GET /v1/transactions` | | `billing:ListPayments` | `GET /v1/payments` | `GET /v1/prices` no necesita permiso, porque no necesita identidad. **Las directivas de facturación no pueden ampliarse a un recurso.** Cada acción de facturación autoriza contra `*` — el límite de la organización es la valla de todo el inquilino aquí, ya que hay una factura y pertenece a la organización en lugar de a cualquier cuenta dentro de ella. `billing:GetInvoice` El sistema lo otorga para cada factura; no hay forma de restringirlo a una sola. Conceda acceso de lectura de facturación a nivel de grupo a las personas que lo necesiten, no de forma general. Consulte [policies](/es/iam/policies).