Guía de integración de transportistas de envío personalizados de alto nivel

TABLA DE CONTENIDO

• Introducción
• Tabla de contenido
• Diagrama de flujo de integración
• 1. Requisitos
  • Conocimientos técnicos
  • Servicio de backend
  • Base de datos
  • Interfaz
  • API
• 2. Configuración inicial
  • Crear una aplicación de Marketplace
  • Configurar los ajustes de la aplicación
  • Alcances requeridos
  • Interfaz de usuario de frontend (página personalizada)
  • Manejo del contexto del usuario
  • Manejo de credenciales del operador
• 3. Implementación de tarifas de envío en vivo
  • Registrar transportista en Centryka
  • Implementar devolución de llamada de tarifas en vivo
  • Configurar tarifas de envío en zonas de alto nivel
• 4. Sincronización y cumplimiento de pedidos
  • Habilitar webhooks de pedidos
  • Gestión del webhook de creación de pedidos
  • Actualizaciones de envío de transportistas de manipulación
• 5. Desconexión y desinstalación
  • Eliminar el transportista de envío
• Conclusión

Introducción

Esta guía ofrece una guía completa para desarrollar la integración de una empresa de transporte con el marketplace de Centryka. Una integración personalizada permite a las empresas que utilizan Centryka conectar a sus proveedores de envío preferidos, ofrecer tarifas de envío en tiempo real durante el proceso de compra, automatizar los flujos de trabajo de preparación de pedidos y proporcionar información de seguimiento precisa directamente a los clientes. Esto mejora las funciones nativas de comercio electrónico de Centryka.

Los principales beneficios de implementar una integración de transportista de envío personalizado incluyen:

• Flexibilidad: Conéctese con cualquier transportista que proporcione una API, más allá de las opciones integradas.
• Tarifas precisas: muestra los costos de envío precisos y en tiempo real de tus cuentas de transportistas específicas durante el pago.
• Cumplimiento automatizado: reduzca el esfuerzo manual creando automáticamente etiquetas de envío y activando envíos con su transportista.
• Seguimiento continuo: mantenga a los clientes informados sincronizando la información de seguimiento del transportista con los pedidos de Centryka.
• Experiencia integrada: gestione los aspectos de envío directamente dentro del ecosistema Centryka.

Desarrollar esta integración implica el desarrollo del backend para gestionar las llamadas a la API y los webhooks, el desarrollo del frontend para la configuración del usuario (a menudo mediante una página personalizada) y la gestión segura de las credenciales y el flujo de datos entre Centryka, su servicio y la API del transportista. Siguiendo esta guía, podrá crear una integración robusta que agilice las operaciones de envío para los usuarios de Centryka.

Diagrama de flujo de integración

1. Requisitos

Conocimientos técnicos

• Conocimientos básicos de desarrollo backend (por ejemplo, Node.js, Python, etc.).
• Comprensión de las API REST, webhooks y el flujo de autorización OAuth 2.0.

Servicio de backend

• Un servicio backend capaz de:

• Manejo de la redirección OAuth desde Centryka.
• Recibir y procesar webhooks tanto de Centryka (por ejemplo, eventos de pedido) como del transportista de envío personalizado (por ejemplo, actualizaciones de envío).
• Realizar llamadas API tanto a Centryka como a la API del operador personalizado.
• Sirviendo la interfaz de usuario del frontend (si no está alojada por separado).

Base de datos

• Una base de datos para almacenar de forma segura:

• Tokens OAuth de alto nivel (tokens de acceso y actualización) asociados con ID de ubicación.
• Credenciales del transportista de envío personalizadas (por ejemplo, claves API, secretos) proporcionadas por el usuario, vinculadas a la ubicación de Centryka.
• Mapeo de información entre entidades de alto nivel (como pedidos) y entidades transportistas.

Interfaz

• Una aplicación frontend simple (que se puede implementar como una página personalizada de alto nivel) que permite a los usuarios:

• Iniciar el proceso de conexión.
• Ingrese y guarde sus credenciales de API de transportista de envío.
• Administrar la configuración de conexión (por ejemplo, habilitar o deshabilitar funciones).

API

• Su servicio backend deberá implementar varios puntos finales de API:

• URI de redirección de OAuth: maneja la devolución de llamada de Centryka después de la autorización de la aplicación.
• Oyente de webhook de alto nivel: recibe webhooks de alto nivel (por ejemplo, OrderCreate, OrderStatusUpdate).
• Gestión de credenciales del operador: API para guardar, actualizar y eliminar las credenciales del operador ingresadas a través de la interfaz.
• Oyente de webhook del transportista: recibe webhooks del transportista de envío personalizado.
• Devolución de llamada de tarifas en vivo: un punto final que Centryka llama para obtener tarifas de envío en vivo durante el pago.

2. Configuración inicial

Crear una aplicación de Marketplace

• Siga la documentación de Centryka para crear una nueva aplicación de Marketplace: Documentación de autorización de Centryka

Configurar los ajustes de la aplicación

• Tipo de aplicación: Establezca el tipo de aplicación en Subcuenta . Esto permite la instalación en cuentas de ubicaciones específicas.
• URI de redireccionamiento: configúrelo en la URL del punto final de su servicio de backend designado para manejar la devolución de llamada OAuth (por ejemplo, https://your-backend.com/oauth/callback).
• URL del webhook: Establezca esta URL en el punto final de su servicio backend designado para recibir webhooks de Centryka (p. ej., https://your-backend.com/webhooks/Centryka). Asegúrese de que los webhooks OrderCreatey OrderStatusUpdateestén habilitados en la configuración de la aplicación.

Alcances requeridos

• Su aplicación necesitará los siguientes ámbitos para gestionar envíos y pedidos. Consulte la documentación de ámbitos para conocer los nombres exactos: Documentación de ámbitos de alto nivel

• orders.readonly
• orders.write
• shipping.readonly
• shipping.write

Interfaz de usuario de frontend (página personalizada)

• Desarrollar una interfaz frontend donde los usuarios puedan ingresar sus credenciales de transportista de envío específicas (clave API, secreto, ID de cuenta, etc.).
• Esta interfaz de usuario debe estar integrada en Centryka mediante un enlace de menú personalizado que apunte a su página de interfaz alojada o a un punto final que sirva a la interfaz de usuario.

Manejo del contexto del usuario

• Tu frontend y backend deben identificar la ubicación de Centryka con la que interactúa el usuario. Usa el contexto proporcionado por Centryka al cargar el enlace de tu página/menú personalizado.
• Consulte la documentación sobre el contexto del usuario: Contexto del usuario en aplicaciones del Marketplace
• Normalmente, esto implica analizar un token (como un JWT o una carga útil cifrada) que se pasa como parámetro de consulta cuando Centryka redirige a tu frontend/backend. Descifra y valida este token usando un secreto compartido proporcionado durante la configuración de la aplicación para obtener el locationId.

Ejemplo de backend (Node.js/Express):

// Example using crypto-js for AES decryption

const CryptoJS = require(‘crypto-js’)

function decryptGhlUserData(encryptedData, sharedSecret) {

  try {

    const bytes = CryptoJS.AES.decrypt(encryptedData, sharedSecret)

    const decryptedData = bytes.toString(CryptoJS.enc.Utf8)

    return JSON.parse(decryptedData)

  } catch (error) {

    console.error(‘Decryption failed:’, error)

    throw new Error(‘Failed to decrypt or parse user data’)

  }

}

// Example Express middleware/route handler

app.post(‘/your-context-endpoint’, (req, res) => {

  try {

    // Assuming encrypted data is passed in the request body

    const { encryptedContextData } = req.body

    const sharedSecret = process.env.GHL_APP_SHARED_SECRET // Load your shared secret securely

    if (!encryptedContextData || !sharedSecret) {

      return res.status(400).json({ error: ‘Missing data or configuration’ })

    }

    const userData = decryptGhlUserData(encryptedContextData, sharedSecret)

    console.log(‘Decrypted User Context:’, userData)

    // Now you have access to userData.locationId, userData.userId, etc.

    // Proceed with your logic…

    res.json({ success: true, locationId: userData.locationId })

  } catch (error) {

    res.status(500).json({ error: error.message || ‘Internal Server Error’ })

  }

})

JavaScript

Ejemplo de frontend (página personalizada en JavaScript):

// Function to request and potentially decrypt user context data

async function getUserContext() {

  return new Promise((resolve, reject) => {

    const timeout = setTimeout(() => {

      reject(new Error(‘Timeout waiting for user context response’))

      window.removeEventListener(‘message’, messageHandler)

    }, 5000) // 5-second timeout

    const messageHandler = (event) => {

      // Optional: Add origin check for security

      // if (event.origin !== ‘expected_Centryka_origin’) return;

      if (event.data && event.data.message === ‘REQUEST_USER_DATA_RESPONSE’) {

        clearTimeout(timeout)

        window.removeEventListener(‘message’, messageHandler)

        console.log(‘Received encrypted context from Centryka:’, event.data.payload)

        // Send event.data.payload to your backend for decryption

        // fetch(‘/your-context-endpoint’, { method: ‘POST’, … body: { encryptedContextData: event.data.payload }})

        //   .then(response => response.json())

        //   .then(decryptedData => resolve(decryptedData))

        //   .catch(error => reject(error));

        // For demonstration, assuming payload is the decrypted context (or you handle decryption client-side IF safe)

        resolve(event.data.payload)

      }

    }

    window.addEventListener(‘message’, messageHandler)

    // Request the data from the parent Centryka window

    window.parent.postMessage({ message: ‘REQUEST_USER_DATA’ }, ‘*’) // Use a specific target origin in production

  })

}

// Example usage:

getUserContext()

  .then((context) => {

    console.log(‘User Context:’, context)

    // Use context.locationId, context.userId etc.

  })

  .catch((error) => {

    console.error(‘Failed to get user context:’, error)

  })

JavaScript

Manejo de credenciales del operador

1. Recibir credenciales: obtenga la clave API del operador, el secreto, etc., del usuario a través de su interfaz de usuario.
2. Asociar con la ubicación: almacene estas credenciales de forma segura en su base de datos, vinculándolas con las locationIdobtenidas del contexto del usuario.
3. Validar credenciales: Realice una llamada de prueba a la API del operador con las credenciales proporcionadas para garantizar su validez. Envíe comentarios al usuario.

Ejemplo de interfaz (guardar credenciales):

async function saveCarrierCredentials(locationId, apiKey, apiSecret) {

  try {

    const response = await fetch(‘/your-backend-api/carrier/credentials’, {

      // Your backend endpoint

      method: ‘POST’,

      headers: {

        ‘Content-Type’: ‘application/json’

        // Include authentication if needed (e.g., JWT)

      },

      body: JSON.stringify({

        locationId: locationId, // Send context if needed by backend

        apiKey: apiKey,

        apiSecret: apiSecret

      })

    })

    if (!response.ok) {

      const errorData = await response.json()

      throw new Error(errorData.message || `HTTP error! status: ${response.status}`)

    }

    const result = await response.json()

    console.log(‘Credentials saved successfully:’, result)

    // Update UI (e.g., show success message)

    return result

  } catch (error) {

    console.error(‘Failed to save carrier credentials:’, error)

    // Update UI (e.g., show error message)

    throw error

  }

}

// Example form submission handler

document.getElementById(‘credential-form’).addEventListener(‘submit’, async (event) => {

  event.preventDefault()

  const apiKey = document.getElementById(‘api-key’).value

  const apiSecret = document.getElementById(‘api-secret’).value

  const locationId = ‘USER_LOCATION_ID’ // Get this from user context

  try {

    await saveCarrierCredentials(locationId, apiKey, apiSecret)

    alert(‘Credentials Saved!’)

  } catch (error) {

    alert(`Error saving credentials: ${error.message}`)

  }

})

JavaScript

4. Configurar webhooks del transportista: Use las credenciales validadas del transportista para realizar llamadas API al sistema del transportista y registrar la URL de escucha del webhook del transportista en suhttps://your-backend.com/webhooks/carrier backend (p. ej., ). Esto permite que el transportista notifique a su servicio sobre actualizaciones de envío (como la generación de un número de seguimiento).

3. Implementación de tarifas de envío en vivo

Para permitir que el proceso de pago de Centryka muestre las tarifas de envío en tiempo real de su transportista personalizado, debe registrar su servicio como transportista de envío dentro de Centryka.

Registrar transportista en Centryka

• Tu servicio backend debe realizar una solicitud POST al punto final de la API Centryka, responsable de crear los transportistas. Este punto final suele estar asociado al microservicio Tienda/Pagos. El punto final es POST /shipping-carrier.
• El cuerpo de la solicitud debe incluir el contexto de ubicación ( altId, altType) y detalles sobre la integración con su operador.

Ejemplo de solicitud:

POST /shipping-carrier HTTP/1.1

Host: <Centryka-api-domain>

Authorization: Bearer <location_access_token>

Content-Type: application/json

{

  “altId”: “LOCATION_ID_HERE”, // The location ID obtained from user context

  “altType”: “location”,

  “name”: “Your Custom Carrier Name”, // e.g., “My Awesome Shipping”

  “callbackUrl”: “https://your-backend.com/rates” // Your backend endpoint for live rates

}

JavaScript

• name:El nombre que se muestra al usuario en la configuración de envío de Centryka.
• callbackUrlLa URL base donde Centryka enviará solicitudes POST para obtener tarifas en tiempo real durante el proceso de pago. Centryka añadirá un valor /ratesa esta URL. Por lo tanto, si proporciona [nombre de la URL] https://your-backend.com/shipping, Centryka llamará [nombre de la URL https://your-backend.com/shipping/rates]. En el ejemplo anterior, la URL final llamada será [ nombre de la URL] https://your-backend.com/rates/rates, así que ajuste su valor callbackUrlsegún corresponda (por ejemplo, solo https://your-backend.comsi su punto final es [nombre de la URL /rates]). Corrección basada en la solicitud del usuario: La solicitud implica que la URL completa , incluyendo [nombre de la /ratesURL], debe proporcionarse en [ nombre de la URL callbackUrl]. Supongamos que la solicitud es correcta: Establézcala en [nombre callbackUrlde la URL https://your-backend.com/rates].
• Respuesta: Una respuesta exitosa contendrá los detalles del operador creado, incluyendo un número único _id(llamémoslo shippingCarrierId). Guárdelo shippingCarrierIden su base de datos, asociado con la ubicación y las credenciales del operador.

{

  “data”: {

    “_id”: “SHIPPING_CARRIER_ID_HERE”, // Store this ID

    “altId”: “LOCATION_ID_HERE”,

    “altType”: “location”,

    “name”: “Your Custom Carrier Name”,

    “callbackUrl”: “https://your-backend.com/rates”,

    “marketplaceAppId”: “YOUR_MARKETPLACE_APP_ID”,

    “createdAt”: “…”,

    “updatedAt”: “…”

  },

  “status”: true

}

JavaScript

Implementar devolución de llamada de tarifas en vivo

• Su backend debe implementar el punto final especificado en callbackUrl(por ejemplo, POST /rates).
• Centryka enviará una POSTsolicitud a este punto final durante el pago con detalles del contenido del carrito y la dirección de destino.

Ejemplo de cuerpo de solicitud recibido por su backend ( POST /rates):

{

  “rate”: {

    “altId”: “LOCATION_ID_HERE”,

    “altType”: “location”,

    “origin”: {

      “name”: “Store Owner Name”,

      “companyName”: “Store Name”,

      “address1”: “123 Origin St”,

      “address2”: “Suite 100”,

      “city”: “Origin City”,

      “state”: “CA”,

      “zip”: “90210”,

      “country”: “US”,

      “phone”: “5551112222”,

      “email”: “store@example.com”

    },

    “destination”: {

      “name”: “Customer Name”,

      “companyName”: null,

      “address1”: “456 Destination Ave”,

      “address2”: null,

      “city”: “Destination City”,

      “state”: “NY”,

      “zip”: “10001”,

      “country”: “US”,

      “phone”: “5553334444”,

      “email”: “customer@example.com”

    },

    “items”: [

      {

        “name”: “Product A”,

        “sku”: “SKU123”,

        “quantity”: 2,

        “grams”: 500, // Weight per item

        “unitPrice”: 25.0,

        “totalPrice”: 50.0, // quantity * unitPrice

        “productId”: “HL_PRODUCT_ID_1”,

        “priceId”: “HL_PRICE_ID_1”

      },

      {

        “name”: “Product B”,

        “sku”: “SKU456”,

        “quantity”: 1,

        “grams”: 1200,

        “unitPrice”: 100.0,

        “totalPrice”: 100.0,

        “productId”: “HL_PRODUCT_ID_2”,

        “priceId”: “HL_PRICE_ID_2”

      }

    ],

    “currency”: “USD”

  }

}

JavaScript

• Su lógica de backend:

• Analizar el cuerpo de la solicitud.
• Recupere las credenciales del operador asociadas con altId(locationId) de su base de datos.
• Transforme la carga útil de la solicitud de tarifa Centryka al formato requerido por la API de su operador personalizado.
• Llame a la API del transportista para obtener tarifas de envío en vivo.
• Transformar la respuesta del operador en el formato esperado por Centryka.

• Ejemplo de respuesta enviada por su backend:

{

  “rates”: [

    {

      “serviceName”: “Standard Ground”, // Name of the shipping service

      “amount”: 15.5, // Cost of the service

      “currency”: “USD”, // Currency code

      “estimatedDays”: 5 // Estimated delivery days (optional)

    },

    {

      “serviceName”: “Express Overnight”,

      “amount”: 45.0,

      “currency”: “USD”,

      “estimatedDays”: 1

    }

  ]

}

JavaScript

Configurar tarifas de envío en zonas de alto nivel

• Después de registrar exitosamente el transportista de envío, su integración (o el usuario manualmente) debe agregar tarifas de envío basadas en este transportista a las Zonas de envío relevantes dentro de la configuración de la Tienda Centryka.
• Automatización de backend:

• Utilice la API Centryka para listar las zonas de envío existentes para la ubicación. El punto final es GET /shipping-zone.

Ejemplo de solicitud ( GET /shipping-zone):

GET /shipping-zone?altId=LOCATION_ID_HERE&altType=location HTTP/1.1

Host: <Centryka-api-domain>

Authorization: Bearer <location_access_token>

JavaScript

• Para cada zona relevante devuelta por la llamada anterior, utilice la API Centryka para crear una nueva tarifa de envío ( POST /shipping-zones/{zoneId}/ratespunto final inferido).

• En el cuerpo de la solicitud para crear la tarifa:

• Establecer isCarrierRateen true.
• Proporcionar lo shippingCarrierIdobtenido durante el registro del transportista.
• Establezca un marcador de posición amount(por ejemplo, 0) ya que la tasa real se obtendrá en vivo a través de la devolución de llamada.
• Establecer name(por ejemplo, “Mi increíble envío: tarifas en vivo”).
• Especificar altId, altType.

Ejemplo de cuerpo de solicitud ( POST /shipping-zones/{zoneId}/rates):

{

  “altId”: “LOCATION_ID_HERE”,

  “altType”: “location”,

  “name”: “My Awesome Shipping – Live Rates”, // Name shown to user

  “currency”: “USD”, // Or the location’s currency

  “amount”: 0, // Placeholder, actual rate fetched live

  “conditionType”: “NONE”, // Or based on weight/price if needed, though usually NONE for carrier rates

  “isCarrierRate”: true,

  “shippingCarrierId”: “SHIPPING_CARRIER_ID_HERE” // The ID received when registering the carrier

}

JavaScript

4. Sincronización y cumplimiento de pedidos

Esta sección describe cómo sincronizar pedidos con su transportista y automatizar las actualizaciones de cumplimiento en Centryka.

Habilitar webhooks de pedidos

• Asegúrate de que los webhooks OrderCreatey OrderStatusUpdateestén habilitados en la configuración de tu aplicación Centryka Marketplace. Dirígelos al punto de escucha del webhook de Centryka de tu backend.

Gestión del webhook de creación de pedidos

1. Recibir webhook: su backend recibe una solicitud POST de Centryka cuando se crea un pedido o cambia su estado (específicamente buscando pedidos recientemente completados que sean relevantes para el envío).
2. Validar: verificar la firma/autenticidad del webhook si corresponde.
3. Proceso:

3. Verifique si el estado del pedido es apropiado para el envío (por ejemplo, Completed, Paid).
4. Verificar si el pedido requiere envío (contiene productos físicos).
5. Recupere los detalles completos del pedido utilizando la API Centryka ( GET /orders/{orderId}).
6. Recupere las credenciales del operador asociado de su base de datos utilizando el locationId.

4. Ejemplo de backend (Node.js/Express):
5. // Example Express endpoint for Centryka webhooks
6. app.post(‘/webhooks/Centryka’, async (req, res) => {
7.   try {
8.     // 1. TODO: Validate webhook signature (important for security)
9.     // const signature = req.headers[‘webhook-signature’]; // Example header
10.     // const isValid = validateSignature(req.rawBody, signature, GHL_WEBHOOK_SECRET);
11.     // if (!isValid) return res.status(401).send(‘Invalid signature’);
12.  
13.     const { type, locationId, orderId, status } = req.body // Adjust based on actual webhook payload structure
14.  
15.     console.log(`Received webhook: Type=${type}, LocationId=${locationId}, OrderId=${orderId}, Status=${status}`)
16.  
17.     // 2. Process only relevant events (e.g., completed orders)
18.     if ((type === ‘OrderCreate’ || type === ‘OrderStatusUpdate’) && orderId && status === ‘completed’) {
19.       console.log(`Processing order ${orderId} for location ${locationId}`)
20.       await processOrderForShipping(locationId, orderId)
21.     } else {
22.       console.log(`Skipping webhook type: ${type} or status: ${status}`)
23.     }
24.  
25.     res.status(200).send(‘Webhook received successfully’)
26.   } catch (error) {
27.     console.error(‘Error processing Centryka webhook:’, error)
28.     // Respond with 5xx error but don’t reveal internal details
29.     res.status(500).send(‘Internal Server Error’)
30.   }
31. })
32.  
33. async function processOrderForShipping(locationId, orderId) {
34.   try {
35.     // 3. Retrieve full order details from Centryka API
36.     // const orderDetails = await CentrykaApiClient.getOrder(locationId, orderId);
37.     // Example: const orderDetails = { requiresShipping: true, items: […] }; // Mock
38.  
39.     // Check if order actually needs shipping
40.     // if (!orderDetails || !orderDetails.requiresShipping) {
41.     //   console.log(`Order ${orderId} does not require shipping.`);
42.     //   return;
43.     // }
44.  
45.     // 4. Retrieve carrier credentials for the location from your DB
46.     // const credentials = await database.getCarrierCredentials(locationId);
47.     // if (!credentials) throw new Error(`Credentials not found for location ${locationId}`);
48.  
49.     // 5. Transform Centryka order data to carrier’s API format
50.     // const carrierPayload = transformOrderForCarrier(orderDetails);
51.  
52.     // 6. Call carrier API to create shipment/order
53.     // const carrierResponse = await carrierApiClient.createShipment(credentials, carrierPayload);
54.     // const carrierOrderId = carrierResponse.id;
55.  
56.     // 7. Store mapping in your DB
57.     // await database.storeOrderMapping(locationId, orderId, carrierOrderId);
58.  
59.     console.log(`Successfully created shipment with carrier for order ${orderId}. Carrier ID: ${carrierOrderId}`)
60.   } catch (error) {
61.     console.error(`Failed to process order ${orderId} for shipping:`, error)
62.     // TODO: Implement retry logic or error notification system
63.   }

}

JavaScript

64. Crear pedido con transportista:

64. Transforme los datos del pedido de Centryka al formato requerido por el punto final de API “crear pedido” o “crear envío” de su transportista.
65. Llamar a la API del transportista para crear el pedido/envío.
66. Almacene la asignación entre Centryka orderIdy el ID del pedido/envío del transportista en su base de datos.

Actualizaciones de envío de transportistas de manipulación

1. Recibir webhook: el receptor del webhook del transportista de su backend recibe una notificación del transportista cuando cambia el estado de un envío (por ejemplo, etiqueta impresa, número de seguimiento generado, enviado, entregado).
2. Validar: verificar la autenticidad del webhook basándose en el mecanismo del operador (por ejemplo, firma).
3. Proceso:

3. Analice los datos del webhook para extraer el ID del pedido/envío del transportista y la nueva información de envío (número de seguimiento, URL de seguimiento, estado).
4. Utilice el ID del operador para buscar el Centryka correspondiente orderIdy locationIddesde su mapeo de base de datos.

4. Ejemplo de backend (Node.js/Express):
5. // Example Express endpoint for Carrier webhooks
6. app.post(‘/webhooks/carrier’, async (req, res) => {
7.   try {
8.     // 1. TODO: Validate webhook authenticity (specific to the carrier)
9.     // const isValid = validateCarrierSignature(req);
10.     // if (!isValid) return res.status(401).send(‘Invalid signature’);
11.  
12.     const carrierWebhookData = req.body
13.     console.log(‘Received carrier webhook:’, JSON.stringify(carrierWebhookData))
14.  
15.     // 2. Parse carrier data (adjust keys based on actual payload)
16.     const carrierOrderId = carrierWebhookData.orderReference // Or shipmentId, etc.
17.     const trackingNumber = carrierWebhookData.tracking?.number
18.     const trackingUrl = carrierWebhookData.tracking?.url
19.     const shippingStatus = carrierWebhookData.status // e.g., ‘SHIPPED’, ‘LABEL_CREATED’
20.  
21.     // 3. Check if we have necessary data (especially tracking number for fulfillment)
22.     if (!carrierOrderId || !trackingNumber) {
23.       console.log(‘Carrier webhook missing order reference or tracking number. Skipping.’)
24.       return res.status(200).send(‘Webhook received, but no action needed yet.’)
25.     }
26.  
27.     // 4. Find corresponding Centryka order info from DB mapping
28.     // const mapping = await database.findMappingByCarrierId(carrierOrderId);
29.     // if (!mapping) {
30.     //   console.warn(`Received carrier update for unknown order reference: ${carrierOrderId}`);
31.     //   return res.status(404).send(‘Mapping not found’); // Or 200 to prevent carrier retries
32.     // }
33.     // const { CentrykaOrderId, locationId } = mapping;
34.     // Mock:
35.     const CentrykaOrderId = ‘HL_ORDER_ID_123’
36.     const locationId = ‘LOCATION_ID_XYZ’
37.  
38.     // 5. Create fulfillment in Centryka if applicable (e.g., status is SHIPPED)
39.     if (shippingStatus === ‘SHIPPED’ || shippingStatus === ‘LABEL_CREATED’) {
40.       // Adjust condition as needed
41.       console.log(`Triggering fulfillment for Centryka Order ${CentrykaOrderId}`)
42.       await createCentrykaFulfillment(locationId, CentrykaOrderId, trackingNumber, trackingUrl)
43.     } else {
44.       console.log(`Carrier status ${shippingStatus} doesn’t require fulfillment action yet.`)
45.     }
46.  
47.     res.status(200).send(‘Carrier webhook processed successfully’)
48.   } catch (error) {
49.     console.error(‘Error processing carrier webhook:’, error)
50.     res.status(500).send(‘Internal Server Error’)
51.   }
52. })
53.  
54. async function createCentrykaFulfillment(locationId, orderId, trackingNumber, trackingUrl) {
55.   try {
56.     // Fetch order details to get line items and price IDs if needed
57.     // const orderDetails = await CentrykaApiClient.getOrder(locationId, orderId);
58.     // const itemsToFulfill = orderDetails.items.map(item => ({ priceId: item.price._id, qty: item.quantity })); // Adjust as needed
59.  
60.     const fulfillmentPayload = {
61.       altId: locationId,
62.       altType: ‘location’,
63.       items: [
64.         /* Populate with items being fulfilled, e.g., itemsToFulfill */
65.       ],
66.       trackings: [
67.         {
68.           trackingNumber: trackingNumber,
69.           shippingCarrier: ‘Your Custom Carrier Name’, // Use the name registered earlier
70.           trackingUrl: trackingUrl || undefined // Include URL if available
71.         }
72.       ],
73.       notifyCustomer: true // Or based on user preference/setting
74.     }
75.  
76.     console.log(‘Creating Centryka fulfillment with payload:’, JSON.stringify(fulfillmentPayload))
77.     // await CentrykaApiClient.createFulfillment(locationId, orderId, fulfillmentPayload);
78.     console.log(`Successfully created fulfillment for order ${orderId}`)
79.   } catch (error) {
80.     console.error(`Failed to create fulfillment for order ${orderId}:`, error)
81.     // TODO: Implement retry logic or error notification
82.   }

}

JavaScript

83. Crear cumplimiento en Centryka:  si ahora hay un número de seguimiento disponible, active el proceso de cumplimiento en Centryka.

83. Utilice la API de Centryka para crear un registro de cumplimiento de pedidos. Consulte la documentación oficial: Crear API de Cumplimiento de Pedidos.
84. Por lo general, esto implica realizar una POSTsolicitud a un punto final como /orders/{orderId}/fulfillments, como se muestra en el createCentrykaFulfillmentejemplo de función anterior.

5. Desconexión y desinstalación

Cuando un usuario se desconecta o desinstala su aplicación Marketplace de su ubicación, deberá limpiar la configuración de integración dentro de Centryka.

Eliminar el transportista de envío

• Su backend debe escuchar el webhook de aplicación desinstalada de Centryka (configúrelo en la configuración de su aplicación Marketplace).
• Cuando se recibe este webhook para un propósito específico locationId:

• Busque lo shippingCarrierIdasociado con esto locationIden su base de datos.
• Si se encuentra, solicite DELETEa la API Centryka que elimine el registro del transportista. El punto final es DELETE /shipping-carrier/{shippingCarrierId}.

Ejemplo de solicitud:

DELETE /shipping-carrier/SHIPPING_CARRIER_ID_HERE?altId=LOCATION_ID_HERE&altType=location HTTP/1.1

Host: <Centryka-api-domain>

Authorization: Bearer <location_access_token> // Need a valid token, potentially stored or obtained via app credentials

JavaScript

• Esto elimina al transportista de la configuración de envío de la ubicación, lo que evita errores si la URL de devolución de llamada deja de ser válida.
• Además, realice una limpieza de su lado: elimine las credenciales almacenadas, los registros de webhook con el operador, etc.

Conclusión

Crear una integración personalizada de transportistas para Centryka puede mejorar significativamente las capacidades de comercio electrónico de la plataforma, ofreciendo mayor flexibilidad y automatización en sus procesos de envío. Esta guía describe los pasos esenciales, desde la configuración de la aplicación Marketplace y la gestión de la autenticación hasta la implementación de tarifas en tiempo real, la sincronización de pedidos y el cumplimiento.

Los componentes principales incluyen:

1. Autenticación segura: gestión de tokens OAuth para credenciales de API y Centryka para el operador.
2. Integración de API: interacción con las API de Centryka y del transportista para registro, tarifas, pedidos y cumplimiento.
3. Manejo de webhooks: procesamiento confiable de eventos asincrónicos desde ambas plataformas.
4. Gestión de datos: almacenamiento de credenciales y mapeo de identificaciones entre sistemas.
5. Interfaz de usuario: proporciona una forma clara para que los usuarios configuren la integración.

Al crear su integración, recuerde priorizar la gestión robusta de errores, las mejores prácticas de seguridad (especialmente en lo que respecta a las credenciales) y un registro claro para facilitar la depuración. Considere la escalabilidad de su servicio backend y su base de datos a medida que aumenta el uso. Manténgase al tanto de los cambios en la API de Centryka y de su transportista objetivo para garantizar la compatibilidad a largo plazo.

Si sigue estos principios y adapta los ejemplos proporcionados, podrá crear una integración de transportista de envío valiosa y confiable para el mercado de Centryka.