API v1.0 - Disponible

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
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_xxxxxxxxxxxxxxxxxxxxxxxx

Importante

Nunca expongas tu API key en código del lado del cliente. Utilízala solo desde tu servidor.

3Endpoint Principal

POST/api/v1/documents/extract

Request Body

Soporta dos formatos: multipart/form-data (recomendado) o application/json con base64.

CampoTipoDescripción
fileFileArchivo (JPG, PNG, PDF). Max 10MB
document_typeStringinvoice 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.

NIF/CIFIVAIRPFIBAN

Bill of Lading

Conocimientos de embarque marítimo con validación de contenedores ISO 6346.

B/L NumberContainerVessel

Packing List

Listas de empaque con extracción de items, pesos y dimensiones.

ItemsPesoVolumen

5Ejemplos de Código

Python
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']}€")
JavaScript / Node.js
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
<?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

GET/api/v1/status

Verifica 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
  }
}
GET/api/v1/usage

Obtén estadísticas detalladas de uso. Permite filtrar por período y ver desglose por tipo de documento.

Query Parameters

ParámetroTipoDescripción
periodStringtoday week month all
start_dateISO 8601Fecha inicio personalizada
end_dateISO 8601Fecha fin personalizada
include_detailsBooleanIncluir 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

HTTPCódigoDescripción
401UNAUTHORIZEDAPI key inválida o faltante
429RATE_LIMIT_EXCEEDEDLímite de requests por minuto excedido
403QUOTA_EXCEEDEDQuota mensual excedida
400MISSING_FILENo se proporcionó archivo
400IMAGE_TOO_LARGEArchivo mayor a 10MB
422UNKNOWN_DOCUMENT_TYPENo se pudo detectar el tipo de documento

8Rate Limits y Headers

Cada respuesta incluye headers con información del rate limit:

HeaderDescripción
X-RateLimit-LimitLímite de requests por minuto
X-RateLimit-RemainingRequests restantes en la ventana
X-RateLimit-ResetTimestamp ISO cuando se reinicia el contador
X-Processing-RegionRegió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.