Skip to main content

Colombia — Código de barras de cédula (PDF417)

Lee el código de barras PDF417 impreso en el reverso de una cédula de ciudadanía (CC) colombiana. Usa este endpoint cuando ya tienes una captura del dorso y necesitas los campos de identidad codificados en el código, con comparación opcional contra datos que obtuviste por OCR, formulario o una consulta previa a /v2/co/cedula.

No es una consulta de identidad ante Registraduría o Procuraduría. Para resolver nombres oficiales por número de documento, usa Ciudadano colombiano (GET/POST /v2/co/cedula). Para validación de código de barras dentro de flujos SmartScan, consulta Scan Agent — Código de barras colombiano.

Prevención de Fraude y Detección de Alteraciones

Este endpoint está diseñado específicamente como un mecanismo crítico contra el fraude de identidad. En intentos de suplantación, los atacantes suelen alterar el texto impreso o la foto en el frente de la cédula, pero no pueden falsificar el código de barras bidimensional PDF417 del reverso. Al contrastar el código contra el OCR del frente, cualquier manipulación física queda en evidencia de inmediato (verdict: "mismatch"). Del mismo modo, si intentan alterar o adulterar los módulos del código de barras, fallan los algoritmos de corrección de error Reed-Solomon, impidiendo su lectura (verdict: "unreadable").

Endpoint​

POST https://api.verifik.co/v2/co/cedula/barcode

Misma ruta en el host de la app: POST https://verifik.app/v2/co/cedula/barcode.

Headers​

NameValue
Content-Typeapplication/json
AuthorizationBearer <token>

Parámetros​

NameTypeRequiredDescription
backImagestringSíReverso de la cédula en base64 (con o sin prefijo data:) o URL HTTPS pública. El código de barras debe verse nítido.
documentTypestringNoTipo de documento. Por defecto CC.
documentNumberstringNoContraste: NUIP / número a comparar con el payload del código.
firstNamestringNoContraste: nombre(s) a comparar.
lastNamestringNoContraste: apellido(s) a comparar.
genderstringNoContraste: género a comparar.
dateOfBirthstringNoContraste: fecha de nacimiento (p. ej. DD/MM/YYYY).
bloodTypestringNoContraste: tipo de sangre.
crossCheckobjectNoAlternativa a los campos planos de contraste. Mismas claves: documentNumber, firstName, lastName, gender, dateOfBirth, bloodType.
barcodeReadAttemptsnumberNoLímite opcional de reintentos internos de lectura cuando la imagen es difícil (reflejos, desenfoque).

Solo decodificación: envía backImage (y opcionalmente documentType). data.verdict será decoded o unreadable.

Con contraste: envía backImage más los campos de contraste (planos o dentro de crossCheck). data.verdict será confirmed, mismatch o unreadable.

Solicitud​

curl -X POST "https://api.verifik.co/v2/co/cedula/barcode" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VERIFIK_TOKEN" \
  -d '{
    "backImage": "https://example.com/ejemplo-reverso-cedula.jpg",
    "documentType": "CC"
  }'

Respuesta​

data incluye siempre attempts (intentos de lectura). Los campos del código usan nomenclatura al estilo Registraduría cuando aplica.

CampoCuándoDescripción
verdictSiempredecoded o unreadable (solo decodificación), o confirmed, mismatch, unreadable (con contraste).
barcodeSi no es unreadableCampos parseados del código (tabla inferior).
decodedDecodificación exitivaMismo contenido semántico que barcode en modo solo decodificación.
matchScoresContrastePuntajes de similitud por campo enviado.
disagreementsContrasteCampos que no superaron el umbral.
reasonOpcionalDetalle cuando verdict es unreadable.
attemptsSiempreIntentos internos de lectura del código.

Campos de barcode:

CampoDescripción
documentNumberNUIP / número de documento
primerNombrePrimer nombre
segundoNombreSegundo nombre (puede ir vacío)
primerApellidoPrimer apellido
segundoApellidoSegundo apellido (puede ir vacío)
genderGénero
dateOfBirthFecha de nacimiento
bloodTypeTipo de sangre
fullNameNombre completo armado desde el código
{
  "data": {
    "verdict": "decoded",
    "attempts": 1,
    "decoded": {
      "documentNumber": "1234567890",
      "primerNombre": "MARIA",
      "segundoNombre": "ELENA",
      "primerApellido": "LOPEZ",
      "segundoApellido": "GARCIA",
      "gender": "F",
      "dateOfBirth": "15/03/1992",
      "bloodType": "O+",
      "fullName": "MARIA ELENA LOPEZ GARCIA"
    },
    "barcode": {
      "documentNumber": "1234567890",
      "primerNombre": "MARIA",
      "segundoNombre": "ELENA",
      "primerApellido": "LOPEZ",
      "segundoApellido": "GARCIA",
      "gender": "F",
      "dateOfBirth": "15/03/1992",
      "bloodType": "O+",
      "fullName": "MARIA ELENA LOPEZ GARCIA"
    }
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "October 21, 2026 2:30 PM"
  },
  "id": "BC9A2"
}

Prevención de Fraude: Detección de Cédulas Alteradas o Falsificadas​

En fraudes con cédulas de ciudadanía colombianas, los estafadores rara vez pueden generar un código PDF417 genuino desde cero. La modalidad habitual consiste en adulterar el texto impreso o la foto frontal de una cédula auténtica o robada (modificando el número de documento o suplantando los nombres).

Dos vectores de ataque y por qué fracasan​

  1. Alteración del frente (Nombres o NUIP manipulados)

    • El atacante altera los datos visibles frontales, pero el código de barras PDF417 del reverso permanece intacto con los datos auténticos registrados por la Registraduría Nacional del Estado Civil.
    • Al enviar los datos extraídos del frente vía crossCheck (o activar la validación en SmartScan / SmartEnroll), Verifik contrasta el frente contra el contenido del código.
    • Cualquier discrepancia produce verdict: "mismatch" e identifica exactamente los campos adulterados en disagreements (por ejemplo ["documentNumber", "firstName"]). En SmartEnroll y registros de aplicación, esto detiene el onboarding automático y remite el registro a verificación manual (NEEDS_MANUAL_VERIFICATION).

  2. Manipulación o inyección de códigos falsos

    • Si intentan alterar físicamente, tachar o modificar los pixeles del código bidimensional para acomodarlo a la información fraudulenta del frente, fallan las palabras clave de corrección de error Reed-Solomon.
    • El motor no logra reconstruir la matriz y responde verdict: "unreadable" con reason: "barcode_not_detected".
    • Si intentan inyectar un código generado artificialmente, el parser de Verifik valida la sintaxis y codificación oficial de la Registraduría; cualquier inconsistencia es rechazada o genera mismatch frente a los datos del titular.
Buena práctica antifraude

En procesos de vinculación digital (KYC), captura siempre el frente y el dorso de la cédula colombiana. Todo resultado con verdict: "mismatch" debe ser considerado un indicador explícito de documento adulterado o fraudulento.

Facturación​

  • Las respuestas HTTP 200 se cobran, incluso cuando data.verdict es unreadable.
  • Los errores de validación HTTP 409 no se cobran, según la Política de facturación y consumo de créditos.
  • Los montos de crédito dependen de la tarificación configurada en tu cuenta (panel, Postman o ejecutivo de cuenta). Esta página no publica un precio fijo.

Notas​