facturahub-ocr

Parte del ecosistema FacturaHub — facturación en España, Verifactu, IVA, Modelo 303 y automatización fiscal con IA.

OCR de tickets y recibos por API. Envía una imagen y recibe JSON estructurado: comercio, importe, IVA, fecha, líneas del ticket y deducibilidad. TypeScript · 0 dependencias · MIT.

Receipt & invoice OCR for Spain — send an image, get vendor, amount, VAT, line items and deductibility as JSON.

Instalación

npm i facturahub-ocr

Necesitas una API key gratuita: créala en FacturaHub → Ajustes.

Uso

import { FacturaHubOCR } from 'facturahub-ocr';
import { readFileSync } from 'node:fs';

const ocr = new FacturaHubOCR({ apiKey: process.env.FACTURAHUB_API_KEY! });

// Desde bytes (Node 18+, fetch global)
const bytes = readFileSync('ticket.jpg');
const result = await ocr.scan({ bytes, mediaType: 'image/jpeg' });

console.log(result.vendor);   // "GAMMA"
console.log(result.amount);   // 51.93
console.log(result.currency); // "EUR"
console.log(result.items);    // [{ name, lineTotal, deductible, deductibleReason }, ...]

También acepta un data URL directamente:

await ocr.scan('data:image/jpeg;base64,/9j/4AAQ...');

Respuesta

{
  "vendor": "GAMMA",
  "amount": 51.93,
  "currency": "EUR",
  "date": "2026-06-20",
  "taxRate": 21,
  "confidence": 92,
  "items": [
    { "name": "Ventilador", "lineTotal": 49.99, "category": "equipment",
      "deductible": true, "deductibleReason": "Equipo de oficina" },
    { "name": "Coca-Cola Zero", "lineTotal": 1.79, "category": "meals",
      "deductible": false, "deductibleReason": "Consumo personal" }
  ]
}

API

| Símbolo | Qué hace | |---|---| | new FacturaHubOCR({ apiKey, baseUrl?, fetch? }) | Crea el cliente. apiKey se envía como x-api-key. | | ocr.scan(input) | Escanea un ticket. input = data URL, Uint8Array/ArrayBuffer, o { bytes, mediaType }. Devuelve ReceiptScan. | | toDataUrl(bytes, mediaType?) | Convierte bytes a data URL base64. | | FacturaHubError | Error con status (HTTP) y message (de la API). |

Tipos ReceiptScan y ReceiptItem exportados.

Por qué existe

Teclear tickets a mano es la forma más rápida de perder deducciones de IVA. Esta librería conecta con el motor de OCR con IA de visión de FacturaHub: le mandas la foto del ticket y te devuelve el comercio, el importe, el IVA soportado y, línea a línea, qué es deducible y qué no según las reglas fiscales de tu país — sin entrenar modelos, sin plantillas y sin montar un pipeline de OCR con librerías como Tesseract.

¿Prefieres no escribir código? Manda una foto del ticket por WhatsApp y FacturaHub lo registra solo. Pruébalo gratis.

Hecho por FacturaHub — facturación con IA para autónomos en España: emite Verifactu, lleva tu IVA y Modelo 303 y factura por WhatsApp. Gratis.

Ecosistema FacturaHub

• 🌐 FacturaHub — la app (gratis, Verifactu incluido)
• 📸 OCR de tickets · API de OCR
• 🔌 facturahub-api — API REST + OpenAPI 3.1
• 🤖 facturahub-mcp — servidor MCP (Claude, Cursor, ChatGPT)
• 🧾 facturahub-verifactu — Verifactu por API
• 🧮 Librerías: nif-validator · iva · iban-es · factura-number · verifactu-qr · verifactu-hash · modelo-303

Temas: OCR · OCR tickets · escanear recibos · receipt OCR · gastos deducibles · IVA · Modelo 303 · AEAT · Autónomos · IA · España