DocumentaciónDocumentación
Talk2Sync Documentation
Manual de Usuario
APIs de Conexiones
  • English
  • Español
Talk2Sync Documentation
Manual de Usuario
APIs de Conexiones
  • English
  • Español
  • Portal de Guía de Usuario y Documentación de API
  • User-documentation

    • Manual de Usuario
    • Guide

      • Guía del Usuario: Introducción
      • Conceptos Fundamentales
    • Talk2sync

      • Botones de Conexión
      • Sistema de Códigos de Color
      • Alertas o errores de validación
      • Filtros de comandos
      • La información eliminada todavía aparece: cómo eliminarla
      • Eliminación de datos
    • Conexiones

      • Configuraciones de la conexión
    • Campos

      • Sincronización basada en tiempos
      • Gobierno de datos
      • Campos especiales y adicionales
    • Productos

      • Campos de productos
      • Equivalencias
      • Búsqueda de productos
      • Vincular / Desvincular Productos
    • Ventas

      • Campos
      • Equivalencias de órdenes
      • Búsqueda de órdenes de venta
      • Sin SKU (SKU faltante)
    • Reports

      • Exportación de Productos
      • Reporte de Ventas
    • Faq

      • Amazon

        • Requisitos de Código de Barras en Amazon
        • Discrepancias con el Catálogo de Amazon y Errores de ASIN
        • Requisitos del Fabricante en Amazon
        • Errores de Creación de Nuevos ASIN y Valores de Atributos Inválidos
        • Talk2sync, SKUs e Identificadores de Productos
        • Plantillas de Variación en Amazon
      • Mercadolibre

        • Tiendas Oficiales en Mercado Libre
        • Ubicaciones y Atributos Geográficos en Mercado Libre
        • Recogida en Tienda en Mercado Libre
        • Atributos Adicionales en Mercado Libre
        • Procesamiento de Imágenes y Sincronización en Mercado Libre
        • Error de Vendedor Inhabilitado para Publicar en Mercado Libre
      • Linio

        • Error de Marca No Registrada en Linio
        • Requisitos de Dimensiones Físicas y Peso en Linio
  • APIs para Conexiones

    • APIs de Conexiones
    • Quick-start

      • Introducción y Requisitos
      • Agregar Conexión
      • Configurar Conexión
      • Generar Claves
      • Prueba tu Integración
    • Webhooks

      • API de Webhooks
      • Catalog

        • Webhooks: Listar Productos
        • Webhooks: Listar Producto por ID
        • Webhooks: Agregar/Actualizar Producto
      • Sales

        • Webhooks: Listar Órdenes
        • Listar orden por ID
        • Agregar/Actualizar orden
    • Reverse-connections

      • Reverse Connections
      • Implementation-states

        • Implementación
        • Implementación de consulta: productos y órdenes
        • Implementación de almacenamiento: productos y órdenes
        • Sleep y timeouts
      • Protocol

        • Protocolo
        • Descripción general
        • Carga de productos
        • Carga de órdenes
        • Descarga de productos
        • Descarga de órdenes
      • Rest-calls

        • Llamadas REST
        • Fetching-changes

          • Llamadas REST para obtención de cambios
          • Consultar si está obteniendo cambios
          • Catalog

            • Enviar página de productos
            • Finalizar envíos de productos
          • Sales

            • Enviar página de órdenes
            • Finalizar envíos de órdenes
            • Finalizar todos los envíos
        • Pulling-changes

          • Llamadas REST para descarga de cambios
          • Consultar si está descargando cambios
          • Catalog

            • Obtener el siguiente producto
            • Obtener página de productos
            • Notificar almacenamiento exitoso del producto
            • Notificar error en el almacenamiento del producto
            • Finalizar descarga de productos
          • Sales

            • Obtener la siguiente orden
            • Obtener página de órdenes
            • Notificar almacenamiento exitoso de una orden
            • Notificar error en el almacenamiento de una orden
            • Finalizar descarga de órdenes
            • Finalizar transacción de descarga

Webhooks: Listar Producto por ID

Descripción General

El webhook Listar Producto por ID proporciona un enfoque optimizado de dos etapas para recuperar productos. Esto es útil para optimización de rendimiento cuando tienes un catálogo de productos grande.

En lugar de devolver detalles completos del producto con cada solicitud, puedes devolver una lista ligera de IDs de productos y sus timestamps de last_updated. Talk2sync utiliza esta información para determinar qué productos han cambiado y solo solicita detalles completos para aquellos que necesitan actualización.

Proceso de Recuperación de Dos Etapas

Etapa 1: Listar IDs de Productos (Índice Ligero)

Solicitud:

Talk2sync primero solicita un índice ligero de todos tus productos:

Paginación por Offset Numérico

GET https://www.example.com/your/endpoint/url?offset=0&sortorder=desc&jobid=123
T2SKey: {{API_KEY}}

Paginación por Cursor

GET https://www.example.com/your/endpoint/url?next=YXNkaWhhc3BvZGhpYXM&sortorder=desc&jobid=123
T2SKey: {{API_KEY}}

Respuesta:

Devuelve una lista ligera con solo información esencial:

{
  "paging": {
    "pageSize": 20,
    "itemsTotal": 2,
    "offset": 0
  },
  "products": [
    {
      "_id": "100004777",
      "sku": "100004777",
      "last_updated": 1517360038797
    },
    {
      "_id": "100004778",
      "sku": "100004778",
      "last_updated": 1517360038800
    }
  ]
}

Campos de Respuesta:

CampoTipoDescripción
_idstringIdentificador único del producto (requerido)
skustringSKU/código del producto
last_updatedintegerTimestamp Unix (milisegundos) de la última modificación

Etapa 2: Recuperar Detalles Completos del Producto (Bajo Demanda)

Solicitud:

Cuando Talk2sync determina que un producto necesita actualización, solicita los detalles completos del producto usando el ID del producto:

GET https://www.example.com/your/endpoint/url?id=100004777&jobid=123
T2SKey: {{API_KEY}}

Parámetros de Solicitud:

ParámetroTipoDescripciónObligatorio
idstringID del producto para recuperar detalles completos✓ Sí
jobidintegerIdentificador único para este trabajo de sincronización✓ Sí
T2SKeyheaderTu clave de seguridad✓ Sí

Respuesta:

Devuelve los detalles completos del producto:

{
  "_id": "100004777",
  "sku": "100004777",
  "last_updated": 1517360038797,
  "title": "EON618S JBL SUBWOOFER 18\" AMPLIFICADO",
  "url": "",
  "brand": "",
  "mpn": "",
  "model": "",
  "description": "JBL Premium Transducers",
  "variations": [
    {
      "availabilities": [
        {
          "tag": "default",
          "quantity": 50
        }
      ],
      "prices": [
        {
          "tag": "default",
          "currency": "USD",
          "number": 1060.51
        }
      ],
      "images": [
        {
          "url": "https://www.example.com/13080-thickbox_default/eon618s-jbl-subwoofer-18-amplificado-.jpg"
        }
      ],
      "videos": [
        {
          "url": ""
        }
      ],
      "barcode": "",
      "size": "",
      "color": "",
      "variationid": ""
    }
  ],
  "properties": [
    {
      "extraattributes": {
        "promociones": "",
        "status": "",
        "condicion_venta": "",
        "peso": "",
        "relacionados": "",
        "custom_01": "",
        "custom_02": "1",
        "custom_03": ""
      }
    }
  ]
}

Referencia Completa de Campos

Objeto de Producto Ligero (Etapa 1)

CampoTipoDescripción
_idstringIdentificador único del producto (requerido)
skustringSKU/código del producto
last_updatedintegerTimestamp Unix (milisegundos) de la última modificación

Objeto de Producto Completo (Etapa 2)

CampoTipoDescripción
_idstringIdentificador único del producto (requerido)
skustringSKU/código del producto
last_updatedintegerTimestamp Unix (milisegundos) de la última modificación
titlestringNombre/título del producto
urlstringURL del producto en tu tienda
brandstringMarca del producto
mpnstringNúmero de Parte del Fabricante
modelstringModelo del producto
descriptionstringDescripción detallada del producto
variationsarrayArray de variaciones del producto
propertiesarrayArray de propiedades/atributos personalizados

Objeto de Variación (Solo Etapa 2)

CampoTipoDescripción
variationidstringIdentificador único de la variación
sizestringAtributo de tamaño
colorstringAtributo de color
barcodestringCódigo de barras/EAN
availabilitiesarrayInformación de inventario por ubicación
pricesarrayInformación de precios
imagesarrayImágenes del producto
videosarrayVideos del producto

Objeto de Disponibilidad

CampoTipoDescripción
tagstringIdentificador de ubicación (p.ej., "default", "warehouse_1")
quantityintegerCantidad disponible

Objeto de Precio

CampoTipoDescripción
tagstringIdentificador de nivel de precio (p.ej., "default", "wholesale")
currencystringCódigo de moneda ISO 4217 (p.ej., "USD", "MXN")
numbernumberValor del precio

Ejemplo de Implementación (Node.js/Express)

// Etapa 1: Listar IDs de productos con timestamps de last_updated
app.get('/api/products', (req, res) => {
  const { offset = 0, next, sortorder = 'desc', jobid } = req.query;
  const apiKey = req.headers['t2skey'];

  // Validar clave de API
  if (apiKey !== process.env.TALK2SYNC_KEY) {
    return res.status(401).json({ error: 'No autorizado' });
  }

  try {
    // Obtener datos de productos ligeros (solo IDs y timestamps)
    const allProducts = fetchProductsLightweight(sortorder);
    
    const pageSize = 20;
    const startIndex = parseInt(offset) || 0;
    const paginatedProducts = allProducts.slice(startIndex, startIndex + pageSize);

    const response = {
      paging: {
        pageSize: paginatedProducts.length,
        itemsTotal: allProducts.length,
        offset: startIndex
      },
      products: paginatedProducts.map(product => ({
        _id: product.id,
        sku: product.sku,
        last_updated: new Date(product.updatedAt).getTime()
      }))
    };

    res.json(response);
  } catch (error) {
    console.error('Error al obtener productos:', error);
    res.status(500).json({ error: 'Error Interno del Servidor' });
  }
});

// Etapa 2: Recuperar detalles completos del producto por ID
app.get('/api/products', (req, res) => {
  const { id, jobid } = req.query;
  const apiKey = req.headers['t2skey'];

  // Validar clave de API
  if (apiKey !== process.env.TALK2SYNC_KEY) {
    return res.status(401).json({ error: 'No autorizado' });
  }

  try {
    // Si el parámetro ID está presente, devuelve detalles completos del producto
    if (id) {
      const product = fetchProductById(id);
      
      if (!product) {
        return res.status(404).json({ error: 'Producto no encontrado' });
      }

      const response = {
        _id: product.id,
        sku: product.sku,
        last_updated: new Date(product.updatedAt).getTime(),
        title: product.name,
        url: product.url,
        brand: product.brand,
        mpn: product.mpn,
        model: product.model,
        description: product.description,
        variations: product.variations.map(v => ({
          variationid: v.id,
          size: v.size || "",
          color: v.color || "",
          barcode: v.barcode || "",
          availabilities: v.stocks.map(s => ({
            tag: s.location || "default",
            quantity: s.quantity
          })),
          prices: v.prices.map(p => ({
            tag: p.tier || "default",
            currency: p.currency || "USD",
            number: p.value
          })),
          images: v.images.map(img => ({ url: img })),
          videos: v.videos.map(vid => ({ url: vid }))
        })),
        properties: [{
          extraattributes: product.customFields || {}
        }]
      };

      res.json(response);
    }
  } catch (error) {
    console.error('Error al obtener producto:', error);
    res.status(500).json({ error: 'Error Interno del Servidor' });
  }
});

Cómo Talk2sync Utiliza Este Enfoque

  1. Primera Solicitud: Talk2sync llama a tu endpoint sin parámetro id para obtener el índice ligero
  2. Comparación: Talk2sync compara el timestamp last_updated con lo que tiene almacenado
  3. Solicitudes Selectivas: Para productos con valores de last_updated más nuevos, Talk2sync realiza solicitudes individuales con el parámetro id
  4. Optimización de Ancho de Banda: Solo los productos que han cambiado realmente generan solicitudes de datos completos

Beneficios de Rendimiento

AspectoBeneficio
Ancho de BandaReducido al obtener solo detalles completos para productos cambiados
Velocidad de SincronizaciónMucho más rápida la comparación inicial del índice
Carga de Base de DatosCarga más baja de menos búsquedas completas de productos
EscalabilidadManeja catálogos grandes eficientemente

Cuándo Usar Este Enfoque

✓ Úsalo cuando:

  • Tu catálogo tiene 10,000+ productos
  • Los productos se actualizan con poca frecuencia
  • Quieres minimizar el uso de ancho de banda
  • El tiempo de respuesta es crítico

✗ Evítalo cuando:

  • Tu catálogo es pequeño (< 1,000 productos)
  • La mayoría de productos cambian frecuentemente
  • El ancho de banda no es una preocupación
  • La simplicidad es más importante que la optimización

Códigos de Estado de Respuesta

EstadoSignificadoAcción
200 OKDatos recuperados exitosamenteTalk2sync procesa la respuesta
400 Bad RequestParámetros inválidosVerifica tus parámetros de solicitud
401 UnauthorizedClave de API inválida o faltanteVerifica tu clave de seguridad
404 Not FoundID de producto no existeVerifica el ID del producto
500 Internal Server ErrorError del servidorRevisa los registros de tu servidor

Guías de Paginación

Etapa 1: Endpoints de Lista

Usa las mismas estrategias de paginación que Listar Productos:

  • Offset Numérico: Para conjuntos de datos pequeños a medianos
  • Basada en Cursor: Para conjuntos de datos grandes o que cambian frecuentemente

Etapa 2: Solicitud de Producto Único

Sin paginación necesaria—este endpoint siempre devuelve un único producto completo.


Buenas Prácticas

✓ Haz:

  • Devuelve datos ligeros en Etapa 1 (solo IDs y timestamps)
  • Mantén timestamps de last_updated precisos y actualizados
  • Valida la clave de API en cada solicitud
  • Devuelve 404 si un ID de producto solicitado no existe
  • Cachea detalles completos del producto cuando sea posible

✗ No hagas:

  • Devuelvas detalles completos del producto en Etapa 1 (anula el propósito)
  • Devuelvas datos incompletos en Etapa 2
  • Incluyas información sensible en respuestas
  • Ignores el parámetro de ordenamiento en Etapa 1

Comparación: Listar Productos vs Listar Producto por ID

CaracterísticaListar ProductosListar Producto por ID
Caso de UsoCatálogos pequeños, integraciones simplesCatálogos grandes, optimización de rendimiento
Respuesta Etapa 1Detalles completos del productoLigero (ID + timestamp)
Respuesta Etapa 2N/ADetalles completos del producto (bajo demanda)
Uso de Ancho de BandaAlto (todos los detalles siempre enviados)Bajo (solo productos cambiados obtenidos)
ComplejidadSimpleMás compleja (dos endpoints)
Mejor Para< 1,000 productos10,000+ productos

Webhooks Relacionados

  • Listar Productos
  • Agregar/Actualizar Producto

Documentación Relacionada

  • Quick Start: Generar Claves
  • Descripción General de Webhooks
Actualizado el: 28/08/26, 12:58 a.m.
Prev
Webhooks: Listar Productos
Next
Webhooks: Agregar/Actualizar Producto