SDK
SDK oficiales
Los cinco SDK oficiales del API Gateway (Python, JavaScript/TypeScript, PHP, .NET y Go): qué tienen en común, cómo elegir y en qué se diferencian.
En esta página
Compense mantiene un SDK oficial por lenguaje. Los cinco están en la versión 1.1.0, cubren las
115 operaciones del contrato v1 y comparten las mismas reglas, comprobadas con pruebas de
paridad contra el contrato fijado (gateway develop 9cf78da): mismo verbo, ruta e idempotencia por
operación, y —en JS, PHP, .NET y Go— el mismo cuerpo exacto que envía el SDK de Python.
compense-sdk-python
Python
El SDK de referencia. Cliente síncrono y asíncrono (httpx) y la CLI
compense.
@compense/sdk
JavaScript / TypeScript
Node 18+, Deno, Bun y edge. Sin dependencias, ESM y CommonJS, con tipos y CLI.
compense/sdk
PHP
PHP 8.1+, cualquier cliente PSR-18, argumentos con nombre; listo para Laravel y Symfony.
Compense.Sdk
.NET
net8.0 y netstandard2.0, todo async, IHttpClientFactory y configuración de ASP.NET Core.
compense-saas-sdk-go
Go
Go 1.21+, solo biblioteca estándar, context en cada llamada e iteradores.Qué hacen todos #
| Capacidad | Detalle |
|---|---|
| Autenticación | Cabecera X-API-Key en cada llamada; entornos production, sandbox y dev, o URL base propia. |
| Idempotencia | Idempotency-Key en toda escritura con llave: la tuya o un UUIDv4 generado. |
| Reintentos | 429/502/503/504 con backoff exponencial, jitter y Retry-After; escrituras solo con retryWrites. |
| Errores | Excepciones tipadas por código con el Problem RFC 9457 y su trace_id. |
| Montos | Texto decimal exacto (MoneyCOP) desde enteros, decimales o texto. |
| Paginación | Page y OffsetPage iterables, con recorrido automático en JS, .NET y Go. |
| Deprecaciones | Un aviso por operación cuando el gateway envía Deprecation/Sunset. |
| Webhooks | Verificación HMAC-SHA256 sin estado, con varios secretos (rotación), tolerancia de tiempo y detección de eventos de prueba; catálogo de 52 eventos. |
| Paridad | Pruebas que fallan si una operación del contrato no está cubierta o difiere en verbo, ruta o idempotencia. |
Cómo se llaman las cosas en cada uno #
Los nombres siguen los operationId del contrato, agrupados por módulo, en la convención de cada
lenguaje. La referencia del API muestra el método exacto de cada operación en
los cinco.
| Operación | Python | JavaScript / TS | PHP | .NET | Go |
|---|---|---|---|---|---|
payBill | client.wallet.bills.pay(...) | client.wallet.bills.pay({...}) | $client->wallet->bills->pay(...) | client.Wallet.Bills.PayAsync(...) | client.Wallet.Bills.Pay(ctx, &BillPayParams{...}) |
registerLoanPayment | client.loans.register_payment(...) | client.loans.registerPayment(id, {...}) | $client->loans->registerPayment(...) | client.Loans.RegisterPaymentAsync(...) | client.Loans.RegisterPayment(ctx, id, &LoanPaymentParams{...}) |
sendWebhookTestEvent | client.webhooks.endpoints.send_test(...) | client.webhooks.endpoints.sendTest(...) | $client->webhooks->endpoints->sendTest(...) | client.Webhooks.Endpoints.SendTestAsync(...) | client.Webhooks.Endpoints.SendTest(ctx, ...) |
| Verificar webhook | verify_webhook(body, headers, secret) | verifyWebhook(body, headers, secret) | Webhook::verify($body, $headers, $secret) | CompenseWebhooks.Verify(body, headers, secret) | webhook.Verify(body, header, secrets) |
| Convención | Python | JavaScript / TS | PHP | .NET | Go |
|---|---|---|---|---|---|
| Nombres | snake_case | camelCase | camelCase | PascalCase + Async | PascalCase |
| Parámetros | argumentos con nombre | objeto de opciones | argumentos con nombre (PHP 8) | parámetros con nombre/opcionales | struct *Params (o nil) + ...CallOption |
| Asincronía | CompenseClient y AsyncCompenseClient | todo Promise | síncrono | todo Task con CancellationToken | síncrono con context.Context |
| Campos libres | extra= / **fields | extra / fields | extra: / argumentos con nombre extra | IReadOnlyDictionary<string, object?> | Extra / Fields map[string]any |
CLI compense | sí | sí (npx compense) | no | no | no |
Cómo elegir #
- Usa el SDK del lenguaje de tu sistema. Todos tienen la misma cobertura; no hay funciones exclusivas salvo la CLI (Python y JS) y el cliente asíncrono explícito de Python.
- ¿Sin SDK para tu lenguaje? El contrato es OpenAPI 3.1: llama por HTTP siguiendo la referencia y aplica las reglas de Conceptos (idempotencia, reintentos y verificación de webhooks son las que más se olvidan).
- ¿Varios lenguajes en tu entidad? Mezclarlos es seguro: hablan el mismo contrato y verifican las firmas de webhooks de forma idéntica (las pruebas usan vectores generados por el SDK de Python).
Código fuente #
Los repositorios son privados de Appiasoft; Compense da acceso de lectura en el onboarding. Cada uno trae su README (en inglés), una guía en español por módulo y ejemplos ejecutables.
| SDK | Repositorio | Guías en español | Ejemplos |
|---|---|---|---|
| Python | Appiasoft/compense-saas-sdk-python | Docs/features/ | README |
| JavaScript / TS | Appiasoft/compense-saas-sdk-js | docs/ | examples/ |
| PHP | Appiasoft/compense-saas-sdk-php | docs/ | examples/ |
| .NET | Appiasoft/compense-saas-sdk-dotnet | docs/modulos/ | examples/ |
| Go | Appiasoft/compense-saas-sdk-go | docs/ | examples/ |