Autenticação

#Visão Geral

A API Selectwin autentica cada requisição por uma chave de API (API Key) enviada no cabeçalho. Não há login nem token de sessão para renovar: a chave vale até ser revogada ou, se você definir uma validade ao gerá-la, até essa data.

#A Chave SelectKey

Toda requisição à API Selectwin deve incluir uma chave de API válida no cabeçalho HTTP SelectKey. Esta chave identifica sua conta, define permissões e registra as atividades realizadas, garantindo a segurança e a auditoria das operações.

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

#Ambientes e Prefixos

A Selectwin oferece dois ambientes distintos, cada um com seu próprio formato de chave:

O ambiente da requisição é determinado pelo namespace da própria chave (a API resolve o ambiente a partir da chave apresentada). O prefixo é uma conveniência de leitura — permite distinguir uma chave de teste de uma de produção rapidamente:

# Ambiente de sandbox
SelectKey: sk_test_aBcDeFgHiJkLmNoPqRsTuVwXyZ

# Ambiente de produção
SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ

#Obtendo suas Chaves

As chaves de API são geradas no Painel Administrativo da Selectwin:

1. Acesse o Painel Administrativo
2. No seletor ao lado do logo, escolha o ambiente da chave: em Sandbox você gera sk_test_…; em Produção, sk_live_…
3. Navegue até Configurações → Desenvolvedores
4. Na seção Chaves de API, clique em Gerar chave

Ao gerar, você define:

Só o proprietário da conta gera chaves de API.

Webhooks, eventos e logs de entrega não ficam nesta página: no painel, estão na Workbench, que a página Desenvolvedores abre por um atalho.

#Acesso: Total ou Restrita

• Total: a chave alcança todos os recursos da API pública da sua conta.
• Restrita: a chave alcança só o que você marcou ao gerá-la, recurso a recurso. Para cada um (Vendas, Assinaturas, Clientes, Cartões, Produtos, Cupons, Checkouts, Webhooks, Saques e Recebíveis), escolha Nada, Ler (consultar) ou Tudo (consultar, criar, alterar, excluir e as demais ações do recurso, como estornar uma venda).

Uma requisição fora do que a chave restrita permite recebe 403, com o código forbidden. Para uma integração que só precisa de parte da API (um ERP que só consulta vendas, por exemplo), prefira uma chave restrita.

#Chave publicável (pk_)

Cada chave gerada no painel vem com uma chave publicável do mesmo ambiente (pk_test_… ou pk_live_…), mostrada abaixo do identificador da chave. Diferente da chave secreta, ela pode ir ao navegador: só identifica a sua conta ao tokenizar um cartão e não autentica nenhuma outra chamada. Ela vale enquanto a chave secreta correspondente valer. Veja Cartões - Tokenização no navegador.

#Segurança das Chaves

A chave secreta (sk_…) autentica em nome da sua conta (com acesso Total, em toda a API pública), portanto trate-a com a mesma segurança que uma senha:

1. Nunca compartilhe suas chaves de produção: Mantenha-as restritas apenas a pessoas autorizadas
2. Não armazene chaves em código-fonte: Utilize variáveis de ambiente ou sistemas seguros de gerenciamento de configuração
3. Não inclua a chave secreta em aplicativos frontend: Ela deve ser utilizada apenas em ambientes backend seguros. No navegador, só a chave publicável
4. Dê só o acesso necessário: Prefira chaves restritas e, para uma integração temporária, defina a data de expiração
5. Rotação regular: Substitua suas chaves periodicamente como medida de segurança adicional
6. Monitoramento: Verifique regularmente o uso da API para detectar atividades suspeitas

// INCORRETO - Chave exposta no código
const selectKey = "sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ";

// CORRETO - Chave obtida de variável de ambiente
const selectKey = process.env.SELECTWIN_API_KEY;

#Múltiplas Chaves

Você pode criar e utilizar múltiplas chaves de API para diferentes finalidades:

• Separação de ambientes: Chaves distintas para desenvolvimento, teste e produção
• Integração de sistemas: Chaves específicas para cada sistema ou serviço integrado
• Equipes distintas: Chaves separadas para diferentes equipes ou departamentos
• Rastreabilidade: Identificação facilitada da origem de cada requisição

#Revogação de Chaves

Em caso de comprometimento de segurança ou quando não for mais necessária, você pode revogar uma chave a qualquer momento:

1. Acesse o Painel Administrativo, no ambiente da chave (Produção ou Sandbox)
2. Navegue até Configurações → Desenvolvedores
3. Em Chaves de API, clique em Revogar ao lado da chave e confirme

A revogação é imediata e não pode ser desfeita: as requisições seguintes com essa chave recebem 401, com o código unauthorized, e a chave publicável dela também deixa de funcionar. O mesmo acontece quando a chave chega à data definida em Expira em.

#Headers Adicionais

Além do cabeçalho obrigatório SelectKey, recomendamos incluir os seguintes cabeçalhos em todas as requisições:

curl -X POST "https://api.selectwin.io/v1/transactions" \
     -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "User-Agent: MeuApp/1.0.0" \
     -H "X-Idempotency-Key: 2dfc6a63-5df5-4900-baca-e49d91ef393e"

#Boas Práticas

1. Valide respostas: Sempre verifique os códigos de status HTTP e trate adequadamente erros de autenticação
2. Configuração por ambiente: Utilize configurações diferentes para sandbox e produção
3. Registre tentativas de autenticação: Mantenha logs para análise de segurança
4. Rotação preventiva: Substitua suas chaves periodicamente
5. Verifique regularmente: No painel, cada chave mostra a situação e o último uso; revogue as que não estão mais em uso