Splitter

Sube un único PDF que contiene varios documentos y recibe un documento totalmente extraído por cada documento lógico detectado.

Paso 1 — Sube con el Splitter

Añade "useSplitter": true al campo info. Sigue enviando type como siempre (salvo que uses también el Classifier).

$
curl -s -X POST "https://api.invofox.com/v1/ingest/uploads" \
>
  -H "x-api-key: $INVOFOX_API_KEY" \
>
  -F "files=@combinedfile.pdf" \
>
  -F 'info={"type":"<TYPE_ID>","useSplitter":true}'

La respuesta de la subida no incluye documentIds — Invofox no sabe cuántos documentos contiene el archivo hasta que termina de procesarlo. Guarda el importId en su lugar:

1
{
2
  "accountId": "666839c78ea472012a9b8875",
3
  "environmentId": "6a338e5239207f9311eccd36",
4
  "importId": "6a34a9266e5e80ef224351ce",   // ← guarda esto
5
  "files": [
6
    { "id": "6a34a9266e5e80ef224351d1", "filename": "combinedfile.pdf" }
7
  ]
8
  // sin documentId — es lo esperado en una subida con splitter
9
}

Cualquier clientData que incluyas en el campo info se propaga a todos los documentos producidos por la división — todos los subdocumentos comparten exactamente el mismo clientData.

Paso 2 — Obtén los resultados

Recupera los documentIds una vez terminado el procesamiento. Los webhooks son la opción recomendada; también puedes hacer polling al import.

Opción A · Webhooks (recomendado para producción)

Se dispara un evento document.processed por cada documento conforme termina. Cada evento lleva el documento completo extraído en su campo data — el mismo formato de payload descrito en el Paso 3 de Integrar Invofox, incluido el bloque import.info.splitter.

Como no sabes de antemano en cuántos documentos se dividirá un archivo, no puedes fiarte de contar los eventos document.processed para saber cuándo está completa la división. En su lugar, escucha import.processed — este evento se dispara una vez, tras procesarse por completo todos los documentos de la división. Cuando llegue, has terminado.

1
{
2
  "type": "import.processed",
3
  "id": "6a34a9266e5e80ef224351ce",
4
  "timestamp": "2026-06-19T03:06:31.931Z",
5
  "data": {
6
    "id": "6a34a9266e5e80ef224351ce",
7
    "status": "processed",
8
    "files": [
9
      {
10
        "id": "6a34a9266e5e80ef224351d1",
11
        "filename": "combinedfile.pdf",  // ← nombre de archivo original
12
        "status": "processed",
13
        "documentIds": [                 // ← todos los documentos producidos
14
          "6a34a946f6d9ce414a37ab72",
15
          "6a34a947f6d9ce414a37ab97",
16
          "6a34a948f503345c6ed84a66"
17
        ],
18
        "clientData": {}
19
      }
20
    ]
21
  }
22
}

Opción B · Polling al import

Haz polling a GET /v1/ingest/imports/{importId} hasta que status sea "processed". Mientras procesa, status es "processing" y el contador documents aumenta conforme se extrae cada documento — no te fíes de él hasta que status sea "processed".

1
{
2
  "id": "6a34a9266e5e80ef224351ce",
3
  "status": "processed",                 // ← espera a esto
4
  "documents": 3,                        // ← total de documentos producidos (fiable una vez processed)
5
  "files": [
6
    {
7
      "id": "6a34a9266e5e80ef224351d1",
8
      "filename": "combinedfile.pdf",    // ← el nombre original vive aquí
9
      "status": "processed",
10
      "compressed": false,               // ← true si la subida fue un archivo ZIP
11
      "documentIds": [                   // ← documentos producidos por este archivo
12
        "6a34a946f6d9ce414a37ab72",
13
        "6a34a947f6d9ce414a37ab97",
14
        "6a34a948f503345c6ed84a66"
15
      ]
16
    }
17
  ]
18
}

files[] tiene una entrada por archivo subido, cada una con su filename original y la lista de documentIds producidos. Recopila todos los documentId de todos los files[].

Obtén cada documento

Para cada documentId, llama a GET /documents/{documentId} — mismo endpoint y formato de respuesta que el flujo estándar, con un bloque splitter adicional bajo import.info:

1
{
2
  "result": {
3
    "_id": "6a34a946f6d9ce414a37ab72",
4
    "type": "<id o alias del document type>",
5
    "name": "split_1.pdf",               // ← nombre de división generado (no el original)
6
    "publicState": "approved",
7
    "confidence": "high",
8
    "data": { "...": "campos extraídos" },
9
    "import": {
10
      "ref":  "6a34a9266e5e80ef224351ce", // ← importId
11
      "file": "6a34a9266e5e80ef224351d1", // ← fileId de la subida original
12
      "info": {
13
        "splitter": {
14
          "original": "https://…/original.pdf?…", // ← URL firmada al PDF original
15
          "pages": { "from": 1, "to": 2 },        // ← páginas del original que cubre esta división
16
          "splits": 3                              // ← número total de divisiones
17
        }
18
      }
19
    }
20
  }
21
}

Cada división se renombra a split_n.pdf — un índice en base 1 en orden de páginas. El nombre original no está presente en el propio documento dividido; puedes encontrarlo en la respuesta del import (files[].filename) del paso de polling de arriba.

Combinar con el Classifier

Si el PDF en lote contiene tipos de documento mezclados, añade "useClassifier": true y omite type — Invofox detectará el tipo de cada documento dividido automáticamente.

$
curl -X POST https://api.invofox.com/v1/ingest/uploads \
>
  -H "x-api-key: $INVOFOX_API_KEY" \
>
  -F "files=@mixed-batch.pdf" \
>
  -F 'info={"useSplitter":true,"useClassifier":true}'

Todo lo demás funciona igual que en el Paso 2 — polling y webhooks se comportan idénticamente. La única diferencia es que cada documento en los resultados tendrá su campo type ya rellenado con el tipo de documento detectado, así que no necesitas pasarlo en la subida.