Instala el SDK · Compense Docs

Hay un SDK oficial por lenguaje. Los cinco cubren las 115 operaciones del gateway con los mismos nombres (adaptados a la convención de cada lenguaje) y resuelven lo que toda integración termina haciendo a mano: autenticación, Idempotency-Key en las escrituras, reintentos con backoff, errores tipados problem+json, paginación, avisos de deprecación y verificación de webhooks. Todos están en la versión 1.1.0 y apuntan al API v1 (SemVer alineado: mayor del SDK = mayor del API).

Requisitos #

SDK	Paquete	Requisitos	Dependencias
Python	`compense-sdk-python` (se importa como `compense_gateway`)	Python 3.9+	`httpx` (cliente síncrono y asíncrono)
JavaScript / TypeScript	`@compense/sdk`	Node.js 18+ (también Deno, Bun y edge)	Ninguna: usa `fetch` nativo. ESM y CommonJS con tipos
PHP	`compense/sdk`	PHP 8.1+	Cualquier cliente PSR-18 (Guzzle sugerido)
.NET	`Compense.Sdk`	`net8.0` o `netstandard2.0` (.NET Framework 4.6.2+)	`System.Text.Json`, `Microsoft.Extensions.Http`
Go	`github.com/Appiasoft/compense-saas-sdk-go`	Go 1.21+ (iteradores con 1.23+)	Solo biblioteca estándar

Instalación #

Instalar

pip install compense-sdk-python

npm install @compense/sdk
# o: pnpm add @compense/sdk · yarn add @compense/sdk

composer require compense/sdk guzzlehttp/guzzle
# cualquier PSR-18 sirve, p. ej.: composer require compense/sdk symfony/http-client nyholm/psr7

dotnet add package Compense.Sdk --version 1.1.0

go get github.com/Appiasoft/compense-saas-sdk-go@v1.1.0

# No hay nada que instalar: cualquier cliente HTTP sirve.
curl --version

¿Tu gestor de paquetes no encuentra el SDK?

Los SDK todavía no están en los registros públicos (PyPI, npm, Packagist, NuGet): se distribuyen como releases de sus repositorios privados en GitHub. En el onboarding Compense le da a tu equipo acceso de lectura y descargas el paquete del release v1.1.0 de cada repo (compense-saas-sdk-python, -js, -php, -dotnet, -go de la organización Appiasoft). Se instala igual: pip install ./compense_sdk_python-1.1.0-py3-none-any.whl, npm install ./compense-sdk-1.1.0.tgz, dotnet add package Compense.Sdk --source ./artifacts, un repositorio vcs (o path con el zip) en composer.json, y en Go GOPRIVATE=github.com/Appiasoft/* antes del go get. Las instrucciones exactas vienen en cada release.

Crea el cliente #

Crea un cliente por llave y reutilízalo: todos son seguros para uso concurrente y mantienen un pool de conexiones.

import os
from compense_gateway import CompenseClient, AsyncCompenseClient

client = CompenseClient(api_key=os.environ["COMPENSE_API_KEY"], environment="sandbox")

# Misma superficie, todo awaitable (FastAPI, aiohttp…):
async_client = AsyncCompenseClient(api_key=os.environ["COMPENSE_API_KEY"], environment="sandbox")

import { CompenseClient } from "@compense/sdk";            // ESM / TypeScript
// const { CompenseClient } = require("@compense/sdk");    // CommonJS

const client = new CompenseClient({ apiKey: process.env.COMPENSE_API_KEY!, environment: "sandbox" });

<?php
require __DIR__ . '/vendor/autoload.php';

use Compense\Sdk\CompenseClient;

$client = new CompenseClient(apiKey: getenv('COMPENSE_API_KEY'), environment: 'sandbox');

using Compense.Sdk;

// Consola o servicio sin DI:
using var client = new CompenseClient(
    Environment.GetEnvironmentVariable("COMPENSE_API_KEY")!, CompenseEnvironment.Sandbox);

// ASP.NET Core: cliente tipado con IHttpClientFactory, configurado desde appsettings/variables
// (Compense__ApiKey, Compense__Environment, Compense__Timeout, Compense__Retry__MaxAttempts…)
builder.Services.AddCompense(builder.Configuration.GetSection("Compense"));

import compense "github.com/Appiasoft/compense-saas-sdk-go"

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithEnvironment(compense.Sandbox))
if err != nil {
	log.Fatal(err) // *compense.ConfigError: llave vacía, entorno desconocido o URL inválida
}

export COMPENSE_BASE_URL="https://sandbox.dev.compense.co/gw"
curl "$COMPENSE_BASE_URL/v1/gateway/health/" -H "X-API-Key: $COMPENSE_API_KEY"

Opciones del cliente #

Las mismas perillas existen en los cinco SDK:

Opción	Python	JavaScript / TS	PHP	.NET	Go
Entorno	`environment=`	`environment`	`environment:`	`CompenseEnvironment` / `Environment`	`WithEnvironment`
URL base propia (gana al entorno)	`base_url=`	`baseUrl`	`baseUrl:`	`BaseUrl`	`WithBaseURL`
Timeout por intento	`timeout=` (s)	`timeout` (ms)	`timeout:` (s)	`Timeout` (`TimeSpan`)	`WithTimeout`
Reintentos	`retry=RetryConfig(...)`	`retry: {...}`	`retry: new RetryConfig(...)`	`Retry = new RetryOptions {...}`	`WithRetry(RetryConfig{...})`
Reintentar escrituras	`RetryConfig(retry_writes=True)`	`retryWrites: true`	`RetryConfig(retryWrites: true)`	`RetryWrites = true`	`WithRetryWrites(true)`
Cliente HTTP propio	`http_client=` / `transport=` (httpx)	`fetch`	`httpClient:` (PSR-18)	`new CompenseClient(httpClient, options)`	`WithHTTPClient`
Avisos de deprecación	logger `compense_gateway`	`logger`	`logger:` (PSR-3)	`ILogger` (`Compense.Sdk`)	`WithLogger` (`slog`)

Ejemplo con todo configurado:

from compense_gateway import CompenseClient, RetryConfig

client = CompenseClient(
    api_key=os.environ["COMPENSE_API_KEY"],
    environment="sandbox",
    timeout=30.0,
    retry=RetryConfig(max_attempts=5, backoff_base=0.5, backoff_max=30.0, jitter=True),
)

const client = new CompenseClient({
  apiKey: process.env.COMPENSE_API_KEY!,
  environment: "sandbox",
  timeout: 30_000,
  retry: { maxAttempts: 5, backoffBaseMs: 500, backoffMaxMs: 30_000, jitter: true, retryWrites: false },
  logger: console,
});

use Compense\Sdk\CompenseClient;
use Compense\Sdk\RetryConfig;

$client = new CompenseClient(
    apiKey: getenv('COMPENSE_API_KEY'),
    environment: 'sandbox',
    timeout: 30.0,
    retry: new RetryConfig(maxAttempts: 5, backoffBase: 0.5, backoffMax: 30.0, jitter: true),
);

var client = new CompenseClient(new CompenseClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("COMPENSE_API_KEY")!,
    Environment = CompenseEnvironment.Sandbox,
    Timeout = TimeSpan.FromSeconds(30),
    Retry = new RetryOptions
    {
        MaxAttempts = 5, BackoffBase = TimeSpan.FromSeconds(0.5),
        BackoffMax = TimeSpan.FromSeconds(30), Jitter = true,
    },
});

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithEnvironment(compense.Sandbox),
	compense.WithTimeout(30*time.Second),
	compense.WithRetry(compense.RetryConfig{MaxAttempts: 5}),
	compense.WithUserAgent("horizonte-erp/2.0"),
)

# Con HTTP directo, el timeout y los reintentos son tuyos:
curl --max-time 30 --retry 3 --retry-all-errors "$COMPENSE_BASE_URL/v1/gateway/health/" \
  -H "X-API-Key: $COMPENSE_API_KEY"
# ¡Ojo! --retry solo es seguro en lecturas o en escrituras con la misma Idempotency-Key.

Los detalles de cada opción están en Reintentos y backoff y en la página de cada SDK. Siguiente paso: tu primera llamada.