Webhooks: Listar Órdenes

Descripción General

El webhook Listar Órdenes permite que Talk2sync recupere tu historial de órdenes completo. Talk2sync solicitará periódicamente tu endpoint de órdenes para sincronizar datos de órdenes de venta incluyendo información del cliente, artículos de la orden, envíos y estado de la orden.

Requisitos del Endpoint

Debes crear un endpoint GET que acepte parámetros de paginación y ordenamiento de Talk2sync.

Formato de Solicitud

Talk2sync enviará solicitudes GET a tu endpoint de órdenes configurado con los siguientes parámetros:

Paginación por Offset Numérico (Recomendado)

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

Paginación por Cursor (Alternativa)

Si la paginación por offset numérico no es viable para tu sistema, puedes implementar paginación basada en cursor:

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

Parámetros de Solicitud

Autenticación

La clave de seguridad debe incluirse en el encabezado T2SKey:

T2SKey: tu_clave_generada_aqui

Formato de Respuesta

Tu endpoint debe devolver una respuesta JSON con la siguiente estructura:

{
  "paging": {
    "pageSize": 20,
    "itemsTotal": 1,
    "offset": 0
  },
  "orders": [
    {
      "_id": "75554554546",
      "orderid": "75554554546",
      "last_updated": 1517360038797,
      "status": "paid",
      "dateCreated": "",
      "dateClosed": "",
      "total": {
        "amount": 350,
        "currency": "USD"
      },
      "orderItems": [
        {
          "id": "7778545",
          "variation_id": "0",
          "quantity": 1,
          "unitPrice": 350,
          "currencyId": "USD"
        }
      ],
      "buyer": {
        "id": "4578889",
        "email": "testbuyer@example.com",
        "phone": "88888888",
        "firstName": "John",
        "lastName": "Doe",
        "billingaddress": {
          "addressline": "",
          "zipcode": "",
          "city": "",
          "state": "",
          "country": ""
        },
        "shipmentaddress": {
          "addressline": "",
          "zipcode": "",
          "city": "",
          "state": "",
          "country": ""
        }
      },
      "shipments": [
        {
          "id": "123",
          "shiptracknum": "TRK-1203912",
          "shipitems": ["4578889"],
          "shiptype": "Fedex",
          "shipstatus": "shipping"
        }
      ],
      "rating": 2.5,
      "feedback": "",
      "messages": [
        {
          "message_id": "",
          "date_created": 0,
          "from": "",
          "message": ""
        }
      ]
    }
  ]
}

Estructura de Respuesta

Objeto de Paginación

Objeto de Orden

Objeto Total

Objeto de Artículo de Orden

Objeto de Comprador

Objeto de Dirección (Facturación y Envío)

Objeto de Envío

Objeto de Mensaje

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

app.get('/api/orders', (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 órdenes de tu base de datos
    const allOrders = fetchOrdersFromDatabase(sortorder);
    
    // Implementar paginación (ejemplo con offset numérico)
    const pageSize = 20;
    const startIndex = parseInt(offset) || 0;
    const paginatedOrders = allOrders.slice(startIndex, startIndex + pageSize);

    // Construir respuesta
    const response = {
      paging: {
        pageSize: paginatedOrders.length,
        itemsTotal: allOrders.length,
        offset: startIndex
      },
      orders: paginatedOrders.map(order => ({
        _id: order.id,
        orderid: order.orderNumber,
        last_updated: new Date(order.updatedAt).getTime(),
        status: order.status,
        dateCreated: order.createdAt,
        dateClosed: order.closedAt || "",
        total: {
          amount: order.totalAmount,
          currency: order.currency || "USD"
        },
        orderItems: order.items.map(item => ({
          id: item.productId,
          variation_id: item.variationId || "0",
          quantity: item.quantity,
          unitPrice: item.price,
          currencyId: order.currency || "USD"
        })),
        buyer: {
          id: order.buyerId,
          email: order.buyerEmail,
          phone: order.buyerPhone || "",
          firstName: order.buyerFirstName || "",
          lastName: order.buyerLastName || "",
          billingaddress: {
            addressline: order.billingAddress?.street || "",
            zipcode: order.billingAddress?.zipcode || "",
            city: order.billingAddress?.city || "",
            state: order.billingAddress?.state || "",
            country: order.billingAddress?.country || ""
          },
          shipmentaddress: {
            addressline: order.shippingAddress?.street || "",
            zipcode: order.shippingAddress?.zipcode || "",
            city: order.shippingAddress?.city || "",
            state: order.shippingAddress?.state || "",
            country: order.shippingAddress?.country || ""
          }
        },
        shipments: order.shipments?.map(ship => ({
          id: ship.id,
          shiptracknum: ship.trackingNumber || "",
          shipitems: ship.itemIds || [],
          shiptype: ship.carrier || "",
          shipstatus: ship.status || "pending"
        })) || [],
        rating: order.rating || 0,
        feedback: order.review || "",
        messages: order.messages?.map(msg => ({
          message_id: msg.id || "",
          date_created: new Date(msg.createdAt).getTime(),
          from: msg.sender || "",
          message: msg.content || ""
        })) || []
      }))
    };

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

Códigos de Estado de Respuesta

Guías de Paginación

Estrategia de Offset Numérico

Mejor para: Conjuntos de datos pequeños a medianos (< 100,000 órdenes)

• Devuelve elementos desde offset hasta offset + pageSize
• Incrementa offset por pageSize para cada solicitud
• Incluye offset en la respuesta de paginación

Estrategia de Cursor

Mejor para: Conjuntos de datos grandes o datos que cambian frecuentemente

• Codifica el punto de inicio de la siguiente página como un cursor en base64
• Devuelve el cursor en la respuesta como next
• Usa el parámetro next para solicitudes posteriores
• Más eficiente para conjuntos de datos grandes

Valores de Estado de Orden

Los valores comunes de estado de orden incluyen:

Nota: Usa valores de estado que coincidan con tu sistema. Talk2sync almacenará los valores que devuelvas.

Sincronización y Frecuencia

• Talk2sync solicitará órdenes según el programa de sincronización configurado en los ajustes de tu conexión
• El parámetro jobid te ayuda a rastrear qué trabajo de sincronización inició cada solicitud
• Cada solicitud debe procesarse y devolver una respuesta dentro de 1 minuto

Manejo de Actualizaciones de Órdenes

Cuando se actualizan las órdenes:

• Actualiza el timestamp de last_updated a la hora actual
• Asegúrate de que el estado de la orden refleje el estado más reciente
• Incluye todos los envíos y mensajes hasta la hora actual
• Devuelve la orden actualizada en la siguiente sincronización

Buenas Prácticas

✓ Haz:

• Devuelve datos ordenados consistentemente (usa el parámetro sortorder)
• Incluye timestamps de last_updated precisos
• Valida la clave de API en cada solicitud
• Implementa paginación para manejar listas grandes de órdenes
• Usa formato ISO 8601 para campos de fecha
• Incluye información completa del comprador y dirección cuando esté disponible
• Mantén información de seguimiento de envío

✗ No hagas:

• Incluyas información sensible de pago (números de tarjeta de crédito)
• Devuelvas información personal más allá de lo necesario
• Devuelvas la misma orden múltiples veces
• Ignores el parámetro de ordenamiento
• Devuelvas respuestas mayores a 10MB por página
• Incluyas notas internas del sistema o comentarios privados

Mejores Prácticas de Mapeo de Datos

Fechas

Usa consistentemente uno de estos formatos:

• ISO 8601: 2024-01-15T10:30:00Z (recomendado)
• Cadena vacía: "" (si la fecha no está disponible)

Monedas

Siempre usa códigos de moneda ISO 4217 de 3 letras:

• USD (Dólar estadounidense)
• MXN (Peso mexicano)
• EUR (Euro)
• GBP (Libra esterlina)

Campos de Estado

Mantén valores de estado consistentes y predecibles. Ejemplos:

• Estado de Orden: pending, paid, processing, shipped, delivered, cancelled, refunded
• Estado de Envío: pending, shipping, delivered, returned, lost
• Estado de Comprador: active, inactive, blocked

Webhooks Relacionados

• Listar Orden por ID
• Agregar/Actualizar Orden

Documentación Relacionada

• Quick Start: Generar Claves
• Descripción General de Webhooks
• Listar Productos (enfoque de paginación similar)