Importación de datos

¿Qué es la Importación de Datos?

La Importación de Datos permite ingresar datos externos en DatAscend mediante la carga de archivos (Excel/CSV) a través de una API REST. Esto es útil para la carga masiva de datos, migraciones desde otros sistemas o integración con fuentes de datos externas. La API proporciona endpoints para iniciar trabajos de importación, rastrear su progreso y gestionar errores de validación.

Estructura de una solicitud de Importación de Datos

Encabezados

Campo	Tipo	Descripción	Requerido
Authorization	string	Token Bearer para autenticación.	Sí
Content-Type	string	Debe ser multipart/form-data.	Sí
domain	string	Dominio de destino para los registros.	Sí

Parámetros de ruta

Campo	Tipo	Descripción	Requerido
version	string	Versión actual de la aplicación.	Sí
entity	string	Nombre o ID de la entidad a importar.	Sí

Endpoints para gestionar la Importación de Datos

Crear una importación de datos desde un archivo

Cuerpo de la solicitud

Sigue el formato multipart/form-data con los siguientes campos:

Campo	Tipo	Requerido	Descripción
type	string	Sí	El tipo de archivo, puede ser csv o xlsx
file	string($binary)	Sí	El archivo a cargar, enviado como datos binarios
mapping	object	Sí	Mapa de índices de columnas (comenzando en 1) a nombres de propiedad de la entidad
locale	string	No	Configuración regional del usuario para analizar fechas
timezoneOffset	number	No	Desfase horario en minutos respecto a UTC

POST /api/v1/entities/:entity/import

Ejemplo de respuesta:

{
  "status": 200,
  "error": false,
  "message": "string",
  "errors": [
    {}
  ],
  "data": {
    // Identificadores únicos para el trabajo de importación
    "id": "A0123456-7890-ABCD-EF00-00000000000",
    "entity": "E0123456-7890-ABCD-EF00-00000000000",

    // Estado del trabajo de importación.
    "duration": "10 seconds",
    "status": "QUEUED",
    "type": "IMPORT",
    "progress": 100,
    "payload": {},
    "output": {},

    // Tiempos del ciclo de vida del trabajo.
    "jobEnd": "2020-01-01T00:00:10.000Z",
    "jobStart": "2020-01-01T00:00:00.000Z",
    "createdAt": "2022-01-01T00:00:00.000Z",
    "updatedAt": "2022-01-01T00:00:00.000Z",
    "lastHeartbeat": "2022-01-01T00:00:05.000Z"
  },
  "pagination": { <Paginación> }
}

Monitoreo y comportamiento

• La importación se procesa de forma asíncrona; utilice el endpoint de estado de trabajos en segundo plano /api/v1/job/:id para verificar el progreso.
• Al completarse exitosamente, el jobStatus puede pasar a completed, con valores de importedCount y failedCount.
• Los errores de validación y las filas fallidas se reportan en los detalles del trabajo.

Obtener un trabajo por ID

Este endpoint permite recuperar el estado y los detalles de un trabajo de importación específico.

GET /api/v1/job/{id}

Parámetros de ruta

Nombre	Tipo	Descripción	Requerido
id	string	El valor del ID del trabajo (por ejemplo, 24a55348-e5c9-48b7-b377-07db2f1df368)	Sí

Respuesta

Devuelve un objeto Job con detalles sobre el proceso de importación.

Ejemplo de respuesta:

{
  "errors": [],
  "status": 200,
  "error": false,
  "message": "string",
  "data": {
    "id": "132e4567-e89b-12d3-a456-426614174000",
    "entity": "132e4567-e89b-12d3-a456-426614174000",
    "duration": "10 seconds",
    "status": "QUEUED",
    "type": "IMPORT",
    "progress": 100,
    "payload": {},
    "output": {},
    "jobEnd": "2022-01-05T16:27:16.560Z",
    "jobStart": "2022-01-05T16:27:16.560Z",
    "createdAt": "2022-01-05T16:27:16.560Z",
    "updatedAt": "2022-01-05T16:27:16.560Z",
    "lastHeartbeat": "2022-01-05T16:27:16.560Z"
  }
}