> ## 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. # Faturamento > Leia o catálogo de preços público, o uso mensal atualizado, as faturas, os créditos e os pagamentos. O pagamento acontece no console. Veja [Resource references](/pt/reference-resolution) para tipos de referência aceitos, escopo de pesquisa, identidades canônicas e filtros de lista exata. A faturação responde o que você consumiu e o que foi cobrado. É **global** — um endpoint, uma conta, nenhum segmento de região: ``` https://billing.basaltic.sh ``` Uma conta cobre toda a sua organização. O uso de cada conta dentro dele é acumulado em uma única fatura mensal, portanto, não há `X-Account-Id` nessas chamadas — a organização que você autenticou é o escopo inteiro. **A API de faturamento é somente leitura, deliberadamente.** A liquidação de uma fatura, a adição ou alteração de um método de pagamento e a configuração de faturamento são fluxos de console no painel de controle do sistema. [Arquivo de Console.basaltic.sh](https://console.basaltic.sh) Se você está procurando um endpoint para pagar uma fatura de forma programática, não há um, mas você pode usar o PayU para fazer isso. Público e não autenticado — todo o catálogo, idêntico para todos. O que está a acumular agora e o que já foi facturado. Como os subsídios são consumidos e onde eles aparecem em uma fatura. Dias de retenção, atraso e o que o não pagamento pode custar. ## O catálogo de preços público `GET /v1/prices` toma **sem credenciais**- Como? [Descoberta da região](/pt/regions), o catálogo de preços é público e não requer uma conta selecionada. ```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" } ``` É público porque não há nada específico do conta nele. Não há taxas de nível de conta, descontos ou termos de uso comprometido nesta tabela — cada chamada recebe os mesmos números, que é precisamente por isso que é seguro publicar e útil para ler. Ele existe para que uma página de preços ou um estimador de custos leia a taxa de faturamento que realmente cobrará, em vez de manter sua própria cópia que se desloca da próxima vez que algo é reajustado. Como não requer credenciais, o orçamento é contado **por IP do cliente**: 100 solicitações por minuto. Leia `X-RateLimit-Remaining` e `X-RateLimit-Reset` em vez de codificar isso; em um `429`, espere `Retry-After` segundos, uma vez que a re-tentativa antecipada estende a janela. As respostas carregam `Cache-Control: public, max-age=300` — o catálogo muda quando algo é reavaliado, não por solicitação, então armazená-lo em cache por cinco minutos não custa nada. ### Filtros | Parâmetro | Efeito | | - | - | | `service` | Apenas SKUs faturados por um serviço, por ex. `compute` | | `resource_type` | Apenas um tipo de recurso, por ex. `instance` | | `sku` | Exatamente uma SKU | | `family` | Apenas SKUs cujo `metadata.family` corresponde | | `at` | Leia o catálogo como um instante RFC 3339 em vez de agora | `family` é como os produtos gerenciados são diferenciados dos tipos de instância de computação gerais com os quais compartilham um `resource_type` — réplicas de balanceador de carga e nós de cluster de banco de dados são cobrados como instâncias, mas são sua própria família. `at` é o que você usa para explicar uma fatura passada: passe o `period_start` da fatura e você obtém as taxas que estavam em vigor na época. `as_of` na resposta ecoa o instante em que as linhas foram selecionadas, para que um cliente possa dizer qual revisão do catálogo ele está mantendo. O dinheiro é uma **cadeia decimal**, nunca um número JSON, em todos os lugares nesta API. `"0.085"` sobrevive a uma viagem de ida e volta através do analisador JSON de qualquer linguagem exatamente; um float não. A taxa cotada é a que será cobrada, por isso não pode ser permitido arredondar de forma diferente no caminho de saída. Não há paginação neste ponto de extremidade. O catálogo é a resposta completa — um cliente que tivesse que paginar poderia observar metade de uma revisão e metade da próxima. ### Desempenho adicional de volume de bloco [Desempenho do volume provisionado](/pt/storage/volumes#provisioning-more-performance) tem preços separados de IOPS-mês e MiB/s-mês em `resource_type=volume-performance`. Somente a alocação sustentada acima da cota incluída de um volume é cobrada. As taxas são proporcionais ao mês UTC real a partir do momento em que uma alteração é aplicada, incluindo o tempo separado ou interrompido. Retornar às configurações incluídas ou excluir o volume encerra a alocação extra. O uso de desempenho aparece após a hora UTC ter sido concluída. ## Uso do mês até à data ```bash theme={null} GET /v1/usage ``` Retorna o uso não faturado acumulado até agora no mês atual **UTC**, com uma análise por SKU ordenada por custo: ```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" } ] } ``` A linha `amount` tem quatro casas decimais enquanto o total tem duas. Isso não é inconsistência — no início de um mês uma linha pode valer uma fração de um centavo, e arredondá-la para dois dígitos a tornaria como `0.00` e faria parecer que nada está acúmulo. O total, e cada figura em uma fatura, fica no dois do livro. ## Faturas Uma fatura é gerada no **1º de cada mês**, cobrindo o mês anterior UTC, uma por organização. ```bash theme={null} GET /v1/invoices # one page, no line items GET /v1/invoices/{invoice_id} # the invoice with its line items ``` `period_start` é o primeiro dia do mês de cobrança e `period_end` é **exclusivo** — o primeiro dia do mês seguinte. O uso tardio de meses mais antigos é varrido para a próxima fatura gerada em vez de reabrir uma fechada, portanto, os itens de linha de uma fatura nem sempre estão confinados ao período rotulado. A aritmética é `subtotal - credits_applied = total`. Linhas de uso carregam `kind: "usage"`; linhas de crédito carregam `kind: "credit"` e um `amount` negativo. `items` é preenchido apenas no ponto final de detalhe. `GET /v1/invoices` retorna os documentos de fatura sem itens de linha, porque uma lista de faturas de um ano com cada linha expandida é uma resposta grande que ninguém pediu. ### Status | Status do produto | Significado da palavra | | - | - | | `open` | Emitido e não pago. A coleta está em andamento. | | `paid` | Settled. Também como uma fatura de cancelamento lê — veja abaixo. | | `past_due` | A programação de retenções terminou sem coletar. | | `uncollectible` | Desistiu. | | `void` | Cancelado; nada é devido. | `due_at` é igual a `issued_at`. Uma fatura é devida quando é emitida e a primeira tentativa de cobrança ocorre imediatamente. Os dias seguintes são tentativas repetidas, não um período de carência. **Faturas pequenas são canceladas em vez de cobradas.** Um total abaixo de **1,00** na moeda da fatura é cancelado na geração, e a fatura diz `paid` sem que nenhum pagamento tenha sido tentado. O custo de coleta de um valor de subunidade excede o valor. ### A declaração PDF ```bash theme={null} GET /v1/invoices/{invoice_id}/pdf ``` Renderizado sob demanda a partir do estado atual da fatura, sob a mesma autorização que o documento da fatura — não há nenhum arquivo armazenado para ficar fora de sincronia com o status que ele mostra. O campo `pdf_url` em uma fatura é o caminho para esse ponto final, não um link pré-assinado que você pode entregar a outra pessoa. ## Créditos ```bash theme={null} GET /v1/credits ``` Um crédito de concessão carrega o `amount` que foi emitido e o saldo `remaining`, mais uma `source` — `promo`, `coupon`, `adjustment` ou `migration` — e um opcional `expires_at`. Os subsídios são consumidos na geração da fatura, **o primeiro a expirar**, até que o subtotal seja coberto. Cada fatia consumida se torna sua própria linha negativa na fatura e sua própria entrada `credit_applied` no livro-razão, para que você possa sempre rastrear qual subsídio pago para o que. Os créditos são aplicados automaticamente. Não há nenhum endpoint para aplicar um a uma fatura específica e nenhum para resgatar um código — um código é resgatado no console, que é o que cria a concessão. ## Transações e pagamentos ```bash theme={null} GET /v1/transactions GET /v1/payments ``` `GET /v1/transactions` é o livro: `payment`, `refund`, `adjustment`, `credit_grant` e `credit_applied` entradas. O `amount` da transação é **sempre positivo**. A direção vive no `type`, não no sinal. Somando valores sem ler tipos dá um número que não significa nada. ### Referências de Ledger A `description` e a `reference` de uma transação são independentes e podem ser `null`. `reference` substitui `reference_type`: identifica a fatura, pagamento ou concessão de crédito relacionada com um CRN. O próprio `crn` da transação identifica a entrada do ledger, não o recurso relacionado. Entradas manuais e entradas sem um alvo suportado retornam `reference: null`. Por exemplo, estas linhas ilustrativas do livro-razão mostram todos os três tipos de alvo e uma entrada sem um alvo: ```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 o tipo em `reference`, em vez de inferi-lo de `type`: um acordo de pagamento ou aplicação de crédito pode fazer referência a uma fatura diretamente. | Referência tipo | Pesquisa exata | | - | - | | `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}` | Substitua `{id}` com o UUID da referência e URL-codificação do valor da consulta `crn`. Esses filtros selecionam o CRN próprio do item da coleção. Por exemplo, `GET /v1/transactions?crn=crn:billing:::transaction/{id}` seleciona uma entrada de livro; ele não encontra todas as transações associadas a uma fatura. Todas as pesquisas permanecem dentro da sua organização autenticada. Uma referência válida mas não combinada retorna uma coleção vazia; referências malformadas retornam `INVALID_INPUT`. Para uma referência de pagamento, leia a `invoice` incorporada do pagamento correspondente. Quando presente, use `invoice.id` com `GET /v1/invoices/{invoice_id}` para ler seus itens de linha. Quando `invoice` é nulo, o status do pagamento, o valor, a tentativa e as datas permanecem disponíveis. Resolver pagamentos requer `billing:ListPayments`; uma pesquisa vazia ou negada não altera a entrada do livro-razão ou sua referência. Na página de transações do console, **Description** e **Referência** aparecem separadamente, com `-` para valores ausentes. Referências de fatura abrem detalhes da fatura. Clique em **Ver pagamento** para resolver uma referência de pagamento para sua fatura ou detalhes de pagamento. Crédito e referências não reconhecidas permanecem como texto. ### Tentativas de pagamento `GET /v1/payments` lista as tentativas de cobrança. Cada linha carrega `attempt`, um contador baseado em 1 dentro da programação de coleta para sua fatura, e um `status` de `pending`, `processing`, `succeeded`, `failed` ou `refunded`. Várias linhas contra uma fatura é a forma normal de uma sequência de tentativas, não um sinal de cobranças duplicadas. Cada pagamento inclui `invoice`, substituindo o antigo campo `invoice_id`. O objeto incorporado contém os campos de lista de faturas atuais, incluindo `pdf_url`, sem `items`. Ela reflete a fatura quando você lista pagamentos, não um instantâneo da tentativa de cobrança. Se a fatura foi excluída, `invoice` é explicitamente `null`; verifique-o antes de ler `invoice.id` ou outros campos de fatura. Por exemplo, uma resposta com uma fatura disponível e uma fatura excluída: ```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 } } ``` ## O que acontece com uma fatura não paga A cobrança é realizada de acordo com um cronograma fixo a partir do momento em que a fatura é emitida: ```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 ``` Se nenhuma das três tentativas coletar, a fatura se move para `past_due`. **O não pagamento eventualmente lhe custará seus recursos.** No dia 7 a organização é suspensa. No dia 15, ele é encerrado e seus recursos são excluídos depois disso. Cada etapa re-verifica a fatura primeiro, então liquidá-la em qualquer ponto interrompe a sequência imediatamente. Resolver uma fatura `past_due` a partir do console. É também aí que você corrige o método de pagamento que causou as recusas — a API não tem caminho para nenhum deles. ## Permissões | Ação e aventura | Ponto de extremidade | | - | - | | `billing:GetCurrentUsage` | `GET /v1/usage` | | `billing:ListInvoices` | `GET /v1/invoices` | | `billing:GetInvoice` | `GET /v1/invoices/{id}` e seu PDF | | `billing:ListCredits` | `GET /v1/credits` | | `billing:ListTransactions` | `GET /v1/transactions` | | `billing:ListPayments` | `GET /v1/payments` | `GET /v1/prices` não precisa de permissão, porque não precisa de identidade. **As políticas de faturamento não podem ser alargadas a um recurso.** Cada ação de faturamento autoriza contra `*` — o limite da organização é a cerca de todo o conta aqui, uma vez que há uma conta e ela pertence à organização e não a qualquer conta dentro dela. Uma política que concede `billing:GetInvoice` concede-o para cada fatura; não há como restringi-lo a um. Conceda acesso de leitura de faturamento no nível do grupo para as pessoas que precisam, não de forma ampla. Veja [políticas](/pt/iam/policies).