SDK Python

Instale cobrebase, crie cliente e assinatura com idempotency_key, paginação com list_all, webhooks com construct_event e helpers de sandbox.

Instalar

Pacote PyPI: cobrebase. Python 3.11 ou superior. A chave fica no servidor.

pip install cobrebase

Neste repositório: pip install -e . dentro de sdk-python/.

Iniciar o cliente

cb_test_ aponta o sandbox. cb_live_ cobra de verdade. Sem base_url, o cliente chama https://api.cobrebase.com.br.

import os

from cobrebase import CobreBase

cb = CobreBase(os.environ["COBREBASE_API_KEY"])

# Desenvolvimento local (Compose)
cb_local = CobreBase(
    os.environ["COBREBASE_API_KEY"],
    base_url="http://localhost:18000",
)

Dinheiro é inteiro em centavos (R$ 10,00 = 1000).

Cliente e assinatura

Todo POST envia Idempotency-Key. Passe idempotency_key como argumento nomeado. Rede, 429 e 5xx repetem com a mesma chave.

customer = cb.customers.create(
    {"name": "Acme Tecnologia", "email": "[email protected]"},
    idempotency_key="customer-acme-42",
)

subscription = cb.subscriptions.create(
    {
        "customer_id": customer["id"],
        "items": [{"price_id": "price_...", "quantity": 1}],
    },
    idempotency_key="sub-acme-42",
)

Listagem e paginação

list devolve a primeira página {data, links, meta}. page começa em 1 e limit vai até 100. list_all percorre as páginas:

for customer in cb.customers.list_all({"limit": 100}):
    customer["id"]

Webhook no body cru

construct_event recebe o body cru, antes do JSON.

import os

from cobrebase import WebhookSignatureError, construct_event

payload = request.get_data()  # bytes ou str: body cru
header = request.headers.get("CobreBase-Signature")

try:
    event = construct_event(payload, header, os.environ["COBREBASE_WEBHOOK_SECRET"])
except WebhookSignatureError:
    # responda HTTP 400 e pare
    raise

if event["type"] == "invoice.paid":
    invoice = event["data"]["object"]

Detalhes: documentação de webhooks.

Sandbox: test_helpers e test_clocks

Só com cb_test_. Com chave live a API responde 403.

cb.test_helpers.confirm_payment("pay_...")
cb.test_helpers.fail_payment("pay_...", "card_declined")
cb.test_helpers.expire_payment("pay_...")
cb.test_helpers.pay_late("pay_...", 3)
cb.test_helpers.fixture("invoice.paid", {"method": "pix"})

clock = cb.test_clocks.create(1_700_000_000)
advanced = cb.test_clocks.advance(clock["id"], 1_700_086_400)
if advanced["status"] == "advancing":
    cb.test_clocks.wait_until_ready(clock["id"])

create e advance recebem frozen_time em unix (segundos).

Erros

Erros da API sobem como CobreBaseError com status, type, code, message e param.

from cobrebase import CobreBaseError

try:
    cb.customers.create(
        {"name": "Acme"},
        idempotency_key="customer-acme",
    )
except CobreBaseError as err:
    # err.status, err.type, err.code, err.message, err.param
    ...

Contrato HTTP: https://api.cobrebase.com.br/docs.