API de Procesamiento de Documentos
Integra el poder del OCR en tu aplicación. Extrae datos estructurados de facturas, Bill of Lading y Packing Lists en segundos.
1Quick Start
curl -X POST https://escaneafactura.es/api/v1/documents/extract \
-H "x-api-key: sk_live_tu_api_key" \
-H "Content-Type: multipart/form-data" \
-F "file=@factura.pdf" \
-F "document_type=invoice"2Autenticación
Todas las peticiones requieren una API key en el header x-api-key.
x-api-key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxImportante
Nunca expongas tu API key en código del lado del cliente. Utilízala solo desde tu servidor.
3Endpoint Principal
/api/v1/documents/extractRequest Body
Soporta dos formatos: multipart/form-data (recomendado) o application/json con base64.
| Campo | Tipo | Descripción |
|---|---|---|
file | File | Archivo (JPG, PNG, PDF). Max 10MB |
document_type | String | invoice bill_of_lading packing_list auto |
Response (200 OK)
{
"success": true,
"document_type": "invoice",
"data": {
"company_name": "Empresa Ejemplo S.L.",
"nif_cif": "B12345678",
"invoice_number": "FAC-2024-001",
"issue_date": "2024-01-15",
"base_amount": 1000.00,
"vat_percent": 21,
"vat_amount": 210.00,
"total_amount": 1210.00,
"currency": "EUR",
"line_items": [...]
},
"validation": {
"confidence": 0.95,
"is_valid": true,
"errors": [],
"warnings": []
},
"metadata": {
"processing_time_ms": 2500,
"tokens_used": 450,
"detected_language": "es"
}
}4Tipos de Documentos
Facturas
Facturas españolas y europeas con IVA, retenciones y líneas de detalle.
Bill of Lading
Conocimientos de embarque marítimo con validación de contenedores ISO 6346.
Packing List
Listas de empaque con extracción de items, pesos y dimensiones.
5Ejemplos de Código
import requests
response = requests.post(
"https://escaneafactura.es/api/v1/documents/extract",
headers={"x-api-key": "sk_live_tu_api_key"},
files={"file": open("factura.pdf", "rb")},
data={"document_type": "invoice"}
)
data = response.json()
print(f"Empresa: {data['data']['company_name']}")
print(f"Total: {data['data']['total_amount']}€")const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('file', fs.createReadStream('factura.pdf'));
form.append('document_type', 'invoice');
const response = await fetch(
'https://escaneafactura.es/api/v1/documents/extract',
{
method: 'POST',
headers: { 'x-api-key': 'sk_live_tu_api_key' },
body: form
}
);
const data = await response.json();
console.log(`Empresa: ${data.data.company_name}`);
console.log(`Total: ${data.data.total_amount}€`);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://escaneafactura.es/api/v1/documents/extract",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["x-api-key: sk_live_tu_api_key"],
CURLOPT_POSTFIELDS => [
"file" => new CURLFile("factura.pdf"),
"document_type" => "invoice"
]
]);
$response = curl_exec($curl);
$data = json_decode($response, true);
echo "Empresa: " . $data["data"]["company_name"] . "\n";
echo "Total: " . $data["data"]["total_amount"] . "€\n";6Consultar Estado y Quota
/api/v1/statusVerifica el estado de tu API key y consulta tu quota restante. Útil para monitorear el uso antes de hacer requests.
Response (200 OK)
{
"success": true,
"client": {
"id": "uuid",
"name": "Mi Empresa S.L.",
"is_active": true
},
"api_key": {
"prefix": "sk_live_abc...",
"name": "Production Key",
"is_active": true,
"last_used_at": "2024-01-20T14:22:00Z"
},
"quota": {
"monthly_limit": 1000,
"used_this_month": 150,
"remaining": 850,
"unlimited": false,
"exceeded": false,
"reset_date": "2024-02-01T00:00:00Z"
},
"rate_limit": {
"requests_per_minute": 60
}
}/api/v1/usageObtén estadísticas detalladas de uso. Permite filtrar por período y ver desglose por tipo de documento.
Query Parameters
| Parámetro | Tipo | Descripción |
|---|---|---|
period | String | today week month all |
start_date | ISO 8601 | Fecha inicio personalizada |
end_date | ISO 8601 | Fecha fin personalizada |
include_details | Boolean | Incluir logs individuales (últimos 100) |
Response (200 OK)
{
"success": true,
"period": {
"start": "2024-01-01T00:00:00Z",
"end": "2024-01-31T23:59:59Z",
"label": "month"
},
"stats": {
"total_requests": 150,
"successful_requests": 145,
"failed_requests": 5,
"success_rate": 96.67,
"total_tokens": 45000,
"avg_processing_time_ms": 2500,
"avg_confidence": 0.92
},
"by_document_type": {
"invoice": 100,
"bill_of_lading": 30,
"packing_list": 20
},
"by_day": [
{ "date": "2024-01-15", "requests": 25, "tokens": 7500 }
]
}7Códigos de Error
| HTTP | Código | Descripción |
|---|---|---|
| 401 | UNAUTHORIZED | API key inválida o faltante |
| 429 | RATE_LIMIT_EXCEEDED | Límite de requests por minuto excedido |
| 403 | QUOTA_EXCEEDED | Quota mensual excedida |
| 400 | MISSING_FILE | No se proporcionó archivo |
| 400 | IMAGE_TOO_LARGE | Archivo mayor a 10MB |
| 422 | UNKNOWN_DOCUMENT_TYPE | No se pudo detectar el tipo de documento |
8Rate Limits y Headers
Cada respuesta incluye headers con información del rate limit:
| Header | Descripción |
|---|---|
X-RateLimit-Limit | Límite de requests por minuto |
X-RateLimit-Remaining | Requests restantes en la ventana |
X-RateLimit-Reset | Timestamp ISO cuando se reinicia el contador |
X-Processing-Region | Región de procesamiento (siempre EU - GDPR compliant) |
¿Listo para integrar?
Obtén acceso a la API con el plan Pro. Incluye quota mensual, soporte prioritario y panel de estadísticas.
GDPR Compliant - Procesamiento en Europa
Todos los documentos se procesan en servidores de Azure ubicados en la Unión Europea. No almacenamos ningún documento ni dato personal. Los datos solo se procesan en tiempo real y se devuelven en la respuesta.