> ## Documentation Index
> Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Divisor de documentos (doc_splitter)
> Analiza un PDF con varios documentos, obtén los cortes con sus rangos de páginas y clasificación, y crea ítems de verificación a partir de cada corte.
El ítem `doc_splitter` analiza un PDF, identifica los documentos que contiene y devuelve una lista de **cortes** (splits) con su rango de páginas y clasificación. Después puedes crear ítems adicionales (por ejemplo `doc_validation`, `ac_mx`, `aa_mx`) usando un corte específico como archivo de entrada.
## Cuándo usarlo
Usa `doc_splitter` cuando:
* Recibes un solo PDF que agrupa varios documentos (por ejemplo, un expediente con acta constitutiva, actas de asamblea, poderes, etc.).
* Necesitas identificar qué documento está en cada rango de páginas antes de procesarlo.
* Quieres reprocesar un subconjunto de páginas del PDF original sin volver a subir el archivo.
El `doc_splitter` **no clasifica** el PDF en un solo tipo: lo divide en varios sub-documentos. Si tu caso es "un archivo = un documento" y solo necesitas clasificarlo, usa `doc_validation` directamente.
## Conceptos clave
### Corte (split)
Un **corte** representa un documento identificado dentro del PDF original. Cada corte tiene:
* **`support_id`** — identificador único del corte (formato `ds_`). Cada corte corresponde a un documento individual que el splitter detectó dentro del PDF original. Usa este valor en `file_source_info.support_id` cuando quieras crear un ítem hijo para procesar ese documento.
* **`page_start` / `page_end`** — rango de páginas que ocupa el corte dentro del PDF original (1-based, inclusivas). Por ejemplo, `page_start: 4` y `page_end: 7` significa que el documento detectado abarca de la página 4 a la 7.
* **`support_url`** — URL firmada al sub-PDF que Trébol generó para este corte. Es solo informativa (por ejemplo, para previsualizar el documento); no la envíes al crear ítems hijo — Trébol resuelve el archivo internamente.
* **`support_metadata`** — metadatos que el modelo de IA generó al clasificar el corte: qué tipo de documento es (`document_type`), una etiqueta descriptiva (`classification`) y la fecha de expedición detectada (`expedition_date`), cuando aplica.
### Ciclo de vida
El procesamiento del `doc_splitter` es asíncrono. En la API pública solo verás dos estados en `item_status`:
* **`pending`** — el análisis está en curso (descarga del PDF y detección de cortes).
* **`complete`** — el análisis terminó. Distingue el resultado por `item_error`:
* Sin `item_error` (o `null`) → éxito. Los cortes están disponibles en `item_value.split_documents`.
* Con `item_error` → falló. Consulta el código para identificar la causa (PDF inválido, tipos personalizados desconocidos, etc.). Ver [Errores](#errores).
Otros tipos de ítem exponen también `needs-review` y `error` (ver [Respuestas por tipo de item](/docs/guia-devs/referencia/respuestas-por-tipo-de-item)). `doc_splitter` **no usa** esos estados: no requiere revisión manual (el resultado es determinista sobre el PDF) y los fallos del pipeline se reportan siempre como `complete` + `item_error` para que un mismo consumidor de webhooks maneje éxito y fallo con la misma señal terminal.
Un `doc_splitter` en `complete` **con** `item_error` NO expone cortes usables: `item_value.split_documents` estará vacío. Referencia un corte solo cuando el ítem esté `complete` **y** `item_error` sea `null`.
El `doc_splitter` solo acepta archivos **PDF**. Cualquier otro formato (JPG, PNG, DOCX, etc.) falla con `item_error: "unsupported_file_type"`. PDFs con contraseña fallan con `item_error: "password_protected_pdf"`.
***
## Autenticación
Todos los endpoints requieren tu API key en el header `x-api-key`.
***
## Crear un ítem `doc_splitter`
Puedes crear un ítem `doc_splitter` de dos formas: al **crear una verificación nueva** o **agregándolo a una verificación existente**. El cuerpo del ítem es idéntico en ambos casos.
### Opciones del ítem
Debe ser `"doc_splitter"`.
URL descargable del PDF a dividir. Requerido al crear el ítem (o usa `options.file_source: "item"` para referenciar un corte de un `doc_splitter` previo). El [flujo de carga directa](/docs/guia-devs/crear-verificaciones/via-api/carga-directa) con `upload_url` **no aplica** a `doc_splitter`.
Restringe el universo de tipos de documento que el splitter puede reconocer. Acepta tipos built-in (por ejemplo `ac_mx`, `aa_mx`, `csf_mx`) y nombres de [tipos de ítem personalizados](/docs/producto/guias/tipos-de-item-personalizados) (`cit_...`). Si se envía vacío o se omite, se usa el catálogo base completo.
Atajo para especificar un único tipo esperado. Equivalente a `allowed_item_types: [""]`.
### Opción 1 — Al crear la verificación
`POST /verifications`
```bash cURL theme={"dark"}
curl -X POST https://api.gotrebol.com/verifications \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"country": "mx",
"tag": "empresa-ejemplo-001",
"items": [
{
"type": "doc_splitter",
"options": {
"file_url": "https://ejemplo.com/expediente-completo.pdf",
"allowed_item_types": ["ac_mx", "aa_mx", "pw_mx", "fme_mx"]
}
}
]
}'
```
```javascript JavaScript theme={"dark"}
const response = await fetch("https://api.gotrebol.com/verifications", {
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
country: "mx",
tag: "empresa-ejemplo-001",
items: [
{
type: "doc_splitter",
options: {
file_url: "https://ejemplo.com/expediente-completo.pdf",
allowed_item_types: ["ac_mx", "aa_mx", "pw_mx", "fme_mx"],
},
},
],
}),
});
```
```python Python theme={"dark"}
import requests
response = requests.post(
"https://api.gotrebol.com/verifications",
headers={"x-api-key": "YOUR_API_KEY"},
json={
"country": "mx",
"tag": "empresa-ejemplo-001",
"items": [
{
"type": "doc_splitter",
"options": {
"file_url": "https://ejemplo.com/expediente-completo.pdf",
"allowed_item_types": ["ac_mx", "aa_mx", "pw_mx", "fme_mx"],
},
}
],
},
)
```
### Opción 2 — En una verificación existente
`PUT /verifications/{verification-id}/add-items`
```bash cURL theme={"dark"}
curl -X PUT https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1/add-items \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"type": "doc_splitter",
"options": {
"file_url": "https://ejemplo.com/expediente-completo.pdf",
"allowed_item_types": ["ac_mx", "aa_mx", "pw_mx", "fme_mx"]
}
}
]
}'
```
```javascript JavaScript theme={"dark"}
const response = await fetch(
"https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1/add-items",
{
method: "PUT",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{
type: "doc_splitter",
options: {
file_url: "https://ejemplo.com/expediente-completo.pdf",
allowed_item_types: ["ac_mx", "aa_mx", "pw_mx", "fme_mx"],
},
},
],
}),
}
);
```
```python Python theme={"dark"}
import requests
response = requests.put(
"https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1/add-items",
headers={"x-api-key": "YOUR_API_KEY"},
json={
"items": [
{
"type": "doc_splitter",
"options": {
"file_url": "https://ejemplo.com/expediente-completo.pdf",
"allowed_item_types": ["ac_mx", "aa_mx", "pw_mx", "fme_mx"],
},
}
]
},
)
```
Restringir con `allowed_item_types` o `client_item_type` mejora la precisión del splitter cuando ya sabes qué tipos de documento esperar. Si omites ambos, Trébol usa el catálogo base completo. También puedes combinar tipos built-in con tipos personalizados: `["ac_mx", "cit_contrato_arrendamiento"]`.
***
## Consumir el resultado
Consulta la verificación una vez que el ítem esté en `item_status: "complete"`:
`GET /verifications/{verification-id}`
Cuando el `doc_splitter` termina con éxito, cada ítem incluye los cortes bajo `item_value.split_documents`.
### Estructura de la respuesta
`true` si se detectó más de un documento; `false` si el PDF corresponde a un único documento.
Lista de cortes identificados.
Identificador único del corte (por ejemplo `ds_9f7d3a1c-...`). Es el valor que se pasa como `support_id` en `file_source_info` al crear un ítem hijo a partir de este corte.
URL firmada al sub-PDF generado para este segmento. **Informativa**: no la envíes al crear ítems a partir del corte; Trébol resuelve el archivo internamente con `file_source: "item"`.
Primera página del corte en el PDF original (1-based, inclusiva).
Última página del corte en el PDF original (1-based, inclusiva).
Metadatos de clasificación generados por el modelo de IA durante la división.
Etiqueta descriptiva del documento (por ejemplo `"certificate_of_incorporation"`).
Tipo canónico de Trébol o de un tipo personalizado (por ejemplo `"ac_mx"`, `"cit_contrato_arrendamiento"`).
Fecha de expedición detectada, en formato ISO 8601 cuando aplica.
```json Fragmento de un ítem doc_splitter theme={"dark"}
{
"id": 30829,
"item_type": "doc_splitter",
"item_status": "complete",
"item_value": {
"has_multiple_documents": true,
"split_documents": [
{
"support_id": "ds_9f7d3a1c-1c72-4b0f-b8e2-5c9c8b5d4a11",
"support_url": "https://files.gotrebol.com/.../30829_doc_splitter_ds_9f7d3a1c-....pdf?...",
"page_start": 1,
"page_end": 3,
"support_metadata": {
"classification": "ac_mx",
"document_type": "ac_mx",
"expedition_date": "2026-05-10"
}
},
{
"support_id": "ds_2b1e0f8a-3d44-4a1e-9c02-a7e6d1234567",
"support_url": "https://files.gotrebol.com/.../30829_doc_splitter_ds_2b1e0f8a-....pdf?...",
"page_start": 4,
"page_end": 7,
"support_metadata": {
"classification": "aa_mx",
"document_type": "aa_mx",
"expedition_date": "2026-05-15"
}
},
{
"support_id": "ds_5c4a9e02-7f81-4d33-a55c-e12b8f9b3210",
"support_url": "https://files.gotrebol.com/.../30829_doc_splitter_ds_5c4a9e02-....pdf?...",
"page_start": 8,
"page_end": 11,
"support_metadata": {
"classification": "unknown",
"document_type": "property_title_certificate"
}
}
]
}
}
```
Cuando el splitter no logra mapear un corte contra los tipos disponibles (los de `allowed_item_types` o el catálogo base), el `document_type` se devuelve como `"unknown"`. Si el modelo tampoco pudo inferir metadatos adicionales, el objeto `support_metadata` puede omitirse por completo del corte. Usa `support_metadata?.document_type ?? "unknown"` en tu código para cubrir ambos casos.
El `doc_splitter` puede dejar páginas sin cubrir (portadas, anexos, separadores en blanco). No todas las páginas del PDF original tienen que aparecer en un corte.
***
## Crear un ítem a partir de un corte
Para procesar un documento identificado por el splitter, agrega un nuevo ítem referenciando el `doc_splitter` original y el corte específico. Trébol resuelve internamente el sub-PDF; **no necesitas enviar `support_url`**.
`PUT /verifications/{verification-id}/add-items`
### Opciones del ítem
Cualquier tipo soportado que acepte un archivo como entrada (por ejemplo `doc_validation`, `generic`, `ac_mx`, `aa_mx`, `csf_mx`).
Debe ser `"item"`.
Referencia al corte del `doc_splitter`.
`id` del ítem `doc_splitter` que produjo el corte (entero positivo).
`support_id` del corte, tomado de `split_documents[].support_id`.
No envíes `bucket` ni `key` en `file_source_info`. Si están presentes, Trébol **no** resuelve el corte y usa esos valores tal cual — camino reservado para integraciones internas.
```bash cURL theme={"dark"}
curl -X PUT https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1/add-items \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"type": "ac_mx",
"options": {
"file_source": "item",
"file_source_info": {
"item_id": 30829,
"support_id": "ds_9f7d3a1c-1c72-4b0f-b8e2-5c9c8b5d4a11"
}
}
}
]
}'
```
```javascript JavaScript theme={"dark"}
const response = await fetch(
"https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1/add-items",
{
method: "PUT",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{
type: "ac_mx",
options: {
file_source: "item",
file_source_info: {
item_id: 30829,
support_id: "ds_9f7d3a1c-1c72-4b0f-b8e2-5c9c8b5d4a11",
},
},
},
],
}),
}
);
```
```python Python theme={"dark"}
import requests
response = requests.put(
"https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1/add-items",
headers={"x-api-key": "YOUR_API_KEY"},
json={
"items": [
{
"type": "ac_mx",
"options": {
"file_source": "item",
"file_source_info": {
"item_id": 30829,
"support_id": "ds_9f7d3a1c-1c72-4b0f-b8e2-5c9c8b5d4a11",
},
},
}
]
},
)
```
Un corte puede alimentar directamente a extractores específicos (`ac_mx`, `aa_mx`, `csf_mx`, etc.) sin pasar antes por `doc_validation`. Elige el tipo destino según lo que necesites: `doc_validation` para validar/clasificar, o el extractor específico para procesar el documento directamente.
Cada llamada a `add-items` con la misma referencia (`item_id` + `support_id`) crea un ítem hijo nuevo. No hay deduplicación del lado servidor: si envías la misma referencia dos veces, obtendrás dos ítems.
***
## Errores
Los errores de configuración de la petición se devuelven como códigos HTTP estándar. Los fallos del procesamiento asíncrono se exponen en el campo `item_error` del ítem `doc_splitter`.
### Errores HTTP al referenciar un corte
| Código | `message` (aprox.) | Causa |
| ------ | ------------------------ | ---------------------------------------------------------------------- |
| 400 | `invalid_split_source` | `item_id` no es entero positivo o `support_id` está vacío. |
| 400 | `source_item_wrong_type` | El `item_id` referenciado no es un `doc_splitter`. |
| 404 | `source_item_not_found` | No existe un ítem con ese `item_id` en la verificación. |
| 404 | `split_not_found` | El `doc_splitter` existe, pero ningún corte tiene ese `support_id`. |
| 409 | `source_item_not_ready` | El `doc_splitter` aún no está `complete`, o completó con `item_error`. |
### `item_error` en un `doc_splitter` fallido
Un `doc_splitter` que termina en `item_status: "complete"` con `item_error` significa que el análisis falló. Los valores posibles son:
| `item_error` | Causa |
| -------------------------------- | --------------------------------------------------------------------------------------- |
| `password_protected_pdf` | El PDF está protegido con contraseña. Reenvía una versión desbloqueada. |
| `unsupported_file_type` | El archivo no es un PDF. Solo se aceptan PDFs. |
| `unknown_custom_item_type` | `allowed_item_types` / `client_item_type` incluye un tipo personalizado que no existe. |
| `misconfigured_custom_item_type` | Un tipo personalizado referenciado no está listo para uso (falta clasificación activa). |
| `no_splits_returned` | El análisis no identificó ningún documento en el PDF. |
| `pdf_slice_failed` | No se pudo leer o recortar el PDF (archivo corrupto, error al descargar el original). |
| `pdf_slice_upload_failed` | Falló la subida de al menos uno de los sub-PDFs. |
| `doc_splitter_request_failed` | Falló la llamada al servicio de análisis. Reintenta o contacta a soporte si persiste. |
***
## Ejemplo completo
Flujo end-to-end: divide un expediente en documentos individuales y procesa dos de ellos.
Agrega el ítem a una verificación existente, restringiendo los tipos esperados.
```bash theme={"dark"}
curl -X PUT https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1/add-items \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"type": "doc_splitter",
"options": {
"file_url": "https://ejemplo.com/expediente.pdf"
}
}
]
}'
```
La respuesta contiene el `id` del ítem `doc_splitter` (aquí `30829`); guárdalo para los pasos siguientes. El `verification-id` (`c8dc41fc-...`) es el mismo que usaste en la URL del `add-items`.
```json Respuesta abreviada theme={"dark"}
[
{
"id": 30829,
"item_type": "doc_splitter",
"item_status": "pending",
"item_value": {}
}
]
```
Si `add-items` responde con más ítems (por ejemplo un `doc_validation` que agregaste en la misma llamada), el `doc_splitter` es el que tiene `item_type: "doc_splitter"`. Filtra por ese campo antes de leer el `id`.
El análisis es asíncrono. Tienes dos opciones:
* **Webhooks (recomendado)**: suscríbete al evento [`verification_item.v2.completed`](/docs/guia-devs/webhooks#verification_item-v2-completed). Trébol te avisa cuando el ítem termina; filtra por `data.item_type: "doc_splitter"` y `data.item_id: 30829`.
* **Polling**: consulta `GET /verifications/{verification-id}` hasta que el ítem esté en `item_status: "complete"`.
```bash theme={"dark"}
curl https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1 \
-H "x-api-key: YOUR_API_KEY"
```
Cuando el ítem 30829 termine, su `item_value.split_documents` contendrá los cortes con sus `support_id`.
**Regla para referenciar cortes**: procede al paso 3 solo si `item_status === "complete"` **y** `item_error` es `null` (o está ausente). Un `doc_splitter` en `complete` con `item_error` significa que falló — `split_documents` estará vacío y `add-items` responderá `409 source_item_not_ready`. Ver [Errores](#errores) para los códigos posibles y cómo reintentar.
Del array `split_documents`, elige los cortes según su `support_metadata.document_type`. Ejemplo:
```json theme={"dark"}
{
"split_documents": [
{
"support_id": "ds_9f7d3a1c-...",
"page_start": 1,
"page_end": 3,
"support_metadata": { "document_type": "ac_mx" }
},
{
"support_id": "ds_2b1e0f8a-...",
"page_start": 4,
"page_end": 7,
"support_metadata": { "document_type": "aa_mx" }
}
]
}
```
Envía los ítems hijos en una sola llamada a `add-items`.
```bash theme={"dark"}
curl -X PUT https://api.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1/add-items \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"type": "ac_mx",
"options": {
"file_source": "item",
"file_source_info": {
"item_id": 30829,
"support_id": "ds_9f7d3a1c-..."
}
}
},
{
"type": "aa_mx",
"options": {
"file_source": "item",
"file_source_info": {
"item_id": 30829,
"support_id": "ds_2b1e0f8a-..."
}
}
}
]
}'
```
Cada ítem hijo ejecuta su flujo normal de extracción / validación, pero solo sobre las páginas del corte referenciado.
Los ítems hijos también son asíncronos: aparecen en `item_status: "pending"` y pasan a `complete` cuando terminan (con `item_error` si fallaron). Suscríbete a [`verification_item.v2.completed`](/docs/guia-devs/webhooks#verification_item-v2-completed) filtrando por sus `item_id` — o, si quieres esperar a que **todo** el expediente termine, escucha [`verification.v2.finished`](/docs/guia-devs/webhooks#verification-v2-finished) sobre el `verification-id`. Nunca asumas que el ítem hijo está listo justo después de que `add-items` responde.
***
## Siguientes pasos
Lista completa de tipos que puedes usar en `allowed_item_types` y como destino de un corte.
Combina el splitter con tipos personalizados (`cit_...`) para reconocer documentos propios de tu cuenta.
Personaliza la extracción de los documentos que el splitter identifique.
Recibe notificaciones cuando el `doc_splitter` termine de procesarse.