API para revendedores

A API v2 permite consultar o saldo da carteira, listar produtos e criar pedidos de forma programática — o mesmo motor de compra do site, com o mesmo desconto de nível da sua conta. Ideal para lojas, bots e painéis que revendem contas de e-mail.

URL base

Todos os endpoints ficam sob a URL base:

https://viamail.xyz/api/v2

Autenticação

Cada conta tem uma única chave de API ativa, no formato mbr_ + 32 caracteres. Envie a chave em todas as requisições no cabeçalho X-Api-Key:

X-Api-Key: mbr_SUA_CHAVE_AQUI

• A chave completa é exibida uma única vez, no momento da criação. Depois disso, só o prefixo fica visível.
• Gerar uma nova chave revoga a anterior imediatamente — requisições com a chave antiga passam a receber 401.
• Não compartilhe sua chave: quem a possui pode gastar o saldo da sua carteira.

Como obter sua chave

1. Crie sua conta (ou entre) e adicione créditos à carteira comprando um pacote.
2. Abra Minha conta → API para revendedores.
3. Clique em Gerar chave de API e copie a chave exibida — ela não será mostrada de novo.

Formato das respostas

Todas as respostas seguem o mesmo envelope JSON. Valores monetários são sempre centavos inteiros (por exemplo, 990 = R$ 9,90).

{
  "success": true,
  "message": "OK",
  "data": { ... },
  "error": null
}

Em caso de erro, success é false e error.code traz o código da tabela abaixo.

Endpoints

GET /api/v2/wallet/balance — saldo da carteira

curl https://viamail.xyz/api/v2/wallet/balance \
  -H "X-Api-Key: mbr_SUA_CHAVE_AQUI"

Resposta: { "balanceCents": 10000, "currency": "BRL" }.

GET /api/v2/products — listar produtos

Parâmetros de consulta: q (busca por nome/SKU), categoryId, page (padrão 0), size (padrão 20, máx. 100) e sort (newest, price_asc ou price_desc).

curl "https://viamail.xyz/api/v2/products?q=gmail&size=10&sort=price_asc" \
  -H "X-Api-Key: mbr_SUA_CHAVE_AQUI"

Resposta: { items, total, page, size }, cada item com priceCents, stock, outOfStock, deliveryMode e discountPct (desconto exibido do produto).

POST /api/v2/orders — criar pedido

curl -X POST https://viamail.xyz/api/v2/orders \
  -H "X-Api-Key: mbr_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"productId": 1, "quantity": 2}'

O valor é debitado do saldo já com o desconto do seu nível, quando houver. Produtos de entrega automática retornam o pedido DELIVERED com os dados de acesso em items[].data; produtos sob encomenda retornam PENDING até a entrega manual. A resposta inclui subtotalCents (preço cheio), discountPercent, discountCents e totalCents (valor efetivamente pago).

GET /api/v2/orders — meus pedidos

Lista apenas os pedidos da conta dona da chave, com paginação (page, size).

curl "https://viamail.xyz/api/v2/orders?page=0&size=10" \
  -H "X-Api-Key: mbr_SUA_CHAVE_AQUI"

GET /api/v2/orders/{id} — detalhe do pedido

curl https://viamail.xyz/api/v2/orders/123 \
  -H "X-Api-Key: mbr_SUA_CHAVE_AQUI"

Quando o pedido está DELIVERED, a resposta inclui os dados entregues. Pedidos de outras contas retornam 404 NOT_FOUND.

Códigos de erro

Níveis e desconto

Compras pela API usam o mesmo nível da conta no site: o desconto é calculado sobre o total acumulado em pedidos entregues (nível 2: 7% a partir de R$ 500 acumulados; nível 3: 15% a partir de R$ 2.000). O campo discountPercent do pedido mostra o desconto aplicado.