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

Peça a ativação do acesso à API na sua conta de revendedor, pelos contatos acima.

Com o acesso ativo, abra supercoinsy.com/account/reseller/api-users: é ali que você gerencia todos os seus usuários de API.

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.

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.

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/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 os SC Points voltam para o seu saldo.

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."
}

Algumas coisas que vale saber

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.

"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

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

Ainda não existe callback, então consulte a lista de pedidos ou o endpoint de detalhes num intervalo razoável, sem ficar batendo em loop.

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