A Selectwin API foi desenvolvida seguindo os melhores padrões REST, proporcionando uma integração simples e eficiente para qualquer aplicação. As operações são realizadas por meio de requisições aos endpoints, utilizando os verbos HTTP apropriados e corpos de mensagem no formato JSON. As respostas são facilmente interpretadas por meio dos códigos de status HTTP, garantindo uma experiência de integração clara e intuitiva, independentemente da linguagem de programação escolhida.

Além disso, disponibilizamos uma chave de testes, permitindo que as integrações sejam realizadas com total segurança, sem o risco de realizar cobranças reais nos cartões de crédito. Dessa forma, você pode testar à vontade e garantir o perfeito funcionamento antes de ir para produção.

• Customers: Gerenciamento completo de clientes, incluindo criação, consulta, atualização e exclusão
• Addresses: Gerenciamento de endereços para clientes e empresas

• Transactions: Processamento e gerenciamento de transações financeiras com múltiplos métodos de pagamento.
• Subscriptions: Gestão de assinaturas recorrentes, incluindo cobrança automática, renovação, e controle dos ciclos de pagamento.
• Wallets: Gerenciamento de carteiras digitais para armazenamento seguro de métodos de pagamento.
• Finance: Operações financeiras, balanços, saques e relatórios de recebíveis.
• Cards: Gerenciamento seguro de cartões de crédito e débito

• Utils: Funções utilitárias como validação de BIN de cartão, consulta de CEP e listagem de bancos
• Webhooks: Sistema robusto de notificações em tempo real para eventos da plataforma, dividido em Endpoints (configuração) e Events (histórico e reenvio)

Para se autenticar na API, você precisa obter sua credential selectKey. Acesse sua conta na dashboard da Selectwin para coletar suas credenciais.

As chamadas de testes e de produção devem ser feitas para o respectivo endpoint. O que definirá se a transação usará o simulador ou seguirá o fluxo de produção será a chave utilizada.

Todas as requisições à API devem incluir suas credenciais no cabeçalho da requisição:

curl -X GET "https://api.selectwin.io/v1/*" \
     -H "SelectKey: sl_abc123..." \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Nossa API valida todos os campos enviados na requisição antes de prosseguir com a criação, consulta ou gerenciamento de pedidos, transações e recursos disponíveis.

A API segue os códigos de resposta padrão do HTTP para indicar o sucesso ou falha de uma requisição. Códigos 2xx indicam respostas bem-sucedidas, enquanto códigos 4xx referem-se a erros nos dados fornecidos, como omissão de um campo obrigatório ou envio de um cartão sem validade. Códigos 5xx indicam problemas nos nossos servidores, que estamos empenhados em resolver.

Quando ocorre um erro, a API retorna um objeto JSON com informações detalhadas sobre o problema. Abaixo estão os atributos do objeto de erro:

Exemplo de resposta de erro:

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "payment[card][numbering]": "The credit card number is invalid."
      }
    ],
    "suggestedActions": [
      "Check if the credit card number is correct",
      "Check if the credit card is not expired"
    ],
    "docUrl": "https://docs.selectwin.io/errors/validation",
    "supportUrls": [
      "https://suporte.selectwin.io/ajuda"
    ]
  }
}

A Selectwin API oferece suporte a buscas em massa por meio dos métodos de listagem, permitindo a recuperação eficiente de grandes volumes de dados, como usuários, assinaturas, pedidos e outros recursos. Todos esses métodos seguem uma estrutura comum que inclui paginação e filtros.

Por padrão, nossa API suporta os seguintes parâmetros de paginação:

• sort: Especifica a direção da ordenação (ascending para ascendente, descending para descendente).
• offset: Define a partir de qual ponto nos resultados a consulta deve começar a retornar dados.
• limit: Define o número máximo de registros retornados pela consulta.

Esses parâmetros permitem um controle refinado sobre os resultados retornados, facilitando a navegação por grandes conjuntos de dados.

Todas as respostas de listagem seguem um formato padrão, onde apenas o conteúdo do array data varia de acordo com o recurso consultado:

{
  "offset": 0,
  "limit": 10,
  "total": 6,
  "page": {
    "offset": {
      "first": 0,
      "prev": 0,
      "next": 0,
      "last": 0
    },
    "current": 1,
    "total": 1
  },
  "hasMore": false,
  "data": [
    {
      // Dados específicos do recurso consultado
      "id": "wbe_abc1234567890xyz",
      "name": "Nome do Recurso",
      // Outros atributos específicos...
      "updatedAt": "2025-01-26T10:15:00.000Z",
      "createdAt": "2024-07-15T08:45:00.000Z"
    },
    // Mais itens...
  ]
} 

Para garantir a segurança na troca de informações, é necessário que nossos servidores sejam liberados no seu ambiente. Recomendamos fortemente que você libere o domínio: api.selectwin.io.

Como uma empresa certificada com PCI Compliance, seguimos padrões rigorosos de segurança na troca de informações com nossa API. Seguem as configurações aceitas:

• TLS 1.2
• TLS 1.3 (Recomendamos fortemente a utilização deste protocolo)

• SHA256
• SHA384
• SHA512

• Com criptografia igual ou superior a 128 bits

A Selectwin utiliza uma tecnologia que provisiona automaticamente os certificados digitais para as aplicações dos seus domínios. Esses certificados têm validade de 90 dias. Por isso, recomendamos que os clientes enviem transações para o nome completo (FQDN) dos endpoints da nossa API.

Importante: Não recomendamos o pinning de certificados com a chave pública.

Para garantir a eficiência e a performance da nossa API, o uso de polling — a prática de fazer requisições repetidas em intervalos curtos para verificar o status de transações ou recursos — não é permitido.

Em vez disso, recomendamos o uso de webhooks para notificações em tempo real. Com os webhooks, sua aplicação será automaticamente informada quando houver uma mudança no status de uma transação, eliminando a necessidade de consultas frequentes e garantindo uma integração mais eficiente e escalável.

Caso o polling excessivo seja detectado, nos reservamos o direito de limitar ou suspender o acesso à API para evitar sobrecarga no sistema.

Para configurar webhooks, utilize os endpoints de Webhooks Endpoints (/v1/webhooks/endpoints) e Webhooks Events (/v1/webhooks/events) conforme documentado nas seções correspondentes.