Requisitos técnicos

A continuación se listan los requisitos técnicos necesarios para implementar una integración por Archivos con YOM.

🗄️ Servidor SFTP

El servidor donde estén los archivos puede ser del cliente o en un servidor de YOM.

Servidor de YOM

YOM hosteará un servidor SFTP para los ambientes de development y production. Las credenciales a manejar son:

Host → sftp-integrations.youorder.me
Port → 22
Username → *Por definir

Para garantizar la seguridad, el acceso al servidor SFTP se realiza mediante autenticación SSH con clave privada. YOM proporcionará al cliente un archivo que contiene la clave privada necesaria para autenticarse.

<aside> ⚠️

La clave privada debe mantenerse segura y nunca compartirse con terceros.

</aside>

*Coordinar con equipo TI.

📋 Formato de Archivos

Los archivos deben estar en formato CSV, con punto y coma ; como separador por defecto y encoding UTF-8.

Separador → ;

La estructura de sus nombres debe ser:

<fecha>_<hora>_<entidad>.csv

Formato Fecha → YYYYMMDD

Formato Hora → HHMMSS

Ejemplo para un archivo con lista de Products cargado el día 01 de Febrero de 2024 a las 18 hrs:

20240201_180000_product.csv

📂 Carpetas

Se debe implementar una estructura de carpetas como la siguiente:

/nombre_cliente
	/load
		/product
			/all
				20240201_180000_product.csv
				20240201_073000_product.csv
				20240131_180000_product.csv
				20240131_073000_product.csv
			/created
				...
			/updated
				...
			...
		/commerce
			/all
				20240201_180000_commerce.csv
				20240131_180000_commerce.csv
				20240130_180000_commerce.csv
			/created
				...
			/updated
				...
			...
		/override
			...
		...

Explicación de la Estructura de Carpetas

/<nombre_cliente> → Esta carpeta principal representa al cliente específico que se integra con YOM.

/production → Carpeta para el entorno de producción, donde se almacenan los archivos utilizados en operaciones en vivo.

/load → Subcarpeta dentro de producción donde se organizan los diferentes tipos de datos.

/<entidad> → Carpeta específica para archivos relacionados con productos.

/all → Archivos que contienen todos las entidades.

/updated → Archivos que contienen entidades actualizadas luego de la carga anterior.

/created → Archivos que contienen entidades creadas luego de la carga anterior.

/development → Carpeta para el entorno de desarrollo, usada para pruebas y desarrollo continuo.

<aside> 🚧

Por el momento, solo se consideran los archivos en la carpeta /all. Consultar por la habilitación de la carga incremental utilizando las carpetas /created y /updated.

</aside>

📋 Política de Aplanamiento de Objetos JSON

Las entidades se definen originalmente como objetos con campos anidados, los cuales representan objetos o listas. Están pensadas para ser transmitidas mediante estructuras JSON En la integración por API Programada.

Para convertir estructuras JSON anidadas en un formato CSV, es necesario “aplanar” los objetos, es decir, convertir las propiedades anidadas en una estructura de clave-valor plana.

Para aplanar el objeto JSON anterior a un formato CSV, se sigue la siguiente lógica:

Propiedades anidadas se separan con guiones bajos → _
Elementos en listas se enumeran.

A continuación se ejemplifica la lógica de aplanamiento de JSON.

JSON Original

{
  "id": "001",
  "name": "Example Object",
  "details": {
    "type": "Example Type",
    "description": "This is a detailed description",
    "metadata": {
      "createdBy": "User1",
      "createdAt": "2023-07-01T12:00:00Z",
      "updatedBy": "User2",
      "updatedAt": "2023-07-02T15:30:00Z"
    }
  },
  "tags": ["tag1", "tag2", "tag3"],
  "attributes": [
    {
      "key": "color",
      "value": "red"
    },
    {
      "key": "size",
      "value": "medium"
    }
  ],
  "status": "active",
  "relatedObjects": [
    {
      "relationType": "parent",
      "objectId": "002"
    },
    {
      "relationType": "sibling",
      "objectId": "003"
    }
  ],
  "additionalInfo": [
    {
      "infoType": "extra",
      "infoDetails": {
        "detailKey": "detailValue"
      }
    }
  ]
}

CSV Aplanado

id;name;details_type;details_description;details_metadata_createdBy;details_metadata_createdAt;details_metadata_updatedBy;details_metadata_updatedAt;tags_1;tags_2;tags_3;attributes_1_key;attributes_1_value;attributes_2_key;attributes_2_value;status;relatedObjects_1_relationType;relatedObjects_1_objectId;relatedObjects_2_relationType;relatedObjects_2_objectId;additionalInfo_1_infoType;additionalInfo_1_infoDetails_detailKey
001;Example Object;Example Type;This is a detailed description;User1;2023-07-01T12:00:00Z;User2;2023-07-02T15:30:00Z;tag1;tag2;tag3;color;red;size;medium;active;parent;002;sibling;003;extra;detailValue

Explicación del Aplanamiento

Propiedades Simples → Se mantienen como están (id, name, status).

Propiedades Anidadas → Las propiedades anidadas se separan con un guion bajo (_):

details.type se convierte en details_type.

details.metadata.createdBy se convierte en details_metadata_createdBy.

Listas de Strings → Cada elemento de la lista se convierte en una columna separada:

tags[0] se convierte en tags_0.

tags[1] se convierte en tags_1.

Listas de Objetos → Cada objeto en una lista se descompone en columnas, incluyendo el índice en el nombre de la columna:

attributes[0].key se convierte en attributes_0_key.

attributes[1].value se convierte en attributes_1_value.

Listas de Objetos con Propiedades Anidadas → Para objetos en listas que también tienen propiedades anidadas:

additionalInfo[0].infoDetails.detailKey se convierte en additionalInfo_0_infoDetails_detailKey.

Pasos anteriores

<aside> <img src="/icons/arrow-left_gray.svg" alt="/icons/arrow-left_gray.svg" width="40px" /> Archivos (Carga de datos)

</aside>

Siguientes pasos

<aside> <img src="/icons/arrow-right_gray.svg" alt="/icons/arrow-right_gray.svg" width="40px" /> Archivos a disponibilizar

</aside>

Tabla de contenidos