Divisor de documentos (doc_splitter)

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_<uuid>). 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.

Otros tipos de ítem exponen también needs-review y error (ver 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

string

required

Debe ser "doc_splitter".

string

required

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 con upload_url no aplica a doc_splitter.

array

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 (cit_...). Si se envía vacío o se omite, se usa el catálogo base completo.

string

Atajo para especificar un único tipo esperado. Equivalente a allowed_item_types: ["<tipo>"].

Opción 1 — Al crear la verificación

POST /verifications

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"]
        }
      }
    ]
  }'

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"],
        },
      },
    ],
  }),
});

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

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"]
        }
      }
    ]
  }'

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"],
          },
        },
      ],
    }),
  }
);

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

boolean

true si se detectó más de un documento; false si el PDF corresponde a un único documento.

array

Lista de cortes identificados.

Show Propiedades de cada corte

string

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.

string

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

integer

Primera página del corte en el PDF original (1-based, inclusiva).

integer

Última página del corte en el PDF original (1-based, inclusiva).

object

Metadatos de clasificación generados por el modelo de IA durante la división.

Show Propiedades de support_metadata

string

Etiqueta descriptiva del documento (por ejemplo "certificate_of_incorporation").

string

Tipo canónico de Trébol o de un tipo personalizado (por ejemplo "ac_mx", "cit_contrato_arrendamiento").

string

Fecha de expedición detectada, en formato ISO 8601 cuando aplica.

{
  "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

string

required

Cualquier tipo soportado que acepte un archivo como entrada (por ejemplo doc_validation, generic, ac_mx, aa_mx, csf_mx).

string

required

Debe ser "item".

object

required

Referencia al corte del doc_splitter.

Show Propiedades de file_source_info

integer

required

id del ítem doc_splitter que produjo el corte (entero positivo).

string

required

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.

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"
          }
        }
      }
    ]
  }'

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",
            },
          },
        },
      ],
    }),
  }
);

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.

Crear el doc_splitter

Agrega el ítem a una verificación existente, restringiendo los tipos esperados.

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.

Respuesta abreviada

[
  {
    "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.

Esperar el resultado

El análisis es asíncrono. Tienes dos opciones:

Webhooks (recomendado): suscríbete al evento 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".

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 para los códigos posibles y cómo reintentar.

Seleccionar los cortes que quieres procesar

Del array split_documents, elige los cortes según su support_metadata.document_type. Ejemplo:

{
  "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" }
    }
  ]
}

Crear ítems a partir de los cortes

Envía los ítems hijos en una sola llamada a add-items.

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 filtrando por sus item_id — o, si quieres esperar a que todo el expediente termine, escucha 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

Tipos de documentos

Lista completa de tipos que puedes usar en allowed_item_types y como destino de un corte.

Tipos de ítem personalizados

Combina el splitter con tipos personalizados (cit_...) para reconocer documentos propios de tu cuenta.

Extracciones personalizadas

Personaliza la extracción de los documentos que el splitter identifique.

Webhooks

Recibe notificaciones cuando el doc_splitter termine de procesarse.

​Cuándo usarlo

​Conceptos clave

​Corte (split)

​Ciclo de vida

​Autenticación

​Crear un ítem doc_splitter

​Opciones del ítem

​Opción 1 — Al crear la verificación

​Opción 2 — En una verificación existente

​Consumir el resultado

​Estructura de la respuesta

​Crear un ítem a partir de un corte

​Opciones del ítem

​Errores

​Errores HTTP al referenciar un corte

​item_error en un doc_splitter fallido

​Ejemplo completo

​Siguientes pasos

Tipos de documentos

Tipos de ítem personalizados

Extracciones personalizadas

Webhooks

Cuándo usarlo

Conceptos clave

Corte (split)

Ciclo de vida

Autenticación

Crear un ítem `doc_splitter`

Opciones del ítem

Opción 1 — Al crear la verificación

Opción 2 — En una verificación existente

Consumir el resultado

Estructura de la respuesta

Crear un ítem a partir de un corte

Opciones del ítem

Errores

Errores HTTP al referenciar un corte

`item_error` en un `doc_splitter` fallido

Ejemplo completo

Siguientes pasos