Documentación de la API

Introducción

La API de Extraer Datos de Pasaporte te permite extraer datos de pasaportes de cualquier país de manera programática. Utiliza inteligencia artificial para procesar las imágenes, extraer todos los campos de la página principal y validar la zona MRZ con los dígitos de control del estándar ICAO 9303.

URL Base: https://extraerdatosdepasaporte.com/api/v1

Autenticación

Todas las peticiones a la API requieren autenticación mediante una API key. Incluye tu API key en el header X-API-Key de cada petición.

curl -H "X-API-Key: pas_tu_api_key" \
  https://extraerdatosdepasaporte.com/api/v1/balance

Puedes generar y administrar tus API keys desde el dashboard.

Métodos de Upload

La API soporta múltiples métodos para enviar imágenes. El método se detecta automáticamente del header Content-Type.

MétodoContent-TypeUso recomendado
Recomendado
Multipart
multipart/form-datacurl, Postman, formularios HTML
Base64 JSONapplication/jsonJavaScript, apps moviles
URL Fetchapplication/jsonImágenes hospedadas en la nube
Binarioimage/jpeg, image/png, image/webpCLI tools, streaming

Endpoints

POST/api/v1/extract

Extrae datos de una imagen de la página principal del pasaporte.

RecomendadoMultipart Form-Data

Envía archivos directamente. Ideal para curl y Postman.

CampoTipoDescripción
image_frontfilePágina principal del pasaporte (requerido)
image_backfilePágina adicional (opcional)
curl -X POST https://extraerdatosdepasaporte.com/api/v1/extract \
  -H "X-API-Key: pas_tu_api_key" \
  -F "image_front=@./pasaporte.jpg" \
  -F "image_back=@./pasaporte_extra.jpg"

Base64 JSON

Envía imágenes codificadas en base64. El prefijo data URL es opcional.

CampoTipoDescripción
image_frontstringBase64 de imagen frontal (requerido)
image_backstringBase64 de imagen trasera (opcional)
# Codificar imagen a base64
IMAGE_BASE64=$(base64 -i pasaporte.jpg)

curl -X POST https://extraerdatosdepasaporte.com/api/v1/extract \
  -H "X-API-Key: pas_tu_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"image_front\": \"$IMAGE_BASE64\"}"

URL Fetch

Envía URLs de imágenes hospedadas. Solo se permiten URLs HTTPS.

CampoTipoDescripción
image_front_urlstringURL HTTPS de imagen frontal (requerido)
image_back_urlstringURL HTTPS de imagen trasera (opcional)
curl -X POST https://extraerdatosdepasaporte.com/api/v1/extract \
  -H "X-API-Key: pas_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image_front_url": "https://storage.example.com/pasaporte.jpg",
    "image_back_url": "https://storage.example.com/pasaporte_extra.jpg"
  }'

Upload Binario

Envía la imagen como body binario. Solo soporta una imagen por petición.

curl -X POST https://extraerdatosdepasaporte.com/api/v1/extract \
  -H "X-API-Key: pas_tu_api_key" \
  -H "Content-Type: image/jpeg" \
  --data-binary @./pasaporte.jpg

Respuesta exitosa

{
  "success": true,
  "extraction_id": "clx1234567890",
  "data": {
    "passportNumber": "G12345678",
    "surname": "GOMEZ VELAZQUEZ",
    "givenNames": "MARGARITA",
    "nationality": "MEXICANA",
    "dateOfBirth": "05/07/1980",
    "sex": "F",
    "placeOfBirth": "COAHUILA",
    "dateOfIssue": "05/07/2023",
    "dateOfExpiry": "05/07/2033",
    "issuingCountry": "MEX",
    "issuingAuthority": "SRE",
    "personalNumber": "GOVM800705MCLRLR01",
    "mrzLine1": "P<MEXGOMEZ<VELAZQUEZ<<MARGARITA<<<<<<<<<<<<<",
    "mrzLine2": "G123456786MEX8007050F3307054<<<<<<<<<<<<<<08"
  },
  "tokens_remaining": 19,
  "upload_method": "multipart"
}
GET/api/v1/balance

Obtiene el saldo actual de tokens de tu cuenta.

Ejemplo

curl https://extraerdatosdepasaporte.com/api/v1/balance \
  -H "X-API-Key: pas_tu_api_key"

Respuesta

{
  "success": true,
  "balance": 20
}

Ejemplos de Integración

JavaScript / Node.js

// Usando fetch con FormData
const formData = new FormData();
formData.append('image_front', fileInput.files[0]);

const response = await fetch('https://extraerdatosdepasaporte.com/api/v1/extract', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pas_tu_api_key'
  },
  body: formData
});

const result = await response.json();
console.log(result.data);

Python

import requests

url = 'https://extraerdatosdepasaporte.com/api/v1/extract'
headers = {'X-API-Key': 'pas_tu_api_key'}

# Usando archivos (multipart)
files = {
    'image_front': open('pasaporte.jpg', 'rb'),
    'image_back': open('pasaporte_extra.jpg', 'rb')
}

response = requests.post(url, headers=headers, files=files)
result = response.json()
print(result['data'])

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://extraerdatosdepasaporte.com/api/v1/extract',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: pas_tu_api_key'],
    CURLOPT_POSTFIELDS => [
        'image_front' => new CURLFile('pasaporte.jpg'),
        'image_back' => new CURLFile('pasaporte_extra.jpg')
    ]
]);

$response = curl_exec($curl);
$result = json_decode($response, true);
print_r($result['data']);

Códigos de error

CódigoHTTPDescripción
MISSING_API_KEY401No se proporcionó API key
INVALID_API_KEY401API key inválida o revocada
MISSING_IMAGE400No se proporcionó imagen frontal
INVALID_IMAGE_FORMAT400Formato no soportado (use JPEG, PNG o WebP)
IMAGE_TOO_LARGE400Imagen excede 10 MB
INVALID_BASE64400Error al decodificar base64
INVALID_MULTIPART400Error al procesar formulario multipart
URL_FETCH_FAILED400No se pudo obtener imagen de la URL
URL_INVALID400URL inválida (debe ser HTTPS)
URL_BLOCKED400URL bloqueada por seguridad
URL_TIMEOUT400Timeout al obtener imagen (10s)
UNSUPPORTED_CONTENT_TYPE415Content-Type no soportado
INSUFFICIENT_TOKENS402Saldo insuficiente de tokens
RATE_LIMITED429Demasiadas solicitudes fallidas o en proceso por minuto; las extracciones exitosas no cuentan (ver header Retry-After)
TOO_MANY_FAILED_EXTRACTIONS429Demasiadas extracciones fallidas consecutivas; revisa la calidad de las imágenes
EXTRACTION_FAILED500Error en la extracción (token reembolsado)
INTERNAL_ERROR500Error interno del servidor

Campos extraídos

La API extrae los siguientes campos de la página principal del pasaporte:

passportNumber

Número de pasaporte

surname

Apellidos

givenNames

Nombres

nationality

Nacionalidad

dateOfBirth

Fecha de nacimiento

sex

Sexo

placeOfBirth

Lugar de nacimiento

dateOfIssue

Fecha de expedición

dateOfExpiry

Fecha de vencimiento

issuingCountry

País emisor (código ICAO)

issuingAuthority

Autoridad emisora

personalNumber

Número personal (CURP en México)

mrzLine1

Línea 1 de la zona MRZ

mrzLine2

Línea 2 de la zona MRZ

Límites y cuotas

  • Cada extracción consume 1 token
  • Tamaño máximo de imagen: 10MB
  • Formatos soportados: JPEG, PNG, WebP
  • Timeout para URL fetch: 10 segundos
  • Si una extracción falla por un error del sistema, el token se reembolsa automáticamente
  • Los tokens no expiran