DocumentationDocumentation
Talk2Sync Documentation
User Documentation
Connector APIs
  • English
  • Español
Talk2Sync Documentation
User Documentation
Connector APIs
  • English
  • Español
  • User Guide Portal & API Documentation
  • User-documentation

    • User Documentation
    • Guide

      • User Guide: Introduction
      • Core Concepts
    • Talk2sync

      • Connection Buttons
      • Color Coding System
      • Issues and Alerts
      • Command Filters
      • Deleted Information Still Appears: How to Remove It
      • Deletions
    • Conexiones

      • Connection Settings
    • Fields

      • Time Based Sync
      • Data Governance
      • Special and Extra Fields
    • Productos

      • Product Fields
      • Equivalences
      • Product Search
      • Link / Unlink Products
    • Ventas

      • Fields
      • Equivalences
      • Sales Search
      • No SKU (Missing SKU)
    • Reports

      • Product Export
      • Sales Report
    • Faq

      • Amazon

        • Amazon Barcode Requirements
        • Amazon Catalog Discrepancies and ASIN Mismatches
        • Amazon Manufacturer Requirements
        • New ASIN Creation Errors and Invalid Attribute Values
        • Talk2sync, SKUs, and Product Identifiers
        • Amazon Variation Templates
      • Mercadolibre

        • Mercado Libre Official Stores
        • Mercado Libre Locations and Geographic Attributes
        • Mercado Libre Pick-up in Store
        • Mercado Libre Extra Attributes
        • Mercado Libre Image Processing and Synchronization
        • Mercado Libre Seller Unable to List Error
      • Linio

        • Linio Brand Not Registered Error
        • Linio Physical Dimensions and Weight Requirements
  • Connector APIs

    • Connector APIs
    • Quick-start

      • Introduction & Requirements
      • Add Connection
      • Configure Connection
      • Generate Keys
      • Test Your Integration
    • Webhooks

      • Webhooks API
      • Catalog

        • Webhooks: List Products
        • Webhooks: List Product by ID
        • Webhooks: Add/Update Product
      • Sales

        • Webhooks: List Orders
        • List Order by ID
        • Add/Update Order
    • Reverse-connections

      • Reverse Connections
      • Implementation-states

        • Implementation
        • Query Implementation: Products and Orders
        • Store Implementation: Products and Orders
        • Sleep and Timeouts
      • Protocol

        • Protocol
        • Overview
        • Product Upload
        • Order Upload
        • Product Download
        • Order Download
      • Rest-calls

        • REST Calls
        • Fetching-changes

          • Fetching Changes REST Calls
          • Ask if Fetching
          • Catalog

            • Push Products Page
            • Set Finish Product Pushes
          • Sales

            • Push Orders Page
            • Set Finish Order Pushes
            • Set Finish All Pushes
        • Pulling-changes

          • Pulling Changes REST Calls
          • Ask if Pulling
          • Catalog

            • Get Next Product to Pull
            • Pull Products Page
            • Notify Product Storage Success
            • Notify Product Storage Failure
            • Set Finish Product Download
          • Sales

            • Get Next Order to Pull
            • Pull Orders Page
            • Notify Order Storage Success
            • Notify Order Storage Failure
            • Set Finish Order Download
            • Transact Finish Pull

Webhooks: List Products

Overview

The List Products webhook allows Talk2sync to retrieve your complete product catalog. Talk2sync will periodically request your product endpoint to synchronize product data including details, prices, availability, images, and custom attributes.

Endpoint Requirements

You must create a GET endpoint that accepts pagination and sorting parameters from Talk2sync.

Request Format

Talk2sync will send GET requests to your configured products endpoint with the following parameters:

Numeric Offset Pagination (Recommended)

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

Cursor-Based Pagination (Alternative)

If numeric offset pagination is not feasible for your system, you can implement cursor-based pagination:

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

Request Parameters

ParameterTypeDescriptionRequired
offsetintegerStarting position for numeric pagination (0-based)If using numeric pagination
nextstringBase64-encoded cursor for cursor-based paginationIf using cursor pagination
sortorderstringSort direction: asc (ascending) or desc (descending)✓ Yes
jobidintegerUnique identifier for this sync job (for tracking)✓ Yes
T2SKeyheaderYour security key provided by Talk2sync✓ Yes

Authentication

The security key must be included in the T2SKey header (not the Authorization header for this endpoint):

T2SKey: your_generated_key_here

Response Format

Your endpoint must return a JSON response with the following structure:

{
  "paging": {
    "pageSize": 20,
    "itemsTotal": 2,
    "offset": 0
  },
  "products": [
    {
      "_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": ""
          }
        }
      ]
    }
  ]
}

Response Structure

Paging Object

FieldTypeDescription
pageSizeintegerNumber of items returned in this page
itemsTotalintegerTotal number of products in your system
offsetintegerCurrent offset position (only for numeric pagination)
nextstringBase64-encoded cursor for the next page (only for cursor pagination)

Product Object

FieldTypeDescription
_idstringUnique product identifier (required)
skustringProduct SKU/code
last_updatedintegerUnix timestamp (milliseconds) of last modification
titlestringProduct name/title
urlstringProduct URL in your store
brandstringProduct brand
mpnstringManufacturer Part Number
modelstringProduct model
descriptionstringDetailed product description
variationsarrayArray of product variations (see below)
propertiesarrayArray of custom properties/attributes

Variation Object

FieldTypeDescription
variationidstringUnique variation identifier
sizestringSize attribute
colorstringColor attribute
barcodestringBarcode/EAN code
availabilitiesarrayStock information by location/warehouse
pricesarrayPricing information by currency/region
imagesarrayProduct images
videosarrayProduct videos

Availability Object

FieldTypeDescription
tagstringLocation identifier (e.g., "default", "warehouse_1")
quantityintegerAvailable quantity at this location

Price Object

FieldTypeDescription
tagstringPrice tier identifier (e.g., "default", "wholesale")
currencystringISO 4217 currency code (e.g., "USD", "MXN")
numbernumberPrice value

Image Object

FieldTypeDescription
urlstringFull URL to the product image

Extra Attributes Object

Custom fields can be included in the extraattributes object. Common examples:

FieldTypeDescription
promocionesstringPromotion information
statusstringProduct status (active, inactive, etc.)
condicion_ventastringSales condition
pesostringProduct weight
relacionadosstringRelated products
custom_01 to custom_03stringCustom fields

Implementation Example (Node.js/Express)

app.get('/api/products', (req, res) => {
  const { offset = 0, next, sortorder = 'desc', jobid } = req.query;
  const apiKey = req.headers['t2skey'];

  // Validate API key
  if (apiKey !== process.env.TALK2SYNC_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  try {
    // Fetch products from your database
    const allProducts = fetchProductsFromDatabase(sortorder);
    
    // Implement pagination (numeric offset example)
    const pageSize = 20;
    const startIndex = parseInt(offset) || 0;
    const paginatedProducts = allProducts.slice(startIndex, startIndex + pageSize);

    // Build response
    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(),
        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 fetching products:', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

Response Status Codes

StatusMeaningAction
200 OKProducts retrieved successfullyTalk2sync processes the data
400 Bad RequestInvalid parametersCheck your request parameters
401 UnauthorizedInvalid or missing API keyVerify your security key
500 Internal Server ErrorServer errorCheck your server logs

Pagination Guidelines

Numeric Offset Strategy

Best for: Small to medium datasets (< 100,000 items)

  • Return items from offset to offset + pageSize
  • Increment offset by pageSize for each request
  • Include offset in the paging response

Cursor-Based Strategy

Best for: Large datasets or frequently changing data

  • Encode the next page's starting point as a base64 cursor
  • Return the cursor in the response as next
  • Use the next parameter for subsequent requests
  • More efficient for large datasets

Timing and Frequency

  • Talk2sync will request products according to the synchronization schedule configured in your connection settings
  • The jobid parameter helps you track which sync job initiated each request
  • Each request should be processed and return within 1 minute

Best Practices

✓ Do:

  • Return data sorted consistently (use sortorder parameter)
  • Include accurate last_updated timestamps
  • Validate the API key on every request
  • Implement pagination to handle large catalogs
  • Test with various page sizes
  • Monitor API response times

✗ Don't:

  • Include sensitive information in responses
  • Return the same product multiple times
  • Ignore the sorting parameter
  • Return responses larger than 10MB per page

Related Webhooks

  • List Product by ID
  • Add/Update Product

Related Documentation

  • Quick Start: Generate Keys
  • Webhooks Overview
Last Updated: 8/21/26, 12:13 PM
Next
Webhooks: List Product by ID