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

# Recuperación de información

> Endpoints de la API y estructuras de datos para recuperar información sobre los imports, files y documents procesados por Invofox.

Esta sección proporciona los endpoints de la API y las estructuras de datos para recuperar información sobre tus Imports, Files y Documents. Para actualizaciones en tiempo real del estado de procesamiento, usa [webhooks](/webhooks-reference/webhook-implementation) en lugar de hacer polling a estos endpoints.

**Cuándo usar estas APIs:**

- Sincronización inicial con el estado actual
- Recuperación tras eventos de webhook perdidos
- Comprobación masiva de estados para dashboards
- Recuperación de estructuras y metadatos detallados de las entidades

## Import API

Recupera información sobre tus operaciones de importación mediante nuestra API REST.

**Listar Imports:** `GET /v1/ingest/imports/`\
**Obtener un Import:** `GET /v1/ingest/imports/{id}`

### Estructura de Import

```typescript
type Import = {
  id: string;
  accountId: string;
  environmentId: string;
  channel: "api" | "upload" | "email";
  status: "processing" | "processed";
  createdAt: string; // marca de tiempo ISO 8601
  documents: number; // Total de documentos extraídos de todos los archivos
  files: File[]; // Array de archivos (ver estructura de File abajo)
  clientData?: object; // Metadatos personalizados de la subida
  providerInfo?: object; // Información específica del proveedor
};
```

**Notas:**

- Import devuelve una lista de todos los archivos, incluidos los ZIP y su contenido extraído
- El campo `documents` indica el total de documentos extraídos en todos los archivos
- El campo `channel` indica cómo se creó el import (API, subida web o email)
- Cada archivo del array `files` sigue la estructura de File documentada abajo
- Los archivos comprimidos (ZIP) tienen `compressed: true` y normalmente un array `documentIds` vacío
- Los archivos extraídos de un ZIP incluyen `parentFileId`, que referencia al archivo comprimido original
- `clientData` contiene los metadatos personalizados aportados durante la subida (objeto vacío si no hay)
- Los archivos rechazados incluyen un campo `error` con el código de error para manejarlo de forma programática

Para las definiciones de estado de Import y la lógica de transición, consulta [Procesamiento de Imports](/webhooks-reference/processing-tracking#import-processing).

## File API

Accede a la información de procesamiento de archivos y a las actualizaciones de estado.

### Estructura de File

```typescript
type File = {
  id: string; // Identificador único
  accountId: string;
  environmentId: string;
  companyId?: string;
  importId: string;
  filename: string;
  mimeType: string; // Tipo MIME (p. ej. "application/pdf", "image/jpeg")
  status: "pending" | "processing" | "processed" | "rejected";
  compressed: boolean; // true para archivos ZIP
  documentIds: string[]; // Array de IDs de documentos extraídos de este archivo
  parentFileId?: string; // Referencia al ZIP padre (si se extrajo de un ZIP)
  error?: string; // Código de error cuando el estado es "rejected" (p. ej. "ERR_UNSUPPORTED_FILE_FORMAT")
  clientData?: object; // Metadatos personalizados de la subida
  createdAt: string; // marca de tiempo ISO 8601
  updatedAt: string; // marca de tiempo ISO 8601
};
```

**Notas:**

- Cada archivo incluye un array `documentIds` (siguiendo la convención de nombres: array de IDs en singular + sufijo "Ids")
- El campo `mimeType` indica el formato del archivo (campo obligatorio)
- Los archivos comprimidos (ZIP) tienen `compressed: true` y un array `documentIds` vacío
- Los archivos extraídos de un ZIP incluyen el campo `parentFileId`, que referencia al archivo comprimido original
- Los archivos rechazados (status: "rejected") incluyen un campo `error` con el código de error para manejarlo de forma programática
- Todas las respuestas usan el campo `id` como identificador principal (no `_id`)
- `clientData` contiene los metadatos personalizados aportados durante la subida (objeto vacío si no hay)

Para las definiciones de estado de File y la lógica de transición, consulta [Procesamiento de Files](/webhooks-reference/processing-tracking#file-processing).

## Documents API

El procesamiento de documentos puede introducir latencia al recuperar información por ID de Document. Usa [webhooks](/webhooks-reference/webhook-implementation) para actualizaciones en tiempo real.

**Listar Documents:** `GET /v1/documents/`
**Obtener un Document:** `GET /v1/documents/{id}`

### Estructura de Document

La estructura completa del documento está disponible en la documentación de referencia de la API.


Para las definiciones de estado de Document y la lógica de transición, consulta [Procesamiento de Documents](/webhooks-reference/processing-tracking#document-processing).

## Implementación técnica

### Buenas prácticas

- **Usa webhooks primero** - el polling a la API debe complementar las [notificaciones por webhook](/webhooks-reference/webhook-implementation), no sustituirlas
- **Implementa paginación** - los conjuntos de resultados grandes se paginan por rendimiento
- **Gestiona los límites de tasa** - implementa backoff exponencial para las respuestas de rate limit

### Manejo de errores

La API devuelve códigos de estado HTTP estándar:

- **200** - Éxito
- **400** - Petición incorrecta (errores de validación)
- **401** - No autorizado (revisa tu API key)
- **404** - Recurso no encontrado
- **429** - Límite de tasa superado
- **500** - Error interno del servidor

Las respuestas de error incluyen información detallada para ayudar con la depuración y la resolución.

### Estrategias de polling

<Warning>
No recomendado en entornos de producción. Usa webhooks para actualizaciones en tiempo real en su lugar.
</Warning>

Cuando los webhooks no estén disponibles, usa estos patrones de polling:

- **Carga inicial** - haz polling cada 5-10 segundos durante el procesamiento activo
- **Sincronización en segundo plano** - haz polling cada 30-60 segundos para actualizaciones de estado
- **Backoff exponencial** - aumenta gradualmente los intervalos de polling (p. ej. 5s → 10s → 20s → 40s → 80s → 160s → 300s) hasta un máximo de 5 minutos, ya que el procesamiento de documentos puede ser complejo y llevar tiempo
- **Peticiones por lotes** - usa los endpoints de listado para reducir las llamadas a la API