API de revenda: como funciona

Como funciona a plataforma de revendedores: o saldo de revendedor, a reserva, as chaves de clientes, os códigos, os planos e tudo o que o painel faz por uma API REST para o seu próprio site ou bot.

Como funciona

O revendedor recarrega o próprio saldo a preço de atacado e vende tokens aos seus clientes na forma de chaves e códigos. Tudo o que você faz no painel (a aba Revendedor em app.oneprovider.dev) também está disponível pela API, então você pode montar o seu próprio site, bot ou checkout.

• Saldo de revendedor. Um saldo em USD separado do seu dinheiro pessoal. Você o recarrega a preço de atacado; GET /pricing retorna o preço por 1 USD e o desconto.
• Chaves de clientes. Cada chave tem um limite de gasto em USD e um prazo de validade (uma chave criada a partir de um plano ou de um lote de códigos também pode não ter validade: nesse caso expires_at é null e o limite continua valendo). O seu cliente a usa como qualquer chave da OneProvider.
• Códigos. Lotes de códigos de uso único que você vende onde quiser. Um código ativado vira uma chave cujo limite é igual ao valor do código.
• Planos. Os seus preços para os clientes: valor da chave, preço, moeda e validade. As chaves são emitidas a partir deles por POST /orders.
• Dashboard neutro por chave. Toda chave tem um link dashboard_url: o seu cliente vê o consumo e o saldo restante sem a sua marca e sem que o segredo da chave seja exposto.

A regra do dinheiro: reservar e debitar

O saldo de revendedor tem três números (no bloco abaixo, “Free” é “Disponível” no painel):

Reseller balance (balance_usd) = your money on the platform
Reserved (reserved_usd) = unredeemed codes + remaining limits of live keys
Free (available_usd) = Reseller balance - Reserved

O dinheiro não é debitado quando você cria algo, mas quando o cliente recebe e gasta o valor. Até lá ele fica apenas reservado:

• Um lote de códigos apenas reserva o valor. Revogar códigos não ativados libera a reserva.
• Um código ativado vira uma chave cujo limite continua reservado.
• Emitir uma chave reserva o limite dela; o gasto na chave é debitado do saldo de revendedor.
• Excluir uma chave ou reduzir o limite dela devolve na hora o restante não gasto para Disponível (Free).
• Pausar uma chave mantém a reserva dela.

Toda chave nova, recarga de chave e lote de códigos precisa caber em Disponível (Free); caso contrário, a resposta é 409 insufficient_balance. Os três números vêm de GET /balance: balance_usd, reserved_usd, available_usd.

Primeira requisição

1. No painel, abra a aba Revendedor, “API e configurações”, e crie um token. O valor é exibido uma única vez.
2. Coloque o token em uma variável de ambiente no seu servidor e chame /balance:

export OP_PARTNER_TOKEN="rsk_..."
curl -s https://app.oneprovider.dev/partner/v1/balance \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"balance_usd": "120.00",
"reserved_usd": "35.50",
"available_usd": "84.50"
}

O exemplo mostra apenas alguns dos campos da resposta; o dinheiro é sempre uma string com duas casas decimais. O conjunto completo está na referência de métodos e na OpenAPI .

Recarregar o saldo de revendedor

As formas de pagamento disponíveis e os valores mínimos delas estão em topup_providers de GET /balance. Um pagamento é criado com POST /balance/topups (permissão billing; o cabeçalho Idempotency-Key é obrigatório). Você entrega ao pagador o link de pagamento retornado.

curl -s -X POST https://app.oneprovider.dev/partner/v1/balance/topups \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-2026-10-08-001" \
-H "Content-Type: application/json" \
-d '{"balance_usd":"100.00","provider":"<id from topup_providers>"}'

A resposta contém order_id e pay_url (201). Status do pagamento: GET /balance/topups/{order_id}; o crédito também é anunciado pelo evento de webhook balance.topped_up.

Registro de auditoria

GET /audit (permissão read) retorna o registro de todas as ações na sua conta: feitas pelo painel, por tokens de API e pelo sistema. Os registros são imutáveis (não existe rota de edição nem de exclusão) e nunca contêm segredos: nem chaves, nem tokens, nem códigos, nem segredos de webhook. O objeto aparece de forma resumida: o final de uma chave, o rótulo de um lote ou o nome de um plano.

curl -s "https://app.oneprovider.dev/partner/v1/audit?period=7d&action=key.&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"items": [
{
"id": "<row id>",
"at": "2026-10-08T12:00:00Z",
"actor": { "kind": "token", "label": "shop backend" },
"action": "key.created",
"object": { "type": "key", "label": "anna-main (...4f2a)" },
"money": { "reserve_delta": "25.00", "debit_delta": "0.00", "available_after": "59.50" },
"ip": "203.0.113.7",
"request_id": "req_..."
}
],
"next": null,
"actions": ["key.created", "key.topped_up"]
}

actor.kind é user (o painel), token, system ou bot (o bot de vendas do revendedor). money (null quando a ação não mexeu em dinheiro) mostra as variações, com sinal, da reserva e do débito; available_after pode ser null. A resposta também traz a lista completa de ações em actions:

key.created key.topped_up key.limit_changed key.updated key.paused key.resumed key.exhausted key.rotated key.extended key.expiry_changed key.deleted
code_batch.created code_batch.revoked code_batch.expired code.redeemed
plan.created plan.updated plan.deleted
token.created token.revoked
webhook.created webhook.deleted webhook.tested webhook.retried
balance.topup order.completed
customer.created customer.updated customer.blocked customer.unblocked
settings.updated account.activated

Convenções

• Base URL: https://app.oneprovider.dev/partner/v1.
• JSON em tudo; o dinheiro é uma string em USD com duas casas decimais ("12.50"); os horários são ISO 8601 em UTC (2026-10-08T12:00:00Z).
• Chame a API apenas do seu servidor: não há CORS, e o token nunca deve ir parar em um navegador ou em um app de celular.
• Tokens, permissões, limite de requisições, erros, idempotência e paginação: Autorização e limites .

Próximos passos

• Chaves e clientes : emitir, recarregar, pausar, excluir.
• Pedidos : como montar o seu próprio site.
• Códigos e planos .
• Webhooks : eventos e verificação da assinatura.
• Referência de métodos e openapi.yaml .