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) e ordens de saque automático (/v1/withdrawals/auto).
• 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 histórico de movimentações (/balance/history).

#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.

#Marketplace (sub-contas)

• Marketplace: para contas habilitadas como plataforma — estado da função (/v1/marketplace), sub-contas (create, list, read, taxa simples e plano), o link de credenciamento (KYC) de cada sub-conta (generate, status, revoke) e os planos de taxas (CRUD + atribuição). A cobrança em nome da sub-conta é o onBehalfOf de Transactions e Checkouts. Nota: recurso de conta — escritas só com chave de produção (sk_live_); respostas sem merchant/_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, singles de webhook endpoints, delete de auto-cashout, list-all/analytics em vários casos). Listas padrão paginadas geralmente incluem merchant + _links. A especificação OpenAPI é a regra exata 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 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 especificação OpenAPI e o guia de cada recurso.