Pedidos da API de revenda

Monte a sua própria loja: o cliente paga a você, você chama POST /orders e recebe uma chave. Idempotência por external_order_id e recargas de chaves existentes.

O fluxo de vendas

1. O seu cliente paga a você no seu site, pelo seu próprio checkout (a OneProvider não participa desse pagamento).
2. O seu servidor recebe a confirmação do pagamento e chama POST /orders.
3. A OneProvider reserva o limite da chave no seu saldo de revendedor (o dinheiro é debitado conforme é gasto) e cria um pedido com o status completed.
4. Você entrega ao cliente a chave da resposta e, se quiser, o dashboard_url.

Um pedido ou emite uma chave nova (kind: "new_key") ou recarrega uma existente (kind: "topup" quando key_id é informado).

Criar um pedido

O que entregar é definido por um plano (plan_id, veja Códigos e planos ) ou diretamente por um valor: limit_usd e expires_days ou expires_hours. O cliente pode ser informado como customer_id ou customer_external_id (um cliente criado antes). Os campos charged_amount e charged_currency registram o que o cliente pagou a você; eles alimentam GET /stats e não afetam o débito.

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1042" \
-H "Content-Type: application/json" \
-d '{
"external_order_id": "shop-1042",
"limit_usd": "10.00",
"expires_days": 30,
"customer_external_id": "user-77",
"name": "anna-main",
"charged_amount": "890.00",
"charged_currency": "RUB"
}'

{
"id": 42,
"external_order_id": "shop-1042",
"status": "completed",
"kind": "new_key",
"key_id": "<key id>",
"amount_usd": "10.00",
"charged_amount": "890.00",
"charged_currency": "RUB",
"created_at": "2026-10-08T12:00:00Z",
"key": {
"id": "<key id>",
"name": "anna-main",
"status": "active",
"limit_usd": "10.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}
}

key é o objeto da chave (como na resposta de emissão), o segredo está em key.key. Ele só vem para uma chave nova, na resposta de POST /orders (e em uma repetição exata dela); GET /orders e GET /orders/{id} não o trazem. Guarde o segredo na mesma transação em que registra o pedido. Quando o pedido é feito a partir de um plano sem prazo (expires_never), a chave tem expires_at null.

Idempotência por external_order_id

external_order_id é o número do pedido no seu sistema. Repetir uma requisição com o mesmo número e os mesmos parâmetros não emite uma segunda chave nem debita duas vezes: você recebe de volta o mesmo pedido e a mesma chave (com o mesmo segredo, então uma resposta perdida no caminho pode ser recuperada repetindo a chamada). O mesmo número com parâmetros diferentes dá 409 external_order_id_conflict. Isso torna seguro tentar de novo depois de um tempo esgotado ou de uma conexão interrompida. Você encontra um pedido com GET /orders?external_order_id=shop-1042.

Recarregar uma chave existente

Informe key_id e um valor (limit_usd ou um plano):

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1043" \
-H "Content-Type: application/json" \
-d '{"external_order_id":"shop-1043","key_id":"<key id>","limit_usd":"10.00","charged_amount":"890.00","charged_currency":"RUB"}'

Na resposta, kind é topup e não há segredo. O valor é somado ao limite total da chave e, como tudo, precisa caber em Disponível (Free): ele é reservado e debitado conforme é gasto.

Exemplo de tratamento do pagamento (Python)

import os
import requests
BASE = "https://app.oneprovider.dev/partner/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["OP_PARTNER_TOKEN"]}
def fulfil_paid_order(order_no: str, user_id: str, plan_id, paid: str, currency: str) -> dict:
"""Call it after YOUR payment provider confirmed the payment (it may be called twice)."""
r = requests.post(
BASE + "/orders",
headers={**HEADERS, "Idempotency-Key": "order-" + order_no},
json={
"external_order_id": order_no,
"plan_id": plan_id,
"customer_external_id": user_id,
"charged_amount": paid,
"charged_currency": currency,
},
timeout=30,
)
if r.status_code == 409 and r.json()["error"]["code"] == "insufficient_balance":
raise RuntimeError("Top up the reseller balance, then retry the same call")
r.raise_for_status()
order = r.json()
# order["key"] (the key object, the secret is order["key"]["key"]) is present on a new_key order, a repeat returns it again
return order

Acompanhe available_usd e assine o webhook balance.low para recarregar antes que um pedido receba 409 insufficient_balance. Veja Webhooks .