VerifikaDocs
ReferenciaEgresos

Leer una factura con IA

«Registrar gasto con IA» del panel, por API: mandas la foto o el PDF de la factura y devuelve el borrador del gasto (proveedor, NIT, número de factura, fecha, total, subtotal, IVA, categoría sugerida) y los gastos parecidos que ya existen. No crea nada salvo con create: true.

La factura queda guardada en nuestro almacenamiento privado; al crear el gasto se adjunta a él. Límite: 20 lecturas por minuto y 300 al día por negocio. No funciona con llaves de prueba.

POST
/expense-scans

Autorización

apiKey expenses.scan
AutorizaciónBearer <token>

La llave del negocio, creada en el panel: Integraciones → API pública. vk_live_… es una llave real; vk_test_…, una llave de modo prueba (verificaciones simuladas, nada toca el libro real). Ver la guía «Modo de prueba».

Va en: header

Permiso: expenses.scan

Parámetros de consulta

companyId?string

Sobre qué negocio actúa la petición. Obligatorio solo si la llave entra a varios negocios; con uno solo, se deduce.

Parámetros de cabecera

Idempotency-Key?string

Llave única de la operación. Un reintento con la misma llave y el mismo cuerpo devuelve la respuesta original en vez de volver a ejecutar. Ver la guía de idempotencia.

Longitudlength <= 255

Cuerpo de la petición

Tipos de TypeScript

Usa el tipo request body en TypeScript.

Una sola forma de archivo por petición (multipart file, fileBase64 + fileName, o fileUrl). Foto (JPG, PNG, WebP, HEIC) o PDF, hasta 15 MB.

Elige una de dos formas (o usa multipart con file). Lo obligatorio va con asterisco (*).

Obligatorio: fileUrl (https pública). Lo demás es opcional.

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/expense-scans" \  -H "Content-Type: application/json" \  -d '{    "fileUrl": "https://cdn.tuerp.com/facturas/fe-20931.pdf"  }'
{  "object": "expenseScan",  "id": "cmuhb7c8d0061x8w1f2g3h4jk",  "outcome": "EXTRACTED",  "message": null,  "documentKind": "INVOICE",  "confidence": "HIGH",  "draft": {    "amount": 357000,    "subtotal": 300000,    "tax": 57000,    "paidTo": "Harina La Espiga S.A.S.",    "vendorTaxId": "900123456-7",    "invoiceNumber": "FE-20931",    "occurredAt": "2026-10-10T05:00:00.000Z",    "categoryId": "cmt7xbfrm0003q3w121ldx6wz",    "categoryName": "Proveedores y mercancía",    "paymentMethod": "TRANSFER",    "accountLabel": null,    "notes": "20 bultos de harina"  },  "duplicates": [],  "file": {    "attachmentId": "cmuhb7c9e0062x8w1m4n5b6vc",    "fileName": "factura-fe-20931.pdf",    "contentType": "application/pdf",    "size": 84210  },  "expenseId": null,  "expense": null,  "expiresAt": "2026-10-18T21:20:00.000Z",  "createdAt": "2026-10-12T21:20:00.000Z"}

Eliminar una categoría de egreso DELETE

Solo si no tiene gastos. Una categoría con movimientos no se borra: borrarla dejaría egresos huérfanos y rompería el histórico, que es justo el dato por el que el negocio paga. Para esas, PATCH { "active": false }.

Ver una lectura de factura GET

El escaneo, con los duplicados recalculados (o el gasto, si ya se creó).