PQRS · 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 `pqrs` #

Descripción en el contrato: PQRS (peticiones, quejas, reclamos y sugerencias) for the entity’s CRM / call center: file on behalf of an affiliate (by document), list with filters, detail with history, respond and change status as the entity, and stats.

Método	Ruta	Operación	Scope	Idem.
GET	`/v1/gateway/pqrs/`	List PQRS (status, type, area, date range, document)	`pqrs:read`	—
POST	`/v1/gateway/pqrs/`	File a PQRS on behalf of an affiliate	`pqrs:submit`	recomendada
GET	`/v1/gateway/pqrs/stats/`	PQRS stats (by status, area, type; overdue)	`pqrs:read`	—
GET	`/v1/gateway/pqrs/{pqrs_id}/`	PQRS detail (responses and status history)	`pqrs:read`	—
POST	`/v1/gateway/pqrs/{pqrs_id}/respond/`	Respond to a PQRS as the entity	`pqrs:manage`	recomendada
POST	`/v1/gateway/pqrs/{pqrs_id}/status/`	Change the status / priority of a PQRS	`pqrs:manage`	recomendada

List PQRS (status, type, area, date range, document) #

GET/v1/gateway/pqrs/

operationId listPqrs
Autenticación X-API-Key · scope pqrs:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo	Descripción
`status`	query	string	Filter by status.
`issue_type`	query	string	Filter by type.
`service_area`	query	string	Filter by area.
`date_from`	query	string (date)	Filed on/after (YYYY-MM-DD).
`date_to`	query	string (date)	Filed on/before (YYYY-MM-DD).
`origin_channel`	query	string	Filter by origin channel.
`document`	query	string	Affiliate document.
`external_reference`	query	string	Your CRM case id.
`overdue`	query	boolean	Only overdue (legal deadline passed, not resolved).
`page`	query	integer
`page_size`	query	integer

Respuestas

Código	Descripción	Cuerpo
200	Paginated PQRS (newest first).	`PqrsPage` 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.pqrs.list()

client.pqrs.list()

$client->pqrs->list()

await client.Pqrs.ListAsync()

client.PQRS.List(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/pqrs/" \
  -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.

File a PQRS on behalf of an affiliate #

POST/v1/gateway/pqrs/

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

Requires pqrs:submit. Emits the pqrs.created webhook.

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 PqrsSubmitIn — File a PQRS on behalf of an affiliate. The radicado (PQRS-AAAA-NNNNNN) and the legal deadline (15 business days, Ley 1755/2015) are set by the engine.

Campo	Tipo	Descripción
`agent`	string	Your agent/user reference (traceability). Ej.: `"ana.p"` Máx. 80 caracteres.
`description` obligatorio	string	Ej.: `"El afiliado reporta un cobro que no reconoce."`
`document` obligatorio	string	Affiliate national document. Ej.: `"1032456789"`
`electronic_notification_consented` obligatorio	boolean	REQUIRED: whether the affiliate accepted electronic notification (Ley 1437 art. 56).
`external_reference`	string	Case id in your CRM. Ej.: `"CRM-88231"` Máx. 100 caracteres.
`issue_type` obligatorio	string	Valores: `petition`, `complaint`, `claim`, `suggestion`.
`origin_channel`	string	Valores: `web`, `call_center`, `phone`, `email`, `in_person`, `chat`, `whatsapp`, `crm`, `api`, `other`.
`related_credit_application_id`	string (nullable)
`related_credit_id`	string
`related_subsidy_active_id`	string
`related_subsidy_application_id`	string (nullable)
`related_type`	string (nullable)	Valores: `credit_application`, `subsidy_application`, `credit`, `subsidy`, .
`service_area` obligatorio	string	Valores: `subsidies`, `credits`, `health`, `marketplace`, `benefits`, `wallet`, `payments`, `general`.
`subject` obligatorio	string	Ej.: `"Cobro no reconocido"` Máx. 255 caracteres.

Respuestas

Código	Descripción	Cuerpo
200	Processed; `data` is the PQRS (with history).	`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.pqrs.submit()

client.pqrs.submit()

$client->pqrs->submit()

await client.Pqrs.SubmitAsync()

client.PQRS.Submit(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/pqrs/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "1032456789",
    "issue_type": "claim",
    "service_area": "wallet",
    "subject": "Cobro no reconocido",
    "description": "El afiliado reporta un cobro de 45.000 que no reconoce.",
    "origin_channel": "call_center",
    "electronic_notification_consented": true,
    "external_reference": "CRM-88231",
    "agent": "ana.p"
  }'

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.

PQRS stats (by status, area, type; overdue) #

GET/v1/gateway/pqrs/stats/

operationId getPqrsStats
Autenticación X-API-Key · scope pqrs:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo	Descripción
`issue_type`	query	string	Filter by type.
`service_area`	query	string	Filter by area.
`date_from`	query	string (date)	Filed on/after (YYYY-MM-DD).
`date_to`	query	string (date)	Filed on/before (YYYY-MM-DD).

Respuestas

Código	Descripción	Cuerpo
200	Aggregated counts.	`PqrsStats` 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.pqrs.stats()

client.pqrs.stats()

$client->pqrs->stats()

await client.Pqrs.StatsAsync()

client.PQRS.Stats(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/pqrs/stats/" \
  -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.

PQRS detail (responses and status history) #

GET/v1/gateway/pqrs/{pqrs_id}/

operationId getPqrs
Autenticación X-API-Key · scope pqrs:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo	Descripción
`pqrs_id` obligatorio	ruta	string	PQRS id (uuid) or radicado. Ej.: `PQRS-2026-000123`

Respuestas

Código	Descripción	Cuerpo
200	The PQRS.	`Pqrs` 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.pqrs.get()

client.pqrs.get()

$client->pqrs->get()

await client.Pqrs.GetAsync()

client.PQRS.Get(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/pqrs/PQRS-2026-000123/" \
  -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.

Respond to a PQRS as the entity #

POST/v1/gateway/pqrs/{pqrs_id}/respond/

operationId respondPqrs
Autenticación X-API-Key · scope pqrs:manage
Idempotency-Key recomendada (el SDK la genera)

Requires pqrs:manage. Only while opened / in_progress / escalated (else 409). is_final resolves it. Emits pqrs.responded (+ pqrs.status_changed when final).

Parámetros

Nombre	En	Tipo	Descripción
`pqrs_id` obligatorio	ruta	string	PQRS id (uuid) or radicado. Ej.: `PQRS-2026-000123`
`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 PqrsRespondIn

Campo	Tipo	Descripción
`agent`	string	Máx. 80 caracteres.
`is_final`	boolean	A final response leaves the PQRS `resolved`.
`response_text` obligatorio	string	Ej.: `"Se reversó el cobro el 28-oct."`

Respuestas

Código	Descripción	Cuerpo
200	Processed; `data` is the PQRS (with history).	`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.pqrs.respond()

client.pqrs.respond()

$client->pqrs->respond()

await client.Pqrs.RespondAsync()

client.PQRS.Respond(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/pqrs/PQRS-2026-000123/respond/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "response_text": "Se reversó el cobro el 28-oct."
  }'

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.

Change the status / priority of a PQRS #

POST/v1/gateway/pqrs/{pqrs_id}/status/

operationId changePqrsStatus
Autenticación X-API-Key · scope pqrs:manage
Idempotency-Key recomendada (el SDK la genera)

Requires pqrs:manage. Invalid transitions are 409. Emits pqrs.status_changed when the status actually changes.

Parámetros

Nombre	En	Tipo	Descripción
`pqrs_id` obligatorio	ruta	string	PQRS id (uuid) or radicado. Ej.: `PQRS-2026-000123`
`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 PqrsStatusIn — Change status following the PQRS state machine: closed is terminal, resolved can only be closed; repeating the current status is an idempotent no-op.

Campo	Tipo	Descripción
`agent`	string	Máx. 80 caracteres.
`note`	string	Máx. 1000 caracteres.
`priority`	string	Valores: `low`, `normal`, `high`, `urgent`.
`status` obligatorio	string	Valores: `opened`, `in_progress`, `escalated`, `resolved`, `closed`.

Respuestas

Código	Descripción	Cuerpo
200	Processed; `data` is the PQRS (with history).	`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.pqrs.change_status()

client.pqrs.changeStatus()

$client->pqrs->changeStatus()

await client.Pqrs.ChangeStatusAsync()

client.PQRS.ChangeStatus(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/pqrs/PQRS-2026-000123/status/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "opened"
  }'

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 pqrs #

List PQRS (status, type, area, date range, document) #

Parámetros

Respuestas

Ejemplo

File a PQRS on behalf of an affiliate #

Parámetros

Cuerpo de la petición

Respuestas

Ejemplo

PQRS stats (by status, area, type; overdue) #

Parámetros

Respuestas

Ejemplo

PQRS detail (responses and status history) #

Parámetros

Respuestas

Ejemplo

Respond to a PQRS as the entity #

Parámetros

Cuerpo de la petición

Respuestas

Ejemplo

Change the status / priority of a PQRS #

Parámetros

Cuerpo de la petición

Respuestas

Ejemplo

Operaciones del tag `pqrs` #