Carteiras externas

Uma carteira externa é um serviço que você opera, que guarda o orçamento compartilhado de cada cliente e que uma implantação dedicada do Nodaro Cloud consulta antes de gastar. O Nodaro pede à carteira que reserve créditos antes de cada geração, liquida o valor exato depois e lê o saldo para mostrá-lo ao cliente. A conta de cobrança da implantação continua pagando o uso da plataforma com o próprio saldo pré-pago; a carteira decide quanto disso cada cliente pode usar, em todos os seus produtos.

Como as peças se encaixam

• Uma conta de cobrança paga. A implantação define uma conta de cobrança (billing.payerAccount no perfil de superfície da implantação), cujo saldo pré-pago paga todas as ações da implantação. Veja Edições e perfis de superfície.
• O SSO identifica o cliente. Os clientes entram pelo provedor de SSO da implantação. O subject que o provedor atribui a um cliente, enviado como sso_subject, é como a sua carteira reconhece o cliente.
• A carteira decide. Em cada requisição de nó individual e em cada nó de workflow, o Nodaro verifica o saldo pré-pago da conta de cobrança e depois pede à sua carteira uma reserva no orçamento compartilhado do cliente. O saldo local de créditos do Nodaro do cliente não é considerado.

Um saldo pré-pago vazio pode interromper uma requisição antes de a carteira ser consultada. Depois da consulta, a decisão da carteira é final para o orçamento compartilhado do cliente.

Configurar a implantação

Defina estas variáveis na API e nos workers:

• Defina as três primeiras juntas. Deixe as três sem valor para manter a cobrança atual da implantação.
• Desative os limites de uso locais. A aplicação dos limites de uso por usuário, billing.allowances: "enforce", precisa estar desativada. Uma configuração que combina os dois é recusada na ativação.
• Combine a unidade antes. Antes de ativar a carteira, combine a conversão entre os créditos do Nodaro e o orçamento do seu produto. Defina billing.unitRate e billing.unitLabel no perfil de superfície de acordo com essa conversão, para que os dois produtos mostrem o mesmo número.

O contrato das requisições

O Nodaro envia toda chamada como um POST com um corpo JSON que traz contract: 1 e unit: "nodaro_credit", e o cabeçalho Authorization: Bearer <token>. Os valores são créditos do Nodaro. Nunca os interprete como unidades do seu próprio produto sem uma conversão explícita, controlada pela sua carteira.

Reservar

{
  "contract": 1,
  "unit": "nodaro_credit",
  "action": "reserve",
  "operation_id": "a3354131-4e5e-43a6-8f61-3914f09c658e",
  "job_id": null,
  "user_id": "5bf0d884-47b1-468e-a7b2-2433f957b267",
  "sso_provider": "partner",
  "sso_subject": "customer-123",
  "model_identifier": "example-model",
  "reserved_credits": 30
}

Reserve o valor de forma atômica no orçamento compartilhado disponível do cliente antes de responder. Para permitir a requisição:

{"contract":1,"unit":"nodaro_credit","operation_id":"a3354131-4e5e-43a6-8f61-3914f09c658e","decision":"allow","reserved_credits":30}

Para saldo insuficiente ou uma conta que não pode gastar, responda HTTP 200 com o mesmo envelope e "decision": "deny"; nenhum valor é necessário. Em caso de erro no serviço, responda com um status fora da faixa 2xx.

Nada chega ao modelo sem a permissão da sua carteira. Um timeout, uma resposta malformada, um valor ou id divergente, uma identidade ausente e uma recusa interrompem a requisição. O cabeçalho Idempotency-Key da requisição é <operation_id>:reserve.

Liquidar ou liberar

Quando o trabalho termina, o Nodaro envia os mesmos campos da operação com "action": "settle" e actual_credits. Cobre exatamente esse valor e libere o restante da reserva. Uma liquidação de 0 libera tudo.

{"contract":1,"unit":"nodaro_credit","operation_id":"a3354131-4e5e-43a6-8f61-3914f09c658e","settled":true,"actual_credits":12}

• A chave é <operation_id>:settle. A entrega acontece pelo menos uma vez. Uma nova tentativa precisa devolver o resultado original sem cobrar de novo.
• Recuse conflitos. Rejeite uma requisição para a mesma operação com identidade, teto de reserva ou valor final diferente.
• Uma liquidação pode chegar antes de uma reserva atrasada. Uma liquidação de 0 precisa criar um registro final permanente, mesmo para uma operação que você ainda não conhece. Uma reserva posterior nunca pode reabrir esse registro.
• As reservas nunca expiram. Uma geração, e uma revisão humana do resultado dela, podem durar mais que qualquer requisição HTTP. Mantenha cada reserva até ela ser liquidada, e guarde os seus registros de idempotência. Nunca libere uma reserva ativa porque um callback está atrasado.

Saldo

{"contract":1,"unit":"nodaro_credit","action":"balance","user_id":"5bf0d884-47b1-468e-a7b2-2433f957b267","sso_provider":"partner","sso_subject":"customer-123"}

{"contract":1,"unit":"nodaro_credit","sso_subject":"customer-123","available_credits":250}

• Disponível significa depois das reservas. available_credits exclui todas as reservas em aberto, em todos os seus produtos.
• Aqui, frações são permitidas. O saldo pode ser fracionário, então um resto menor que um crédito cobrável ainda pode ser mostrado. Os valores de reserva e de liquidação são sempre créditos inteiros.
• Um único número no estúdio. O estúdio converte o saldo uma vez para a unidade de exibição da implantação e oculta a própria exibição do limite de uso por usuário. Um saldo indisponível aparece como desconhecido.
• A reserva decide as disputas. Quando requisições chegam ao mesmo tempo, quem vale é a chamada de reserva, e não o saldo.

Entrega e recuperação

• O Nodaro tenta entregar cada liquidação na hora. Se isso falhar, um worker executado a cada minuto tenta de novo, com um backoff de até uma hora. As liquidações sem confirmação são guardadas até serem entregues.
• Por conta própria, o Nodaro cancela só as reservas que nunca foram autorizadas. Os jobs autorizados em execução seguem a recuperação normal de jobs.
• Nunca remova a configuração da carteira, nem a aponte para outra carteira, enquanto houver operações em aberto. Para rotacionar o token, rotacione-o na mesma carteira.

Descoberta de preços

GET /v1/deployment-billing/pricing devolve a tabela de preços da implantação, para a exibição e o planejamento da sua própria carteira. O endpoint exige a sessão da conta de cobrança ou uma das chaves de integração de cobrança dela.

• As variantes de mídia e as operações de texto são resolvidas pelos preços em vigor. Uma variante sem preço configurado fica null, com um código de erro.
• Configurações, quantidade, duração e uso medido podem mudar a cobrança final. Faça a contabilidade com os valores de reserva e de liquidação, nunca com uma tarifa base desta lista.
• Para detectar mudanças, prefira uma requisição completa com If-None-Match. O parâmetro since acompanha os timestamps das linhas de preço e não enxerga todas as mudanças de configuração em tempo de execução.