> ## 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.
# Estados de Verificaciones y Documentos
> Documentación técnica sobre los estados en el sistema de Trébol para la validación de documentos (KYB).
Esta guía detalla los estados que utiliza el sistema de Trébol para gestionar la validación de documentos en procesos KYB. Diferencia entre verificaciones creadas directamente mediante API o dashboard y aquellas creadas a través del widget de onboarding.
***
## Tipos de Creación de Verificaciones
### Verificación por el Dashboard o API
En las verificaciones creadas desde el **dashboard** o mediante la **API**, el estado de carga de documentos (`document_status`) se establece automáticamente en `full_upload` desde el inicio. Esto supone que todos los documentos requeridos se envían directamente por el administrador o desarrollador.
### Verificación por el Widget de Onboarding
Las verificaciones creadas a través del **widget de onboarding** incluyen el estado de carga de documentos (`document_status`). Este estado permite rastrear el progreso mientras los usuarios finales cargan los documentos requeridos.
***
## Estados de un Item (`item_status`)
Un **item** representa un documento individual que debe ser procesado dentro de una verificación.
### Valores posibles
| Estado | Descripción |
| ---------- | ------------------------------------------------------------------------------------------ |
| `pending` | El documento está pendiente de ser procesado o está siendo procesado actualmente. |
| `complete` | El documento ha sido procesado exitosamente y ha pasado todas las validaciones requeridas. |
***
## Estados de una Verificación (`verification_status`)
Una **verificación** agrupa múltiples items que deben ser validados para una empresa.
### Valores posibles
| Estado | Descripción |
| ---------- | ------------------------------------------------------------------------------------------- |
| `pending` | Hay items obligatorios (no opcionales) que están pendientes de procesar (`pending`). |
| `finished` | Todos los items obligatorios (no opcionales) han sido procesados exitosamente (`complete`). |
***
## Estados de Carga de Documentos (`document_status`)
### Valores posibles
| Estado | Descripción |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `pending_upload` | No se ha iniciado la carga de documentos. Estado inicial por defecto (solo widget). |
| `partial_upload` | Algunos documentos requeridos han sido cargados, pero faltan otros por completar (solo widget). |
| `pending_external` | Falta diligenciar los formularios, incluyendo los de propietarios reales. (solo widget). |
| `full_upload` | Todos los documentos requeridos han sido cargados y están listos para ser procesados. |
Este estado **solo cambia al utilizar widget de onboarding**. Las
verificaciones creadas mediante API o dashboard el estado se establece
automáticamente como `full_upload`
***
## Flujo Típico de Estados
### Verificación por el Dashboard o API
1. **Se crea una verificación**
* La verificación comienza con:
* `verification_status: pending`
* `document_status: full_upload`
* Todos los documentos requeridos ya están cargados y listos para ser procesados.
2. **Procesamiento de items**
* Cada item asociado a la verificación pasa de `item_status: pending` a `item_status: complete` tras su validación.
3. **Finalización de la verificación**
* Una vez que todos los items requeridos están en `item_status: complete`, la verificación cambia a `verification_status: finished`.
***
### Verificación por el Widget de Onboarding
1. **Se crea una verificación**
* La verificación comienza con los estados `verification_status: pending` y `document_status: pending_upload`.
2. **Carga parcial de documentos**
* Los usuarios finales cargan algunos documentos requeridos, actualizando el estado a `document_status: partial_upload`.
3. **Documentos cargados, formularios pendientes**
* Cuando todos los documentos requeridos se cargaron pero aún faltan formularios (incluyendo el de propietarios reales), el estado pasa a `document_status: pending_external`.
4. **Carga completa**
* Cuando los formularios también se completan, el estado pasa a `document_status: full_upload`.
5. **Procesamiento de items**
* Los items individuales comienzan en `item_status: pending` y se procesan hasta alcanzar `item_status: complete`.
6. **Finalización de la verificación**
* Una verificación pasa a `verification_status: finished` solo cuando todos los items requeridos están en `complete`.
***
## Resumen de Estados por Categoría
| Categoría | Estado | Descripción |
| ----------------------- | ------------------ | ---------------------------------------------------------------------------------------- |
| **Verificación** | `pending` | Existen items obligatorios (no opcionales) pendientes por procesar. |
| | `finished` | Todos los items obligatorios (no opcionales) han sido procesados exitosamente. |
| **Item** | `pending` | El documento está pendiente o en proceso. |
| | `complete` | El documento fue procesado con éxito. |
| **Carga de Documentos** | `pending_upload` | No se han iniciado las cargas (solo aplica a verificaciones creadas por widget). |
| | `partial_upload` | Carga en progreso, faltan documentos (solo aplica a verificaciones creadas por widget). |
| | `pending_external` | Falta diligenciar los formularios, incluyendo los de propietarios reales. (solo widget). |
| | `full_upload` | Todos los documentos requeridos están cargados y listos para procesar. |
***
## Siguientes pasos
Cómo consultar el dictamen y los datos extraídos de una verificación.
Cómo recibir eventos automáticos cuando los estados cambian.
Cómo configurar notificaciones cuando se completa una verificación.