SDK da Selectwin para Python
O SDK oficial da Selectwin para Python (selectwin): pagamentos (cartão de crédito, Pix, boleto),
assinaturas, carteiras, webhooks e mais. Síncrono e assíncrono, todo tipado.
Shell
pip install selectwinPrimeiros passos
Python
import os
from selectwin import Selectwin, CardError
sw = Selectwin(api_key=os.environ["SELECTWIN_API_KEY"]) # sk_test_… / sk_live_…
# Crie uma transação Pix (valores em centavos)
tx = sw.transactions.create({"amount": 9990, "payment": {"method": "pix", "currency": "BRL"}})
# Atalhos com id / id + corpo
one = sw.transactions.retrieve("tra_…")
sw.subscriptions.pause("subs_…")
# Erros tipados: decida pela classe ou pelo error.code, nunca pela mensagem
try:
sw.transactions.create({...})
except CardError as e:
print(e.display_message, e.reversible) # texto ao comprador + se pode repetirAssíncrono
Python
import asyncio
from selectwin import AsyncSelectwin
async def main():
async with AsyncSelectwin(api_key="sk_test_…") as sw:
tx = await sw.transactions.create({"amount": 9990, "payment": {"method": "pix", "currency": "BRL"}})
async for t in sw.transactions.list(limit=100):
...
asyncio.run(main())Paginação
Os métodos list() de primeiro nível devolvem um paginador que busca páginas e também é iterável:
Python
# síncrono: percorre todas as transações, de todas as páginas
for tx in sw.transactions.list(limit=100):
...
first_page = sw.transactions.list(limit=20).first() # um objeto de página (.data, .has_more, …)
some = sw.customers.list().to_list(max=500) # junta tudo, com teto opcional
# assíncrono
async for tx in sw.transactions.list(limit=100):
...A API gerada inteira (todo operation_id) continua ao alcance pelo .raw:
Python
from selectwin._core.api.transactions import create_transaction
# ou, a partir do próprio recurso:
sw.transactions.raw # o módulo gerado deste recursoWebhooks
Python
# raw_body PRECISA ser exatamente os bytes/a str recebidos (não serialize de novo)
event = sw.webhooks.construct_event(
raw_body,
request.headers["x-selectwin-signature"],
os.environ["SELECTWIN_WEBHOOK_SECRET"], # whsec_…
)
if event.type == "transaction.approved":
obj = event.payload.objectO WEBHOOK_EVENT_TYPES (o catálogo oficial) e o is_webhook_event_type() são exportados para validação;
o WebhookEventType é um typing.Literal com todos os tipos de evento.
O que o SDK acrescenta ao cliente gerado
O pacote é um núcleo gerado (openapi-python-client, da especificação OpenAPI v2.0.0) mais uma camada de conveniência escrita à mão:
- Clientes tipados:
Selectwin(api_key=…)(síncrono) eAsyncSelectwin(api_key=…)(gerenciador de contexto assíncrono), comsw.transactions,sw.subscriptions,sw.customers, … - Atalhos concisos por recurso (
create/retrieve/update/list/deletee verbos próprios), que aceitam um dict ou o modelo de corpo gerado; o.rawexpõe toda a superfície gerada. - Erros tipados pelo status HTTP e pelo
error.code:CardError(402,display_message/reversible),ValidationError(params),RateLimitError(retry_after),AuthenticationError,PermissionDeniedError,NotFoundError,ConflictError,APIError,APIConnectionError. - Novas tentativas automáticas (429, 5xx e falha de rede), com backoff exponencial e respeitando o
Retry-After. - Idempotência: toda operação de escrita leva um
X-Idempotency-Key(dá para trocar a cada chamada). - Tempo limite e um cliente
httpxsó, compartilhado e já autenticado, por cliente do SDK. - Paginação automática: iteradores síncronos (
for …) e assíncronos (async for …),.first(),.to_list(max=…),.pages(). - Verificação de webhook:
construct_event(HMAC-SHA256 do corpo bruto, em tempo constante).
A autenticação vai no header SelectKey; o ambiente (sandbox ou produção) sai do prefixo da chave
(sk_test_ / sk_live_).
Arquitetura
Texto
src/selectwin/
_core/ # saída do openapi-python-client — NÃO edite; sincronizada do selectwin-sdks
resources.py # GERADO: namespaces dos recursos (síncronos e assíncronos) — NÃO edite
webhook_events.py # GERADO: catálogo de eventos de webhook (tipos + verificação) — NÃO edite
errors.py # hierarquia de erros tipados
http.py # transporte httpx (tentativas/tempo limite) + ganchos (idempotência, UA) + erros
pagination.py # SyncPager / AsyncPager
webhooks.py # construct_event (verificação da assinatura)
client.py # Selectwin / AsyncSelectwin: ligam a autenticação e o cliente httpx próprioO que vale para todas as chamadas entra uma vez só no cliente httpx que o núcleo gerado compartilha: todo endpoint herda, e endpoint novo funciona sozinho quando o núcleo é gerado de novo.
Desenvolvimento
Shell
pip install -e ".[dev]"
python scripts/sync_core.py # traz o núcleo gerado do selectwin-sdks e refaz
python scripts/gen_resources.py # refaz o src/selectwin/resources.py
python scripts/gen_webhook_events.py # refaz o src/selectwin/webhook_events.py
pytest # suíte de unidade
pytest -m integration # suíte do sandbox (pede SELECTWIN_SANDBOX_KEY; veja tests/integration)
mypy src/selectwin # confere os tipos da camada de conveniênciaAtualizado em 21 de outubro de 2026