Documentación de la API

Integre Robodam Scan en sus procesos: envíe el PDF de una factura y obtenga datos estructurados (JSON) y, si es necesario, un archivo de importación contable (Rivilė .eip o Centas XML). Funciona con «Power Automate», cron, Postman y scripts.

abajo {BASE} — la dirección de la API https://scan-api.robodam.com (NE la dirección de la aplicación/inicio de sesión es scan.robodam.com — solo sirve la interfaz del navegador). Para monitorización: GET {BASE}/health (una ruta raíz, no bajo /api/v1) devuelve {"status":"healthy"}.

1. Autentifikacija

Cada solicitud debe incluir su clave Bearer personal en la cabecera. Para la automatización (Power Automate, cron, scripts) cree una clave API permanente: Configuración → Cuenta → Claves API — raktas (rbs_…) se muestra solo una vez y sigue siendo válido hasta que lo revoque. Para pruebas manuales rápidas también sirve el «Clave de prueba» de arriba, sin embargo, es temporal (clave de sesión) — no la utilice para flujos automatizados.

Authorization: Bearer <su-clave>

2. Extracción de facturas (PDF → JSON)

Extracción síncrona: envía el PDF y obtiene los datos en la misma respuesta (sin solicitudes adicionales ni polling).

Solicitud

multipart/form-data, el documento se pasa en el campo file. Formatos aceptados: PDF y fotos (JPG / PNG / HEIC) — las fotos se convierten a PDF automáticamente en el servidor. Parámetros opcionales:

Límites: solo PDF; hasta 10 MB; hasta 20 páginas (un administrador puede aumentarlo para un cliente concreto; /extract-direct mantiene su propio límite, más bajo); 30 solicitudes/min. Un PDF con varias facturas se trata aquí como un único documento (la división solo se produce mediante /upload).

Ejemplo (cURL)

curl -X POST "{BASE}/api/v1/invoices/extract-direct" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@saskaita.pdf"

Respuesta (200 OK)

{
  "success": true,
  "filename": "saskaita.pdf",
  "confidence_score": 100,        // 0–100, confianza de la IA
  "auto_validated": true,         // true kai confidence_score >= 85
  "validation_warnings": [],      // texto para una persona
  "validation_issues": [],        // lo mismo para una máquina — con código (véase más abajo)
  "risk_flags": [],               // qué vale la pena comprobar antes de contabilizar
  "document_type": "invoice",     // invoice / credit_note / receipt / unknown / ...
  "from_cache": false,
  "duplicate_of": null,
  "extracted_data": { ... },      // campos de la factura (véase la sección 3)
  "export": null                  // se rellena solo con include_export
}

3. Campos extraídos (extracted_data)

Todos los campos son opcionales — si un campo no está en la factura, es null u omitido.

{
  "invoice_number": "SF Nr. 70",
  "invoice_date": "2026-05-29",     // YYYY-MM-DD
  "due_date": "2026-06-12",
  "currency": "EUR",
  "subtotal": 1100.0,               // suma be PVM
  "tax_amount": 231.0,              // importe del IVA (ausente cuando 0% / sin IVA)
  "tax_rate": 21,                   // dokumento PVM %, sveikas sk.
  "total_amount": 1331.0,           // suma su PVM
  "bank_account": "LT74...",
  "document_type": "invoice",
  "vendor": {                       // proveedor (vendedor)
    "name": "MB Decentrum",
    "company_code": "306265414",    // código de empresa
    "tax_id": "306265414",          // código de IVA (LT… si es sujeto pasivo de IVA)
    "address": "Ceikiniu g. 3, Lietuva"
  },
  "customer": {                     // comprador
    "name": "UAB Robodam",
    "company_code": "...",
    "tax_id": "LT100017242115",
    "address": "Kaunas, Vytauto pr. 27"
  },
  "line_items": [
    {
      "description": "Programavimo paslaugos",
      "quantity": 1.0,
      "unit": "vnt",
      "unit_price": 1100.0,         // vieneto kaina be PVM
      "total": 1100.0,              // importe de la línea sin IVA
      "tax_rate": 21,               // % de IVA de la línea (si falta — el tax_rate del documento)
      "item_number": "..."          // código del artículo del proveedor, si existe
    }
  ],
  "notes": "..."
}

La respuesta también puede contener _validation bei _recovery blokai — tai vidiniai diagnostikos duomenys, juos galite ignoruoti.

4. Señales de calidad

confidence_score pasako, kiek estamos. Estos dos campos indican kas negerai — y están pensados para un programa, no para una persona. Ambos son siempre en la respuesta; para un documento limpio son listas vacías.

validation_issues — qué comprobamos nosotros

{
  "code": "total_mismatch",       // estable — seguro para ramificar según él
  "field": "total_amount",
  "message": "Total amount (100.0) does not match calculated total (121.00)",
  "severity": "warning",          // warning | error
  "kind": "semantic"              // format | semantic | extraction
}

kind skiria nuestro comprobación (format — formato, semantic — importes y fechas) del propio comentario del modelo sobre su propia lectura (extraction). Estos últimos son texto libre y no llevan código — inventarlo supondría prometer un contrato que no cumpliríamos. Los códigos más comunes: total_mismatch, line_sum_mismatch, tax_amount_mismatch,date_format, due_before_invoice, iban_checksum.El textual validation_warnings se mantiene — está pensado para mostrarse a una persona.

risk_flags — qué vale la pena comprobar

Tai faktai, o ne verdiktai. La decisión la toma usted, porque usted conoce la dirección:

• own_company_in_vendor_slot — la empresa de su cliente está en el del vendedor lauke. En una factura de compra esto significa que las partes están intercambiadas; en una factura de venta esto es normal.
• same_party_both_sides — la misma empresa en ambos lados. No existe ningún caso en que esto sea correcto.
• duplicate_invoice_number — el mismo proveedor ya ha enviado una factura con este mismo número. El campo duplicate_of_invoice_number indica el id, el importe y la fecha de la factura anterior — la diferencia de importes es precisamente lo que le dice si el proveedor reescribió el documento o simplemente lo reenvió. La comprobación de duplicados a nivel de archivo no puede ver esto: un documento reescrito son bytes distintos.
• credit_note_signs_applied — el documento fue reconocido como factura rectificativa, por lo que total_amount,subtotal y los importes de las líneas forzadas a negativo. Los números en la respuesta pueden no coincidir con los signos impresos en el PDF.

La lista de códigos sigue creciendo. Un código desconocido debe ignórelasen lugar de tratarse como un error — así su integración no se romperá cuando añadamos uno nuevo.

5. Reenvío

Si reenvía el mismo archivo (los mismos bytes, la misma cuenta), entonces allow_duplicate yra false (por defecto) — devuelve la extracción anterior, de forma gratuita(from_cache: true, duplicate_of apunta al ID anterior; la IA no se vuelve a ejecutar). De este modo, un flujo de «Power Automate» que lee la misma carpeta cada día no se factura de nuevo. Para forzar una nueva extracción, envíe allow_duplicate=true.

6. Exportación contable (Rivilė / Centas)

Puede obtener el archivo de dos formas. Ambas devuelven el archivo base64 en formato JSON dentro (content_base64) — decodifíquelo y guárdelo.

A. Junto con la extracción (un archivo)

Añada el parámetro a la solicitud de la sección 2 include_export (rivile, centas arba finvalda) — atsakyme atsiras export campo con el archivo de esa factura:

export el campo tiene la misma estructura que la respuesta por lotes (véase más abajo).

B. Para facturas seleccionadas / filtradas (lote)

{format} = rivile, centas o finvalda. El cuerpo de la solicitud son o bien ids específicos, o bien filtros (como en la lista de facturas, hasta 1000):

{ "invoice_ids": ["<id1>", "<id2>"] }
// arba
{ "start_date": "2026-05-01", "end_date": "2026-05-31" }

Respuesta — Rivilė (.zip con archivos .eip):

{
  "format": "rivile",
  "filename": "Rivile_eksportas-20260612-061255.zip",
  "content_type": "application/zip",
  "content_base64": "UEsDBB...",   // base64 → bytes → guardar como .xml
  "problems": [],                  // avisos para el contable (véase más abajo)
  "skipped_count": 0,
  "purchase_count": 1,
  "sale_count": 0
}

Respuesta — Centas (.xml, o .zip cuando hay tanto compras como ventas):)

{
  "format": "centas",
  "filename": "Centas_eksportas-20260612-061255.xml",
  "content_type": "application/xml",   // o application/zip
  "content_base64": "PD94bWw...",      // base64 → bytes → guardar como .xml
  "problems": [],
  "skipped_count": 0,
  "purchase_count": 1,
  "sale_count": 0
}

problems — advertencias dirigidas a una persona (facturas omitidas, una clase de IVA al 0%/inversión del sujeto pasivo que necesita confirmación) — muéstrelas antes de la importación.

7. Configuración de la empresa

Algunos valores no están en la factura — su código de empresa (para distinguir compras de ventas), los códigos de clase de IVA. Guárdelos una vez y cada exportación los usará:

{format} = rivile o centas. Cuerpo del PUT (envíe solo lo que desee establecer; el resto se mantiene con sus valores predeterminados). Los campos difieren según el formato:

Rivilė:

{ "config": {
    "own_company_code": "304827491",
    "own_vat_code": "LT100001738313",
    "vat_class_map": { "21": "PVM1", "0": "PVM5" },
    "partner_group": "PT001",
    "product_group": "PR001",
    "op_tip_purchase": 1,
    "op_tip_sale": 51
} }

Centas:

{ "config": {
    "own_company_code": "304827491",
    "own_vat_code": "LT100001738313",
    "vat_class_map": { "21": "PVM1", "0": "PVM5" },
    "account_purchase": "SANAUDOS",
    "account_sale": "PAJAMOS"
} }

Finvalda:

{ "config": {
    "own_company_code": "304827491",
    "own_vat_code": "LT100001738313",
    "op_type_purchase": "1",
    "op_type_sale": "51",
    "journal_purchase": "PIRK",
    "journal_sale": "PARD",
    "import_param": "IMP1",
    "default_client_code": "KL001",
    "account_purchase": "6001",
    "account_sale": "5001"
} }

Finvalda PVM klasės lauko neturi — klasę parenka imp_param, tad vat_class_map šiam formatui netaikomas.

Utilice snake_case claves (una clave desconocida devuelve 422). Importante: la clase de IVA del 0% / inversión del sujeto pasivo ("0") por defecto es PVM5 — confirme el código correcto con su contable (un código incorrecto pero válido distorsiona silenciosamente la contabilidad del IVA). Establezca abu — own_company_code ir own_vat_code: la compra/venta se reconoce cuando coincide cualquiera de los dos (la IA a veces no logra leer el código de empresa, especialmente en facturas extranjeras).

8. Errores y límites

¿Preguntas sobre la integración? Póngase en contacto — kontaktai.