Recursos da API

Estrutura de Recursos

A API Selectwin é organizada em torno de recursos RESTful, onde cada recurso representa uma entidade de negócio específica. Todos os recursos seguem uma convenção de nomeação consistente e são acessados por meio de URLs previsíveis que facilitam a integração.

Recursos Principais

A API pública expõe os seguintes recursos (12 principais, com sub-recursos onde aplicável). Todos os identificadores públicos seguem o padrão prefixo_valor (ex.: cus_..., tra_...).

Gestão de Clientes e Relacionados

• Customers: CRUD completo de clientes (com documentos, contatos, endereços e cartões associados em respostas de leitura/criação).
• Addresses: CRUD de endereços (associados a clientes ou empresas).
• Cards: Gerenciamento de cartões tokenizados (create/list/read/delete; dados sensíveis protegidos).

Pagamentos e Transações

• Transactions: Criação, consulta, listagem, analytics e ações (capture, refund, dispute, export). Suporta crédito, PIX, boleto e outros métodos.
• Subscriptions: Assinaturas recorrentes, com ciclos, itens e splits. Operações: create, list, read, cancel + sub-rotas /cycles, /items, /splits.
• Products (e Variants): Catálogo de produtos e variantes com precificação. Listagem otimizada (muitas vezes array direto ou sem merchant/_links), batch create/update de variantes.

Financeiro e Recebimentos

• Wallets: Carteiras/bancos para recebimento (create, list, read, delete; list-all disponível).
• Withdrawals: Saques manuais (listagem, criação e consulta). Regras de saque automático (auto-cashout) existem na plataforma, mas não fazem parte da API pública — são configuradas pelo painel.
• Receivables: Consulta de recebíveis (listagem paginada com projeção completa de 19 campos incluindo expectedOn, grossAmount, anticipationFee; analytics com array list).
• Finance: Saldos (/balance) e saúde de risco do merchant (/risk-health — shape especial sem merchant/_links).

Cupons e Extensões

• Coupons: Gerenciamento de cupons de desconto (list, create, read, update, delete, list-all como array direto). Nota: respostas de cupons não incluem merchant nem _links.

Notificações e Integrações

• Webhooks:
  • Endpoints: Configuração de URLs de notificação (list paged, create/read/update/delete; singles de endpoint não retornam merchant/_links; create retorna secret whsec_...).
  • Events: Histórico de eventos disparados (list com dispatches aninhados).
  • Dispatches: Histórico de entregas por endpoint + reenvio/redispatch.
  • Analytics e resend/redispatch retornam indicadores como sended: true ou redispatched: true.

Observação: Alguns recursos e operações omitem merchant e/ou _links intencionalmente (cupons, produtos/variantes, risk-health, singles de webhook endpoints, delete de auto-cashout, list-all/analytics em vários casos). Listas padrão paginadas geralmente incluem merchant + _links. Consulte a especificação OpenAPI para as regras exatas por operação.

Navegação e Descoberta (HATEOAS)

A API Selectwin implementa o padrão HATEOAS (Hypermedia as the Engine of Application State). A maioria das respostas de sucesso (criação, leitura, listagens paginadas) inclui um objeto _links no nível raiz com links para ações relacionadas e navegação.

Exemplo realista (lista de wallets, fiel à implementação):

{
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "GET",
      "description": "List all wallets."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "POST",
      "description": "Create a new wallet."
    }
  }
}

Outros contextos incluem chaves como read, update, delete, next, capture, refund, dispute etc., dependendo da operação e do recurso.

Importante: Nem todas as respostas incluem _links ou merchant (veja notas em Recursos Principais e a especificação OpenAPI para exceções como cupons, produtos, risk-health e singles de webhook endpoints).

Estes links permitem que sua aplicação descubra dinamicamente os recursos relacionados disponíveis. Para a lista completa de operações, schemas de entrada e exemplos de resposta, consulte a Referência da API e os guias por recurso.