Visão geral

Introdução

O recurso de Carteiras é um componente fundamental da Selectwin API, permitindo o gerenciamento de contas bancárias para recebimento de valores de transações processadas pela plataforma. Este recurso possibilita configurar múltiplas contas de destino para liquidação, com suporte para diferentes bancos e tipos de conta, facilitando a gestão financeira de sua empresa.

A API de Carteiras foi projetada com foco na segurança, integração bancária e flexibilidade, permitindo que os desenvolvedores implementem soluções robustas para gestão financeira e recebimento de valores.

Conceito e Funcionalidade

As carteiras representam contas bancárias dentro da plataforma, armazenando de forma segura as informações necessárias para processar transferências e liquidações financeiras. Este recurso permite que os vendedores configurem destinos para recebimento dos valores provenientes de vendas e outras operações financeiras.

Cada carteira está associada a um vendedor específico e pode ser utilizada em diversas operações financeiras, como recebimento de liquidações, saques e transferências. Uma carteira pode ser marcada como principal, sendo utilizada como destino padrão para as liquidações automáticas.

Estrutura do Objeto Carteira

O objeto Carteira contém informações detalhadas sobre a conta bancária, titular e configurações. A estrutura completa (create/read) inclui:

{
  "id": "wall_01hqzvabc",
  "name": "Minha Carteira Principal",
  "holderName": "João Santos",
  "bankName": null,
  "bankCode": "260",
  "routingNumber": "0001",
  "accountNumber": "11111111-5",
  "accountType": "checking",
  "pixKey": null,
  "primary": true,
  "enabled": true,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": { "self": { "href": "https://api.selectwin.io/v1/wallets/wall_01hqzvabc", "method": "GET", "description": "Read a wallet." } }
}

Campos do Objeto

Notas de fidelidade (respostas da API):

• Respostas de recurso (create/read/set-primary) incluem merchant + _links no root.
• List (/v1/wallets): envelope paginado { offset, limit, total, page, hasMore, data, merchant, _links }.
• List-all (/v1/wallets/listall): array simples de carteiras (cada item carrega o objeto completo, mas sem _links).
• Delete: { id, resource:"wallet", deleted:true, merchant, _links }.

Sem campo de status: a carteira não possui um campo status (não há fluxo pending → enabled → rejected). O estado da carteira é descrito pelos booleanos primary e enabled. Não existem endpoints de atualização de dados bancários nem de habilitar/desabilitar pela API pública; a única mutação além de criar/excluir é definir a carteira como principal (set-primary).

Recursos Disponíveis

Webhooks Acionados

Apenas wallet.created e wallet.deleted são emitidos. Não há eventos wallet.pending/enabled/disabled/rejected.

Casos de Uso Comuns

• Marketplace: Configuração de múltiplas carteiras para diferentes vendedores ou lojas
• E-commerce: Configuração de carteira principal para recebimento de valores de vendas
• Gestão Financeira: Direcionamento de recebíveis para diferentes contas baseado em regras de negócio
• Contabilidade: Separação de recebimentos por categoria ou área de negócio
• Empresas com Múltiplas Filiais: Configuração de carteiras específicas para cada unidade

Melhores Práticas

1. Sempre valide os dados bancários antes de criar uma carteira para evitar problemas de liquidação
2. Utilize o campo primary para designar uma carteira como principal quando apropriado
3. Adote nomes descritivos para facilitar a identificação das carteiras
4. Verifique se a carteira existe antes de tentar operações como exclusão
5. Utilize filtros na listagem para localizar carteiras específicas mais facilmente
6. Considere o contexto de uso ao decidir entre criar múltiplas carteiras ou centralizar em uma única
7. Mantenha as informações atualizadas para evitar falhas nas transferências bancárias

Solução de Problemas Comuns

Integração com Outros Recursos

O recurso de Carteiras integra-se com:

• Finance: Carteiras são destinos para saques e liquidações financeiras
• Transactions: Valores processados em transações são direcionados para carteiras
• Webhooks: Notificações em tempo real sobre mudanças de status nas carteiras
• Receivables: Recebíveis são liquidados nas carteiras configuradas