Subsidios · Compense Docs

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.

Operaciones del tag `subsidies` #

Descripción en el contrato: Statutory subsidy intake and decisioning (unemployment, housing, …).

Método	Ruta	Operación	Scope	Idem.
GET	`/v1/gateway/subsidies/applications/`	Subsidy application inbox	`subsidies:read`	—
GET	`/v1/gateway/subsidies/applications/{app_id}/`	Subsidy application detail	`subsidies:read`	—
POST	`/v1/gateway/subsidies/applications/{app_id}/decision/`	Decide a subsidy	`subsidies:decide`	recomendada
POST	`/v1/gateway/subsidies/{subsidy_type}/`	Submit a subsidy (unemployment, housing, …)	`subsidies:submit`	recomendada

Subsidy application inbox #

GET/v1/gateway/subsidies/applications/

operationId listSubsidyApplications
Autenticación X-API-Key · scope subsidies:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo
`page`	query	integer
`page_size`	query	integer
`search`	query	string
`status`	query	string

Respuestas

Código	Descripción	Cuerpo
200	Paginated subsidy applications.	`Page` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.subsidies.list_applications()

client.subsidies.listApplications()

$client->subsidies->listApplications()

await client.Subsidies.ListApplicationsAsync()

client.Subsidies.ListApplications(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/subsidies/applications/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Subsidy application detail #

GET/v1/gateway/subsidies/applications/{app_id}/

operationId getSubsidyApplication
Autenticación X-API-Key · scope subsidies:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo	Descripción
`app_id` obligatorio	ruta	string	Subsidy application id. Ej.: `SUB-2026-000045`

Respuestas

Código	Descripción	Cuerpo
200	Subsidy application detail.	object application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.subsidies.get_application()

client.subsidies.getApplication()

$client->subsidies->getApplication()

await client.Subsidies.GetApplicationAsync()

client.Subsidies.GetApplication(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/subsidies/applications/SUB-2026-000045/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Decide a subsidy #

POST/v1/gateway/subsidies/applications/{app_id}/decision/

operationId decideSubsidyApplication
Autenticación X-API-Key · scope subsidies:decide
Idempotency-Key recomendada (el SDK la genera)

Parámetros

Nombre	En	Tipo	Descripción
`app_id` obligatorio	ruta	string	Subsidy application id. Ej.: `SUB-2026-000045`
`Idempotency-Key`	cabecera	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. Ej.: `horizonte-2026-06-26-credit-000123`

Cuerpo de la petición

Tipo de contenido: application/json · obligatorio

Esquema SubsidyDecisionIn

Campo	Tipo	Descripción
`decision` obligatorio	string	Valores: `APPROVE`, `REJECT`. Ej.: `"APPROVE"`
`reason`	string (nullable)	Ej.: `"Cumple requisitos de permanencia."`

Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.

Respuestas

Código	Descripción	Cuerpo
200	Accepted; transaction enqueued / processed.	`TransactionEnvelope` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.subsidies.decide_application()

client.subsidies.decideApplication()

$client->subsidies->decideApplication()

await client.Subsidies.DecideApplicationAsync()

client.Subsidies.DecideApplication(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/subsidies/applications/SUB-2026-000045/decision/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "APPROVE",
    "reason": "Cumple requisitos de permanencia."
  }'

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Submit a subsidy (unemployment, housing, …) #

POST/v1/gateway/subsidies/{subsidy_type}/

operationId submitSubsidyApplication
Autenticación X-API-Key · scope subsidies:submit
Idempotency-Key recomendada (el SDK la genera)

Parámetros

Nombre	En	Tipo	Descripción
`subsidy_type` obligatorio	ruta	string	Subsidy type slug. Ej.: `unemployment`
`Idempotency-Key`	cabecera	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. Ej.: `horizonte-2026-06-26-credit-000123`

Cuerpo de la petición

Tipo de contenido: application/json · obligatorio

Esquema SubsidyApplicationIn — Statutory subsidy application. subsidy_type is the path segment (e.g. unemployment).

Campo	Tipo	Descripción
`afiliado` obligatorio	`AffiliateRef`
`external_reference`	string	Ej.: `"HORIZONTE-SUB-2026-000045"`
`period`	string	Settlement period YYYY-MM. Ej.: `"2026-06"`

Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.

Respuestas

Código	Descripción	Cuerpo
200	Accepted; transaction enqueued / processed.	`TransactionEnvelope` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.subsidies.submit_application()

client.subsidies.submitApplication()

$client->subsidies->submitApplication()

await client.Subsidies.SubmitApplicationAsync()

client.Subsidies.SubmitApplication(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/subsidies/unemployment/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "afiliado": {
      "document_type": "CC",
      "document_number": "1032456789"
    },
    "period": "2026-06",
    "external_reference": "HORIZONTE-SUB-2026-000045"
  }'

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Operaciones del tag subsidies #

Subsidy application inbox #

Parámetros

Respuestas

Ejemplo

Subsidy application detail #

Parámetros

Respuestas

Ejemplo

Decide a subsidy #

Parámetros

Cuerpo de la petición

Respuestas

Ejemplo

Submit a subsidy (unemployment, housing, …) #

Parámetros

Cuerpo de la petición

Respuestas

Ejemplo

Operaciones del tag `subsidies` #