Desarrollos propios

Introducción a desarrollos propios

Si tu tienda es un desarrollo propio, es decir, no usa un CMS tradicional como Prestashop o Magento, sino que ha sido programada específicamente para tu negocio, también puedes integrarte con Lighthouse Feed. En este caso, al dar de alta tu tienda o en la configuración de la misma (Desde el botón Usuario, sección Configuración, Configuración de CMS) podrás indicar que estás usando un desarrollo a medida.

Desde principios de 2023, el API de desarrollos propios también está abierto para CMS tradicionales. Estos pueden conectar automáticamente con Lighthouse Feed, pero si lo desean también pueden hacer operaciones avanzadas mediante nuestro API.

Cuando seleccionas la opción “Desarrollo propio, otros CMS” verás que aparece un panel que te redirige a esta guía, y un botón Ver Credenciales. Estas son las credenciales que deberás comunicar a tu equipo de desarrollo para que integren tu tienda con Lighthouse Feed.

A continuación, damos una explicación técnica orientada a los desarrolladores de tu tienda, que les ayudará durante el desarrollo. En general, los desarrolladores deberán realizar dos integraciones con el sistema.
Una de ellas consistirá en integrar el script de medición en las páginas de tu tienda, de tal manera que se registre y se envíe a Lighthouse Feed cuándo un cliente visualiza un producto y/o se realiza una venta, lo cual permitirá que la analítica de Lighthouse Feed te proporcione datos estadísticos sobre el funcionamiento de tu negocio.
La otra consistirá en sincronizar tu catálogo de productos, stocks y precios con Lighthouse Feed, de tal manera que Lighthouse sea capaz de publicar los datos correctos a los marketplaces y comparadores, y en conseguir que tu página web reciba los pedidos que recibimos en Lighthouse Feed por parte de los marketplaces.

Nota: Las funcionalidades que se describen a continuación son adicionales a la obtención de tu Feed. Es decir, la mayoría de datos de tu catálogo serán obtenidos mediante un Feed según la especificación aceptada por Google Merchant que deberás generar desde tu tienda, y que nosotros recogeremos periódicamente. Este comportamiento es análogo al de las tiendas que no poseen desarrollos a medida (Basadas en CMS como Prestashop, Magento y similares).

Script de medición

Para que la analítica de los clicks y ventas que ocurren en vuestra tienda se registre en Lighthouse Feed, deberás incluir nuestro script de medición en vuestra página. Dicho script está disponible en Lighthouse Feed, en la sección Usuario -> Configuración -> Pixel. Simplemente con copiar dicho script en la página de cada producto, ya se recogerían los clicks sobre ese producto. Para garantizar la seguridad de dicha operación, el script únicamente funciona en el sitio web en que indicaste que está tu tienda al darla de alta (Puedes editarla en Usuario -> Configuración -> Datos de tienda, en el campo ‘Sitio Web’).

Los clicks se recogen automáticamente poniendo ese script en la página del producto, que, como se ve en la captura, llama a una función lthfeed.init().

Éste contenido estaba disponible en una versión anterior de Lighthouse Feed, pero actualmente ya no es válido.
En versiones actuales de Lighthouse Feed, para enviar las ventas de tu tienda a Lighthouse Feed, usa nuestro API RESTful (Recurso /api/CustomDevs/CmsSales)

Para recoger las ventas, al ser un desarrollo propio, deberás customizar ese script. Para ello, cuando cargues ese mismo script en vuestra página de finalización de venta, en lugar de llamar a la función lthfeed.init(), como hace en el script de ejemplo, deberéis llamar a la función lthfeed.initTrackOrder() (Según como esté diseñada vuestra página, es posible que desees hacer esto nada más cargar la página de fin de pedido, o posteriormente, si por ejemplo el pedido se finaliza con una llamada AJAX al servidor).

Esta función initTrackOrder es la que envía la venta a la analítica de Lighthouse Feed.
Sus parámetros son:

//orderId - identificador único que la tienda use para identificar cada venta (Cadena de caracteres o número)
//orderTotal - importe total de la venta, contando los gastos de envío (número)
//deliveryExpenses - gastos de envío de la venta (número)
//products - un array de objetos con las siguientes propiedades:
//// gID: gID del producto, identificador único que la tienda usa para el producto y con el que se representa en el feed de google merchant. (Cadena de caracteres)
//// Quantity: Nº de unidades compradas en la venta (Número)
//// Price: Precio de cada unidad (Número)
lthfeed.initTrackOrder(orderId, orderTotal, deliveryExpenses, products);

Ejemplo de llamada a initTrackOrder

lthfeed.initTrackOrder(280385, 46.15, 5.20, [
{gID: "PR123", Quantity: 2, Price: 10.50 },
{gID: "ES987", Quantity: 1, Price: 19.95 }
]);

Sincronización

Además de integrar vuestra página con el script de medición, será necesario que vuestro servicio envíe a Lighthouse Feed el catálogo de productos, stocks y precios de la tienda periódicamente. De manera similar, vuestra aplicación debe recoger de forma periódica los pedidos que llegan desde los marketplaces y quedan registrados en Lighthouse Feed. Finalmente y para poder visualizar los pedidos que los clientes realizan directamente en vuestra página, así como contabilizarlos en la analítica de Lighthouse Feed, es preciso que nos enviéis los datos de vuestros pedidos en tienda cuando se produzcan. Para estas operaciones es necesario usar el API RESTful que suministramos.

API para desarrolladores

Lighthouse Feed expone un API RESTful, con mensajes y respuestas en formato JSON, y que además conforma a la especificación OpenAPI v3. Esto significa que una aplicación de terceros, como tu tienda, puede conectar con Lighthouse Feed mediante este servicio para obtener datos de los pedidos, enviar a Lighthouse Feed el stock y precios actuales de tu tienda, y otras características necesarias para integrar una aplicación.

Autenticación

Para poder lanzar consultas al API de Lighthouse Feed, deberás identificarte. Nuestro API RESTful autoriza y autentica a los usuarios mediante los estándares OAuth2 y OpenID. En concreto y actualmente, para clientes de terceros soportamos el flujo Client Credentials. En este flujo, una aplicación cliente (En este caso, tu sitio web) se autentica de servidor a servidor, mediante un identificador de cliente y un valor secreto (Suministrado por Lighthouse Feed desde la configuración de la tienda, como vimos en la introducción a este tema).

Para lanzar una solicitud de autenticación, deberás lanzar una petición POST contra https://app.lighthousefeed.com/connect/token, como se ve en los siguientes ejemplos (Sustituye tu-id-de-cliente y tu-secreto-de-cliente por los valores obtenidos de Lighthouse Feed):

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.lighthousefeed.com/connect/token',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => 'grant_type=client_credentials&client_secret=tu-secreto-de-cliente&client_id=tu-id-de-cliente',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var client = new RestClient("https://app.lighthousefeed.com/connect/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("grant_type", "client_credentials");
request.AddParameter("client_secret", "tu-secreto-de-cliente");
request.AddParameter("client_id", "tu-id-de-cliente");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

curl --location --request POST 'https://app.lighthousefeed.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret=tu-secreto-de-cliente' \
--data-urlencode 'client_id=tu-id-de-cliente'

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=client_credentials&client_secret=tu-secreto-de-cliente&client_id=tu-id-de-cliente");
Request request = new Request.Builder()
  .url("https://app.lighthousefeed.com/connect/token")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();
Response response = client.newCall(request).execute();

import http.client

conn = http.client.HTTPSConnection("app.lighthousefeed.com")
payload = 'grant_type=client_credentials&client_secret=tu-secreto-de-cliente&client_id=tu-id-de-cliente'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/connect/token", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var https = require('follow-redirects').https;
var fs = require('fs');

var qs = require('querystring');

var options = {
  'method': 'POST',
  'hostname': 'app.lighthousefeed.com',
  'path': '/connect/token',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = qs.stringify({
  'grant_type': 'client_credentials',
  'client_secret': 'tu-secreto-de-cliente',
  'client_id': 'tu-id-de-cliente'
});

req.write(postData);

req.end();

Ejempo de respuesta:

Código de respuesta: 200 - OK.
Content-Type: application/json;charset=UTF-8
{
    "access_token": "cadena-de-mas-de-1000-caracteres",
    "token_type": "Bearer",
    "expires_in": 3599
}

Donde access_token es el token que usaremos en las peticiones del API. Dicho token tiene un tiempo de vida especificado en expires_in, generalmente de ~3600 segundos (60 minutos). Pasado este tiempo caducará, y las peticiones que usen este token como autenticación devolverán un código de respuesta 401 – Unauthorized. El sistema del cliente debe estar preparado para solicitar un nuevo token cuando esto ocurra.

Cuando tengamos ese access_token y mientras no esté caducado, podemos usarlo para lanzar peticiones contra el API de lighthousefeed añadiendo a nuestras peticiones una cabecera HTTP:

Authorization con valor Bearer <access_token>

Referencia del API

Pulsando aquí puedes consultar la referencia completa de todos los métodos ofrecidos por el API. Desde esa página y pulsando el botón Authorize puedes incluso solicitar tokens de autenticación y probar las funcionalidades del API.

Versionado

Como se ve en la referencia del API, podrán lanzarse versiones futuras del API de Lighthouse Feed que no sean compatibles con la especificación actual. Se recomienda enviar en todas las peticiones el parámetro api-version en el queryString de la solicitud. Por defecto y si no se envía dicho parámetro se llamará a la versión más antigua soportada (Actualmente 1.0).
Ejemplo:
https://app.lighthousefeed.com/api/CustomDevs/Recurso?api-version=1.0

El número menor de la versión (Por ejemplo 1.0, 1.1, 1.2) indica versiones superiores que añaden mejoras, pero no son incompatibles con una versión anterior del cliente.

Eventos (Webhooks)

Ir al árticulo principal – Webhooks

Normalmente, la comunicación entre Lighthouse Feed y tu desarrollo a medida ocurrirá en el sentido de tu aplicación hacia Lighthouse Feed. Para este tipo de comunicaciones, puedes emplear las opciones descritas arriba, como nuestro API RESTful y nuestro script de medición. Sin embargo, hay situaciones en las que puedes desear que sea Lighthouse Feed quien avise a tu sistema cuando ocurra algo, o el usuario realice alguna acción dentro de Lighthouse Feed. Para esto, te ofrecemos suscribirte a nuestro sistema de eventos (Webhooks). Enviaremos una petición http POST a la URL que nos indiques cuando ocurran eventos en Lighthouse Feed, y tú podrás leerlos y actuar en consecuencia.

Opcional – Cliente OpenAPI

Puedes usar el API que te ofrecemos directamente mediante un cliente http para el lenguaje de programación que utilices, pero si lo prefieres, puedes generar un cliente OpenAPI nativo en el lenguaje que desees. El fichero JSON de especificación de cliente es:

https://app.lighthousefeed.com/api/help/versions/1.0/document.json

Consulta la página del generador de OpenAPI para más información.

Una vez generes el cliente, puedes usarlo de la siguiente forma (Ejemplo en C#):

        await new CustomDevsApi(new Configuration { AccessToken = "obtenido-de-una-peticion-rest" }).ApiCustomDevsSalesGetAsync();

Nota: Por lo general, los clientes autogenerados por OpenAPI no gestionan la autenticación (Obtención del access token). Dicha autenticación se puede realizar con un cliente http corriente en tu lenguaje de programación, como se ve en los ejemplos de la sección Autenticación.

Entorno de pruebas

El entorno de pruebas de Lighthouse Feed se encuentra en:

https://lighthousefeeddev.azurewebsites.net

Contáctanos en info@lighthousefeed.com para solicitar una cuenta en el entorno de pruebas. A partir de ahí, podrás entrar a dicho entorno con tu tienda (Al principio tu tienda no tendrá datos), donde puedes realizar cualquier solicitud que realizarías al API sustituyendo app.lighthousefeed.com por la URL de pruebas, y cambiando tu identificador y secreto de cliente por los que generes en el entorno de pruebas. Por ejemplo, para obtener un token en el entorno de pruebas (cURL):

curl --location --request POST 'https://lighthousefeeddev.azurewebsites.net/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret=tu-secreto-de-cliente-dev' \
--data-urlencode 'client_id=tu-id-de-cliente-dev'

Puedes usar cualquier funcionalidad disponible en producción en éste entorno, incluyendo el uso normal de la aplicación web de Lighthouse Feed, llamadas al API, etc.

Ejemplos

Para ver ejemplos de cada llamada ofrecida por el API ofrecemos una colección de llamadas compatibles con el cliente HTTP gratuito Postman.

Puedes importar esta colección mediante File -> Import… en Postman.
Para configurarla, pulsa sobre la colección, ve a la pestaña Variables y edita client_id y client_secret con los valores de tu tienda. Pulsa Guardar tras editar los valores:

Además de gestionar automáticamente la obtención de tokens de acceso para hacer pruebas, Postman ofrece código de ejemplo de cada llamada en el lenguaje que prefieras.