X-Account-Id nessas chamadas — a organização que você autenticou é o escopo inteiro.
Preços
Público e não autenticado — todo o catálogo, idêntico para todos.
Uso e faturas
O que está a acumular agora e o que já foi facturado.
Créditos
Como os subsídios são consumidos e onde eles aparecem em uma fatura.
A linha do tempo da coleção
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, o catálogo de preços é público e não requer uma conta selecionada.
É 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.
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
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.Desempenho adicional de volume de bloco
Desempenho do volume provisionado tem preços separados de IOPS-mês e MiB/s-mês emresource_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
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.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
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
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
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
GET /v1/transactions é o livro: payment, refund, adjustment, credit_grant e credit_applied entradas.
Referências de Ledger
Adescription 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:
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.
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:
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: Se nenhuma das três tentativas coletar, a fatura se move parapast_due.
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.
Paginação
GET /v1/invoices, /v1/credits, /v1/transactions e /v1/payments todas as páginas da mesma forma: passe limit (padrão 20, máximo 100) e echo back meta.marker da página anterior.
Permissões
GET /v1/prices não precisa de permissão, porque não precisa de identidade.
Próximo
Limites de taxa
Como os cabeçalhos
X-RateLimit-* funcionam, e assinando cada outra requisição.Políticas
Quem na sua organização pode ler a conta.
Regiões
Por que o faturamento não tem segmento de região.
Referência da API
Todas as operações de faturamento, com esquemas de solicitação e resposta.