How to integrate via API platform

Integrating BCome Extension in Your E-commerce

BCome has developed a custom script for seamless integration of BCome metrics into your platform, enabling automation, optimizing data management, and enhancing flexibility for greater efficiency. This guide provides step-by-step instructions for manually installing and configuring the API extension.

Limitations

The API can be consumed from any platform or framework since it returns data in JSON format, ensuring compatibility with most programming languages.

Authentication

Authentication is managed using an API Key, generated uniquely for each user. If the API Key is compromised, it can be reset after notifying the client to ensure uninterrupted access. To regenerate your API Key, simply contact the BCome team, and they will assist you promptly.

API Data Response

The API returns specific data based on your plan and integration, covering key sustainability metrics across various categories. Explore detailed insights on traceability, lifecycle analysis, compliance, and more!

Product Lifecycle Management (PLM)
Life Cycle Assessment (LCA)
Circular Economy Indicators (CEI)
Eco-Score
AGEC Law
Others

The following image provides a complete example of the API response:

📍 Note: If certain data points are missing, they may not be enabled in your current plan. To access additional features, ensure they are activated or contact support.

How to Implement the Script

The API makes the integration process highly flexible. Follow these steps:

Step 01 | Obtain Your API Key

Log into your account, navigate to the Digitization → Integration section, and copy your unique API Key.

Step 02 | Make the API Call

Make a GET request to the specified URL provided by BCome. You’ll need to pass two query parameters:

hostname: Must be registered and approved in your account as an allowed host.
references: Specify the items for which you want to retrieve data.

Additionally, include a security header called securehash, which you must generate. Instructions on creating this hash are provided below.

Step 03 | Authenticate the API

Authenticate your API call by generating a hash, which concatenates the hostname and references parameters, using your API Key. This hash ensures secure communication and prevents tampering.

To maintain security, avoid exposing your API Key and always use HTTPS for encrypted data transmission.

Step 04 | Test the Integration

Run tests to verify that the API is functioning properly. Ensure all data is being transferred and that no errors are present.

Step 05 | Understand the Returned Data

The API returns specific data based on your plan and integration. Each data point relates to sustainability metrics like traceability, Product Lifecycle Management (PLM), Life Cycle Assessment (LCA), Circular Economy Indicators (CEI), and more!

Security and Request

For added security, generate a token using the sha512 algorithm and pass it in the securehash header. Follow these steps to create the token:

1. Create the String to Encrypt
Concatenate the hostname, the + symbol, and the references parameter into a single string. Example: [hostname]+[references].

2. Encrypt the String with sha512
Encrypt this string using the sha512 algorithm and your API Key as the encryption key. Here’s an example in JavaScript:

3. PHP example
Below is a PHP example to generate the hash, as PHP is one of the most common programming languages:

This process ensures that your API requests are secure and properly authenticated. If needed, examples in other programming languages can be provided.

How to Test API Integration Without Writing Code

If you’d like to test using Postman or another client without coding yet, you can generate the securehash using this website: HMAC Generator.

Step 01 | Generate the Secure Hash

To test the API without coding, use the HMAC Generator here. Select the hashing algorithm (e.g., SHA-512), input hostname+references, and enter the API Key as the secret. This will generate the securehash.

Step 02 | Set the API Request Parameters

Specify the API URL, and include the hostname and references as parameters. Add the securehash as a value in the request header to authenticate.

Step 03 | Retrieve the API Response

When the API request is executed, it returns a JSON object containing multiple nested objects, detailing results based on the provided parameters.

Additionally, here is a functional call example using CURL:

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

Understanding Status Codes

Status codes indicate the server’s response to an API request. Here are common ones and their meanings:

200 OK – The request was successful, and the expected response was returned.
400 Bad Request – The request is invalid or incorrectly formatted. Check syntax and parameters.
403 Forbidden – The request is valid, but you lack permission to access the resource.
404 Not Found – The requested resource does not exist or the endpoint is incorrect.
500 Internal Server Error – A general server error; the issue may be temporary or need troubleshooting.

For API issues, check authentication, request formatting, and access permissions.

Troubleshooting API Issues

If you’re experiencing API issues, follow these steps to diagnose and resolve them:

Status Code 400 | Bad Request

Ensure the request is correctly formatted and follows API specifications.
Verify that all required parameters are included and properly structured.
Check for typos or incorrect data types in the request payload.

Status Code 403 | Forbidden

If your API is configured but you’re still receiving a 403 error, check the following:

Ensure the API is activated as part of your contract.
Verify that the secure hash is calculated correctly.
- The secure hash must be recalculated for each reference used.
- SHA-512 must be used (no other hashing algorithm).
Confirm that the hostname used for hash calculation matches the one passed as a parameter.
Ensure both the hostname and reference are included in the API call parameters.

Status Code 404 | Not Found

Ensure you have uploaded Ecommerce references (SKU) to the BCome platform.
Verify that the reference being passed is from the Ecommerce references (SKU), not the article reference itself.

Status Code 500 | Internal Server Error

If a 500 error occurs, contact support with the following details: