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

# Crear una verificación

> Endpoint POST /verifications: variantes, atributos principales y cómo elegir tu forma de procesamiento.

Esta guía explica cómo usar el endpoint `POST /verifications` para crear verificaciones vía API. Para entender las 3 formas de procesar documentos (clasificación, validación, extracción), consulta [Cómo funciona Vía API](/docs/guia-devs/crear-verificaciones/via-api/overview).

<Note>
  Para el schema técnico completo del endpoint con tipos, validaciones y ejemplos generados del OpenAPI spec, consulta [API Reference — Crear una nueva verificación](https://docs.gotrebol.com/api-reference/creacion-de-verificacion/crear-una-nueva-verificación).
</Note>

***

## Requisitos comunes

Cuando envías documentos con `file_url` (aplica a todas las formas de procesamiento):

<Warning>
  La URL debe estar **disponible por al menos 5 minutos** para garantizar la descarga exitosa por parte de Trébol.
</Warning>

<Info>
  **¿No tienes un `file_url`?** Si tus documentos están en almacenamiento privado o se generan dinámicamente, usa el flujo de [carga directa](/docs/guia-devs/crear-verificaciones/via-api/carga-directa), donde Trébol te proporciona una `upload_url` para subir el archivo directamente.

  **¿El PDF tiene contraseña?** Envíala en `options.file_password` junto con `file_url` (o al confirmar una carga directa). Trébol procesa una copia sin contraseña y conserva el original cifrado; la contraseña es por item. Trébol la almacena cifrada en la base de datos y no la devuelve en respuestas ni webhooks. Si es incorrecta, el item termina con `item_error: invalid_file_password`. Detalle en [PDF protegido con contraseña](/docs/guia-devs/crear-verificaciones/via-api/carga-directa#pdf-protegido-con-contrasena).
</Info>

***

## Variantes del endpoint

`POST /verifications` acepta dos esquemas en el body, dependiendo de si usas un account-flow predefinido o envías los items directamente:

| Variante | Cuándo usar | Campos requeridos |
| - | - | - |
| **Con `items`** (API sin flow) | Cada verificación define sus propios items. Máxima flexibilidad. **Es la forma más común en integración API.** | `country`, `tag`, `items` |
| **Con `flow_id`** (con account-flow) | Reutilizas una configuración de flow previamente creada. Más común en widget; poco frecuente en API directa. | `country`, `tag`, `flow_id`, `tax_id` |

***

## Atributos principales

| Atributo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `country` | `string` | Sí | Código del país. Valores soportados: `mx`, `co`. Otros valores se procesan como `not_specified`. |
| `tag` | `string` | Sí | Identificador único de la verificación (tu ID interno del cliente o solicitud). |
| `tax_id` | `string` | Depende | RFC / NIT de la empresa. Requerido cuando usas `flow_id`. |
| `friendly_name` | `string` | No | Nombre descriptivo de la empresa o persona asociada a la verificación. |
| `email` | `string` | No | Email del cliente de la verificación. |
| `flow_id` | `string` | Depende | ID de un account-flow predefinido. Usar **sin** `items`. |
| `items` | `array` | Depende | Items a procesar. Usar **sin** `flow_id`. Ver las 3 formas en [Cómo funciona Vía API](/docs/guia-devs/crear-verificaciones/via-api/overview). |
| `options` | `object` | No | Flags específicos del caso de uso (ej: `skip_siger`). |
| `metadata` | `object` | No | Información adicional para tu integración (no procesada por Trébol). |
| `key_people` | `array` | No | **Solo KYB México**. Apoderados con poderes legales. Ver [Overview KYB México](/docs/guia-devs/uso-kyb/mexico/overview#key-people-y-scope-apoderados-y-poderes). |

Para el schema técnico completo con todos los atributos, tipos y ejemplos de request/response, consulta [API Reference](https://docs.gotrebol.com/api-reference/creacion-de-verificacion/crear-una-nueva-verificación).

***

## Siguiente paso: elige tu forma de procesamiento

Cada forma tiene ejemplos de payload completos y estructura de respuesta:

<CardGroup cols={3}>
  <Card title="Forma 1: Clasificación" href="/docs/guia-devs/crear-verificaciones/via-api/forma-clasificacion">
    Trébol detecta el tipo del documento (item `generic`).
  </Card>

  <Card title="Forma 2: Validación" href="/docs/guia-devs/crear-verificaciones/via-api/forma-validacion">
    Verifica tipo y reglas (item `doc_validation`).
  </Card>

  <Card title="Forma 3: Extracción" href="/docs/guia-devs/crear-verificaciones/via-api/forma-extraccion">
    Extrae directamente con tipo directo.
  </Card>
</CardGroup>

## Ejemplos de payload por caso de uso

Cada caso de uso tiene su overview con **variaciones de creación** y ejemplos de payload completos copy-pasteables:

<CardGroup cols={2}>
  <Card title="KYB México" href="/docs/guia-devs/uso-kyb/mexico/overview">
    Verificación de empresas mexicanas: SIGER, SAT, actas, apoderados.
  </Card>

  <Card title="KYB Colombia" href="/docs/guia-devs/uso-kyb/colombia/overview">
    Verificación de empresas colombianas: RUES, RUT, Cámara de Comercio.
  </Card>

  <Card title="KYB Estados Unidos" href="/docs/guia-devs/uso-kyb/eeuu/overview">
    Verificación de empresas en EEUU: certificate of incorporation, IRS EIN, FinCEN.
  </Card>

  <Card title="KYB Todos los países" href="/docs/guia-devs/uso-kyb/todos-paises/items-documentos">
    Items universales para KYB: person\_id, proof\_address, bank\_statement, etc.
  </Card>

  <Card title="Hipotecas" href="/docs/guia-devs/uso-hipotecas/overview">
    Escrituras de propiedad, certificados de gravámenes, avalúos.
  </Card>

  <Card title="Nómina" href="/docs/guia-devs/uso-nomina/overview">
    Recibos de nómina y pensión.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.