API Documentation - Decarb Desk

We are thrilled to announce the expansion of our Decarb Desk offering with the launch of our first API gateway. This new capability allows cargo owners, freight forwarders, and digital platforms to seamlessly integrate our climate solutions into their existing applications, enabling a more efficient and effective approach to sustainability.

With the Decarb Desk API, recognized sustainability solutions like insetting and offsetting are now digitally accessible, making it easier than ever to incorporate these practices into your operations. This digital integration streamlines the exchange of information, reduces inefficiencies, and enhances the overall impact of your sustainability initiatives.

On this page, you'll find all the instructions and resources you need to get started with the Decarb Desk API and leverage its full potential.

General guidelines:

The FincoEnergies API is built on REST (Representational State Transfer) principles, ensuring a simple, scalable, and stateless architecture that facilitates seamless integration with diverse applications. All interactions with our API are performed over HTTPS, adhering to standard HTTP methods (GET, POST, PUT, DELETE) for resource manipulation. To maintain security and protect user data, the API uses OAuth 2.0 for authorization, requiring clients to obtain an access token for authenticated requests. This ensures that only authorized users can access and manipulate resources, providing a secure and efficient environment for our partners and developers.

API Endpoints:

The FincoEnergies API provides a variety of endpoints that allow you to interact with different aspects of our services. These endpoints are designed to give you access to essential data and functionalities, enabling seamless integration with your applications. Here's a brief overview of the key endpoints you can test:

• Product Categories:
  • Get a List of Product Categories: Retrieve a comprehensive list of available product categories, helping you understand the different offerings within our platform.
• Emissions:
  • Transportation & Distribution: Access data related to emissions from transportation and distribution activities, crucial for sustainability reporting and carbon footprint management.
• Sales Orders:
  • Place an Order: Submit orders directly through the API, streamlining your procurement process.
  • Get a Sales Order: Retrieve details of a specific sales order to track its status and contents.
  • Get a List of Sales Orders: Access a list of all sales orders, providing an overview of your transactions with FincoEnergies.
• Allocations:
  • Get Credit Balance: Check the credit balance for your account, ensuring you have the necessary credits to proceed with transactions.
  • Create an End-Customer: Add a new end-customer to your account, facilitating transactions and credit allocations.
  • Get a List of End-Customers: View a list of all end-customers associated with your account.
  • Place a Transaction to End-Customer: Allocate credits to an end-customer, managing their energy or sustainability allocations.
  • Get a List of Transactions to End-Customer: Retrieve a history of all transactions made to end-customers, allowing you to track and manage allocations effectively.

These endpoints provide powerful tools to integrate FincoEnergies' services into your operations, giving you the flexibility and control needed to manage product categories, emissions data, sales orders, and credit allocations efficiently.

Learn how to securely connect and start using our API.

Step 1: Request Access to FincoEnergies API

To get started, you'll first need to request access to the FincoEnergies API. Simply head over to our contact form to get in touch with our team. Once your request is approved, you'll receive the necessary credentials to begin integrating with our services.

Step 2: Authenticate with Your API Keys

After approval, the FincoEnergies team will provide you with API keys for accessing the sandbox environment of the Decarb Desk. These keys are essential for authenticating your requests. Use the following endpoint for the sandbox environment: https://api-cloud0106.emagizcloud.com/swaggerui/index.html.

Step 3: Test API Requests from Your Browser

With your sandbox API keys, you can start experimenting with our API. Navigate to the Swagger UI to explore available endpoints and try out requests directly from your browser. This is a great way to familiarize yourself with the API before moving to live data.

Step 4: Transition to Live Data

Ready to move beyond the sandbox? Contact the FincoEnergies team to obtain a new set of API keys for our live environment. These keys will allow you to access and work with real-time data, enabling you to fully integrate our services into your applications. If you need assistance during this process, our team is here to help.

Understand common issues and how to troubleshoot them.

The FincoEnergies API uses standard HTTP status codes to indicate the success or failure of an API request. Common error codes include:

• 400 Bad Request for invalid or malformed requests,
• 401 Unauthorized for requests lacking proper authentication (e.g., missing or invalid OAuth token),
• 403 Forbidden for requests that are authenticated but lack the necessary permissions,
• 404 Not Found when a requested resource cannot be found, and
• 500 Internal Server Error for unexpected server-side issues. Each error response includes a JSON-formatted message with additional details to help diagnose and correct the issue. We recommend implementing appropriate error handling in your application to manage these responses and retry or adjust requests as necessary.

The Change Log for the FincoEnergies API will provide a detailed record of all updates, enhancements, and fixes as we continue to develop and improve the platform. Since this is our initial release, there are currently no changes to report. As we move forward, any modifications to the API will be documented here, ensuring that you stay informed about new features, improvements, and important changes that may affect your integration. We recommend checking the Change Log regularly to stay up-to-date with the latest developments.

The current FincoEnergies API is our initial release and does not yet include versioning. As we continue to enhance and expand our API, future updates may introduce versioning to ensure backward compatibility and to allow developers to continue using existing integrations without disruption. When versioning is implemented, it will likely be indicated in the API URL (e.g., /v1/resource). We will provide clear guidelines and ample notice before making any changes that could impact current users.

The FincoEnergies API is currently available exclusively in English, ensuring consistency and clarity across all endpoints and documentation. While we recognize the global nature of our user base, our focus on English as the primary language allows us to maintain high-quality, precise communication. For support, our technical team is available during European Central Time (CET) office hours, ready to assist with any questions or issues you may encounter. We are committed to providing reliable and timely support to help you effectively integrate and use our API, regardless of your location.

FincoEnergies provides comprehensive API documentation through Swagger, a powerful and interactive tool that helps developers understand and explore our API. The Swagger docs offer a clear, user-friendly interface where you can view all available endpoints, see detailed descriptions of each operation, and test API calls directly within the documentation. This interactive environment allows you to quickly learn how to integrate with the FincoEnergies API, experiment with different parameters, and see real-time responses, making development faster and more efficient. The Swagger docs ensure that you have all the information you need to effectively utilize our API.

The latest version of the Swagger UI documentation can be found on the link below:

fincoenergies.com/api