Operating Guide

This guide walks through a full test run in the automation environment: register your webhook, create a lead, evaluate it, read it back through the API, make the client re-enter and complement a lead with an income co-applicant.

Automation only

Every request below goes to https://automation.api.banca.me with your automation API key. The /automation/real-estate/* endpoints emulate the client in creditos.banca.me and respond 404 ERR_ENDPOINT_NOT_AVAILABLE in any other environment.

1. Register your webhook (once)

Only needed to test webhooks. Register a destination in automation with POST /partner/webhook/subscription, subscribed to new_lead and/or pre_approve. From then on every lead you create in the next steps is delivered there, in the same format and with the same verification as in production.

2. Create a lead

Emulates the client entering their RUT in creditos.banca.me.

curl -X POST https://automation.api.banca.me/automation/real-estate/lead \
  -H "Authorization: Bearer <AUTOMATION_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "rut": "12345678-5", "originLabel": "<your-origin-label>" }'

Field	Required	Description
`rut`	Yes	Client RUT. Any valid RUT works; use a test RUT to force a rejection.
`originLabel`	Yes	Origin of the project the lead belongs to. It must belong to your partner.
`metadata`	No	Optional contact and profile data, same shape as `metadata` in `POST /partner/pre-loan-request`.

Response 201

{
  "data": {
    "plrId": "c157ad9f-6592-4324-bec7-8ec583772989",
    "step": "NEEDS_CU",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

plrId is the lead id (idBancame in webhooks). Keep it for the next step.
step is NEEDS_CU: the lead is waiting for the client, as it would right after they enter their RUT.
token is the client session token used by creditos.banca.me. You do not need it for these tests.

Webhook: new_lead is delivered at this point.

3. Generate the pre-approves

Emulates the client completing the flow in creditos.banca.me. The lead is evaluated against your project's risk policies using the mocked risk profile of its RUT (see Test Cases).

curl -X POST https://automation.api.banca.me/automation/real-estate/pre-approve/<plrId> \
  -H "Authorization: Bearer <AUTOMATION_API_KEY>"

Response 201 — approved

{
  "data": {
    "plrId": "c157ad9f-6592-4324-bec7-8ec583772989",
    "step": "READY_FOR_LOAN",
    "accepted": true,
    "archivedComment": null,
    "preApproves": [
      {
        "id": "5247f080-6099-4c66-a4cd-0a544a04d651",
        "accepted": true,
        "productType": "mortgage",
        "productSubtype": "main",
        "maxAmount": 141059550,
        "maxPeriods": 288,
        "rate": 0.051322486,
        "complementable": false,
        "complementaryPlrId": null,
        "hardFilterResults": {
          "min_age": true,
          "max_age": true,
          "min_net_salary": true,
          "protest_and_delinquency_1year": true,
          "protest_and_delinquency_5years": true
        }
      }
    ]
  }
}

Response 201 — rejected (RUT 11111111-1)

{
  "data": {
    "plrId": "144053f9-1160-4b85-a553-7f85b756d2e9",
    "step": "ARCHIVED_FAIL",
    "accepted": false,
    "archivedComment": "Rechazo Automático: No se cumplen las condiciones para otorgar un producto.",
    "preApproves": [
      {
        "id": "80f4668d-23a3-42d2-ba84-7e726069d91e",
        "accepted": false,
        "productType": "mortgage",
        "productSubtype": "main",
        "maxAmount": 141059550,
        "maxPeriods": 288,
        "rate": 0.051854253,
        "complementable": false,
        "complementaryPlrId": null,
        "hardFilterResults": {
          "min_net_salary": true,
          "protest_and_delinquency_1year": false,
          "protest_and_delinquency_5years": false
        }
      }
    ]
  }
}

hardFilterResults is shortened in these examples. It lists every filter of your policy: true means the filter passed, and false means it failed and explains the rejection.

Field	Description
`accepted`	`true` if at least one product was pre-approved.
`step`	`READY_FOR_LOAN` when approved, `ARCHIVED_FAIL` when rejected.
`archivedComment`	Rejection reason when the lead was archived, otherwise `null`.
`preApproves`	One entry per product evaluated for your project.
`preApproves[].complementable`	`true` when the pre-approve was rejected only for income-related filters, so an income co-applicant could make it pass. See Complement a lead.
`preApproves[].complementaryPlrId`	The co-applicant's `plrId` for a pre-approve produced by a complement, otherwise `null`.

Webhook: pre_approve is delivered at this point, with the evaluation result.

4. Read the lead through the API

Now test your API integration exactly as you would in production. These are the regular partner endpoints, with the same automation API key:

What you want	Endpoint
Every lead of a RUT, newest first	`GET /partner/pre-loan-request/{idNumber}`
The latest evaluation of a RUT	`GET /partner/pre-approve/rut/{rut}`
Leads of several RUTs at once	`POST /partner/lead/batch`
The pre-approves of a lead	`GET /partner/pre-approve/{preLoanRequestId}`

curl https://automation.api.banca.me/partner/pre-approve/rut/12345678-5 \
  -H "Authorization: Bearer <AUTOMATION_API_KEY>"

5. Re-enter with the same RUT

Calling step 2 again with a RUT that already has a lead in the same project emulates a person who comes back to creditos.banca.me:

The previous lead is archived (ARCHIVED_FAIL) with the comment Automation: solicitud archivada porque la persona reingresó con el mismo RUT. If it was already archived, for example because it was rejected, it is left as is.
A new lead is created with a new plrId, in NEEDS_CU.
new_lead is delivered again, for the new lead.

Then run step 3 with the new plrId. The archived lead can no longer be evaluated: POST /automation/real-estate/pre-approve/{oldPlrId} responds 422 ERR_INVALID_STEP.

Reading the RUT through the API after a re-entry is a good test too: GET /partner/pre-loan-request/{idNumber} returns both leads, the new one first, with the old one in ARCHIVED_FAIL and its archivedComment. GET /partner/pre-approve/rut/{rut} keeps returning the previous evaluation until you evaluate the new lead in step 3.

Reusing RUTs across runs

Because every call to step 2 starts a fresh lead, a CI pipeline can reuse the same RUTs on every run. You do not need to generate new RUTs or clean anything up between runs.

6. Complement a lead

A lead rejected only for income-related reasons comes back with complementable: true — in the webhook and in step 3's response. In production the client then invites an income co-applicant (for example their spouse), who goes through creditos.banca.me with the invitation link; banca.me evaluates the lead again with both incomes combined.

POST /automation/real-estate/complement/{plrId} emulates that co-applicant: it creates their lead linked to yours, evaluates it with the mocked profile of their RUT, and applies the complement to your lead.

curl -X POST https://automation.api.banca.me/automation/real-estate/complement/<leadPlrId> \
  -H "Authorization: Bearer <AUTOMATION_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "rut": "13131313-6", "declaredRelationship": "conyuge" }'

Field	Required	Description
`rut`	Yes	Co-applicant RUT. It must differ from the lead's. Any RUT has a healthy profile; `11111111-1` adds delinquencies.
`declaredRelationship`	No	Relationship to the lead: `conyuge` (default), `hijo`, `padre` or `otro`.

Response 201 — the lead 55555555-5 complemented by a healthy co-applicant

{
  "data": {
    "plrId": "bbabdbc0-a4f6-407a-8ffc-8230402072e3",
    "step": "READY_FOR_LOAN",
    "accepted": true,
    "archivedComment": null,
    "complementaryPlrId": "912d0162-6ef4-47e0-bfe8-0a84a435f17c",
    "preApproves": [
      {
        "id": "c04a5757-1110-4b02-819e-50a7aa685f65",
        "accepted": true,
        "productType": "mortgage",
        "productSubtype": "main",
        "maxAmount": 158692000,
        "maxPeriods": 288,
        "rate": 0.051322486,
        "complementable": false,
        "complementaryPlrId": "912d0162-6ef4-47e0-bfe8-0a84a435f17c",
        "hardFilterResults": { "min_net_salary": true, "min_brute_salary": true }
      },
      {
        "id": "00893bef-3d3f-4ce0-9e1e-c6af0abb2be0",
        "accepted": false,
        "productType": "mortgage",
        "productSubtype": "main",
        "maxAmount": 17632444,
        "maxPeriods": 288,
        "rate": 0.051698957,
        "complementable": true,
        "complementaryPlrId": null,
        "hardFilterResults": { "min_net_salary": false, "min_brute_salary": false }
      }
    ]
  }
}

The response describes the lead (plrId), not the co-applicant:

preApproves keeps the lead's own evaluation (complementaryPlrId: null) and adds the complemented one (complementaryPlrId = the co-applicant).
If the complement is accepted, the lead leaves ARCHIVED_FAIL and moves to READY_FOR_LOAN.
complementaryPlrId at the top level is the co-applicant's lead.

Webhooks — read this before testing them:

Lead	Events delivered
The co-applicant	`new_lead` and `pre_approve`, as a lead of their own, describing their evaluation alone. Nothing in them marks a complement.
Your lead	None. Applying the complement does not send a new `pre_approve`; the last one you received still says `rechazado`.

To see the combined result, read the lead's RUT with GET /partner/pre-loan-request/{idNumber}: the lead comes back in its new step, and its preApproves include the complemented one, with the co-applicant's id in complementaryPreLoanRequestId. GET /partner/pre-approve/rut/{rut} keeps reporting the lead's own evaluation and does not reflect the complement.

Errors

Status	Error	When
`404`	`ERR_ENDPOINT_NOT_AVAILABLE`	The request was not sent to the automation environment.
`401`	—	Missing or invalid API key.
`404`	`ERR_PARTNER_ENTITY_NOT_FOUND`	`originLabel` does not belong to your partner and you have more than one project. With a single project, the lead is created in that project's default origin.
`403`	`ERR_PARTNER_ENTITY_NOT_ACTIVE`	The project of `originLabel` is inactive.
`404`	`ERR_PRE_LOAN_REQUEST_NOT_FOUND`	`plrId` does not exist or belongs to another partner.
`422`	`ERR_INVALID_STEP`	`plrId` is archived, for example after a re-entry. Use the latest `plrId`.
`422`	`ERR_INVALID_ID_NUMBER`	`rut` is not a valid RUT.
`422`	`ERR_LEAD_NOT_COMPLEMENTABLE`	Complement: the lead has no pre-approve that can be complemented (for example `11111111-1`, rejected for delinquency).
`422`	`ERR_INCORRECT_PRE_LOAN_REQUEST_STATE`	Complement: the co-applicant `rut` is the lead's own RUT.
`422`	`ERR_INVALID_DECLARED_RELATIONSHIP`	Complement: `declaredRelationship` is not one of `conyuge`, `hijo`, `padre`, `otro`.

1. Register your webhook (once)​

2. Create a lead​

3. Generate the pre-approves​

4. Read the lead through the API​

5. Re-enter with the same RUT​

6. Complement a lead​

Errors​