Documentación para Desarrolladores

Authorization: Bearer TU_API_KEY

curl -X POST https://app.holalexy.com/api/ingest \
  -H "Authorization: Bearer a3f8b2c1d4e5f6789..." \
  -F "[email protected]" \
  -F "document_type_id=550e8400-e29b-41d4-a716-446655440000"

{
  "file_url": "https://example.com/documents/invoice.pdf",
  "document_type_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "consulta_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

curl -X POST https://app.holalexy.com/api/ingest \
  -H "Authorization: Bearer a3f8b2c1d4e5f6789abcdef..." \
  -F "file=@/ruta/a/factura.pdf" \
  -F "document_type_id=550e8400-e29b-41d4-a716-446655440000"

curl -X POST https://app.holalexy.com/api/ingest \
  -H "Authorization: Bearer a3f8b2c1d4e5f6789abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/documents/factura.pdf",
    "document_type_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "consulta_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "document_type_id": "550e8400-e29b-41d4-a716-446655440000",
  "application_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "created_at": "2024-01-15T10:30:00.000Z"
}

{
  "consulta_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "completed",
  "document_type_id": "550e8400-e29b-41d4-a716-446655440000",
  "application_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "created_at": "2024-01-15T10:30:00.000Z",
  "analysis": {
    "numero_factura": "F-2024-001",
    "fecha_emision": "2024-01-15",
    "total": 150000
  }
}

{
  "consulta_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "failed",
  "document_type_id": "550e8400-e29b-41d4-a716-446655440000",
  "application_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "created_at": "2024-01-15T10:30:00.000Z",
  "error": {
    "message": "Error en el modelo de reconocimiento de documentos"
  }
}

{
  "data": [
    {
      "consulta_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "completed",
      "document_type_id": "550e8400-e29b-41d4-a716-446655440000",
      "application_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "created_at": "2024-01-15T10:30:00.000Z",
      "analysis": { "numero_factura": "F-2024-001", "total": 150000 }
    }
  ],
  "limit": 20,
  "offset": 0
}

# Página 1
GET /api/consultas?limit=20&offset=0

# Página 2
GET /api/consultas?limit=20&offset=20

async function esperarResultado(consultaId, intervalMs = 3000, maxIntentos = 20) {
  for (let i = 0; i < maxIntentos; i++) {
    const res = await fetch(
      `https://app.holalexy.com/api/consultas/${consultaId}`,
      { headers: { Authorization: `Bearer ${process.env.LEXY_API_KEY}` } }
    );
    const data = await res.json();
    if (data.status === 'completed') return data.analysis;
    if (data.status === 'failed') throw new Error(data.error.message);
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error('Tiempo de espera agotado');
}

Content-Type: application/json
x-lexy-signature: <hmac-sha256-hex>

{
  "event": "consulta.completed",
  "consulta_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_type_id": "550e8400-e29b-41d4-a716-446655440000",
  "analysis": {
    "numero_factura": "F-2024-001",
    "fecha_emision": "2024-01-15",
    "proveedor": "Empresas XYZ S.A.S.",
    "nit_proveedor": "900.123.456-7",
    "subtotal": 126050,
    "iva": 23950,
    "total": 150000
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "event": "consulta.failed",
  "consulta_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "organization_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_type_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "category": "analysis",
    "message": "Error en el modelo de reconocimiento de documentos"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

const crypto = require('crypto');

function verificarFirmaLexy(req, sharedSecret) {
  const signature = req.headers['x-lexy-signature'];
  if (!signature) return false;

  // IMPORTANTE: usar el body crudo (Buffer), no req.body ya parseado
  const bodyRaw = req.rawBody;
  const expected = crypto.createHmac('sha256', sharedSecret).update(bodyRaw).digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, 'utf8'),
      Buffer.from(signature, 'utf8')
    );
  } catch {
    return false; // longitudes distintas
  }
}

const consultasProcesadas = new Set(); // en producción usa Redis o DB

app.post('/webhook/lexy', (req, res) => {
  // ... verificar firma primero ...
  const { consulta_id, analysis } = JSON.parse(req.body.toString());

  if (consultasProcesadas.has(consulta_id)) {
    return res.status(200).json({ received: true, note: 'already processed' });
  }

  consultasProcesadas.add(consulta_id);
  procesarAnalisis(consulta_id, analysis);
  res.status(200).json({ received: true });
});

app.post('/webhook/lexy', async (req, res) => {
  // 1. Verificar firma...

  // 2. Responder inmediatamente (dentro de los 15s)
  res.status(200).json({ received: true });

  // 3. Procesar en background (no bloquea la respuesta)
  setImmediate(async () => {
    const payload = JSON.parse(req.body.toString());
    await procesarAnalisisEnDB(payload.consulta_id, payload.analysis);
  });
});

ngrok http 3000

{
  "error": "Descripción del error"
}

# .env
LEXY_API_KEY=tu_api_key_de_64_chars_hex
LEXY_SHARED_SECRET=tu_shared_secret_de_64_chars_hex
LEXY_BASE_URL=https://app.holalexy.com
LEXY_DOCUMENT_TYPE_ID=550e8400-e29b-41d4-a716-446655440000

const express = require('express');
const crypto = require('crypto');
const FormData = require('form-data');
const fs = require('fs');

const app = express();
const LEXY_API_KEY = process.env.LEXY_API_KEY;
const LEXY_SHARED_SECRET = process.env.LEXY_SHARED_SECRET;
const LEXY_BASE_URL = process.env.LEXY_BASE_URL;
const DOCUMENT_TYPE_ID = process.env.LEXY_DOCUMENT_TYPE_ID;

const procesadas = new Set(); // en producción usa Redis o base de datos

// ─── Enviar documentos ────────────────────────────────────────
async function enviarDocumento(rutaArchivo) {
  const form = new FormData();
  form.append('file', fs.createReadStream(rutaArchivo));
  form.append('document_type_id', DOCUMENT_TYPE_ID);

  const response = await fetch(`${LEXY_BASE_URL}/api/ingest`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${LEXY_API_KEY}`, ...form.getHeaders() },
    body: form,
  });

  if (!response.ok) {
    const { error } = await response.json();
    throw new Error(`Lexy API error ${response.status}: ${error}`);
  }

  const { consulta_id } = await response.json();
  return consulta_id;
}

// ─── Webhook endpoint ─────────────────────────────────────────
app.post('/webhook/lexy', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-lexy-signature'];
  if (!signature) return res.status(401).json({ error: 'Firma ausente' });

  const expected = crypto
    .createHmac('sha256', LEXY_SHARED_SECRET)
    .update(req.body)
    .digest('hex');

  if (
    signature.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  ) {
    return res.status(401).json({ error: 'Firma inválida' });
  }

  const payload = JSON.parse(req.body.toString());
  const { consulta_id, analysis } = payload;

  if (procesadas.has(consulta_id)) {
    return res.status(200).json({ received: true });
  }
  procesadas.add(consulta_id);

  res.status(200).json({ received: true });
  setImmediate(() => {
    console.log('[Lexy] Análisis recibido:', JSON.stringify(analysis, null, 2));
  });
});

app.listen(3000);

import hashlib, hmac, os
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
import httpx

LEXY_API_KEY = os.environ["LEXY_API_KEY"]
LEXY_SHARED_SECRET = os.environ["LEXY_SHARED_SECRET"]
LEXY_BASE_URL = os.environ["LEXY_BASE_URL"]
DOCUMENT_TYPE_ID = os.environ["LEXY_DOCUMENT_TYPE_ID"]

app = FastAPI()
consultas_procesadas: set[str] = set()

async def enviar_documento(ruta_archivo: str) -> str:
    async with httpx.AsyncClient() as client:
        with open(ruta_archivo, "rb") as f:
            response = await client.post(
                f"{LEXY_BASE_URL}/api/ingest",
                headers={"Authorization": f"Bearer {LEXY_API_KEY}"},
                files={"file": f},
                data={"document_type_id": DOCUMENT_TYPE_ID},
                timeout=30.0,
            )
    if response.status_code != 202:
        raise Exception(f"Error {response.status_code}: {response.json().get('error')}")
    return response.json()["consulta_id"]

@app.post("/webhook/lexy")
async def recibir_webhook(request: Request):
    signature = request.headers.get("x-lexy-signature")
    if not signature:
        raise HTTPException(status_code=401, detail="Firma ausente")

    body_bytes = await request.body()
    expected = hmac.new(
        LEXY_SHARED_SECRET.encode("utf-8"), body_bytes, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise HTTPException(status_code=401, detail="Firma inválida")

    payload = await request.json()
    consulta_id = payload["consulta_id"]

    if consulta_id in consultas_procesadas:
        return JSONResponse({"received": True})

    consultas_procesadas.add(consulta_id)
    print(f"[Lexy] Análisis: {payload['analysis']}")
    return JSONResponse({"received": True})

<?php
namespace AppHttpControllers;

use IlluminateHttpRequest;
use IlluminateHttpJsonResponse;

class LexyWebhookController extends Controller
{
    public function handle(Request $request): JsonResponse
    {
        $signature = $request->header('X-Lexy-Signature');
        if (!$signature) {
            return response()->json(['error' => 'Firma ausente'], 401);
        }

        $rawBody = $request->getContent();
        $expected = hash_hmac('sha256', $rawBody, config('services.lexy.shared_secret'));

        if (!hash_equals($expected, $signature)) {
            return response()->json(['error' => 'Firma inválida'], 401);
        }

        $payload = $request->json()->all();
        $consultaId = $payload['consulta_id'];

        $cacheKey = "lexy_webhook_{$consultaId}";
        if (cache()->has($cacheKey)) {
            return response()->json(['received' => true]);
        }
        cache()->put($cacheKey, true, now()->addDays(7));

        ProcessLexyAnalysis::dispatch($consultaId, $payload['analysis']);
        return response()->json(['received' => true]);
    }
}

# Genera la firma correcta y simula un webhook
BODY='{"event":"consulta.completed","consulta_id":"test-123","organization_id":"org-456","document_type_id":"doc-789","analysis":{"nombre":"Juan Perez","total":150000},"timestamp":"2024-01-15T10:30:00.000Z"}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$LEXY_SHARED_SECRET" | awk '{print $2}')

curl -X POST http://localhost:3000/webhook/lexy \
  -H "Content-Type: application/json" \
  -H "x-lexy-signature: $SIGNATURE" \
  -d "$BODY"