en es il ru

Requisitos de Tec.Delivery para la capa de representación de datos (REST API) del sistema de gestión para la obtención de datos SCU

Este documento describe los requisitos mínimos para la capa de representación de datos (en adelante, API) del sistema de gestión para la obtención de información de productos mediante el complemento universal de sincronización de Tec.Delivery.

Concepto general

El complemento de sincronización obtiene datos de la capa de representación de datos (en adelante, API) del sistema de gestión, por ejemplo, 1C.

1. Requisitos generales de los endpoints de la API

1.1 Métodos compatibles

GET /api/v1/get obtención de productos y categorías
GET /api/v1/balance Opcional obtención de existencias de productos

Los parámetros se envían mediante query string.

Las URL mostradas son únicamente ejemplos y pueden ser reemplazadas por cualquier URL válida definida por el desarrollador de la API.

2. Obtención de productos y categorías

Ejemplo de solicitud:

/api/v1/get?type=product&modified_since=2026-02-01T00:00:00Z&limit=100&offset=0

Parámetros admitidos (filtros y paginación):

type — category / product
modified_since indica a la API que devuelva los registros cuyo momento de modificación sea mayor o igual al valor especificado
limit parámetro de paginación que define la cantidad de registros por lote
offset parámetro de paginación que define el desplazamiento dentro del conjunto de resultados

3. Campos

Cada objeto debe contener los siguientes campos:

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	Identificador único y estable
`type`	string	Sí	Tipo de entidad: `category` o `product`
`parent`	string	Sí	Identificador de la entidad padre (`0` o `null` para una categoría raíz)
`name`	string	Sí	Nombre del producto o categoría
`modified_at`	string	Sí	Fecha y hora de la última modificación del producto o categoría
`description`	string	No	Descripción del producto
`bulk`	bool	No	`false` — producto por unidad, `true` — producto vendido por peso
`price`	number	No	Precio del producto
`discount`	number	No	Importe del descuento
`store_balance`	number	No	Existencia disponible del producto
`image_url`	string	No	URL pública de la imagen del producto
`image_hash`	string / number	No	Hash de la imagen u otro valor utilizado para detectar cambios en ella

Requisitos:

El ID debe ser único y no debe cambiar con el tiempo
La relación parent debe ser válida
La URL de la imagen debe ser accesible públicamente sin autenticación ni redirecciones
El campo modified_at debe actualizarse ante cualquier cambio en el producto o la categoría
Los valores de price, discount y store_balance deben enviarse en un formato numérico válido

4. Lógica de creación, modificación y eliminación de productos

Creación

El complemento crea todos los productos recibidos cuyos ID no existan en Tec.Delivery.
Modificación de datos

El complemento actualiza todos los datos del producto cuando cambia el valor del campo modified_at.
Eliminación

Si un producto fue creado previamente en Tec.Delivery pero ya no está presente en la respuesta actual de la API, el complemento lo marca como bloqueado y deja de mostrarse en la tienda.

Si el producto es nuevo → se crea en Tec.Delivery
Si cambia modified_at → el producto se actualiza
Si cambia image_hash → solo se actualiza la imagen
Si el producto desaparece de la API → el producto se oculta (se marca como bloqueado)

5. Actualización de imágenes

La vigencia de la imagen del producto se controla mediante el campo image_hash. Se recomienda utilizar un hash real de la imagen, aunque también se permiten otros mecanismos de control de cambios, como la fecha de actualización de la imagen o cualquier otra versión de la misma.

El campo image_hash se procesa de forma independiente de modified_at. Por lo tanto, para actualizar una imagen basta con modificar el valor de image_hash; el resto de los datos del producto permanecerán sin cambios.

6. Estructura de respuesta y paginación (obligatoria)

La respuesta de la API debe ser un objeto JSON válido que contenga:

data — arreglo con los datos de productos o categorías
total — cantidad total de registros que cumplen los filtros establecidos, sin considerar la paginación

La API debe soportar paginación y aceptar los parámetros limit y offset.

Ejemplo de respuesta:

{
  "data": [
     {
      "id": "b01a1a32-8ba2-11e6-9cf3-10bf484d6226",
      "parent": "551b4ed9-c385-11e6-9cd7-10bf484d6226",
      "type": "product",
      "bulk": false,
      "name": "Arroz largo parboilizado Goodwill 800 g",
      "price": 145,
      "store_balance": 16,
      "modified_at": "2026-02-13T13:24:04",
      "description": "…",
      "image_url": "https://…/images/b01a1a32-8ba2-11e6-9cf3-10bf484d6226.jpg",
      "image_hash": "f9a15f0d6ebf943aea177f597cb96689c2d5c44d"
    },...
    ],
  "total": 15420
}

6. Sincronización de existencias (método opcional)

Si la tienda requiere sincronizaciones frecuentes de inventario (por ejemplo, debido a un alto volumen de ventas en modo supermercado), se recomienda implementar un método simplificado independiente para obtener únicamente los datos de existencias.

Ejemplo de solicitud:

/api/v1/balance?modified_since=2026-02-01T00:00:00Z&limit=100&offset=0

Parámetros admitidos:

modified_since — indica a la API que devuelva los registros cuya fecha de modificación del inventario sea mayor o igual al valor especificado
limit — parámetro de paginación que define la cantidad de registros por lote
offset — parámetro de paginación que define el desplazamiento dentro del conjunto de resultados

Respuesta

{
  "data": [
     {
      "id": "b01a1a32-8ba2-11e6-9cf3-10bf484d6226",
      "store_balance": 16
    },...
    ],
  "total": 15420
}

7. Estructura jerárquica (parent → child)

El modelo del catálogo es jerárquico. La profundidad mínima es 2 y la máxima es 3:

1 — Categoría
2 — Subcategoría / Producto
3 — Producto