Referencia del API · tag affiliates
Afiliados
Cruce e ingesta de la base de afiliados de la entidad: por lotes JSON, por archivo y consulta por documento.
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 affiliates #
Descripción en el contrato: Affiliate base cross-check, ingestion and file upload.
| Método | Ruta | Operación | Scope | Idem. |
|---|---|---|---|---|
| POST | /v1/gateway/affiliates/ | Cross / register the affiliate base | affiliates:upsert | recomendada |
| POST | /v1/gateway/affiliates/upload/ | Upload affiliates from a file (CSV / Excel) | affiliates:upsert | recomendada |
| GET | /v1/gateway/affiliates/{document}/ | Cross-check an affiliate by document | affiliates:read | — |
Cross / register the affiliate base #
POST/v1/gateway/affiliates/
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
Lista (array) de AffiliateRecordIn
.
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Batch processed. | TransactionEnvelope
application/json |
Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502) — application/problem+json
| 400 | Malformed request. | about:blank |
| 401 | Missing or invalid API key. | about:blank |
| 403 | The key is valid but lacks the required scope, or the source IP is not allow-listed. | about:blank |
| 404 | The requested resource does not exist. | about:blank |
| 409 | Idempotency conflict — same key, original still processing. | https://errors.compense.co/gateway/idempotency-conflict |
| 422 | Request body failed validation. | https://errors.compense.co/gateway/validation |
| 429 | Per-key rate limit or monthly quota exceeded; see Retry-After. | https://errors.compense.co/gateway/rate-limited |
| 500 | Unexpected gateway error; quote the trace_id to support. | about:blank |
| 502 | The processing engine returned an error. | https://errors.compense.co/gateway/upstream-error |
Ver Errores problem+json para la excepción equivalente en cada SDK.
Ejemplo
client.affiliates.cross()client.affiliates.cross()$client->affiliates->cross()await client.Affiliates.CrossAsync()client.Affiliates.Cross(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/affiliates/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '[
{
"document_type": "CC",
"document_number": "1032456789",
"first_name": "María",
"last_name": "Gómez",
"email": "maria.gomez@example.co",
"category": "A"
}
]'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.
Upload affiliates from a file (CSV / Excel) #
POST/v1/gateway/affiliates/upload/
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: multipart/form-data · obligatorio
| Campo | Tipo | Descripción |
|---|---|---|
file obligatorio | string (binary) | CSV or XLSX, max 25 MB. |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | File parsed and batch processed. | TransactionEnvelope
application/json |
Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502) — application/problem+json
| 400 | Malformed request. | about:blank |
| 401 | Missing or invalid API key. | about:blank |
| 403 | The key is valid but lacks the required scope, or the source IP is not allow-listed. | about:blank |
| 404 | The requested resource does not exist. | about:blank |
| 409 | Idempotency conflict — same key, original still processing. | https://errors.compense.co/gateway/idempotency-conflict |
| 422 | Request body failed validation. | https://errors.compense.co/gateway/validation |
| 429 | Per-key rate limit or monthly quota exceeded; see Retry-After. | https://errors.compense.co/gateway/rate-limited |
| 500 | Unexpected gateway error; quote the trace_id to support. | about:blank |
| 502 | The processing engine returned an error. | https://errors.compense.co/gateway/upstream-error |
Ver Errores problem+json para la excepción equivalente en cada SDK.
Ejemplo
client.affiliates.upload()client.affiliates.upload()$client->affiliates->upload()await client.Affiliates.UploadAsync()client.Affiliates.Upload(ctx, …)curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/affiliates/upload/" \
-H "X-API-Key: $COMPENSE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F "file=@afiliados.csv"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.
Cross-check an affiliate by document #
GET/v1/gateway/affiliates/{document}/
Parámetros
| Nombre | En | Tipo | Descripción |
|---|---|---|---|
document obligatorio | ruta | string | National document number. Ej.: 1032456789 |
Respuestas
| Código | Descripción | Cuerpo |
|---|---|---|
| 200 | Affiliate found. | AffiliateLookup
application/json |
Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502) — application/problem+json
| 400 | Malformed request. | about:blank |
| 401 | Missing or invalid API key. | about:blank |
| 403 | The key is valid but lacks the required scope, or the source IP is not allow-listed. | about:blank |
| 404 | The requested resource does not exist. | about:blank |
| 409 | Idempotency conflict — same key, original still processing. | https://errors.compense.co/gateway/idempotency-conflict |
| 422 | Request body failed validation. | https://errors.compense.co/gateway/validation |
| 429 | Per-key rate limit or monthly quota exceeded; see Retry-After. | https://errors.compense.co/gateway/rate-limited |
| 500 | Unexpected gateway error; quote the trace_id to support. | about:blank |
| 502 | The processing engine returned an error. | https://errors.compense.co/gateway/upstream-error |
Ver Errores problem+json para la excepción equivalente en cada SDK.
Ejemplo
client.affiliates.get()client.affiliates.get()$client->affiliates->get()await client.Affiliates.GetAsync()client.Affiliates.Get(ctx, …)curl "https://sandbox.dev.compense.co/gw/v1/gateway/affiliates/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.