Documentación de la API v2.3.0

Bienvenido a la documentación rápida de la API de extracción y categorización de facturas. Aquí encontrarás los conceptos esenciales para integrar la versión v2.3.0, que incorpora el nuevo sistema de categorías con IDs. Para detalles ampliados revisa los archivos API_USAGE_GUIDE.md y API_CATEGORIES_GUIDE.md incluidos en el repositorio.

Tipos de documento e IVA

La API soporta dos valores principales para documentType:

invoice-uy: Facturas de Uruguay, orientadas a usos contables/fiscales donde se respeta la estructura del comprobante (tipo de documento, timbrado, tasas de IVA por ítem, etc.).
invoice-global: Facturas y tickets genéricos pensados para aplicaciones de finanzas personales o familiares, donde se prioriza el monto efectivamente gastado.

En modo invoice-global, el IVA se considera parte del costo real:

items[].unitPrice representa siempre el precio final por unidad con IVA incluido (equivalente a total / quantity).
items[].total es el precio final de la línea con IVA incluido (lo que se pagó por ese ítem).
items[].subtotal es el valor de referencia sin IVA, usado internamente para distribuir vatAmount entre las líneas.
Si el documento solo trae IVA global (vatAmount), este se prorratea entre los ítems en función de su subtotal.

Para análisis de gasto personal, se recomienda usar items[].unitPrice y items[].total, que ya incluyen impuestos.

Endpoints Disponibles

Método	Ruta	Descripción
POST	`/api/upload`	Procesamiento inteligente con detección automática de la mejor estrategia.
POST	`/api/upload/ocr`	Procesamiento con OCR forzado para documentos de baja calidad.
GET	`/health`	Health check detallado del servicio.
GET	`/ping`	Ping simple para verificación rápida.

Parámetros Principales

Nombre	Tipo	Descripción	Obligatorio
`invoices`	Archivo	Facturas en formato PDF, JPG o PNG.	Sí
`documentType`	String	`invoice-global` (default) o `invoice-uy`.	No
`categories`	String (JSON)	Categorías personalizadas con estructura `{ id, name }`.	No
`subcategories`	String (JSON)	Subcategorías personalizadas con estructura `{ id, name }`.	No
`tags`	String (JSON)	Etiquetas personalizadas con estructura `{ id, name }`.	No
`X-API-Key`	Header	Clave de autenticación (modo producción).	Sí

Ejemplo Rápido con Categorías Personalizadas

curl -X POST \
  -H "X-API-Key: tu_api_key" \
  -F "invoices=@./factura.pdf" \
  -F "documentType=invoice-global" \
  -F "categories=[{\"id\":\"CUSTOM001\",\"name\":\"MI_CATEGORIA\"}]" \
  -F "subcategories=[{\"id\":\"CUSTOMSUB001\",\"name\":\"MI_SUBCATEGORIA\"}]" \
  -F "tags=[{\"id\":\"TAG001\",\"name\":\"MI_ETIQUETA\"}]" \
  https://document-extractor.digicont.uy/api/upload

Respuesta con IDs

{
  "success": true,
  "data": {
    "invoiceNumber": "FAC-001",
    "currency": "UYU",
    "expenseCategory": "GROCERIES",
    "expenseCategoryId": "CAT002",
    "expenseSubcategory": "Food items (fruits, vegetables, meat, dairy, canned goods, bread, pasta)",
    "expenseSubcategoryId": "SUB009",
    "tag": "Lácteos",
    "tagId": null,
    "items": [
      {
        "description": "Leche entera 1L",
        "expenseCategory": "GROCERIES",
        "expenseCategoryId": "CAT002",
        "expenseSubcategory": "Food items (fruits, vegetables, meat, dairy, canned goods, bread, pasta)",
        "expenseSubcategoryId": "SUB009",
        "tag": "Lácteos",
        "tagId": null
      }
    ]
  },
  "strategy": "Gemini Direct"
}

Categorías Predefinidas

La API incluye 20 categorías principales (CAT001-CAT020) y 127 subcategorías (SUB001-SUB127).

ID	Categoría	Emoji	Subcategorías
CAT002	GROCERIES	🛒	Food items, Beverages, Infusions, Sweets, Alcohol, Household items, Other.
CAT009	PERSONAL CARE	💄	Hair & beauty, Skin care, Feminine hygiene, Oral hygiene, Fragancias, Hygiene products.
CAT014	WORK	💼	Professional tools, Software, Training, Office supplies, Business travel, Other.

Consulta API_CATEGORIES_GUIDE.md para la lista completa de categorías y subcategorías.

Recursos Adicionales

Documentación extendida: Revisa README.md para novedades y changelog.
Guía de uso: Detalles completos en API_USAGE_GUIDE.md.
Sistema de categorías: Estructura completa en API_CATEGORIES_GUIDE.md.