> This documentation belongs to Invofox, an AI-powered document processing
> platform. The API extracts structured data (fields) from unstructured
> documents (invoices, contracts, forms, bank statements, and more).
> Key concepts: Account, Environment, Document Type, Field, File, Import,
> and Document. When answering, prefer the exact terminology defined in the
> Glossary and cite the relevant API Reference endpoint when applicable.

# Splitter

> Sube un único PDF que contiene varios documentos y recibe un documento totalmente extraído por cada documento lógico detectado, con el Splitter de Invofox.

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

<div className="ivf-bdemo"><div className="ivf-bdemo-cap">El Splitter analiza la estructura de páginas e identifica dónde empieza y termina cada documento — incluso cuando los formatos son desconocidos o inconsistentes.</div><div className="ivf-bstage"><div className="ivf-bscan"></div><div className="ivf-bgroup-wrap"><div className="ivf-bgroup"><div className="ivf-bpage"></div><div className="ivf-bpage"></div></div><div className="ivf-bgroup-label">Doc 1</div></div><div className="ivf-bsep"></div><div className="ivf-bgroup-wrap"><div className="ivf-bgroup"><div className="ivf-bpage"></div></div><div className="ivf-bgroup-label">Doc 2</div></div><div className="ivf-bsep"></div><div className="ivf-bgroup-wrap"><div className="ivf-bgroup"><div className="ivf-bpage"></div><div className="ivf-bpage"></div></div><div className="ivf-bgroup-label">Doc 3</div></div></div></div>

## 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`**

```bash title="cURL"
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 `documentId`s — Invofox no sabe cuántos documentos contiene el archivo hasta que termina de procesarlo. Guarda el `importId` en su lugar:

**`Respuesta de la subida`**

```json title="Respuesta de la subida"
{
  "accountId": "000000000000000000000006",
  "environmentId": "00000000000000000000001c",
  "importId": "000000000000000000000021",   // ← guarda esto
  "files": [
    { "id": "000000000000000000000022", "filename": "combinedfile.pdf" }
  ]
  // sin documentId — es lo esperado en una subida con splitter
}
```

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 `documentId`s una vez terminado el procesamiento. **Los webhooks son la opción recomendada**; también puedes hacer polling al import.

<Cards>
  <Card title="Opción A · Webhooks (Recomendado)" icon="bolt">
    Recibe un evento `document.processed` por cada documento dividido conforme termina. Sin polling, sin sobrecarga de infraestructura.
  </Card>
  <Card title="Opción B · Polling al import" icon="arrows-rotate">
    Comprueba el estado del import hasta que esté procesado, luego lee la lista de `documentId`s y obtén cada uno.
  </Card>
</Cards>

### 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](/documentation/integrating-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.

**`evento import.processed`**

```json title="evento import.processed"
{
  "type": "import.processed",
  "id": "000000000000000000000021",
  "timestamp": "2026-06-19T03:06:31.931Z",
  "data": {
    "id": "000000000000000000000021",
    "status": "processed",
    "files": [
      {
        "id": "000000000000000000000022",
        "filename": "combinedfile.pdf",  // ← nombre de archivo original
        "status": "processed",
        "documentIds": [                 // ← todos los documentos producidos
          "000000000000000000000023",
          "000000000000000000000024",
          "000000000000000000000025"
        ],
        "clientData": {}
      }
    ]
  }
}
```

### 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"`.

<div className="ivf-endpoint"><span className="ivf-method ivf-method-get">GET</span><span>https://api.invofox.com/v1/ingest/imports/{importId}</span></div>

**`Respuesta del import (processed)`**

```json title="Respuesta del import (processed)"
{
  "id": "000000000000000000000021",
  "status": "processed",                 // ← espera a esto
  "documents": 3,                        // ← total de documentos producidos (fiable una vez processed)
  "files": [
    {
      "id": "000000000000000000000022",
      "filename": "combinedfile.pdf",    // ← el nombre original vive aquí
      "status": "processed",
      "compressed": false,               // ← true si la subida fue un archivo ZIP
      "documentIds": [                   // ← documentos producidos por este archivo
        "000000000000000000000023",
        "000000000000000000000024",
        "000000000000000000000025"
      ]
    }
  ]
}
```

`files[]` tiene una entrada por archivo subido, cada una con su `filename` original y la lista de `documentId`s 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`:

<div className="ivf-endpoint"><span className="ivf-method ivf-method-get">GET</span><span>https://api.invofox.com/documents/{documentId}</span></div>

**`Respuesta de un documento dividido`**

```json title="Respuesta de un documento dividido"
{
  "result": {
    "_id": "000000000000000000000023",
    "type": "<id o alias del document type>",
    "name": "split_1.pdf",               // ← nombre de división generado (no el original)
    "publicState": "approved",
    "confidence": "high",
    "data": { "...": "campos extraídos" },
    "import": {
      "ref":  "000000000000000000000021", // ← importId
      "file": "000000000000000000000022", // ← fileId de la subida original
      "info": {
        "splitter": {
          "original": "https://…/original.pdf?…", // ← URL firmada al PDF original
          "pages": { "from": 1, "to": 2 },        // ← páginas del original que cubre esta división
          "splits": 3                              // ← número total de divisiones
        }
      }
    }
  }
}
```

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.

**`Splitter + Classifier`**

```bash title="Splitter + Classifier"
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.