Recuperación de información

Recupera datos sobre tus imports, files y documents.

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

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

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.

File API

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

Estructura de File

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

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.

Documents API

El procesamiento de documentos puede introducir latencia al recuperar información por ID de Document. Usa webhooks 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.

Implementación técnica

Buenas prácticas

  • Usa webhooks primero - el polling a la API debe complementar las notificaciones por webhook, 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

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

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