Códigos e planos da API de revenda
Emita lotes de códigos resgatáveis, revogue-os, resgate um código em uma chave e gerencie seus planos pela API de revenda da OneProvider. Com exemplos.
Emita lotes de códigos resgatáveis, revogue-os, resgate um código em uma chave e gerencie os seus planos pela API de revendedores.
Todos os modelos, recursos e preços Índice da documentação para agentes de IA:https://oneprovider.dev/docs/llms.txt Lotes de códigos
Um lote é criado com POST /code-batches (permissão codes; o cabeçalho Idempotency-Key é obrigatório): label, count até 200, amount_usd até 5000 por código. Opcionais: key_expires_days ou key_expires_hours (por quanto tempo a chave vive depois que o código é ativado, padrão 90 dias), ou key_expires_never: true (uma chave sem validade, o limite continua valendo; não junto com um prazo), e codes_valid_until (até quando um código pode ser ativado, ISO 8601, no futuro e no máximo 2 anos adiante; depois disso os códigos não ativados são revogados automaticamente e a reserva é liberada).
curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: batch-oct-001" \
-H "Content-Type: application/json" \
-d '{"label":"October promo","count":50,"amount_usd":"5.00","key_expires_hours":24,"codes_valid_until":"2026-12-31T23:59:59Z"}'Um lote apenas reserva o seu custo (count x amount_usd) no saldo de revendedor: ele precisa caber em Disponível (Free), mas nada é debitado. Quando um código é ativado, ele vira uma chave cujo limite continua reservado, e o dinheiro é debitado conforme é gasto. Revogar códigos não ativados libera a reserva. Objeto do lote: id, label, count, amount_usd, used, revoked, key_expires_hours, key_expires_days, key_expires_never, codes_valid_until, created_at (key_expires_hours e key_expires_days são null tanto em um lote sem validade de chave quanto em um lote com o padrão de 90 dias: key_expires_never distingue os dois). GET /code-batches/{id} também traz activations: quem ativou qual código e quando (code_tail, redeemed_at, key_id), do mais recente ao mais antigo, no máximo 1000; a resposta da revogação também traz revoked_now e refunded_usd.
# list batches, read one, list its codes
curl -s https://app.oneprovider.dev/partner/v1/code-batches -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s https://app.oneprovider.dev/partner/v1/code-batches/<batch id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s "https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/codes?status=active&limit=100" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# revoke what is still unredeemed
curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/revoke -H "Authorization: Bearer $OP_PARTNER_TOKEN"Objeto do código: code, status (ativo, resgatado, revogado: active/used/revoked), amount_usd, batch_id, redeemed_at, key_id. Status de um código: GET /codes/{code}.
Resgatar um código pela API
Se você mesmo transforma um código em chave, chame POST /codes/{code}/redeem (o cabeçalho Idempotency-Key é obrigatório). O cliente pode ser informado como customer_id ou customer_external_id.
curl -s -X POST https://app.oneprovider.dev/partner/v1/codes/<code>/redeem \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: redeem-<code>" \
-H "Content-Type: application/json" \
-d '{"customer_external_id":"user-77"}'A resposta 201 contém a chave e o segredo dela (repetir a mesma chamada com o mesmo Idempotency-Key retorna a mesma chave). Um código já resgatado de outra forma dá 409 code_used, um revogado dá 409 code_revoked; customer_id junto com customer_external_id dá 400 invalid, um cliente bloqueado dá 409 customer_blocked.
Planos
Um plano é o seu preço para os clientes: quantos USD a chave recebe, quanto o cliente paga a você, em qual moeda e por quanto tempo. Os planos alimentam POST /orders (o parâmetro plan_id). O máximo é de 20 planos (409 plan_limit). Ler os planos exige a permissão read, alterá-los exige plans.
| Campo | Descrição |
|---|---|
name | Nome, até 40 caracteres. |
balance_usd | O valor que a chave recebe. |
price, currency | O seu preço para o cliente e a moeda dele: USD, RUB, XTR ou USDT. |
expires_days / expires_hours | Vida útil da chave: de 1 a 365 dias ou de 1 a 8760 horas (uma das duas; padrão 30 dias). A resposta traz expires_hours (a fonte da verdade); expires_days é null quando a vida útil não é um número inteiro de dias. |
expires_never | true: as chaves do plano nunca vencem (o limite de saldo continua valendo). Não junto com expires_days ou expires_hours (400 invalid). A resposta então traz expires_hours e expires_days como null. |
sort, active | Ordem de exibição e o indicador de ativo. |
curl -s -X POST https://app.oneprovider.dev/partner/v1/plans \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Start 10 USD","balance_usd":"10.00","price":"890.00","currency":"RUB","expires_days":30,"sort":1,"active":true}'
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" -d '{"active":false}'
curl -s -X DELETE https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"GET /pricing retorna os limites a respeitar: valor mínimo e máximo da chave, vida útil máxima, valor máximo do código, tamanho do lote, o número máximo de planos e de tokens, o número máximo de chaves ativas (key_limit) e plan_currencies (as moedas dos planos). Um plano pode ser criado com um Idempotency-Key (opcional): uma repetição retorna o mesmo plano em vez de um segundo. Um PATCH que não menciona a vida útil a deixa como estava. Excluir, aumentar o preço e trocar a moeda são recusados enquanto houver uma compra aberta no bot com o plano (409 plan_in_use).