twila-parcelemais

SDK oficial em Python para a API do Parcele+ — crédito direto ao consumidor (CDC) e parcelamento no momento da compra.

Uso restrito a server-side. O client_secret nunca deve ser embarcado em um app mobile, SPA ou qualquer código que rode no navegador/dispositivo do usuário final.

Compatibilidade

Cliente síncrono, baseado em httpx, com tipos totalmente anotados (py.typed, PEP 561).

Instalação

pip install twila-parcelemais

Quick start

from twila_parcelemais import ParceleMaisClient, ParceleMaisClientOptions, ParceleMaisEnvironment

client = ParceleMaisClient(
    ParceleMaisClientOptions(
        client_id="<seu-client-id>",
        client_secret="<seu-client-secret>",
        environment=ParceleMaisEnvironment.STAGING,
    )
)

ParceleMaisClient é thread-safe e deve ser reaproveitado como singleton na sua aplicação — ele mantém o cache do token de acesso e o estado do circuit breaker. Feche-o só no shutdown (client.close(), ou use como context manager: with ParceleMaisClient(options) as client:).

Simulando parcelas

from twila_parcelemais import SimulateInstallmentsRequest

parcelas = client.simulations.simulate_installments(SimulateInstallmentsRequest(requested_amount=1500.0))

for parcela in parcelas:
    print(f"{parcela.term}x de {parcela.installment_amount} (total {parcela.total_amount})")

Criando um pedido

from twila_parcelemais import CreateOrderRequest, OrderAddress

pedido_id = client.orders.create(
    CreateOrderRequest(
        cpf="12345678901",
        phone_number="+5511999998888",
        establishment_document="12345678000195",
        requested_amount=1500.0,
        name="Maria Souza",
        email="maria.souza@exemplo.com.br",
        date_of_birth="1990-05-20T00:00:00-03:00",
        address=OrderAddress(
            street="Av. Paulista",
            number="1578",
            neighborhood="Bela Vista",
            city="São Paulo",
            state="SP",
            postal_code="01311000",
        ),
    )
)

create retorna só o id do pedido — a API não devolve o pedido completo na criação; use client.orders.get(pedido_id) se precisar dos dados completos logo em seguida.

Clientes por recurso

Paginação

orders.list(...) e customers.list(...) retornam um PagedResult[T] — sem auto-paginação, você controla explicitamente o avanço de página:

from twila_parcelemais import ListOrdersRequest

page = client.orders.list(ListOrdersRequest(page=1, page_size=20))

for order in page.items:
    print(order.id)

if page.has_next:
    next_page = client.orders.list(ListOrdersRequest(page=2, page_size=20))

Tratamento de erros

from twila_parcelemais import ParceleMaisApiError

try:
    client.orders.get(order_id)
except ParceleMaisApiError as error:
    print(f"{error.status_code} {error.error_code}: {error}")

Validando webhooks

from twila_parcelemais import parse_webhook_event

evento = parse_webhook_event(raw_body, signature_header, signing_secret)

Verifica a assinatura HMAC-SHA256 do cabeçalho e a janela de replay (5 minutos) antes de expor o evento. Lança ParceleMaisWebhookSignatureError se a assinatura for inválida ou o evento estiver fora da janela.

Samples

• samples/sample_plain — script standalone, sem framework
• samples/sample_flask — ParceleMaisClient como singleton na app factory do Flask

Qualidade, segurança e cobertura

• Build/Test (ci.yml) — mypy --strict + suíte de testes (pytest + respx) em Python 3.9–3.14.
• Quality (quality.yml) — análise estática via Codacy CLI (pylint), resultados publicados na aba Security → Code scanning do repositório.
• Security (security.yml) — CodeQL para Python, rodando a cada PR/push e semanalmente.
• Coverage — cobertura de testes coletada via pytest-cov e publicada no Codecov.

Documentação completa

documentacao.parcelemais.com.br — referência de todos os endpoints, autenticação, webhooks e mais.

Contribuindo

Veja CONTRIBUTING.md.

Código de conduta

Este projeto segue o Código de Conduta.

Licença

MIT