Uma API para pedidos, carteira e marketplace

Um contrato, versionado por data

Todos os endpoints ficam sob /v1 no host da vitrine com a qual você integra. As respostas são JSON, dinheiro é uma string decimal acompanhada de uma moeda ISO 4217 e datas seguem ISO 8601. Toda resposta traz o cabeçalho X-Api-Version com a data do contrato em uso e um X-Request-Id que você pode informar ao suporte. Os erros têm sempre o mesmo corpo: um objeto error com código estável, mensagem legível e detalhes opcionais, mais o request_id.

O arquivo OpenAPI 3.1 descreve cada caminho, esquema e código de erro. Importe-o no seu cliente HTTP ou gerador de código e você terá requisições tipadas para catálogo, pedidos, carteira, anúncios, ofertas e transferências de negociações.

Chaves, escopos e a conta pela qual agem

A chave é criada pelo dono da conta no plano Revendedor e aparece uma única vez; só o hash fica guardado. Ao criá-la, você escolhe os escopos, uma lista opcional de até 20 IPs permitidos e uma validade opcional. A rotação cria uma chave nova com os mesmos escopos e revoga a antiga, então dá para trocar credenciais sem parar a operação. Pedidos feitos com uma chave são debitados da carteira da conta e aparecem no mesmo painel dos pedidos manuais, com a origem marcada como API.

Cada chave herda o limite de requisições por minuto do nível de cliente da conta. Os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset mostram onde você está; ao passar do limite a API responde 429 com Retry-After, e o certo é esperar exatamente esse tempo.

Escritas idempotentes e lotes

Criar pedido é a única chamada que movimenta dinheiro, por isso é protegida duas vezes. Primeiro, o cabeçalho Idempotency-Key é obrigatório: repetir a requisição com a mesma chave devolve o pedido original sem segunda cobrança, e reutilizar a chave com outro corpo é recusado com 409 IDEMPOTENCY_KEY_REUSE. Segundo, uma janela de duplicidade captura o mesmo serviço, link e quantidade enviados de novo em um intervalo curto sem a chave coincidir, devolvendo 409 DUPLICATE_ORDER.

Lotes aceitam até 100 pedidos por chamada. Cada item é validado e cobrado por conta própria, identificado pela chave do lote mais o índice, e a resposta traz um resultado por item, então uma linha ruim nunca trava as demais. Use POST /v1/orders/preview antes quando quiser o valor exato e o resultado da validação sem criar nada.

• Gere um UUID por pedido lógico e guarde-o antes de enviar.
• Em timeout, reenvie com a mesma chave; nunca gere outra para o mesmo pedido.
• Trate códigos 4xx como finais e 5xx e 429 como repetíveis com backoff.

Webhooks em que você pode confiar

Toda mudança de estado é gravada em um outbox na mesma transação de banco da própria mudança, e um despachante a entrega no seu endpoint https com três cabeçalhos: Webhook-Id, Webhook-Timestamp e Webhook-Signature. A assinatura é um HMAC-SHA256 do timestamp, um ponto e o corpo bruto, calculado com o segredo do endpoint mostrado uma vez na criação. Verifique em tempo constante, rejeite timestamps com mais de cinco minutos e deduplique pelo Webhook-Id, porque um evento reenviado carrega o mesmo id.

Entregas que não recebem 2xx são repetidas após 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas e 24 horas antes de serem marcadas como mortas. Responda rápido e processe de forma assíncrona; um handler lento é a causa mais comum de processamento duplicado.

Painéis filhos pelo endpoint SMM v2

Se o seu painel já fala o formato “SMM API v2”, amplamente usado no mercado, basta adicionar esta vitrine como fornecedor colando a URL /api/v2 e a sua chave. As ações services, add, status, balance, refill, refill_status e cancel são suportadas, os preços voltam na moeda e no nível da sua conta, e os erros usam o formato plano { "error": "mensagem" } que esses painéis esperam. A idempotência é derivada do conteúdo do pedido e do minuto atual, então envios duplicados por acidente dentro do mesmo minuto são unificados.