PQRS · Compense Docs

This page is generated from the contract (data/gateway-v1.json): each operation shows its verb, path, parameters, body, responses, whether it carries an Idempotency-Key, and the equivalent method in all five SDKs. For the end-to-end flow with complete examples, see the implementation guide.

Operations in tag `pqrs` #

Contract description: 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.

Method	Path	Operation	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`	recommended
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`	recommended
POST	`/v1/gateway/pqrs/{pqrs_id}/status/`	Change the status / priority of a PQRS	`pqrs:manage`	recommended

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

GET/v1/gateway/pqrs/

operationId listPqrs
Authentication X-API-Key · scope pqrs:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`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

Responses

Code	Description	Body
200	Paginated PQRS (newest first).	`PqrsPage` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

File a PQRS on behalf of an affiliate #

POST/v1/gateway/pqrs/

operationId submitPqrs
Authentication X-API-Key · scope pqrs:submit
Idempotency-Key recommended (the SDK generates it)

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

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

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

Field	Type	Description
`agent`	string	Your agent/user reference (traceability). E.g.: `"ana.p"` Max. 80 characters.
`description` required	string	E.g.: `"El afiliado reporta un cobro que no reconoce."`
`document` required	string	Affiliate national document. E.g.: `"1032456789"`
`electronic_notification_consented` required	boolean	REQUIRED: whether the affiliate accepted electronic notification (Ley 1437 art. 56).
`external_reference`	string	Case id in your CRM. E.g.: `"CRM-88231"` Max. 100 characters.
`issue_type` required	string	Values: `petition`, `complaint`, `claim`, `suggestion`.
`origin_channel`	string	Values: `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)	Values: `credit_application`, `subsidy_application`, `credit`, `subsidy`, .
`service_area` required	string	Values: `subsidies`, `credits`, `health`, `marketplace`, `benefits`, `wallet`, `payments`, `general`.
`subject` required	string	E.g.: `"Cobro no reconocido"` Max. 255 characters.

Responses

Code	Description	Body
200	Processed; `data` is the PQRS (with history).	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

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

GET/v1/gateway/pqrs/stats/

operationId getPqrsStats
Authentication X-API-Key · scope pqrs:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`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).

Responses

Code	Description	Body
200	Aggregated counts.	`PqrsStats` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

PQRS detail (responses and status history) #

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

operationId getPqrs
Authentication X-API-Key · scope pqrs:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`pqrs_id` required	path	string	PQRS id (uuid) or radicado. E.g.: `PQRS-2026-000123`

Responses

Code	Description	Body
200	The PQRS.	`Pqrs` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Respond to a PQRS as the entity #

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

operationId respondPqrs
Authentication X-API-Key · scope pqrs:manage
Idempotency-Key recommended (the SDK generates it)

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

Parameters

Name	In	Type	Description
`pqrs_id` required	path	string	PQRS id (uuid) or radicado. E.g.: `PQRS-2026-000123`
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Schema PqrsRespondIn

Field	Type	Description
`agent`	string	Max. 80 characters.
`is_final`	boolean	A final response leaves the PQRS `resolved`.
`response_text` required	string	E.g.: `"Se reversó el cobro el 28-oct."`

Responses

Code	Description	Body
200	Processed; `data` is the PQRS (with history).	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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."
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Change the status / priority of a PQRS #

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

operationId changePqrsStatus
Authentication X-API-Key · scope pqrs:manage
Idempotency-Key recommended (the SDK generates it)

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

Parameters

Name	In	Type	Description
`pqrs_id` required	path	string	PQRS id (uuid) or radicado. E.g.: `PQRS-2026-000123`
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

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

Field	Type	Description
`agent`	string	Max. 80 characters.
`note`	string	Max. 1000 characters.
`priority`	string	Values: `low`, `normal`, `high`, `urgent`.
`status` required	string	Values: `opened`, `in_progress`, `escalated`, `resolved`, `closed`.

Responses

Code	Description	Body
200	Processed; `data` is the PQRS (with history).	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Operations in tag pqrs #

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

Parameters

Responses

Example

File a PQRS on behalf of an affiliate #

Parameters

Request body

Responses

Example

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

Parameters

Responses

Example

PQRS detail (responses and status history) #

Parameters

Responses

Example

Respond to a PQRS as the entity #

Parameters

Request body

Responses

Example

Change the status / priority of a PQRS #

Parameters

Request body

Responses

Example

Operations in tag `pqrs` #