API para revendedores - documentação técnica

Última atualização:

API para revendedores - documentação técnica
Integre sua própria loja, bot ou painel direto com a SuperCoinsy. Consulte estoque e preços em tempo real, crie e pague pedidos, acompanhe o status e converse com a nossa equipe: tudo sem abrir o painel de revendedor. Abaixo está o que o seu dev precisa: como liberar o acesso, como autenticar as requisições e o que cada endpoint devolve.
O que você precisa antes de começar
Uma conta de revendedor ativa
A API trabalha em cima do seu saldo de revendedor. Os pedidos são debitados dele, então faça uma recarga antes da primeira chamada.
Acesso à API liberado pelo nosso admin
É uma liberação única, feita do nosso lado. Escreva para [email protected] ou chame no Discord em supercoinsy que a gente ativa na sua conta.
Um IP fixo
Cada usuário de API fica preso ao IP de onde pode se conectar. Deixe o endereço em mãos antes de criar o primeiro token.
Como obter o seu token de acesso
1
Peça a ativação do acesso à API na sua conta de revendedor, pelos contatos acima.
2
Com o acesso ativo, abra supercoinsy.com/account/reseller/api-users: é ali que você gerencia todos os seus usuários de API.
3
Clique em CREATE e informe o IP de onde vai se conectar. Requisições de qualquer outro endereço são recusadas. Você pode colocar * para pular a verificação de IP, mas assume o risco. Isso vale só na API v1.
4
Copie o token de 60 caracteres e guarde em lugar seguro: ele aparece uma única vez e não dá para exibir de novo. Ao lado dele fica também um identificador de 6 caracteres, que marca o seu usuário de API nos nossos logs de operação.
5
Clique em Turn ON na tabela para ativar o usuário de API. A partir daí a conexão funciona. Você pode desligar temporariamente ou apagar de vez a qualquer momento.
Dá para manter vários usuários de API em paralelo, por exemplo um para a loja em produção e outro para testes, cada um com seu próprio IP e seu próprio token.
Autenticação
A autenticação vai nos headers da requisição. Todas as três linhas são obrigatórias, e a chamada precisa sair do IP atribuído àquele usuário de API.
Content-Type: application/json
X-Authorization: <seu token de 60 caracteres>
X-UserID: <seu identificador de 6 caracteres>
Endereço base
Todos os endpoints ficam sob https://supercoinsy.com/api/ e todas as respostas são JSON.
Endpoints (clique para abrir)
GET - Estoque disponível
Mostra o que conseguimos entregar agora, por plataforma. Boa primeira chamada antes de liberar o botão de compra na sua loja.
GET https://supercoinsy.com/api/reseller/available-stock
Resposta
{
  "status": 1,
  "data": [
    { "platform": "PC", "stock_available": 10 },
    { "platform": "PS5, PS4, XSX, XSS, XONE, Stadia", "stock_available": 10 }
  ]
}
GET - Preços atuais
O seu preço de revendedor por plataforma. Puxe com frequência em vez de fixar valores no código, assim a sua margem não escapa.
GET https://supercoinsy.com/api/reseller/prices
Resposta
{
  "status": 1,
  "data": [
    { "platform": "PC", "price": "1.00" },
    { "platform": "PS5, PS4, XSX, XSS, XONE, Stadia", "price": "2.00" }
  ]
}
POST - Criar e pagar um novo pedido
Cria o pedido e já debita do seu saldo de revendedor na mesma chamada. Se o saldo não cobrir, o pedido não é criado.
POST https://supercoinsy.com/api/reseller/new-transaction
Parâmetros
quantity (obrigatório) - valor em K, ou seja, 150 significa 150.000 coins.
platform (obrigatório) - pc ou ps. Atenção: ps cobre todos os consoles, PlayStation, Xbox e Stadia igualmente.
emailapp (obrigatório) - o e-mail da conta EA usado para entrar no WebApp.
passapp (obrigatório) - a senha dessa conta EA.
codesapp (obrigatório) - backup codes da EA, separados por vírgula. Mande pelo menos três novos.
userorderid (opcional) - a sua própria referência de pedido; volta no campo your_id.
usernotes (opcional) - uma observação para a nossa equipe.
Corpo da requisição
{
  "quantity": 150,
  "platform": "pc",
  "emailapp": "[email protected]",
  "passapp": "pass-app-test1",
  "codesapp": "one, two, three",
  "userorderid": "MY-ID2586",
  "usernotes": "please process quickly"
}
Resposta
{
  "status": 1,
  "message": "Payment accepted",
  "number": "R_QWERTY"
}
Guarde o number retornado
O valor de number é o identificador usado em todas as chamadas seguintes: detalhes, mensagens e cancelamento.
GET - Lista de transações
Devolve os seus pedidos paginados, do mais recente para o mais antigo. Use para manter o seu banco sincronizado.
GET https://supercoinsy.com/api/reseller/list-transactions?page=1
page (opcional, inteiro) - sem ele vem a primeira página. A resposta informa quantas páginas existem no total.
Resposta
{
  "total": 10,
  "pages": 1,
  "orders": [
    {
      "number": "R_ABCDEF",
      "placed": "2021-08-17 16:11:57",
      "your_id": "",
      "platform": "PS5, PS4, XSX, XSS, XONe, Stadia",
      "quantity": 100,
      "status": "Paid, waiting for delivery",
      "max_delivery_time": "2021-08-17 18:11:57"
    }
  ]
}
GET - Detalhes da transação
Tudo o que temos sobre um pedido, incluindo os dados que você enviou e o prazo com o qual estamos trabalhando.
GET https://supercoinsy.com/api/reseller/get-transaction/{identifier}?currency=EUR
identifier (obrigatório) - o número do pedido, por exemplo R_ABCDEF.
currency (opcional) - EUR ou USD. Sem ele, o padrão é EUR.
Resposta
{
  "number": "R_ABCDEF",
  "your_id": "TEST123",
  "placed": "2021-08-17 16:11:57",
  "value": "6.40 EUR",
  "platform": "PS5, PS4, XSX, XSS, XONe, Stadia",
  "quantity": 100,
  "emailapp": "[email protected]",
  "passapp": "test_pass",
  "usernotes": "notes-example-text",
  "codesapp": "test_code",
  "status": "Paid, waiting for delivery",
  "max_delivery_time": "2021-08-17 16:11:57"
}
POST - Enviar mensagem para um pedido
Adiciona uma mensagem à conversa do pedido, exatamente como se você tivesse escrito no painel de revendedor. Serve para mandar backup codes novos ou avisar a equipe de qualquer coisa.
POST https://supercoinsy.com/api/reseller/transaction/{identifier}/message
Corpo da requisição
{
  "message": "My new message to the order"
}
Resposta
{
  "status": 1,
  "message": "Message has been sent"
}
GET - Cancelar um pedido
Envia um pedido de cancelamento. É uma solicitação, não um cancelamento imediato: o nosso admin aprova e só então o valor volta para o seu saldo em EUR.
GET https://supercoinsy.com/api/reseller/cancel-transaction/{identifier}
Resposta
{
  "status": 1,
  "message": "A cancellation request has been sent. SC Points will be refund to your account after approval by the admin."
}
API v2 e webhooks
A API v2 funciona ao lado da v1, e a v1 não muda. A v2 traz mais produtos, saldo e histórico do saldo, exportações e webhooks. Quais produtos você pode pedir depende da sua conta: GET /products lista todos.
Token próprio e endereço base
A API v2 tem usuários de API próprios. Crie-os no painel de revenda, em API & webhooks (supercoinsy.com/account/reseller/api-v2). O token da v2 começa com sc2_ e só funciona na v2; um token da v1 não funciona lá. Os cabeçalhos são os mesmos: X-UserID e X-Authorization. Cada usuário de API precisa de uma lista de IPs permitidos: lista vazia recusa todas as requisições. Limites: 120 requisições por minuto por usuário de API e 300 por conta de revenda.
https://supercoinsy.com/api/reseller/v2
Endpoints
GET   /stock
GET   /prices
GET   /products
GET   /orders
POST  /orders          (header Idempotency-Key, up to 20 items, all or nothing)
GET   /orders/{id}
PATCH /orders/{id}/account
POST  /orders/{id}/cancel
GET   /orders/{id}/proof
GET   /orders/{id}/messages
POST  /orders/{id}/messages
GET   /division-rivals/quote
GET   /balance
GET   /ledger
GET   /topups
POST  /exports
GET   /exports/{id}
GET   /webhooks
PUT   /webhooks
POST  /webhooks/rotate
POST  /webhooks/test
GET   /webhooks/deliveries
Os erros voltam em JSON com error e message. A lista completa com exemplos está na página de documentação do painel: supercoinsy.com/account/reseller/api-v2/docs
Códigos (API v2)
A API v2 também cobre códigos: chaves de jogos, assinaturas, gift cards e recargas, e moeda dentro do jogo. Leia o catálogo com GET /codes (um item: GET /codes/{sku}, em que o sku começa com SC-K-). Compre com POST /orders e items[].sku, pagando com o seu saldo. O código é devolvido em GET /orders/{id}. Quais códigos você pode comprar depende da sua conta. Referência completa: página de documentação no painel, supercoinsy.com/account/reseller/api-v2/docs.
Diferenças em relação à v1
  • Quantidade. Coins: quantity_k, em milhares (150 significa 150.000 coins). Códigos, contas e outros produtos do catálogo: quantity, um número inteiro de itens (150 significa 150 itens). GET /products mostra os campos do formulário de cada produto.
  • Plataforma. Coins: pc ou ps. Boosting: pc, ps ou xbox (xbox vale para boosting só de Xbox). Em produtos com um preço único de console, ps cobre PlayStation e Xbox.
  • Backup codes (coins). No mínimo 2, recomendamos 6.
  • Cancelamento. POST /orders/{id}/cancel devolve o valor na hora quando nada começou. Se a entrega já começou, é um pedido que a nossa equipe confirma.
  • Lista de IPs. Endereços públicos e faixas (IPv4 no máximo /16, até 20 entradas). O curinga * só funciona na v1.
Webhooks
  • Defina um endereço https no painel (API & webhooks) ou com PUT /webhooks: porta 443, nome de host (não endereço IP), sem redirecionamentos.
  • Escolha os eventos: order.created, order.status_changed, order.needs_action, order.delivered, order.cancelled, export.ready.
  • Enviamos um POST com corpo JSON: id (do evento), event, created_at e data. Nos eventos de pedido, data é o pedido, no mesmo formato da API. Em export.ready, data traz id (da exportação), kind e ready_at. Em webhook.test, traz test: true e sent_at.
  • Cabeçalhos: X-SC-Event, X-SC-Delivery e X-SC-Signature.
  • Confira a assinatura: X-SC-Signature tem o formato t=<hora unix>,v1=<hex>, onde v1 é o HMAC-SHA256 de "<t>.<corpo>" com o seu segredo (whsec_...). O segredo aparece uma vez; POST /webhooks/rotate gera um novo.
  • Responda com qualquer 2xx em até 4 segundos. Se não, tentamos de novo após 1, 5, 15, 60 e 240 minutos; depois de 6 tentativas a entrega fica como failed.
  • Se mais de 1000 eventos ficarem esperando pelo seu endereço, desligamos o webhook e avisamos por e-mail. Corrija o endereço e ligue o webhook de novo no painel.
  • POST /webhooks/test envia um evento webhook.test. GET /webhooks/deliveries mostra as últimas entregas (até 100; os registros ficam 30 dias).
  • Webhooks existem só na API v2. A API v1 não tem webhooks.
{
  "id": "<event id>",
  "event": "order.delivered",
  "created_at": "2026-11-05T10:15:00Z",
  "data": { "id": "R_A2B3C4", "type": "coins", ... }   (order event)
}
Algumas coisas que vale saber
API v1: quantity é sempre em K
Mande 150 quando quiser dizer 150.000 coins. Mandar o número cheio criaria um pedido mil vezes maior do que o pretendido.
API v1: "ps" significa qualquer console
Só existem dois valores de plataforma. Pedidos de Xbox e Stadia entram como ps, junto com PlayStation: eles compartilham o mesmo pool de entrega.
Backup codes são de uso único
Na v1, mande pelo menos três códigos novos em cada pedido. Códigos já usados num pedido anterior não nos deixam entrar, e o pedido fica parado até você enviar outros.
O status muda por polling ou por webhook
A API v1 não tem callback, então consulte a lista de pedidos ou o endpoint de detalhes num intervalo razoável, sem ficar batendo em loop. A API v2 pode chamar o seu servidor quando o status muda: veja a seção de webhooks acima.
Um token, um IP
Se o seu servidor mudar de endereço, edite o usuário de API antes, senão todas as requisições voltam recusadas. E se um token vazar, desligue aquele usuário e crie outro.
Travou em alguma coisa?
Se alguma requisição se comportar diferente do descrito aqui, conte o que você enviou e o que voltou: a gente olha os logs do nosso lado. Escreva para [email protected] ou chame no Discord em supercoinsy.
Ainda não vai integrar?
Tudo o que a API faz também dá para fazer na mão pelo painel de revendedor: recarregar o saldo, criar pedidos e acompanhar o status.
Guia do painel de revendedor →
Pronto para integrar? Crie o seu usuário de API em supercoinsy.com/account/reseller/api-users
deliver
Verificar

Estado do pedido ou da ordem de venda