Compense Developers on Compense Docs

Afiliados

Mon, 01 Jan 0001 00:00:00 +0000

El módulo de afiliados es la puerta de entrada de cualquier integración: créditos, subsidios, cuota monetaria y cartera resuelven al afiliado por su documento, y el motor rechaza la operación si ese documento no está en el registro de tu entidad. Aquí aprendes a mantener ese registro al día desde tu sistema (core, ERP, SOFIA o una hoja de cálculo) y a consultarlo.

Afiliados

Mon, 01 Jan 0001 00:00:00 +0000

Esta página se genera desde el contrato (data/gateway-v1.json): cada operación muestra su verbo, ruta, parámetros, cuerpo, respuestas, si lleva Idempotency-Key y el método equivalente en los cinco SDK. Para el flujo de punta a punta con ejemplos completos, ve a la guía de implementación.

Autenticación

Mon, 01 Jan 0001 00:00:00 +0000

Cada petición al gateway lleva una cabecera de autenticación:

HTTP

X-API-Key: cmp_...

No hay OAuth, ni tokens de sesión, ni id de tenant en la URL: la llave es autoidentificable. El gateway la busca, comprueba que esté activa y vigente, y obtiene de ella el tenant (tu entidad), los scopes, el entorno (sandbox/prod), el límite por minuto y la cuota mensual. Los SDK ponen la cabecera por ti en cada llamada.

Desembolsar un crédito y conciliar

Mon, 01 Jan 0001 00:00:00 +0000

Caja Horizonte origina libranzas desde su ERP. El analista aprueba en el ERP, tesorería ordena el desembolso y contabilidad necesita saber, sin consultar a nadie, cuándo salió la plata, cuánto y contra qué solicitud. Esta receta arma ese circuito de punta a punta con el gateway: radicar → decidir → desembolsar → recibir credits.disbursed → conciliar.

Obtén tu llave de API

Mon, 01 Jan 0001 00:00:00 +0000

Todo el API Gateway se autentica con una llave de API que tu sistema envía en la cabecera X-API-Key. La llave identifica a tu entidad (el tenant): nunca envías un id de caja o de organización, y una llave jamás ve datos de otro tenant.

Preguntas frecuentes

Mon, 01 Jan 0001 00:00:00 +0000

Llaves y entornos #

¿Dónde pongo el id de mi caja o de mi entidad? #

En ninguna parte. La llave cmp_... identifica al tenant; el gateway lo resuelve solo. Los afiliados, pacientes o titulares se identifican con su document.

Python

Mon, 01 Jan 0001 00:00:00 +0000


Paquete	`compense-sdk-python` (se importa como `compense_gateway`)
Versión	1.1.0 · API v1
Requisitos	Python 3.9+
Dependencias	`httpx` (los módulos `models` y `webhooks` solo usan la biblioteca estándar)
Repositorio	Appiasoft/compense-saas-sdk-python · guías en `Docs/features/`

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

Relojes de prueba

Mon, 01 Jan 0001 00:00:00 +0000

Hay comportamientos que solo aparecen con el paso del tiempo: una cuota que pasa a mora, una obligación que vence, un subsidio que exige permanencia. Probarlos esperando días reales no es opción. Un reloj de prueba (test clock) es una fuente de tiempo virtual: lo fijas en una fecha (frozen_time) y lo adelantas las veces que quieras; su current_time es el “ahora” de tu escenario.

Suscribir un endpoint

Mon, 01 Jan 0001 00:00:00 +0000

Un endpoint es una URL tuya que recibe eventos. Lo registras con tu llave de API, eliges a qué eventos se suscribe y Compense te devuelve una sola vez el secreto con el que firmará cada entrega. Todo lo que haces aquí queda ligado a la organización dueña de la llave: un id de otra organización responde 404.

Catálogo de eventos

Mon, 01 Jan 0001 00:00:00 +0000

Cada evento tiene una clave (credits.decision, wallets.topup.completed, pqrs.responded…) que usas al suscribir un endpoint y que llega en la cabecera X-Webhook-Event y en el campo event del cuerpo. Esta página es una foto del catálogo al 1 de noviembre de 2026 (52 eventos). La fuente de verdad es el catálogo en vivo, GET/v1/gateway/webhooks/event-catalog/ : si aparece un evento nuevo, lo verás primero ahí, con su payload_example.

Créditos

Mon, 01 Jan 0001 00:00:00 +0000

El módulo de créditos expone el motor de originación de Compense (reglas, scoring y desembolso) a tu sistema: radicas la solicitud de un afiliado, tu analista o el motor la decide y la desembolsas. Cada paso devuelve un transaction_id rastreable y emite un webhook. Lo que pasa después del desembolso (plan de pagos, recaudo, paz y salvo) vive en Cartera.

Créditos

Mon, 01 Jan 0001 00:00:00 +0000

Cuota monetaria del período

Mon, 01 Jan 0001 00:00:00 +0000

Cada mes, Caja Horizonte liquida la cuota monetaria de sus afiliados y la paga. Un error aquí cuesta caro: pagar dos veces a miles de afiliados, o dejar a la mitad sin pago porque el proceso se cayó a mitad del lote. Esta receta cierra el período octubre de 2026 de forma que se pueda interrumpir y relanzar en cualquier punto sin pagar dos veces.

Instala el SDK

Mon, 01 Jan 0001 00:00:00 +0000

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).

JavaScript / TypeScript

Mon, 01 Jan 0001 00:00:00 +0000


Paquete	`@compense/sdk` (ESM y CommonJS, con declaraciones TypeScript)
Versión	1.1.0 · API v1
Requisitos	Node.js 18+ (usa `fetch` nativo); también Deno, Bun, Cloudflare Workers y Vercel/Next.js edge
Dependencias	Ninguna en tiempo de ejecución
Repositorio	Appiasoft/compense-saas-sdk-js · guías en `docs/` · ejemplos en `examples/`

Instalar #

Shell

npm install @compense/sdk

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

Cliente #

 TypeScript
 
 
const client = new CompenseClient({
 apiKey: process.env.COMPENSE_API_KEY!, // obligatorio; viaja como X-API-Key
 environment: "sandbox", // "production" (defecto) | "sandbox" | "dev"
 baseUrl: undefined, // otra URL; gana sobre environment
 timeout: 30_000, // ms por intento
 retry: { maxAttempts: 3, backoffBaseMs: 500, backoffMaxMs: 30_000, jitter: true, retryWrites: false },
 fetch: undefined, // fetch propio (proxy, instrumentación, pruebas)
 logger: console, // avisos de deprecación
});

Hay un solo cliente y todo devuelve Promise. La llave es un secreto de servidor: aunque el cliente funciona en navegadores, nunca pongas una llave en código de frontend.

Simuladores de ciclo de vida

Mon, 01 Jan 0001 00:00:00 +0000

Tu integración tiene que reaccionar a cada estado por el que pasa un movimiento de dinero: mostrar “en proceso”, confirmar al liquidarse, revertir si falla, conciliar si lo devuelven. Los simuladores te permiten recorrer esos estados en el sandbox un paso a la vez y llegar a cada estado terminal (incluidos los fallos) sin esperar a ningún proveedor.

Sobre de respuesta

Mon, 01 Jan 0001 00:00:00 +0000

El gateway responde de dos formas, según el tipo de operación.

Escrituras: el sobre de transacción #

Toda operación que cambia algo (las que llevan Idempotency-Key) responde con el mismo sobre, sea del módulo que sea:

Soporte

Mon, 01 Jan 0001 00:00:00 +0000

Canales #

Canal	Para qué
developers@compense.co	Dudas de integración, errores del API o de los SDK, llaves y onboarding técnico.
Tu ejecutivo de Compense	Contratos, módulos activos, llaves de producción y límites de tasa.
Guías de uso	Cómo operar la plataforma desde el panel y las apps (para asesores y operadores).

Qué incluir en tu mensaje #

El trace_id del error (o la cabecera X-Request-ID de la respuesta).
La operación (operationId o método y ruta) y la hora aproximada con zona horaria.
El entorno (sandbox, dev o producción) y el SDK y versión (compense-sdk-python 1.1.0…).
Tu Idempotency-Key si fue una escritura.
El cuerpo de la respuesta de error (problem+json) y, si aplica, la petición sin datos sensibles.

Nunca envíes

Idempotencia

Mon, 01 Jan 0001 00:00:00 +0000

En una red real las peticiones se cortan: un timeout, un balanceador que reinicia, tu proceso que muere justo después de enviar. En ese momento no sabes si Compense ejecutó la operación. Si reintentas a ciegas puedes desembolsar dos veces; si no reintentas, puedes dejar un pago sin hacer. La Idempotency-Key resuelve ese dilema: reintentar con la misma llave es siempre seguro.

La CLI compense

Mon, 01 Jan 0001 00:00:00 +0000

compense es una herramienta de línea de comandos para las tareas que haces a mano mientras integras: validar una llave, ver el catálogo de eventos, registrar un endpoint, disparar un evento de prueba, revisar y reintentar entregas, mover un reloj de prueba, avanzar un simulador y reenviar webhooks a tu máquina. Cada orden es una envoltura delgada sobre el SDK e imprime la respuesta del gateway como JSON, así que puedes encadenarla con jq.

PHP

Mon, 01 Jan 0001 00:00:00 +0000


Paquete	`compense/sdk` (namespace `Compense\Sdk`)
Versión	1.1.0 · API v1
Requisitos	PHP 8.1+ (`declare(strict_types=1)`, DTO `readonly`)
HTTP	Cualquier cliente PSR-18 + fábricas PSR-17, descubiertos con `php-http/discovery` (Guzzle sugerido)
Repositorio	Appiasoft/compense-saas-sdk-php · guías en `docs/` · ejemplos en `examples/` (PHP plano y Laravel)

Instalar #

 Shell
 
 
composer require compense/sdk guzzlehttp/guzzle
# o con Symfony HttpClient:
composer require compense/sdk symfony/http-client nyholm/psr7

Cliente #

 PHP
 
 
<?php
declare(strict_types=1);

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

$client = new CompenseClient(
 apiKey: getenv('COMPENSE_API_KEY'), // cmp_...
 environment: 'sandbox', // 'production' (defecto) | 'sandbox' | 'dev'; o baseUrl: '...'
 timeout: 30.0, // se aplica cuando el SDK construye Guzzle
 retry: new RetryConfig(maxAttempts: 3, retryWrites: false),
 httpClient: null, // cualquier PSR-18 (contenedor, mocks…)
 logger: $psrLogger, // PSR-3: avisos de deprecación
);

Si pasas tu propio httpClient, configura en él el timeout. Las fábricas PSR-17 (requestFactory:, streamFactory:) se descubren solas si no las das.

Tu primera llamada

Mon, 01 Jan 0001 00:00:00 +0000

Vas a hablar con el sandbox: el gateway responde con el motor simulado, de forma determinista y sin dinero real. Necesitas una llave de sandbox y el SDK instalado. Elige tu lenguaje en cualquier pestaña: la elección se recuerda en todo el sitio.

Recaudo de cartera

Mon, 01 Jan 0001 00:00:00 +0000

En las oficinas de Caja Horizonte los afiliados pagan sus cuotas de crédito en efectivo, y cada mes llega además el archivo de descuentos de nómina (libranza). Todo ese dinero entra por fuera de la plataforma, así que la caja tiene que reportarlo a Compense para que el saldo, la mora, la app del afiliado y el paz y salvo estén al día. Esta receta integra el sistema de taquilla y el proceso del archivo de nómina con el módulo Cartera.

Subsidios

Mon, 01 Jan 0001 00:00:00 +0000

Subsidios y cuota monetaria

Mon, 01 Jan 0001 00:00:00 +0000

Este módulo cubre los dos frentes de subsidio de una caja de compensación:

Subsidios por solicitud (p. ej. el subsidio al desempleo): el afiliado los pide, tú los radicas, un analista o el motor de reglas los decide.
Cuota monetaria: el subsidio en dinero por persona a cargo que se liquida cada período. Aquí no hay solicitud: generas la liquidación del mes, la revisas y desembolsas cada cuota.

El afiliado debe existir en el registro de tu entidad (ver Afiliados).

Verificar la firma

Mon, 01 Jan 0001 00:00:00 +0000

Tu endpoint es una URL pública: cualquiera puede hacerle POST. La firma es lo que te garantiza que el cuerpo lo envió Compense y que nadie lo alteró en el camino. Nunca proceses una entrega sin verificarla primero. Esta página trae receptores completos en los cinco lenguajes de los SDK y la verificación manual, por si no usas un SDK.

Subsidios

Mon, 01 Jan 0001 00:00:00 +0000

El módulo de Subsidios te permite gestionar de principio a fin las ayudas económicas que tu caja entrega a sus afiliados: desde que el afiliado radica una solicitud en la app o el portal, pasando por la revisión y decisión del operador, hasta el desembolso del dinero.

Créditos

Mon, 01 Jan 0001 00:00:00 +0000

El módulo de Créditos cubre el ciclo completo de un préstamo a un afiliado: solicitud → evaluación → decisión → desembolso → amortización. El afiliado simula y solicita desde la app o el portal; la plataforma evalúa el riesgo de forma automática; el operador decide el monto y el plazo; y, una vez desembolsado, el afiliado consulta y paga sus cuotas.

Pagos y Wallet

Mon, 01 Jan 0001 00:00:00 +0000

Cuando tu caja aprueba un subsidio o desembolsa un crédito, el dinero llega al afiliado a través de su billetera digital (wallet). Esta guía explica, para afiliados y operadores, qué es la billetera, cómo se dispersan los pagos, cómo se consultan saldo y movimientos, y cómo verificar el estado de una dispersión.

Afiliados

Mon, 01 Jan 0001 00:00:00 +0000

El padrón de afiliados es el registro maestro de las personas afiliadas a tu caja. De su exactitud depende todo lo demás: a quién se le paga un subsidio, quién puede recibir una cuota monetaria o quién cumple los requisitos de un crédito. Esta guía explica, para operadores, cómo consultar, registrar y actualizar afiliados y su grupo familiar, y cómo mantener la base al día.

PQRS

Mon, 01 Jan 0001 00:00:00 +0000

El módulo de PQRS es el canal formal para que un afiliado de tu caja presente una Petición, Queja, Reclamo o Sugerencia, y para que tus operadores la atiendan dentro de los plazos de ley. Cada caso recibe un número de radicado, avanza por un conjunto de estados y queda con una trazabilidad completa (quién hizo qué y cuándo).

Notificaciones

Mon, 01 Jan 0001 00:00:00 +0000

Compense mantiene informado al afiliado de forma automática: cada vez que su solicitud avanza —se radica, se decide, se desembolsa— o que su PQRS recibe respuesta, recibe un aviso. Tus operadores no tienen que enviar nada manualmente: las notificaciones se disparan solas con cada hecho de negocio.

.NET

Mon, 01 Jan 0001 00:00:00 +0000


Paquete NuGet	`Compense.Sdk`
Versión	1.1.0 · API v1
Destinos	`net8.0` y `netstandard2.0` (.NET Framework 4.6.2+, .NET 6/7/8+, Mono)
Dependencias	`System.Text.Json`, `Microsoft.Extensions.Http`, `Microsoft.Extensions.Logging.Abstractions`, `Microsoft.Extensions.Options.ConfigurationExtensions`
Repositorio	Appiasoft/compense-saas-sdk-dotnet · guías en `docs/modulos/` · ejemplos en `examples/` (consola y receptor de webhooks)

Instalar #

Shell

dotnet add package Compense.Sdk --version 1.1.0

Cliente #

 C#
 
 
using Compense.Sdk;
using Compense.Sdk.Models;

using var client = new CompenseClient(
 Environment.GetEnvironmentVariable("COMPENSE_API_KEY")!, CompenseEnvironment.Sandbox);

// Con todas las opciones:
var configured = new CompenseClient(new CompenseClientOptions
{
 ApiKey = "cmp_...",
 Environment = CompenseEnvironment.Sandbox, // Production (defecto) | Sandbox | Dev
 BaseUrl = null, // otra URL; gana sobre Environment
 Timeout = TimeSpan.FromSeconds(30),
 Retry = new RetryOptions { MaxAttempts = 3, RetryWrites = false },
 UserAgent = "horizonte-erp/2.0",
});

También new CompenseClient(httpClient, options) con tu propio HttpClient (el SDK no lo desecha e ignora su BaseAddress).

Billetera

Mon, 01 Jan 0001 00:00:00 +0000

Esta guía es para el equipo técnico de una fintech (como Nova) o de una caja (como Caja Horizonte) que opera por API la billetera de sus afiliados, con las mismas reglas que la app: saldo y movimientos, transferencias P2P a otro afiliado, Bre-B a otros bancos, pago de facturas de servicios, recargas de celular, sub-cuentas (bolsillos, ahorros, metas), tarjetas y cambio de divisas. Todo vive bajo la etiqueta wallet del contrato y, en los SDK, bajo client.wallet.

Cobrar una factura desde la billetera

Mon, 01 Jan 0001 00:00:00 +0000

En esta receta, la app de Nova deja que sus usuarios paguen la factura de la luz desde su billetera. Vas a recorrer el flujo completo del lado del backend de Nova: elegir el facturador, consultar la factura, confirmar con el usuario, pagar sin riesgo de cobrar dos veces aunque la red falle, enterarte del resultado por webhook y entregar un comprobante. Los detalles de cada operación están en la guía de Billetera.

Cuota monetaria

Mon, 01 Jan 0001 00:00:00 +0000

Datos de prueba

Mon, 01 Jan 0001 00:00:00 +0000

Todo en el sandbox es determinista: el resultado lo decide el documento que envías, algunos montos y los ids que te devuelve el propio sandbox. Esta página reúne esos valores para que escribas pruebas automáticas que cubran el camino feliz y cada error documentado. Recuerda que el sandbox no guarda estado: el estado viaja en los ids y una escritura no cambia lo que devuelven las lecturas siguientes (Sandbox).

Entornos y llaves

Mon, 01 Jan 0001 00:00:00 +0000

El gateway tiene un solo contrato (las mismas rutas, cuerpos y errores) en todos sus despliegues. Lo que cambia entre “probar” y “operar” es la llave con la que llamas.

Reintentos y backoff

Mon, 01 Jan 0001 00:00:00 +0000

Los cinco SDK traen la misma política de reintentos, pensada para que reintentar nunca duplique una operación.

La política por defecto #

Parámetro	Valor por defecto	Qué hace
Intentos máximos	3 (el primero + 2 reintentos)	`1` desactiva los reintentos.
Base del backoff	0,5 s	Espera del primer reintento, duplicándose en cada uno.
Tope del backoff	30 s	Ninguna espera supera este valor.
Jitter	completo	Cada espera es aleatoria entre 0 y el valor calculado, para no sincronizar a todos los clientes.
`Retry-After`	se respeta	Si el gateway lo envía, el SDK espera exactamente eso.
Estados que se reintentan	`429`, `502`, `503`, `504`	Fallos transitorios. Nunca `4xx` de negocio ni `500`.
Métodos	solo `GET`	Las escrituras se reintentan solo con `retry_writes` activado.
Errores de red sin respuesta	no se reintentan	Los reenvías tú con la misma `Idempotency-Key`.

flowchart TD
 A[Petición] --> B{¿Respuesta?}
 B -- no: timeout / red --> X[Excepción de transporte<br/>reenvía tú con la misma llave]
 B -- sí --> C{¿429/502/503/504?}
 C -- no --> D[Éxito o error tipado]
 C -- sí --> E{¿GET o retry_writes?}
 E -- no --> D
 E -- sí --> F{¿Quedan intentos?}
 F -- no --> D
 F -- sí --> G[Espera Retry-After<br/>o backoff con jitter] --> A

¿Por qué las escrituras no se reintentan solas? #

El gateway sí deduplica: cada escritura con Idempotency-Key repetida devuelve la respuesta guardada (idempotent_replay: true) en lugar de ejecutarse otra vez, en todas las rutas con llave. La razón es otra: el SDK no puede saber qué versión del gateway tiene enfrente, y reintentar una escritura contra un despliegue antiguo sin esa garantía la ejecutaría dos veces. Por eso el valor seguro por defecto es reintentar solo GET.

Rotar el secreto

Mon, 01 Jan 0001 00:00:00 +0000

Rota el secreto de un endpoint cuando se filtró (o sospechas que se filtró), cuando una persona con acceso deja el equipo, cuando lo perdiste, o de forma periódica según tu política de seguridad. La rotación genera un secreto nuevo y lo muestra una sola vez, igual que al crear el endpoint.

Billetera

Mon, 01 Jan 0001 00:00:00 +0000

Cartera

Mon, 01 Jan 0001 00:00:00 +0000

El módulo loans empieza donde termina Créditos: una vez desembolsado, el préstamo tiene un plan de cuotas, intereses, mora y saldo. Desde tu sistema puedes consultar todo eso (para tu oficina virtual, tu call center o tu ERP) y reportar los recaudos que tu entidad recibe por fuera de la plataforma: la taquilla, el descuento de nómina o libranza, el archivo del banco, un abono extraordinario o el pago total.

Enviar dinero: P2P y Bre-B

Mon, 01 Jan 0001 00:00:00 +0000

En esta receta, la app de Nova permite enviar dinero a cualquier persona con su celular, correo, documento o alias. Si el destinatario también es usuario de Nova, el envío es una transferencia P2P interna e inmediata; si su llave está en otro banco, va por Bre-B. El backend de Nova decide el riel, muestra a quién se le va a pagar, envía dentro de la vida del token y concilia el resultado final por webhook. Las operaciones están descritas en Billetera.

Errores problem+json

Mon, 01 Jan 0001 00:00:00 +0000

Toda respuesta que no es 2xx llega como application/problem+json (RFC 9457), con la misma forma en los 13 módulos:

 JSON
 
 
{
 "type": "https://errors.compense.co/gateway/validation",
 "title": "Validation error",
 "status": 422,
 "detail": "One or more fields are invalid.",
 "trace_id": "9f1c2e7a4b8d4e6fa1c0d2e3f4a5b6c7",
 "errors": [
 { "field": "term_months", "message": "Input should be greater than or equal to 1" }
 ]
}

Campo	Qué es
`type`	URI del tipo de error (o `about:blank`). Sirve para distinguir casos que comparten código.
`title`	Resumen corto en inglés.
`status`	El código HTTP.
`detail`	Explicación. En los rechazos del motor trae el mensaje del motor en español (por ejemplo «Saldo insuficiente»); cuando el motor no envía mensaje, el gateway cita su código (`(code: INSUFFICIENT_FUNDS)`).
`trace_id`	Igual a la cabecera `X-Request-ID`. Cítalo siempre a soporte.
`errors`	Solo en `422`: lista de `{field, message}`.

El gateway nunca reenvía el cuerpo crudo ni la traza del motor: en 502/504 el detalle es genérico y el error real queda registrado bajo el trace_id.

Go

Mon, 01 Jan 0001 00:00:00 +0000


Módulo	`github.com/Appiasoft/compense-saas-sdk-go` (paquete `compense`, subpaquete `webhook`)
Versión	1.1.0 (`compense.Version`) · API v1
Requisitos	Go 1.21+ (iteradores `range-over-func` con Go 1.23+)
Dependencias	Solo la biblioteca estándar
Repositorio	Appiasoft/compense-saas-sdk-go · guías en `docs/` · ejemplos en `examples/`

Instalar #

 Shell
 
 
go get github.com/Appiasoft/compense-saas-sdk-go@v1.1.0
# Repositorio privado: GOPRIVATE=github.com/Appiasoft/* y credenciales de git

Cliente #

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

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithEnvironment(compense.Sandbox), // Production (defecto) | Sandbox | Dev
	compense.WithBaseURL("https://gw.example.co"), // otra URL; gana sobre el entorno
	compense.WithHTTPClient(myHTTPClient), // proxies, mTLS, tracing, pruebas (no se modifica)
	compense.WithTimeout(30*time.Second), // por intento (solo cliente creado por el SDK)
	compense.WithRetry(compense.RetryConfig{MaxAttempts: 3}),
	compense.WithRetryWrites(false),
	compense.WithUserAgent("horizonte-erp/2.0"),
	compense.WithLogger(slog.Default()), // avisos de deprecación
)
if err != nil {
	log.Fatal(err) // *compense.ConfigError
}

El *Client es seguro para uso concurrente: crea uno por llave y reutilízalo. Cada método recibe un context.Context primero (plazos y cancelación, también durante las esperas entre reintentos).

Reintentos y entregas

Mon, 01 Jan 0001 00:00:00 +0000

Cada vez que Compense intenta llevar un evento a uno de tus endpoints crea una entrega (delivery). Si tu receptor no responde 2xx, la entrega se reintenta sola; y todo queda en un historial que puedes consultar, filtrar y, para las entregas que fallaron, reintentar a mano.

Cartera

Mon, 01 Jan 0001 00:00:00 +0000

Cita médica y recaudo EPS

Mon, 01 Jan 0001 00:00:00 +0000

IPS Horizonte Salud agenda citas desde su call center y su portal, y concilia los giros de las EPS desde su sistema de cartera. En esta receta conectas ese recorrido con Compense: buscas un cupo, agendas a nombre del paciente, recuerdas la cita, manejas cancelaciones y reprogramaciones, registras la asistencia, ubicas la factura de la atención y registras el pago de la EPS sin duplicarlo. Los detalles de cada operación están en la guía de Salud.

Paginación

Mon, 01 Jan 0001 00:00:00 +0000

Las listas del gateway vienen en una de dos formas:

Forma	Campos	Parámetros	Dónde
`Page`	`count`, `results`, `next`, `previous`	`page`, `page_size`	Bandejas de créditos y subsidios, cuota monetaria, PQRS, salud (citas, facturas, glosas, agenda), administrativo, entregas de webhooks, cartera
`OffsetPage`	`results`, `limit`, `offset`, `has_more`, `next_offset`	`limit`, `offset`	Movimientos de la billetera y pagos de facturas

En todos los SDK una página es iterable sobre sus results y conserva el cuerpo original en raw. Lo que cambia es cómo se piden las siguientes.

PQRS

Mon, 01 Jan 0001 00:00:00 +0000

Con este módulo tu CRM o tu call center gestiona las PQRS (peticiones, quejas, reclamos y sugerencias) de tus afiliados server-to-server, sin entrar al panel de Compense: radicas a nombre del afiliado, listas y filtras (incluidas las vencidas), consultas el detalle con su historial, respondes como la entidad y cambias estado o prioridad. Las reglas son exactamente las mismas de la app y del panel: radicado PQRS-AAAA-NNNNNN, plazo legal, máquina de estados y notificación al afiliado cuando se le responde.

Probar tus webhooks

Mon, 01 Jan 0001 00:00:00 +0000

Antes de salir a producción quieres ver tu receptor aceptando una entrega firmada de verdad, rechazando una alterada y respondiendo a tiempo. Esta página cubre las cuatro herramientas para lograrlo: el evento de prueba del API, la CLI compense (trigger y listen), las pruebas unitarias sin red y el sandbox de webhooks.

De la nómina a la contabilidad

Mon, 01 Jan 0001 00:00:00 +0000

Caja Horizonte registra las horas extra y los recargos de su personal en un sistema de turnos y lleva su contabilidad en un ERP. En esta receta conectas ambos con el módulo Administrativo de Compense: cargas las novedades del mes al periodo de nómina, esperas a que nómina lo apruebe en el panel, lees los desprendibles y el estado de la nómina electrónica, y causas el asiento contable en borrador para que el contador lo contabilice.

Montos como texto decimal

Mon, 01 Jan 0001 00:00:00 +0000

En el contrato, todo monto es un texto decimal: el esquema MoneyCOP ("3500000", "467009.88", "53500.00"). Nunca un número de punto flotante.

 JSON
 
{ "amount": "467009.88", "currency": "COP" }

La razón es simple: 0.1 + 0.2 no es 0.3 en binario. Un float puede convertir 467009.88 en 467009.87999999995 en algún punto del camino (tu ORM, tu serializador JSON, una hoja de cálculo), y en dinero un centavo de diferencia rompe una conciliación. El texto viaja exacto de punta a punta.

PQRS

Mon, 01 Jan 0001 00:00:00 +0000

Salud (IPS)

Mon, 01 Jan 0001 00:00:00 +0000

Esta guía es para el equipo técnico de una IPS (o de una entidad con el módulo de salud contratado) que integra su sistema con Compense server-to-server: agenda de citas, facturación de salud y carné de vacunación. Es el mismo gateway y el mismo modelo de seguridad que créditos o billetera. Los ejemplos usan a IPS Horizonte Salud, que agenda desde su call center y concilia los giros de las EPS desde su sistema de cartera.

Administrativo (ERP)

Mon, 01 Jan 0001 00:00:00 +0000

Esta guía es para el equipo técnico de una entidad (caja, fintech o IPS) que integra su ERP con el módulo Gestión Administrativa de Compense: talento humano, nómina, contabilidad y tesorería. Todo es server-to-server con la llave de la entidad; no hay usuario final involucrado. Los ejemplos usan el ERP de Caja Horizonte, que identifica sus documentos con referencias HORIZONTE-ERP-….

Servicios de salud

Mon, 01 Jan 0001 00:00:00 +0000

Versionado y deprecaciones

Mon, 01 Jan 0001 00:00:00 +0000

Versiones #

El API está en la versión mayor v1, que va en la ruta (/v1/gateway/...). Dentro de v1 solo se hacen cambios compatibles.
Los SDK siguen SemVer alineado con el API: la versión mayor del SDK es la mayor del API (1.x habla con v1). Todos están hoy en 1.1.0 (changelog).

Cambios compatibles (pueden llegar sin aviso) #

Operaciones, módulos y eventos de webhook nuevos.
Campos nuevos en las respuestas y en el resource de los webhooks (la version del evento no cambia).
Parámetros opcionales nuevos.
Valores nuevos en enumeraciones de respuesta (estados, categorías).

Escribe tu integración para tolerarlos: ignora campos que no conoces, no valides el catálogo de eventos contra una lista cerrada y trata los estados desconocidos como “pendiente de revisar”.

Administrativo

Mon, 01 Jan 0001 00:00:00 +0000

Límites de tasa y cuotas

Mon, 01 Jan 0001 00:00:00 +0000

Cada llave tiene dos límites, configurados al emitirla:

Límite	Valor por defecto	Al superarlo
Por minuto	120 peticiones por minuto	`429` con `Retry-After` hasta que se libere la ventana
Cuota mensual (opcional)	Sin cuota, salvo que tu contrato la fije	Avisos al cruzar umbrales y, según el contrato, `429` hasta el siguiente período

Si tu volumen necesita más, pídelo en el onboarding o a soporte: el límite se ajusta por llave.

Transacciones y sistema

Mon, 01 Jan 0001 00:00:00 +0000

Dos operaciones transversales que no pertenecen a ningún módulo de negocio, pero que toda integración usa:

Operación	Método SDK (Python)	Scope	Para qué
GET`/v1/gateway/transactions/{tx_id}/`	`client.transactions.get(tx_id)`	ninguno (cualquier llave válida)	Estado y traza de una escritura que hiciste por el gateway.
GET`/v1/gateway/health/`	`client.system.health()`	ninguno	Validar la llave: tenant y scopes. Health check de tu monitoreo.

En los demás SDK: client.transactions.get / client.system.health() (TypeScript), $client->transactions->get / $client->system->health() (PHP), client.Transactions.GetAsync / client.System.HealthAsync() (.NET) y client.Transactions.Get / client.System.Health (Go).

Webhooks

Mon, 01 Jan 0001 00:00:00 +0000

Sandbox

Mon, 01 Jan 0001 00:00:00 +0000

Transacciones

Mon, 01 Jan 0001 00:00:00 +0000

Sistema

Mon, 01 Jan 0001 00:00:00 +0000

Esquemas

Mon, 01 Jan 0001 00:00:00 +0000

Esquemas del contrato tal como los publica el gateway. Los campos marcados como obligatorio deben viajar en la petición; additionalProperties significa que el gateway reenvía al motor los campos adicionales sin tocarlos (por eso los SDK aceptan extra / fields).