Autenticação e limites da API de revenda

Tokens Bearer, permissões, lista de IPs permitidos, limite de requisições, códigos de erro, chaves de idempotência e paginação da API de revendedores.

Tokens

Um token tem o formato rsk_ seguido de 40 caracteres. Crie-o no painel (aba Revendedor, “API e configurações”); o valor é exibido uma única vez, e guardamos apenas um hash e os últimos 4 caracteres. Você pode ter até 10 tokens ativos e revogar qualquer um a qualquer momento. Ao criar um token, é possível definir um prazo de validade (de 1 a 365 dias): depois dele o token responde 401 token_expired, e expires_at em GET /me informa quando isso acontece (null: sem validade).

Authorization: Bearer rsk_...

Permissões

Um token carrega um conjunto de permissões. As permissões são independentes: keys não implica read. GET /me funciona com qualquer token válido. Sem a permissão necessária, a resposta é 403 forbidden_scope.

A permissão de cada método está listada na referência .

Lista de IPs permitidos

Um token pode ser limitado a uma lista de endereços IPv4/IPv6 ou faixas CIDR (até 20). Uma requisição vinda de outro endereço recebe 403 ip_not_allowed. A lista é definida na criação do token.

Limite de requisições

20 requisições por segundo por token e 100 por segundo por endereço IP de origem. Ao exceder: 429 rate_limited e o cabeçalho Retry-After. Aguarde esse número de segundos e tente de novo.

Erros

Todo erro tem o mesmo formato. O mesmo id é enviado no cabeçalho X-Request-Id: informe-o ao suporte.

{
"error": {
"code": "insufficient_balance",
"message": "Not enough free reseller balance for this key.",
"request_id": "req_..."
}
}

Trate o erro por error.code, não pelo texto da mensagem.

Idempotência

Os métodos que gastam dinheiro exigem o cabeçalho Idempotency-Key (de 1 a 128 caracteres imprimíveis); sem ele (ou com um inadequado) a resposta é 400 idempotency_key_required. Eles estão marcados na referência. Repetir uma requisição com o mesmo Idempotency-Key e o mesmo corpo (por revendedor) nunca gasta duas vezes e retorna o mesmo objeto, inclusive o segredo da chave criada por aquela chamada: uma resposta perdida no caminho pode ser recuperada repetindo a chamada. O mesmo Idempotency-Key com outro corpo dá 409 idempotency_key_reused. Use um Idempotency-Key novo para cada pagamento ou pedido novo; em POST /orders a identidade é external_order_id. O cabeçalho é opcional (e respeitado, se enviado) em PATCH /keys/{id} (um extend_days/extend_hours repetido prorroga uma só vez), POST /plans e POST /webhooks (uma repetição retorna o mesmo objeto; o segredo de um webhook não é exibido de novo).

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"client-1","limit_usd":"10.00"}'

Guarde a chave de idempotência junto com o registro do seu próprio pedido, para que, depois de um erro de rede, você repita exatamente a mesma requisição.

Paginação

Os endpoints de listagem aceitam ?limit=1..100 (padrão 50) e &cursor=. A resposta é {"items": [...], "next": "<cursor>"}; next é null na última página. O cursor é opaco: devolva-o como está.

curl -s "https://app.oneprovider.dev/partner/v1/keys?limit=100&cursor=<next from the previous page>" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Sandbox

Os tokens de teste rsk_test_... chegam em breve. Por enquanto, esse token recebe 501 sandbox_not_implemented.