PHPackages                             eitol/colombian-cedula-reader - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. eitol/colombian-cedula-reader

ActiveLibrary

eitol/colombian-cedula-reader
=============================

Librería para leer el código PDF417 de las cedulas de ciudadania de Colombia

497015[1 issues](https://github.com/Eitol/colombian-cedula-reader/issues)PHPCI failing

Since Jul 26Pushed 2y ago2 watchersCompare

[ Source](https://github.com/Eitol/colombian-cedula-reader)[ Packagist](https://packagist.org/packages/eitol/colombian-cedula-reader)[ RSS](/packages/eitol-colombian-cedula-reader/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

### Lector de cédulas colombianas

[](#lector-de-cédulas-colombianas)

Contiene tres componentes:

1- pdf417\_file\_image\_reader.py: Permite leer desde el pdf417 de la cédula colombiada desde una imagen y arrojar el resultado parseado en consola

2- serial\_bar\_code\_scanner\_reader.py: Permite leer el código pdf417 desde un lector manual via USB

3- php: Librería en PHP para decodificar el PDF417

Si deseas decodificar el MRZ de la cédula digital, puedes revisar el siquiente repositorio:

[https://github.com/Eitol/colombian\_cedula\_mrz\_reader](https://github.com/Eitol/colombian_cedula_mrz_reader)

Explicación
-----------

[](#explicación)

La cédula de ciudadanía de Colombia contiene en su posterior un código pdf417, el cual se debe leer en formato binario. Para extraer información se debe hacer lo siguiente:

Primero leer el código desde la imagen.

- Para Android / iOS puedes usar las librerías de ML Vision (son gratuitas y funcionan bien).
- Si quieres leer el contenido del PDF417 desde el backend entonces no existe una alternativa buena para hacerlo que sea gratuita. Puedes usar zxing pero su rendimiento es demasiado pobre. Si quieres obtener buenos resultados lamentablemente tendrás que pagar por librerías que decodifican el PDF417 como dynamsoft, microblink, etc. Repito, no existen SDK gratuitos para backend que permitan leer el PDF417 desde una foto normal y que funcionen bien

Si deseas ahorrarte el tema de un SDK para leer el PDF417 puedes usar un escáner de código de barras de mano QR 2D.

Segundo: Deberás extraer los campos que están en posiciones delimitadas dentro del arreglo de bytes.

FieldStart - EndExampleafis code2 - 1030847811finger card40 - 4816434054document number48 - 5851907053last name58 - 80GONZALEZsecond last name81 - 104MARINfirst name104 - 127MARIAmiddle name127 - 150GABRIELAgender151 - 152F (para masculino es M)birthday year152 - 1561967birthday month156 - 15801birthday day158 - 16028municipality code160 - 16215 (CUNDINAMARCA)department code162 - 165001 (BOGOTA, D.C.)blood type166 - 168O+Cosas a considerar:

- Los campos de municipalidad y departamento están codificados según el documento "pre\_divipol\_02\_agosto\_2011", pero:
    - Para Bogotá hay algunas variaciones (soportadas por este script)
    - No se reconocen los paises extranjeros (Si sabes la tabla por favor envíamela a )
- El campo document number a veces tiene ‘0’ como padding a la izquierda. Deberás eliminarlos.
- Hay varios campos (nombre, apellido, etc) que tienen el carácter “0x00” (null) a la derecha como padding. Deberás eliminarlos.
- Se recomienda usar un visualizador binario para observar los campos y debuguear en tu proceso de desarrollo
- Puedes usar la app "verificame" para verificar el resultado
- El pdf417 tiene:
    - una longitud de 531 bytes en crudo
    - 25 filas y 21 columnas de data
    - Un nivel de seguridad de 5

---

### Instalando dependencias:

[](#instalando-dependencias)

Nota: Se requiere python 3.10 o superior.

pip3 install -r ./requirements.txt

---

### Componente 1: pdf417\_file\_image\_reader.py

[](#componente-1-pdf417_file_image_readerpy)

#### Lector de cédulas colombianas desde imágenes

[](#lector-de-cédulas-colombianas-desde-imágenes)

Se requiere una licencia de dynamsoft.com para usar el lector de cédulas.

#### Ejecutando el script:

[](#ejecutando-el-script)

Ejemplo:

```
export PYTHONPATH=$(pwd)
export LICENSE_KEY="t0073oQAAALynBFjBO5CA5K81zRzE1LOPirl7hdLvd7Pq6ajKzHF7+TQSBJT0gzoj1bcWY9YeIyBQNrgKeaXYGb/lgljYOVhf+9Mi8Q=="
python3 pdf417_file_image_reader.py ./test/testdata/example.jpeg
```

#### Salida

[](#salida)

Por ejemplo para la siguiente imagen:

[![](./test/testdata/example.jpeg)](test/testdata/test_case_1.png)

Se obtiene una salida como la siguiente:

```
{
  "first_name": "DAYFENIX",
  "middle_name": "",
  "last_name": "VALENCIA",
  "second_last_name": "BENITEZ",
  "birth_date": "29-07-1991",
  "blood_type": "A+",
  "gender": "F",
  "location": {
    "department": "BUENAVENTURA",
    "department_code": "019",
    "municipality": "VALLE",
    "municipality_code": "31"
  },
  "document_info": {
    "document_number": "1150940755",
    "afis_code": "26497872",
    "finger_card": "366525"
  }
}
// Esta persona no tiene segundo nombre, pero si lo tuviera se mostrara
```

2- serial\_bar\_code\_scanner\_reader.py: Permite leer el código pdf417 desde un lector manual via USB

---

### Componente 2: serial\_bar\_code\_scanner\_reader.py

[](#componente-2-serial_bar_code_scanner_readerpy)

Permite leer el codigo de barras de una cedula de identidad colombiana desde un lector de códigos de barra físico ( ejemplo: Netum L8BL)

Este debe estar configurado en modo serial (COM)

Notas: Estos lectores arrojan lecturas iguales en linux y mac pero en windows se comportan distinto. Arrojan una lectura en donde truncan los bytes nulos. Esto dificulta un poco la lectura de los datos.

Este script soporta tanto windows como linux y mac.

Por ejemplo para linux y mac el inicio de la lectura inicia así: "0320065791NULNULNULNULNULNULNULNULNULNULNULNULNULNULPubDSK\_1"

Pero para windows iniciaría así: "0320065791NULNULNULPubDSK\_1....."

Note que en windows solo se envían 3 nulos luego del código afis (20065791) mientras que en linux y mac si se envían todos los nulos.

Se utilizó un lector como el siguiente conectado via USB:

[![](./doc/lector_netum.png)](./doc/lector_netum.png)

#### Ejecutando el script:

[](#ejecutando-el-script-1)

```
export PYTHONPATH=$(pwd)
python3 serial_bar_code_scanner_reader.py
```

Cuando el lector detecte un PDF417 de cédula que sea válido, entonces debe mostrarlo en consola.

---

### Componente 3: Librería para PHP

[](#componente-3-librería-para-php)

Nota: usa zxing para leer el código de barras por lo que debe ser usada solo como referencia.

#### Requerimientos

[](#requerimientos)

- PHP >= 7.1

#### Instalación

[](#instalación)

Puedes instalar el paquete a través de composer:

```
{
    "require": {
        "eitol/colombian-cedula-reader": "dev-master"
    }
}
```

Se requiere tener instalada la siguiente extensión de PHP:

ext-intl

---

#### Uso

[](#uso)

```
require __DIR__.'/vendor/autoload.php';

use Eitol\ColombianCedulaReader\ColombianIDCardDecoder;

// Leemos el archivo que contiene una foto
// del posterior de la cédula
$file = file_get_contents("imagen_de_cedula.jpg");

// Decodificamos
$decoder = new ColombianIDCardDecoder();
$result = $decoder->decode($file);
```

resultado

[![doc/result.png](doc/result.png)](doc/result.png)

### Notas:

[](#notas)

Los test unitarios fueron expresamente no agregados git porque contienen data privada. Aun así se tiene un conjunto de datos de prueba que incrementan la calidad de la lectura.

Se está desarrollando el soporte para el nuevo modelo de cédulas con QR

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity23

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity25

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1043061?v=4)[Hector Oliveros](/maintainers/eitol)[@Eitol](https://github.com/Eitol)

---

Top Contributors

[![Eitol](https://avatars.githubusercontent.com/u/1043061?v=4)](https://github.com/Eitol "Eitol (11 commits)")

---

Tags

cedulacolombiacolombiana

### Embed Badge

![Health badge](/badges/eitol-colombian-cedula-reader/health.svg)

```
[![Health](https://phpackages.com/badges/eitol-colombian-cedula-reader/health.svg)](https://phpackages.com/packages/eitol-colombian-cedula-reader)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)