Python

Es el SDK de referencia: los demás comparan sus peticiones contra lo que envía este.

Instalar #

pip install compense-sdk-python

Cliente síncrono #

import os
from compense_gateway import CompenseClient, RetryConfig

with CompenseClient(
    api_key=os.environ["COMPENSE_API_KEY"],   # cmp_...
    environment="sandbox",                    # "production" (defecto) | "sandbox" | "dev"
    timeout=30.0,                             # segundos por intento
    retry=RetryConfig(max_attempts=3, retry_writes=False),
) as client:
    print(client.system.health().tenant)

Parámetros del constructor: api_key, environment, base_url (gana sobre el entorno), timeout, retry, user_agent, y para pruebas o configuración avanzada transport (httpx.BaseTransport) o http_client (httpx.Client propio, que el SDK no cierra).

Cliente asíncrono #

AsyncCompenseClient tiene exactamente la misma superficie; cada método es awaitable. Úsalo en FastAPI, aiohttp o cualquier código asyncio:

import asyncio
from compense_gateway import AsyncCompenseClient

async def main():
    async with AsyncCompenseClient(api_key=os.environ["COMPENSE_API_KEY"], environment="sandbox") as client:
        balance, loans = await asyncio.gather(
            client.wallet.balance("1032456789"),
            client.loans.list("1032456789", status="ACTIVE"),
        )
        print(balance.available.amount, loans.count)

asyncio.run(main())

Convenciones #

• Métodos en snake_case agrupados por módulo: client.credits.submit_application(...), client.wallet.bills.pay(...), client.admin.payroll.create_novelties(...).
• Argumentos con nombre (keyword-only) para todo lo opcional; el titular siempre es document.
• Escrituras → Transaction; lecturas → modelo tipado (Balance, Resolution, Page, OffsetPage, AffiliateLookup, WebhookEndpoint, TestClock, GatewayHealth, TransactionStatus…) o dict. Todos los modelos guardan el cuerpo original en .raw.
• Campos libres: extra= (créditos, subsidios, cartera, PQRS) y **fields en el módulo administrativo, con los nombres del contrato (snake_case).
• client.wallet.accounts, .cards y .fx son los mismos objetos que client.accounts, client.cards y client.fx.
• client.health son los servicios de salud (IPS); la salud del gateway es client.system.health().

Errores #

from compense_gateway import (
    CompenseError, CompenseConfigError, CompenseAPIError, AuthError, NotFoundError,
    IdempotencyConflictError, ValidationError, RateLimitError, UpstreamError, ServerError,
)

CompenseAPIError expone status, title, detail, trace_id, retry_after y el problem completo (problem.type, problem.errors). Los errores de red son los de httpx (httpx.TransportError). Ver Errores.

Paginación #

Page y OffsetPage iteran sobre los resultados de esa página. Para recorrer todas, pide la siguiente con page= u offset= (Paginación).

Webhooks #

from compense_gateway.webhooks import verify_webhook, WebhookVerificationError, EVENT_TYPES

event = verify_webhook(raw_body, headers, secret=[NEW_SECRET, OLD_SECRET], tolerance=300)
event.event_id, event.event, event.resource, event.is_test

No necesita httpx ni una instancia del cliente. Receptores completos con Flask y FastAPI en Verificar la firma.

CLI compense #

Instalar el SDK instala el comando compense (llave en --key o $COMPENSE_API_KEY, entorno sandbox por defecto, salida JSON): health, events, endpoints, endpoint-create, trigger, deliveries, replay, clock, simulate y listen. Referencia completa en CLI.

Pruebas #

Inyecta un httpx.MockTransport para probar tu código sin red:

import httpx
from compense_gateway import CompenseClient

def handler(request: httpx.Request) -> httpx.Response:
    assert request.headers["X-API-Key"] == "cmp_test"
    if request.url.path == "/v1/gateway/wallet/balance/":
        return httpx.Response(200, json={"total": "150000.00", "available_cash": "150000.00", "currency": "COP"})
    return httpx.Response(404, json={"title": "Not Found", "status": 404, "trace_id": "t"})

client = CompenseClient(api_key="cmp_test", environment="sandbox", transport=httpx.MockTransport(handler))
assert client.wallet.balance("1032456789").available.amount == "150000.00"

Para pruebas de integración usa una llave de sandbox: es determinista (Sandbox).