Referencia del API · tag admin
Administrativo
Módulo ERP: talento humano, nómina, contabilidad y tesorería. Los documentos entran como borrador (DRAFT); las aprobaciones siguen en el panel.
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 admin #
Descripción en el contrato: Módulo Administrativo / ERP de la entidad: talento humano (colaboradores, contratos, novedades), nómina (novedades, periodos, desprendibles, nómina electrónica), contabilidad (comprobantes en borrador, terceros, impuestos) y tesorería (recaudos, egresos, cartera y extractos en borrador). Por API no se aprueba, liquida ni contabiliza: eso se hace en el panel.
| Método | Ruta | Operación | Scope | Idem. |
|---|---|---|---|---|
| GET | /v1/gateway/admin/accounting/entries/ | Comprobantes contables | accounting:read | — |
| POST | /v1/gateway/admin/accounting/entries/ | Crear un comprobante contable en BORRADOR | accounting:write | recomendada |
| GET | /v1/gateway/admin/accounting/entries/{entry_id}/ | Comprobante con sus líneas | accounting:read | — |
| POST | /v1/gateway/admin/accounting/taxes/compute/ | Simular impuestos y retenciones | accounting:read | — |
| GET | /v1/gateway/admin/accounting/third-parties/ | Buscar terceros | accounting:read | — |
| POST | /v1/gateway/admin/accounting/third-parties/ | Alta o actualización de un tercero | accounting:write | recomendada |
| GET | /v1/gateway/admin/accounting/third-parties/{third_party}/ | Tercero (por id o documento) | accounting:read | — |
| GET | /v1/gateway/admin/hr/employees/ | Buscar colaboradores | hr:read | — |
| POST | /v1/gateway/admin/hr/employees/ | Alta o actualización de un colaborador (upsert por documento) | hr:write | recomendada |
| GET | /v1/gateway/admin/hr/employees/{employee}/ | Ficha de un colaborador | hr:read | — |
| GET | /v1/gateway/admin/hr/employees/{employee}/contracts/ | Contratos de un colaborador | hr:read | — |
| GET | /v1/gateway/admin/hr/novelties/ | Novedades de talento humano | hr:read | — |
| POST | /v1/gateway/admin/hr/novelties/ | Registrar incapacidad, licencia, permiso o vacaciones | hr:write | recomendada |
| GET | /v1/gateway/admin/payroll/electronic/ | Estado de la nómina electrónica (DIAN) de un mes | payroll:read | — |
| GET | /v1/gateway/admin/payroll/novelties/ | Novedades de nómina | payroll:read | — |
| POST | /v1/gateway/admin/payroll/novelties/ | Cargar novedades de nómina (una o un lote) | payroll:write | recomendada |
| GET | /v1/gateway/admin/payroll/payslips/{payslip_id}/ | Desprendible con sus conceptos | payroll:read | — |
| GET | /v1/gateway/admin/payroll/periods/ | Periodos de nómina | payroll:read | — |
| GET | /v1/gateway/admin/payroll/periods/{period_id}/ | Detalle de un periodo | payroll:read | — |
| GET | /v1/gateway/admin/payroll/periods/{period_id}/payslips/ | Desprendibles de un periodo | payroll:read | — |
| POST | /v1/gateway/admin/treasury/payments/ | Registrar un egreso en BORRADOR | treasury:write | recomendada |
| POST | /v1/gateway/admin/treasury/receipts/ | Registrar un recaudo en BORRADOR | treasury:write | recomendada |
| POST | /v1/gateway/admin/treasury/receivables/ | Registrar una cuenta de cobro en BORRADOR | treasury:write | recomendada |
| POST | /v1/gateway/admin/treasury/statements/ | Cargar un extracto bancario para conciliación | treasury:write | recomendada |
| POST | /v1/gateway/admin/treasury/statements/{statement_id}/auto-match/ | Cruce automático del extracto | treasury:write | recomendada |
Comprobantes contables #
GET/v1/gateway/admin/accounting/entries/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
status | query | string | DRAFT | POSTED | VOID |
voucher_type | query | string | Tipo (CC…). |
date_from | query | string | Desde. |
date_to | query | string | Hasta. |
external_id | query | string | Id del ERP. |
source | query | string | gateway = solo los creados por API. |
q | query | string | Texto o número. |
offset | query | string | Desplazamiento (páginas de 100). |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.accounting.list_entries()client.admin.accounting.listEntries()$client->admin->accounting->listEntries()await client.Admin.Accounting.ListEntriesAsync()client.Admin.Accounting.ListEntries(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/accounting/entries/" \
-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.
Crear un comprobante contable en BORRADOR #
POST/v1/gateway/admin/accounting/entries/
external_id: el mismo id devuelve el comprobante existente (created: false).Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminEntryIn — Comprobante contable en BORRADOR. external_id (id del ERP) lo hace idempotente en el motor. post: true se rechaza: el contador contabiliza en el panel.
| Campo | Tipo | Descripción |
|---|---|---|
date obligatorio | string (date) | |
description obligatorio | string | |
external_id | string | Ej.: "ERP-AS-2026-000123" |
lines obligatorio | array de object | |
reference | string | |
third_party | string | Id o documento del tercero. |
voucher_type | string | Ej.: "CC" |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.accounting.create_entry()client.admin.accounting.createEntry()$client->admin->accounting->createEntry()await client.Admin.Accounting.CreateEntryAsync()client.Admin.Accounting.CreateEntry(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/accounting/entries/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"external_id": "ERP-AS-2026-000123",
"voucher_type": "CC",
"date": "2026-11-02",
"description": "<description>",
"lines": [
{
"account": "13050501"
}
]
}'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.
Comprobante con sus líneas #
GET/v1/gateway/admin/accounting/entries/{entry_id}/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
entry_id obligatorio | ruta | string | Id del comprobante. Ej.: 5c9d… |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Objeto. | AdminObject
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
client.admin.accounting.get_entry()client.admin.accounting.getEntry()$client->admin->accounting->getEntry()await client.Admin.Accounting.GetEntryAsync()client.Admin.Accounting.GetEntry(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/accounting/entries/5c9d…/" \
-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.
Simular impuestos y retenciones #
POST/v1/gateway/admin/accounting/taxes/compute/
Cuerpo de la petición
Tipo de contenido: application/json · obligatorio
Esquema AdminTaxComputeIn
| Campo | Tipo | Descripción |
|---|---|---|
date | string (date) | |
items obligatorio | array de object | |
third_party | string |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.accounting.compute_taxes()client.admin.accounting.computeTaxes()$client->admin->accounting->computeTaxes()await client.Admin.Accounting.ComputeTaxesAsync()client.Admin.Accounting.ComputeTaxes(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/accounting/taxes/compute/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": []
}'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.
Buscar terceros #
GET/v1/gateway/admin/accounting/third-parties/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
q | query | string | Nombre o documento. |
role | query | string | customer | supplier | employee | associate |
limit | query | string | Máximo 500. |
brief | query | string | 1 = solo identificación. |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.accounting.list_third_parties()client.admin.accounting.listThirdParties()$client->admin->accounting->listThirdParties()await client.Admin.Accounting.ListThirdPartiesAsync()client.Admin.Accounting.ListThirdParties(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/accounting/third-parties/" \
-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.
Alta o actualización de un tercero #
POST/v1/gateway/admin/accounting/third-parties/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminThirdPartyIn — Alta o actualización de un tercero (upsert por tipo y número de documento). id_type acepta el código DIAN (31, 13…) o el alias (NIT, CC, CE, PA…). Datos bancarios: solo en el panel.
| Campo | Tipo | Descripción |
|---|---|---|
business_name | string | |
email | string | |
first_last_name | string | |
first_name | string | |
id_number obligatorio | string | Ej.: "900123456" |
id_type obligatorio | string | Ej.: "NIT" |
is_customer | boolean | |
is_supplier | boolean | |
phone | string | |
responsibilities | array de string | |
tax_regime | string |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.accounting.upsert_third_party()client.admin.accounting.upsertThirdParty()$client->admin->accounting->upsertThirdParty()await client.Admin.Accounting.UpsertThirdPartyAsync()client.Admin.Accounting.UpsertThirdParty(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/accounting/third-parties/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"id_type": "NIT",
"id_number": "900123456"
}'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.
Tercero (por id o documento) #
GET/v1/gateway/admin/accounting/third-parties/{third_party}/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
third_party obligatorio | ruta | string | Id o documento del tercero. Ej.: 900123456 |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Objeto. | AdminObject
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
client.admin.accounting.get_third_party()client.admin.accounting.getThirdParty()$client->admin->accounting->getThirdParty()await client.Admin.Accounting.GetThirdPartyAsync()client.Admin.Accounting.GetThirdParty(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/accounting/third-parties/900123456/" \
-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.
Buscar colaboradores #
GET/v1/gateway/admin/hr/employees/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
q | query | string | Texto: nombre, documento, código o correo. |
status | query | string | ACTIVO | RETIRADO |
document | query | string | Documento exacto. |
area | query | string | Id del área. |
position | query | string | Id del cargo. |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.hr.list_employees()client.admin.hr.listEmployees()$client->admin->hr->listEmployees()await client.Admin.Hr.ListEmployeesAsync()client.Admin.HR.ListEmployees(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/hr/employees/" \
-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.
Alta o actualización de un colaborador (upsert por documento) #
POST/v1/gateway/admin/hr/employees/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminEmployeeIn — Alta o actualización de un colaborador (upsert por id_number). Los datos bancarios solo se aceptan en el alta; cambiarlos después se hace en el panel. user_id no se acepta.
| Campo | Tipo | Descripción |
|---|---|---|
area_id | string | |
bank_account_number | string | |
bank_account_type | string | |
bank_name | string | |
email_work | string | |
eps_code | string | |
first_name | string | Ej.: "Laura" |
hire_date | string (date) | Ej.: "2025-02-01" |
id_number obligatorio | string | Ej.: "1032456789" |
id_type | string | Ej.: "CC" |
last_name | string | Ej.: "Pérez" |
pension_fund_code | string | |
phone | string | |
position_id | string |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.hr.upsert_employee()client.admin.hr.upsertEmployee()$client->admin->hr->upsertEmployee()await client.Admin.Hr.UpsertEmployeeAsync()client.Admin.HR.UpsertEmployee(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/hr/employees/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"id_number": "1032456789",
"id_type": "CC",
"first_name": "Laura",
"last_name": "Pérez",
"hire_date": "2025-02-01"
}'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.
Ficha de un colaborador #
GET/v1/gateway/admin/hr/employees/{employee}/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
employee obligatorio | ruta | string | Id del colaborador o su número de documento. Ej.: 1032456789 |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Objeto. | AdminObject
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
client.admin.hr.get_employee()client.admin.hr.getEmployee()$client->admin->hr->getEmployee()await client.Admin.Hr.GetEmployeeAsync()client.Admin.HR.GetEmployee(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/hr/employees/1032456789/" \
-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.
Contratos de un colaborador #
GET/v1/gateway/admin/hr/employees/{employee}/contracts/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
employee obligatorio | ruta | string | Id del colaborador o su número de documento. Ej.: 1032456789 |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.hr.list_employee_contracts()client.admin.hr.listEmployeeContracts()$client->admin->hr->listEmployeeContracts()await client.Admin.Hr.ListEmployeeContractsAsync()client.Admin.HR.ListEmployeeContracts(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/hr/employees/1032456789/contracts/" \
-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.
Novedades de talento humano #
GET/v1/gateway/admin/hr/novelties/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
employee | query | string | Id o documento. |
status | query | string | SOLICITADA, APROBADA… (coma) |
category | query | string | Categoría (coma). |
from | query | string | Desde (AAAA-MM-DD). |
to | query | string | Hasta (AAAA-MM-DD). |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.hr.list_novelties()client.admin.hr.listNovelties()$client->admin->hr->listNovelties()await client.Admin.Hr.ListNoveltiesAsync()client.Admin.HR.ListNovelties(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/hr/novelties/" \
-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.
Registrar incapacidad, licencia, permiso o vacaciones #
POST/v1/gateway/admin/hr/novelties/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminHrNoveltyIn — Novedad de talento humano. Queda SOLICITADA hasta que talento humano la valide.
| Campo | Tipo | Descripción |
|---|---|---|
certificate_number | string | |
days | integer | |
diagnosis_code | string | CIE-10; nunca se devuelve por API. |
employee obligatorio | string | Id o documento del colaborador. Ej.: "1032456789" |
end_date | string (date) | |
hours | number | |
issuing_entity | string | |
reason | string | |
start_date obligatorio | string (date) | |
type_code obligatorio | string | Ej.: "INCAPACIDAD_COMUN" |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.hr.create_novelty()client.admin.hr.createNovelty()$client->admin->hr->createNovelty()await client.Admin.Hr.CreateNoveltyAsync()client.Admin.HR.CreateNovelty(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/hr/novelties/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"employee": "1032456789",
"type_code": "INCAPACIDAD_COMUN",
"start_date": "2026-11-02"
}'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.
Estado de la nómina electrónica (DIAN) de un mes #
GET/v1/gateway/admin/payroll/electronic/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
year | query | string | Año. |
month | query | string | Mes (1-12). |
status | query | string | Estado. |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.payroll.electronic()client.admin.payroll.electronic()$client->admin->payroll->electronic()await client.Admin.Payroll.ElectronicAsync()client.Admin.Payroll.Electronic(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/payroll/electronic/" \
-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.
Novedades de nómina #
GET/v1/gateway/admin/payroll/novelties/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
employee | query | string | Id o documento. |
period | query | string | Id del periodo. |
status | query | string | PENDIENTE | LIQUIDADA | ANULADA |
concept | query | string | Código del concepto. |
from | query | string | Desde. |
to | query | string | Hasta. |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.payroll.list_novelties()client.admin.payroll.listNovelties()$client->admin->payroll->listNovelties()await client.Admin.Payroll.ListNoveltiesAsync()client.Admin.Payroll.ListNovelties(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/payroll/novelties/" \
-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.
Cargar novedades de nómina (una o un lote) #
POST/v1/gateway/admin/payroll/novelties/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminPayrollNoveltyIn — Una novedad (campos de AdminPayrollNovelty en la raíz) o un lote en items (máx. 500, todo o nada). period_id opcional: valida que el periodo esté abierto y que la fecha caiga dentro; sin date, se usa el inicio del periodo.
| Campo | Tipo | Descripción |
|---|---|---|
amount | number | string | |
concept_code | string | |
date | string (date) | |
employee | string | |
items | array de AdminPayrollNovelty | |
period_id | string | |
quantity | number | string |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.payroll.create_novelties()client.admin.payroll.createNovelties()$client->admin->payroll->createNovelties()await client.Admin.Payroll.CreateNoveltiesAsync()client.Admin.Payroll.CreateNovelties(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/payroll/novelties/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{}'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.
Desprendible con sus conceptos #
GET/v1/gateway/admin/payroll/payslips/{payslip_id}/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
payslip_id obligatorio | ruta | string | Id del desprendible. Ej.: 7a2e… |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Objeto. | AdminObject
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
client.admin.payroll.get_payslip()client.admin.payroll.getPayslip()$client->admin->payroll->getPayslip()await client.Admin.Payroll.GetPayslipAsync()client.Admin.Payroll.GetPayslip(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/payroll/payslips/7a2e…/" \
-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.
Periodos de nómina #
GET/v1/gateway/admin/payroll/periods/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
status | query | string | ABIERTO | CALCULADO | APROBADO | REVERTIDO |
kind | query | string | ORDINARIA, PRIMA… |
year | query | string | Año. |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.payroll.list_periods()client.admin.payroll.listPeriods()$client->admin->payroll->listPeriods()await client.Admin.Payroll.ListPeriodsAsync()client.Admin.Payroll.ListPeriods(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/payroll/periods/" \
-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.
Detalle de un periodo #
GET/v1/gateway/admin/payroll/periods/{period_id}/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
period_id obligatorio | ruta | string | Id del periodo de nómina. Ej.: 3f1c… |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Objeto. | AdminObject
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
client.admin.payroll.get_period()client.admin.payroll.getPeriod()$client->admin->payroll->getPeriod()await client.Admin.Payroll.GetPeriodAsync()client.Admin.Payroll.GetPeriod(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/payroll/periods/3f1c…/" \
-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.
Desprendibles de un periodo #
GET/v1/gateway/admin/payroll/periods/{period_id}/payslips/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
period_id obligatorio | ruta | string | Id del periodo de nómina. Ej.: 3f1c… |
employee | query | string | Id o documento. |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Lista. | AdminResultList
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
client.admin.payroll.list_period_payslips()client.admin.payroll.listPeriodPayslips()$client->admin->payroll->listPeriodPayslips()await client.Admin.Payroll.ListPeriodPayslipsAsync()client.Admin.Payroll.ListPeriodPayslips(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/admin/payroll/periods/3f1c…/payslips/" \
-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.
Registrar un egreso en BORRADOR #
POST/v1/gateway/admin/treasury/payments/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminTreasuryDocIn — Recaudo / egreso (third_party, bank_account id o número, date, amount, method, reference, applications) o cuenta de cobro (third_party, issue_date, description, income_account, subtotal, iva_concept). Siempre en BORRADOR.
| Campo | Tipo | Descripción |
|---|---|---|
amount | number | string | |
applications | array de object | |
bank_account | string | |
date | string (date) | |
description | string | |
income_account | string | |
issue_date | string (date) | |
method | string | Ej.: "TRANSFERENCIA" |
reference | string | |
subtotal | number | string | |
third_party obligatorio | string |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.treasury.create_payment()client.admin.treasury.createPayment()$client->admin->treasury->createPayment()await client.Admin.Treasury.CreatePaymentAsync()client.Admin.Treasury.CreatePayment(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/treasury/payments/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"third_party": "<third_party>",
"method": "TRANSFERENCIA"
}'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.
Registrar un recaudo en BORRADOR #
POST/v1/gateway/admin/treasury/receipts/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminTreasuryDocIn — Recaudo / egreso (third_party, bank_account id o número, date, amount, method, reference, applications) o cuenta de cobro (third_party, issue_date, description, income_account, subtotal, iva_concept). Siempre en BORRADOR.
| Campo | Tipo | Descripción |
|---|---|---|
amount | number | string | |
applications | array de object | |
bank_account | string | |
date | string (date) | |
description | string | |
income_account | string | |
issue_date | string (date) | |
method | string | Ej.: "TRANSFERENCIA" |
reference | string | |
subtotal | number | string | |
third_party obligatorio | string |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.treasury.create_receipt()client.admin.treasury.createReceipt()$client->admin->treasury->createReceipt()await client.Admin.Treasury.CreateReceiptAsync()client.Admin.Treasury.CreateReceipt(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/treasury/receipts/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"third_party": "<third_party>",
"method": "TRANSFERENCIA"
}'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.
Registrar una cuenta de cobro en BORRADOR #
POST/v1/gateway/admin/treasury/receivables/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminTreasuryDocIn — Recaudo / egreso (third_party, bank_account id o número, date, amount, method, reference, applications) o cuenta de cobro (third_party, issue_date, description, income_account, subtotal, iva_concept). Siempre en BORRADOR.
| Campo | Tipo | Descripción |
|---|---|---|
amount | number | string | |
applications | array de object | |
bank_account | string | |
date | string (date) | |
description | string | |
income_account | string | |
issue_date | string (date) | |
method | string | Ej.: "TRANSFERENCIA" |
reference | string | |
subtotal | number | string | |
third_party obligatorio | string |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.treasury.create_receivable()client.admin.treasury.createReceivable()$client->admin->treasury->createReceivable()await client.Admin.Treasury.CreateReceivableAsync()client.Admin.Treasury.CreateReceivable(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/treasury/receivables/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"third_party": "<third_party>",
"method": "TRANSFERENCIA"
}'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.
Cargar un extracto bancario para conciliación #
POST/v1/gateway/admin/treasury/statements/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
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 AdminStatementIn — Extracto bancario: lines (JSON) o content (CSV con fecha y valor).
| Campo | Tipo | Descripción |
|---|---|---|
bank_account obligatorio | string | |
closing_balance | number | string | |
content | string | |
date_from | string (date) | |
date_to | string (date) | |
lines | array de object | |
opening_balance | number | string |
Acepta campos adicionales (additionalProperties): se reenvían al motor sin cambios.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.treasury.import_statement()client.admin.treasury.importStatement()$client->admin->treasury->importStatement()await client.Admin.Treasury.ImportStatementAsync()client.Admin.Treasury.ImportStatement(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/treasury/statements/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"bank_account": "<bank_account>"
}'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.
Cruce automático del extracto #
POST/v1/gateway/admin/treasury/statements/{statement_id}/auto-match/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
statement_id obligatorio | ruta | string | Id del extracto. Ej.: 8b1f… |
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 |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Registrado (sobre estándar; data trae el objeto del motor). | 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
client.admin.treasury.auto_match_statement()client.admin.treasury.autoMatchStatement()$client->admin->treasury->autoMatchStatement()await client.Admin.Treasury.AutoMatchStatementAsync()client.Admin.Treasury.AutoMatchStatement(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/admin/treasury/statements/8b1f…/auto-match/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"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.