Cómo integrar a través de una plataforma API

Integración de la extensión BCome en tu E-commerce

BCome ha desarrollado un script personalizado para una integración fluida de las métricas de BCome en tu plataforma, permitiendo la automatización, optimizando la gestión de datos y aumentando la flexibilidad para una mayor eficiencia. Esta guía proporciona instrucciones paso a paso para la instalación y configuración manual de la extensión API.

¿Cómo empezar?

Paso 01 | Configuración

Antes de comenzar la integración, tu sitio web debe contar con una página de producto y SKUs únicos de e-commerce para cada producto.

Además, BCome necesita registrar los siguientes parámetros en nuestro sistema:

Dominio(s) web: Especifica los dominios que se están utilizando, incluyendo cualquier entorno de prueba.
Lista de SKUs: Proporciona la lista de SKUs de referencias activas disponibles en tu sitio web.

Paso 02 | Integración API y diseño de plantilla

Una vez proporcionada y validada la información anterior, nos pondremos en contacto contigo para comenzar la fase de integración y compartir todos los recursos necesarios.

Se recomienda probar la integración con un producto de muestra para facilitar el proceso de solución de problemas.
Proporcionamos ejemplos y casos de estudio de otras marcas que han implementado la integración.
Aunque el diseño de la plantilla es gestionado por tu marca, debes compartirlo con nosotros antes de publicarlo para garantizar su precisión y evitar posibles casos de Greenwashing.

📍 Nota: La API solo devuelve datos para los productos incluidos en el contrato vigente. Además, los datos de Consumo de Agua (litros) solo están disponibles si han sido contratados (no confundir con la métrica de Escasez de Agua).

Limitaciones

La API puede ser utilizada desde cualquier plataforma o framework, ya que devuelve datos en formato JSON, garantizando compatibilidad con la mayoría de los lenguajes de programación.

Autenticación

La autenticación se gestiona mediante una API Key, generada únicamente para cada usuario. Si la API Key se ve comprometida, puede restablecerse notificándolo al cliente para asegurar un acceso ininterrumpido. Para regenerar tu API Key, contacta al equipo de BCome y te asistirán de inmediato.

Respuesta de datos de la API

La API devuelve datos específicos según tu plan e integración, cubriendo métricas clave de sostenibilidad en diversas categorías. Entre ellas:

Gestión del Ciclo de Vida del Producto (PLM)
Evaluación del Ciclo de Vida (LCA)
Indicadores de Economía Circular (CEI)
Eco-Score
Ley AGEC
Otros

La siguiente imagen proporciona un ejemplo completo de la respuesta de la API:

📍 Nota: Si ciertos datos no aparecen, puede deberse a que no están habilitados en tu plan actual. Para acceder a funciones adicionales, asegúrate de que estén activadas o contacta con soporte.

Cómo implementar el script

La API hace que el proceso de integración sea muy flexible. Sigue estos pasos:

Paso 01 | Obtener tu API Key

Inicia sesión en tu cuenta, ve a la sección Digitalización → Integración y copia tu API Key única.

Paso 02 | Realizar la llamada a la API

Realiza una solicitud GET a la URL especificada proporcionada por BCome. Tendrás que pasar dos parámetros de consulta:

hostname: debe estar registrado y aprobado en tu cuenta como host permitido.
references: especifica los elementos para los que desea recuperar datos.

Además, incluye un encabezado de seguridad llamado securehash, que debes generar. A continuación, se proporcionan instrucciones para crear este hash.

Paso 03 | Autentificar la API

Autentica tu llamada API generando un hash, que concatena el nombre de host y los parámetros de referencia, usando tu clave API. Este hash garantiza una comunicación segura y evita la manipulación.

Para mantener la seguridad, evita exponer tu API Key y utiliza siempre HTTPS para la transmisión de datos cifrados.

Paso 04 | Probar la integración

Ejecuta pruebas para verificar que la API esté funcionando correctamente. Asegúrate de que se estén transfiriendo todos los datos y de que no haya errores.

Paso 05 | Entender los datos devueltos

La API devuelve datos específicos en función de tu plan e integración. Cada punto de datos se relaciona con métricas de sostenibilidad como trazabilidad, gestión del ciclo de vida del producto (PLM), evaluación del ciclo de vida (LCA), indicadores de economía circular (CEI) y más!

Seguridad y Request

Para mayor seguridad, genera un token usando el algoritmo sha512 y pásalo en el encabezado securehash. Sigue estos pasos para crear el token:

1. Crear el String to Encrypt
Concatenar el hostname, el símbolo + y el parámetro references en una sola cadena. Ejemplo: [nombre de host]+[referencias].

2. Cifrar la cadena con sha512
Cifra esta cadena usando el algoritmo sha512 y tu API Key como clave de cifrado. Aquí hay un ejemplo en JavaScript:

3. Ejemplo de PHP
A continuación hay un ejemplo de PHP para generar el hash, ya que PHP es uno de los lenguajes de programación más comunes:

Este proceso garantiza que tus solicitudes de API sean seguras y estén debidamente autenticadas. Si es necesario, se pueden proporcionar ejemplos en otros lenguajes de programación.

Cómo probar la integración de API sin escribir código

Si deseas probar la API con Postman u otro cliente sin programar, puedes generar el securehash usando esta web: HMAC Generator.

Paso 01 | Generar el Securehash

Para probar la API sin codificar, usa el generador HMAC aquí. Selecciona el algoritmo de hash (p. ej., SHA-512), ingresa hostname+references e ingresa la API Key como secreto. Esto generará el securehash.

Paso 02 | Configurar los parámetros de solicitud API

Especifica la URL de la API e incluye el hostname y las references como parámetros. Agregua el securehash como valor en el encabezado de la solicitud para autenticar.

Paso 03 | Obtener la respuesta de la API

La solicitud devuelve un objeto JSON con datos detallados según los parámetros proporcionados.

Además, aquí hay un ejemplo de llamada funcional usando CURL:

curl --location 'https://api.bcome.biz/api/externalApi/articles?hostname=www.demo.com&references=GAKNODRAT6270WW56' \
--header 'securehash: a5c5cd2791a73f75f04ae46b942198d4b738d3e7948b02aaf2070457b327c1c8dd6439318b4e81e1210a0fef2b953e74dcfae0761e09ec724ba89df0ef3634f9'

Códigos de estado y solución de problemas

Los códigos de estado indican la respuesta del servidor a una solicitud API. Aquí están los más comunes con sus significados:

200 OK – Solicitud exitosa.
400 Bad Request – Solicitud inválida o malformateada. Verifica sintaxis y parámetros.
403 Forbidden – La solicitud es válida, pero no tienes permisos de acceso.
404 Not Found – El recurso solicitado no existe o el endpoint es incorrecto.
500 Internal Server Error – Error del servidor, puede ser temporal o requerir solución.

Para problemas con la API, verifica la autenticación, el formato de la solicitud y los permisos de acceso.

Solución de problemas

Si estás experimentando problemas con la API, sigue los siguientes pasos para poder diagnosticar y resolverlos:

Error 400 | Bad Request

Asegúrate de que la solicitud sigue las especificaciones de la API.
Verifica que todos los parámetros requeridos estén incluidos y bien estructurados.
Revisa errores tipográficos o formatos incorrectos en la solicitud.

Error 403 | Forbidden

Si tu API está configurada pero sigues recibiendo un error 403, verifica lo siguiente:

Verifica que la API esté activada en tu contrato.
Asegúrate de que el securehash esté calculado correctamente.
- El hash seguro debe recalcularse para cada referencia utilizada.
- Debe usarse SHA-512 (no se permite otro algoritmo de hash).
Confirma que el nombre de host utilizado para el cálculo del hash coincide con el pasado como parámetro.
Asegúrate de que tanto el nombre de host como la referencia estén incluidos en los parámetros de la llamada a la API.

Error 404 | Not Found

Asegúrate de haber subido las referencias de Ecommerce (SKU) a la plataforma BCome.
Verifica que la referencia utilizada corresponda a las referencias de Ecommerce (SKU) y no a la referencia del artículo en sí.

Error 500 | Internal Server Error

Si ocurre un error 500, contacta al soporte con los siguientes detalles:

Clave de API utilizada.
Nombre de host introducido.
Referencias que generan el error.
Pasos para reproducir el problema.

Siguiendo estos pasos, podrás integrar la API de BCome en tu e-commerce de manera eficiente y segura.