Referência da API

Escopo: esta especificação inclui apenas recursos relacionados a: address, card, checkout.payment-links, coupons, customer, finance, product, receivables, subscription, transaction, variant, wallet, webhook, withdrawal.

Introdução

A API Selectwin segue boas práticas REST: você chama os endpoints com os verbos HTTP corretos, envia e recebe JSON e interpreta o resultado pelos códigos de status. Isso vale para qualquer linguagem ou stack.

Oferecemos chaves de sandbox e produção. Em ambiente de testes você valida fluxos sem impacto financeiro real (por exemplo, sem cobrança real em cartão), antes de ir para produção.

Recursos principais

Gestão de clientes

• Customers — CRUD de clientes.
• Addresses — Endereços vinculados a clientes e contextos compatíveis.

Financeiro e pagamentos

• Transactions — Criação e gestão de transações (vários meios de pagamento).
• Subscriptions — Assinaturas, ciclos e cobrança recorrente.
• Wallets — Carteiras para saques e dados bancários.
• Finance — Consultas de saldo e visão financeira da conta.
• Receivables — Listagem e acompanhamento de recebíveis (ex.: /v1/receivables).
• Withdrawals — Saques.
• Cards — Cadastro e gestão segura de cartões.

Notificações

• Webhooks — Notificações assíncronas: configuração em Endpoints e histórico/reenvio em Events.

Autenticação

Todas as requisições autenticadas devem enviar a chave da API no cabeçalho selectkey (o nome HTTP é case-insensitive; em documentação costuma aparecer como SelectKey). Obtenha as chaves no painel Selectwin.

O prefixo da chave indica o ambiente (por exemplo, chaves de teste vs. produção) e o comportamento associado.

curl -sS -X GET "https://api.selectwin.io/v1/transactions" \
  -H "selectkey: sl_live_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Códigos de erro e HTTP

A API valida entradas quando aplicável. Em geral: 2xx sucesso; 4xx erro do cliente (validação, permissão, recurso inexistente); 5xx erro no servidor.

Códigos frequentes

Estrutura típica de erro

Respostas de erro costumam incluir metadados como categoria, mensagem e, quando faz sentido, detalhes por campo.

Paginação

Listagens costumam aceitar sort, offset e limit (nomes e limites exatos podem variar por recurso; veja cada operação no schema).

Formato típico de resposta paginada

O envelope abaixo é representativo: o conteúdo de cada item em data depende do recurso.

{
  "offset": 0,
  "limit": 10,
  "total": 6,
  "page": {
    "offset": { "first": 0, "prev": 0, "next": 0, "last": 0 },
    "current": 1,
    "total": 1
  },
  "hasMore": false,
  "data": [
    {
      "id": "res_abc123",
      "name": "Nome do recurso",
      "updatedAt": "2026-01-26T10:15:00.000Z",
      "createdAt": "2026-07-15T08:45:00.000Z"
    }
  ]
}

Segurança (TLS e PCI)

Libere saída HTTPS para o host api.selectwin.io no seu firewall/proxy quando aplicável.

• TLS: 1.2 e 1.3 (recomendado 1.3).
• Primitivas: SHA-256 / SHA-384 / SHA-512 conforme negociação TLS.
• Cipher suites: preferir suites com criptografia ≥ 128 bits.

Certificados são renovados periodicamente; integre pelo FQDN do endpoint. Não recomendamos certificate pinning pela chave pública.

Polling

Consultas repetidas em curto intervalo para “adivinhar” mudança de status não são o modelo recomendado e podem ser limitadas.

Use webhooks para mudanças de status e eventos. Configure em /v1/webhooks/endpoints e acompanhe em /v1/webhooks/events, conforme esta especificação.

Recursos da API