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étodo | Content-Type | Uso recomendado |
|---|---|---|
| Recomendado Multipart | multipart/form-data | curl, Postman, formularios HTML |
| Base64 JSON | application/json | JavaScript, apps moviles |
| URL Fetch | application/json | Imágenes hospedadas en la nube |
| Binario | image/jpeg, image/png, image/webp | CLI tools, streaming |
Endpoints
/api/v1/extractExtrae datos de una imagen de la página principal del pasaporte.
RecomendadoMultipart Form-Data
Envía archivos directamente. Ideal para curl y Postman.
| Campo | Tipo | Descripción |
|---|---|---|
image_front | file | Página principal del pasaporte (requerido) |
image_back | file | Pá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.
| Campo | Tipo | Descripción |
|---|---|---|
image_front | string | Base64 de imagen frontal (requerido) |
image_back | string | Base64 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.
| Campo | Tipo | Descripción |
|---|---|---|
image_front_url | string | URL HTTPS de imagen frontal (requerido) |
image_back_url | string | URL 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"
}/api/v1/balanceObtiene 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ódigo | HTTP | Descripción |
|---|---|---|
MISSING_API_KEY | 401 | No se proporcionó API key |
INVALID_API_KEY | 401 | API key inválida o revocada |
MISSING_IMAGE | 400 | No se proporcionó imagen frontal |
INVALID_IMAGE_FORMAT | 400 | Formato no soportado (use JPEG, PNG o WebP) |
IMAGE_TOO_LARGE | 400 | Imagen excede 10 MB |
INVALID_BASE64 | 400 | Error al decodificar base64 |
INVALID_MULTIPART | 400 | Error al procesar formulario multipart |
URL_FETCH_FAILED | 400 | No se pudo obtener imagen de la URL |
URL_INVALID | 400 | URL inválida (debe ser HTTPS) |
URL_BLOCKED | 400 | URL bloqueada por seguridad |
URL_TIMEOUT | 400 | Timeout al obtener imagen (10s) |
UNSUPPORTED_CONTENT_TYPE | 415 | Content-Type no soportado |
INSUFFICIENT_TOKENS | 402 | Saldo insuficiente de tokens |
RATE_LIMITED | 429 | Demasiadas solicitudes fallidas o en proceso por minuto; las extracciones exitosas no cuentan (ver header Retry-After) |
TOO_MANY_FAILED_EXTRACTIONS | 429 | Demasiadas extracciones fallidas consecutivas; revisa la calidad de las imágenes |
EXTRACTION_FAILED | 500 | Error en la extracción (token reembolsado) |
INTERNAL_ERROR | 500 | Error interno del servidor |
Campos extraídos
La API extrae los siguientes campos de la página principal del pasaporte:
passportNumberNúmero de pasaporte
surnameApellidos
givenNamesNombres
nationalityNacionalidad
dateOfBirthFecha de nacimiento
sexSexo
placeOfBirthLugar de nacimiento
dateOfIssueFecha de expedición
dateOfExpiryFecha de vencimiento
issuingCountryPaís emisor (código ICAO)
issuingAuthorityAutoridad emisora
personalNumberNúmero personal (CURP en México)
mrzLine1Línea 1 de la zona MRZ
mrzLine2Lí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