Prefetch evaluation data

Partner-facing specification for starting the credit check in the background while the customer completes the first form on the tablet.

Related: Samsung Finance+ API (OpenAPI) — authentication, standard response envelope, and error format.

API version: v1

Purpose

This endpoint lets the tablet app send the customer's DNI as soon as it is entered on the first form, before POST /api/sfp/v1/application/create.

Apurata starts the credit-bureau lookup asynchronously. When the customer finishes the form and consent flow and create runs, the evaluation can reuse data that is already available, reducing wait time after application submission.

Important:

When to call (tablet integration)

View (EN) Vista (ES) Trigger
First form — Verify Identity Primer formulario — Verificar identidad When the customer leaves the DNI field (e.g. onBlur) and the DNI passes local validation (8 digits). Call before the consent screen and before create.

Do not wait for the full form to be submitted. The goal is to overlap user typing with the credit check.

Call once per DNI entry on that screen. If the customer edits the DNI, call again when they leave the field with the new value.

Authentication

Same rules as all Samsung Finance+ partner endpoints (see sfplus.md):

Endpoint

URL: /api/sfp/v1/application/prefetch-evaluation-data

Method: POST

Base URL (production): https://apurata.com

Request body

JSON object. All fields are required.

Field Type Description
dni string Peruvian DNI — exactly 8 digits (^[0-9]{8}$).
store_id string Store DMS code (sfp_dms_code) from onboarding — same value used in create. Used to resolve the store and validate token environment.

Example:

{
  "dni": "12345678",
  "store_id": "TESTKIO99"
}

Success response

Code: 200 OK

{
  "success": true,
  "message": "Scrape started",
  "data": {
    "dni": "12345678"
  },
  "error": {}
}
Field Description
success true when the request was accepted.
message Informational confirmation that the background lookup was queued.
data.dni Echo of the DNI from the request.
error Empty object on success.

There is no polling endpoint for this step. Credit evaluation continues automatically when the application is created.

Error responses

Same envelope as other SFP endpoints: success, message, data, error.

400 — Validation error

Invalid or missing fields (e.g. DNI not 8 digits, missing store_id).

{
  "success": false,
  "message": "",
  "data": {},
  "error": {
    "code": 400,
    "validationErrors": [
      {
        "fieldName": "dni",
        "errorString": "Invalid DNI format"
      }
    ]
  }
}

400 — Authentication error

Missing or wrong Bearer token.

{
  "success": false,
  "message": "",
  "data": {},
  "error": {
    "code": 400,
    "message": "Wrong or missing client token"
  }
}

400 — Store not found

Unknown store_id / onboarding not completed.

{
  "success": false,
  "message": "",
  "data": {},
  "error": {
    "code": 400,
    "message": "Store UNKNOWN_STORE not found, ensure onboarding is completed"
  }
}

401 — Token / store environment mismatch

Production token used against a test store, or staging token against a production store.

{
  "success": false,
  "message": "",
  "data": {},
  "error": {
    "code": 401,
    "message": "You are using a production token for a staging client"
  }

Sample request

curl -X POST 'https://apurata.com/api/sfp/v1/application/prefetch-evaluation-data' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <staging_or_production_token>' \
  --data-raw '{
    "dni": "12345678",
    "store_id": "TESTKIO99"
  }'

Relationship to create

Typical sequence on the tablet:

  1. Customer enters DNI on the first form → prefetch-evaluation-data (this endpoint).
  2. Customer completes the rest of the form and accepts consent.
  3. POST /api/sfp/v1/application/create with the full payload (including the same DNI and store_id).

No application_id is required for prefetch because the application does not exist yet.

Notes for integrators