Scan Agent (SmartScan)

Scan Agent es el punto de entrada OCR de SmartScan usado por flujos de proyecto entrenados para extraer campos estructurados de documentos de identidad. Complementa Escaneo Prompt y Escaneo Estudio.

Endpoint

POST https://api.verifik.co/v2/ocr/scan-agent

Headers

Name	Value
Content-Type	`application/json`
Authorization	`Bearer <token>`

Parámetros

Los campos exactos dependen de la configuración del flujo de proyecto (tipo de documento, lados a capturar y pasos de validación). Los payloads suelen incluir imágenes (image, backImage o claves del flujo) y un identificador de projectFlow.

Name	Type	Required	Description
`colombianBarcodeValidation`	boolean	No	Con `true`, ejecuta la validación antifraude del código PDF417 de cédula colombiana sobre la captura del reverso para detectar documentos alterados o falsificados, adjuntando el resultado en `OCRExtraction.barcodeValidation`. Si se omite, aplica la opción `colombianBarcodeValidation` del flujo de proyecto.

Validación de código de barras colombiano

Para flujos de CC colombiana, el contraste con el código de barras funciona como un escudo automatizado contra el fraude. Si un atacante presenta una cédula con el frente adulterado (número o nombres cambiados), la validación detecta la discrepancia (verdict: "mismatch") y remite el registro a verificación manual (NEEDS_MANUAL_VERIFICATION). Si el código de barras fue manipulado físicamente o adulterado, la lectura falla por completo (verdict: "unreadable").

Activa la validación de código de barras de dos formas:

Flujo de proyecto — habilita colombianBarcodeValidation en la configuración del flujo SmartScan / SmartEnroll en el panel de Verifik.
Cuerpo de la solicitud — envía colombianBarcodeValidation: true en POST /v2/ocr/scan-agent para forzar la lectura en esa llamada.

Cuando está activo y hay una imagen útil del reverso, la extracción OCR incluye barcodeValidation con los mismos veredictos y campos que la API dedicada (decoded / unreadable, o confirmed / mismatch / unreadable cuando el flujo aporta datos de contraste).

Referencia, guía antifraude y facturación: Colombia — Código de barras de cédula (PDF417).

Fragmento de respuesta (código de barras activo)

{
  "data": {
    "OCRExtraction": {
      "documentType": "CC",
      "documentNumber": "1234567890",
      "firstName": "MARIA",
      "lastName": "LOPEZ GARCIA",
      "barcodeValidation": {
        "verdict": "confirmed",
        "attempts": 1,
        "barcode": {
          "documentNumber": "1234567890",
          "primerNombre": "MARIA",
          "segundoNombre": "ELENA",
          "primerApellido": "LOPEZ",
          "segundoApellido": "GARCIA",
          "gender": "F",
          "dateOfBirth": "15/03/1992",
          "bloodType": "O+",
          "fullName": "MARIA ELENA LOPEZ GARCIA"
        },
        "matchScores": {
          "documentNumber": 1,
          "firstName": 0.98,
          "lastName": 0.97
        },
        "disagreements": []
      }
    }
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "October 21, 2026 3:00 PM"
  },
  "id": "SA12B"
}

Notas

La validación del código requiere un reverso nítido; solo el frente puede marcar el paso como unreadable.
El consumo de créditos sigue la configuración SmartScan / smartENROLL de tu cuenta. Consulta Escaneo inteligente.
La captura hospedada de documentos también puede ejecutar la validación cuando el proyecto la tiene activa — ver Validación de documento en registro de aplicación.

Endpoint​

Headers​

Parámetros​

Validación de código de barras colombiano​

Fragmento de respuesta (código de barras activo)​

Notas​