Credit bureau (Colombia)

A mock of a Colombian credit bureau, an operator of financial data under Ley 1266 de 2008, in the style of Datacrédito or TransUnion Colombia. It does two jobs:

• Consultations: a subject's score and history, with their authorisation.
• Negative reports: reporting an overdue obligation, with the law's rules enforced on the bureau's side.

Each bureau's interface comes with its contract, often SFTP file batches. So this mock defines a neutral REST contract, and your adapter maps it to your bureau's format.

Synthetic subjects only: no real person's history is in the mock. Testlie is not affiliated with any bureau.

#Connect

Create a Credit bureau (Colombia) under Banking, and send Authorization: Bearer <API key> (CREDIT_BUREAU_API_KEY). The prior notice period is 20 days (OPERATOR_BUREAU_PRIOR_NOTICE_DAYS).

Bodies are JSON. Errors are { "code", "message" }: UNAUTHORIZED and INVALID_SIGNATURE (401), INVALID_BODY and INVALID_IDEMPOTENCY_KEY (400), NOT_FOUND (404), REPORT_ID_REUSED, IDEMPOTENCY_KEY_REUSED and NOT_OPEN (409).

Idempotency-Key (optional, on reports, payments and rectifications): a write that succeeded under a key answers the same key again with 409 { accepted: true, code: "DUPLICATE_REQUEST", … } and the first result. A different request under that key is 409 { accepted: false, code: "IDEMPOTENCY_KEY_REUSED" }. A refused write is not remembered, so you can correct it and send it again with the same key.

X-Bureau-Signature (optional): when you send it, it must be the hex HMAC-SHA256 of the raw body under the system's request signing secret (CREDIT_BUREAU_SIGNING_SECRET), optionally prefixed sha256=; otherwise the call is 401 INVALID_SIGNATURE.

#Consultations

POST /v1/consultations takes { subject: { documentType, documentNumber, fullName? }, consentId, purpose? }. consentId, the subject's authorisation, is required. documentType is CC, CE, TI, PPT, PASAPORTE or NIT.

The answer:

• reference and consultedAt;
• hasHistory;
• score (150 to 950) and riskBand (A best to E);
• obligations[];
• negativeRecords[].

Scores are synthetic and stable per number:

Reports filed with this mock show up in later consultations of the same subject, and lower the score.

#Negative reports

POST /v1/reports takes:

{ "reportId": "your id (idempotency key)",
  "subject": { "documentType": "CC", "documentNumber": "1020304050", "fullName": "…" },
  "obligation": { "reference": "ACC-000123", "type": "TELECOMUNICACIONES", "amountMinor": 12000000, "currency": "COP", "dueDate": "2026-08-05", "daysPastDue": 60 },
  "priorNotice": { "id": "notice-1", "sentAt": "2026-08-20T10:00:00Z", "deliveredAt": "2026-08-20T10:01:00Z", "channel": "SMS" } }

It answers 201 { accepted: true, providerReference, status: "REPORTED", … }. It answers 422 { accepted: false, code, reasons[] } when the report breaks a rule:

The same reportId with the same report answers the first result again (200), even when daysPastDue has grown, since a retry on a later day recomputes it. With a different subject, obligation or prior notice it answers 409 REPORT_ID_REUSED.

Not implemented: file batches, positive reporting, and the bureau's own scoring models.