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.

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 https://extraerdatosdepasaporte.com/api/v1/balance \
  -H "X-API-Key: pas_tu_api_key"

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.

Endpoints

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"

IMAGE_FRONT=$(base64 < ./pasaporte.jpg | tr -d '\n')

printf '{"image_front": "%s"}' "$IMAGE_FRONT" | curl -X POST https://extraerdatosdepasaporte.com/api/v1/extract \
  -H "X-API-Key: pas_tu_api_key" \
  -H "Content-Type: application/json" \
  --data-binary @-

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"
  }'

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

{
  "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"
}

curl -X POST https://extraerdatosdepasaporte.com/api/v1/extract \
  -H "X-API-Key: pas_tu_api_key" \
  -H "X-Destination-Id: <id de tu destino>" \
  -F "image_front=@./pasaporte.jpg"

{
  "success": true,
  "extraction_id": "...",
  "data": { ... },
  "delivery": {
    "destination_id": "...",
    "succeeded": true,
    "http_status": 200,
    "latency_ms": 312,
    "error_code": null
  }
}

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

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

Enlaces de captura y webhooks

Mándale a tu cliente un enlace de un solo uso: toma la foto de su documento desde su celular y los datos llegan a tu destino (webhook, correo o Telegram), sin que la imagen pase por tu sistema. Disponible para todas las cuentas (beta). Los destinos se configuran en el panel, en Destinos.

curl -X POST https://extraerdatosdepasaporte.com/api/v1/capture-links \
  -H "X-API-Key: pas_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationId": "<id de tu destino>",
    "documentType": "passport",
    "reference": "reserva-8841",
    "requireBack": true
  }'

{
  "success": true,
  "id": "clx_enlace_456",
  "url": "https://extraerdatosdepasaporte.com/c/…",
  "reference": "reserva-8841",
  "documentType": "passport",
  "requireBack": true,
  "askGuestPersona": false,
  "expiresAt": "2026-09-30T18:15:00.000Z"
}

Webhooks: lo que recibe tu servidor

Cada entrega a un destino de tipo webhook, ya sea de un enlace de captura, de /api/v1/extract con X-Destination-Id o del panel, es un POST firmado. Se intenta una sola vez, sin seguir redirecciones y con 10 segundos de espera; responde 2xx.

POST /tu-webhook
Content-Type: application/json
X-Signature: sha256=5f2b…
X-Signature-Timestamp: 1790000000
X-Idempotency-Key: clx1234567890

{
  "version": "1",
  "event": "extraction.completed",
  "idempotencyKey": "clx1234567890",
  "documentType": "passport",
  "source": "capture-link",
  "captureLinkId": "clx_enlace_456",
  "reference": "reserva-8841",
  "extractedAt": "2026-09-30T18:05:02.000Z",
  "data": { "curp": "…", "nombre": "…" }
}

source es api, web o capture-link. image (front/back en base64) solo llega si el destino tiene activado incluir la imagen. Usa X-Idempotency-Key para descartar duplicados.

Firma: X-Signature es sha256= más el HMAC-SHA256 en hexadecimal, con el secreto del destino (whsec_…), de X-Signature-Timestamp + "." + el cuerpo crudo. Verifica sobre los bytes recibidos (no sobre el JSON re-serializado), compara en tiempo constante y rechaza timestamps de más de 5 minutos. Los SDKs oficiales lo hacen por ti.

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(secret, rawBody, signature, timestamp) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signature ?? '')
  return a.length === b.length && timingSafeEqual(a, b)
}

Códigos de error

Campos extraídos

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