API Documentation - Decarb Desk

The GET /ProductCategories endpoint allows users to retrieve a comprehensive list of all product categories available within the FincoEnergies platform. This endpoint is essential for understanding the various categories of products that you can interact with, providing foundational data for further API operations.

Default request:

Request body:

• No input fields needed

Parameters:

• No parameters needed

Default response:

200: Default response

{
"ProductCategory": [
{
"ProductID": "GS-OCEAN",
"Brand": "GoodShipping",
"ProductName": "GoodShipping Ocean",
"ProductSource": "Sustainable Marine Fuel",
"ProductType": "Reduction",
"Vintage": "2025",
"ProductDescription": "GoodShipping Ocean Sustainable Marine Fuel"
}
]
}

422: Validation error response:

{
"error": "Description of validation error."
}

500: Default error message:

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response:

{
"error": "Timeout waiting for response"
}

The POST TransportEmissions endpoint provides access to detailed emissions data related to transportation activities within the FincoEnergies platform. This endpoint is crucial for tracking and managing the environmental impact of your transportation and distribution operations. The emissions data retrieved through this endpoint is calculated based on the Global Logistics Emissions Council (GLEC) framework, an internationally recognized standard for measuring and reporting logistics emissions (ISO14083).

By using this endpoint, you can obtain accurate and standardized emissions data that aligns with global sustainability practices, helping you to monitor and reduce your carbon footprint effectively. This information is vital for companies committed to sustainability and transparency, enabling them to report emissions accurately and make informed decisions to minimize environmental impact.

Default request:

Parameters

• No parameters needed

Request body (mandatory fields):

{
"BatchID": "batch1",
"TransportMode": "Seaship",
"FreightWeight": 10,
"WeightUnitOfMeasurement": "teu",
"Reefer": true,
"OriginCityName": "Rotterdam",
"OriginCountryCode": "NL",
"DestinationCityName": "New York",
"DestinationCountryCode": "US",
"AdvancedSettings": {
"OriginUNLOCODE": "NLRTM",
"DestinationUNLOCODE": "USNYC"
},
"AdvancedRoadSettings": {
"OriginZIPCode": "2636",
"DestinationZIPCode": "07008",
"LoadFactor": 70,
"TruckType": "Class12",
"TruckBodyType": "Curtainsider",
"EmptyRunFactor": 70,
"EmissionClass": "EuEuro1",
"FuelType": "hvo"
},
"AdvancedAirSettings": {
"AircraftType": ""
},
"AdvancedSeaSettings": {
"LoadFactor": 70,
"SeaCargoType": "Container"
}
}

• BatchID - optional field, adds a unique identifier to your emission calculation.
• TransportMode - choose 'Train', 'Truck', 'Inland', 'Seaship' or 'Airplane'.
• FreightWeight - choose a number, e.g. 20.
• WeightUnitOfMeasurement - choose 'teu' (20ft container), 'feu' (40ft container), 'kg' or 'ton' (1.000 kg).
• Reefer - Indicates whether cooled transportation applies, choose True or False.
• OriginCountryCode - the country code of the origin; choose from the list Appendix C (below).
• DestinationCountryCode - the country code of the destination; choose from the list Appendix C (below).
• OriginCityName - choose the city name of the origin (tip: avoid region names, symbols and characters other than the qwerty keyboard).
• DestinationCityName - choose the city name of the destination (tip: avoid region names, symbols and characters other than the qwerty keyboard).

Request body (optional, advanced fields):

1. For ocean transportation (TransportMode = "Seaship"):

"AdvancedSettings": {
"OriginUNLOCODE": "NLRTM",
"DestinationUNLOCODE": "USLGB"
}

In case the user wishes to calculate emissions for a specific port, one can add the UN/LOCODE of the port. Note: these fields overwrite the "OriginCityName" and "DestinationCityName".

• "OriginUNLOCODE": The UN/LOCODE of the origin port, e.g. NLRTM = NL, Rotterdam.
• "DestinationUNLOCODE": The UN/LOCODE of the destination port, e.g. USLGB = US, Long Beach.

"AdvancedSeaSettings": {
"LoadFactor": 60,
"SeaCargoType": "Container"
}

The "LoadFactor" defines how much % of the container is actually being used for cargo. If the loadFactor is high, the emissions of the TEU are shared across more cargo, and therefore lower. Vice-versa also applies: a lower loadFactor of the TEU leads to more emisisons per TEU. Use a value between 1 (for 1%) and 100 (for 100%).

The "SeaCargoType" can be used to specifiy the vessel type. Please use one of the following options:

• "BulkCarrier"
• "ChemicalTanker"
• "Container"
• "GeneralCargo"
• "Liquid"
• "OilTanker"
• "Ferry"
• "RoRo"
• "Vehicle"

2. For road transpotation (TransportMode = "Truck")

"AdvancedRoadSettings": {
"OriginZIPCode": "1031AP",
"DestinationZIPCode": "1100DL",
"TruckType": "Class40",
"TruckBodyType": "car"
"EmissionClass": "EuEuro6",
"FuelType": "hvo",
"EmptyRunFactor": 70
}

In case the user wishes to calculate intra-city emissions (e.g. from London to London), one can add the zip codes. Note: these fields overwrite the "OriginCityName" and "DestinationCityName", but do need to be used in combination with the "OriginCountryCode" and "DestinationCountryCode".

• "OriginZIPCode": concerns the zip code of the origin, e.g. 1013AP.
• "DestinationZIPCode": concerns the zip code of the destination.

For "TruckType", the vehicle type can be specified. The options are summarized in Appendix A.

For "TruckBodyType", the user can specify a truck body type. The following options are available.

• "curtainsider" - Curtain Sider Trailer
• "cargobox" - Trailer with a fixed body (e.g. wood or metal)
• "cooledbox" - Container chassis
• "tank" - Tanker truck
• "car" - Car transporter truck
• "container" - Container chassis truck for a single TEU
• "container2TEU" - Container chassis truck for two TEU or one FEU.

For "EmissionClass", the user can specify the emission class used. The options are summarized in Appendix B.

For "FuelType", the default value is "diesel 100%". The user can use the following options to overwrite the default option:

• "hvo"
• "electricity"

For "EmptyRunFactor", simulates how much of the return trip is empty, with a value between 0 and 100. For example, EmptyRunFactor = 50 assumes that half of the return trip is empty. Default value is 0% (no empty return assumed).

3. For air transportation (TransportMode = "Airplane"):

"AdvancedAirSettings": {
"AircraftType": "string"
}

With "aircraftType", user can specify the aircraft type, e.g. HybSH (hybrid short haul), HybMH (hybrid medium haul) or HybLH (hybrid long haul).

Responses:

200: Default response:

{
"CO2eTons": 6.2315752
}

422: Validation error response:

{
"message": "cvc-enumeration-valid: Value 'seaship' is not facet-valid with respect to enumeration '[Train, Truck, Inland, Seaship, Airplane]'. It must be a value from the enumeration. cvc-type.3.1.3: The value 'seaship' of element 'TransportMode' is not valid."
}

500: Default error response:

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response:

{
"error": "Timeout waiting for response"
}

Appendix A: VehicleType (for trucks):

Appendix B: EmissionClass (for trucks)

Appendix C: Country codes

The POST SalesOrder endpoint allows you to create and submit new sales orders directly within the FincoEnergies platform. This endpoint is a key component of our API, enabling seamless integration of your procurement processes with our system. By using this endpoint, you can automate the creation of sales orders, ensuring that your transactions are processed quickly and efficiently.

When you submit a sales order through this endpoint, you can include all necessary details such as product information and quantities, ensuring that your order is accurately captured and processed. This functionality is essential for businesses looking to streamline their ordering processes and reduce manual effort, ultimately improving operational efficiency and order accuracy.

Default request:

Parameters:

• No parameters required

Request body:

{
"Reference": "string",
"ProductID": "string",
"AllocationUOM": "WtW",
"Amount": 0
}

• Reference - this concerns your internal reference, e.g. a PO number.
• ProductID - use the FincoEnergies ProductID. Obtain via the GET ProductCategories API.
• EmissionLifecycle - optional field only applicable for scope 3 insetting. Use "WtW" for well-to-wake reduction or "TtW" for tank-to-wake reductions. If no value is entered, "WtW" will be used.
• Amount - fill in the amount, in tonnes of CO2eq. Use max 3 decimals behind comma.

Default response:

200: Default response

{
"Message": "Sales order CM000000 has been received correctly",
"SalesOrder": {
"SalesOrderID": "CM000000",
"Reference": "My first Sales Order",
"Amount": 10.001,
"AllocationUOM": "tCO2e WtW",
"ProductID": "GS-OCEAN",
"ProductCategory": "GoodShipping Ocean"
}
}

422: Validation error response:

{
"error": "Description of validation error."
}

500: Default error response:

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response:

{
"error": "Timeout waiting for response"
}

The GET SalesOrder/{SalesOrderID} endpoint allows you to retrieve detailed information about specific sales orders within the FincoEnergies platform. This endpoint is essential for tracking the status and details of your orders, ensuring that you have full visibility into your transactions at any time.

For our insetting credits, this endpoint goes a step further by providing comprehensive traceability information. You can access details such as feedstock type, vessel type, and bunkering date and location, offering unparalleled transparency into the lifecycle of your credits. Additionally, verified certificates associated with your insetting credits can be downloaded directly through this API, ensuring that you have all necessary documentation for compliance and reporting purposes.

Default request:

Request body:

• No input fields needed

Parameters:

• SalesOrderID (required)

For example, use GET SalesOrder/CM000000 (our sales order numbers start with CM followed by 6 digits.

Default response:

200: Default response

{
"SalesOrder": {
"Customer": "Example customer 1",
"SalesOrderID": "CM000000",
"Status": "AUDITED",
"OrderDate": "2024-10-08T00:00:00.000Z",
"FulfillmentDate": "2024-10-08T00:00:00.000Z",
"AssuranceDate": "2024-01-20T00:00:00.000Z",
"SalesOrderLines": [
{
"SalesOrderLineID": "T-CM000000-1",
"Product": "GoodShipping Ocean",
"PricePerUnitInEUR": 1,
"Amount": 5.005,
"AllocationUOM": "tCO2e WtW",
"PriceInEUR": 999,
"AllocationStatus": "Allocated (Verified)",
"AllocationDate": "2024-10-08T00:00:00.000Z",
"VerificationDate": "2024-10-08T00:00:00.000Z",
"Traceability": [
{
"GHGReductionPercentage": 85.01,
"GHGReductionWtW": 5,005
"GHGReductionTtW": 5.466,
"VesselType": "Bulk carrier",
"FeedstockName": "RawMaterial",
"BunkerPort": "Amsterdam",
"DateOfBunkering": "2024-03-31T22:00:00.000Z",
"BiofuelVolumeM3": 100,
"EnergyContentMJ": 390000000,
"EnergyDensityMJM3": 3900000,
"LastBookDate": "2023-10-14T22:00:00.000Z",
"LastClaimDate": "2023-10-14T22:00:00.000Z"
}
],
"Certificate": {
"Message": "Certificate available",
"Base64String": "Base64 encoded string"
}
}
]
}
}

422: Validation error response:

{
"error": "Description of validation error."
}

500: Default error message:

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response:

{
"error": "Timeout waiting for response"
}

The GET SalesOrderList endpoint allows users to retrieve a comprehensive list of all sales orders placed within the FincoEnergies platform. This feature will enable you to efficiently track and manage multiple orders, providing a clear overview of your transactions. While this endpoint is not yet live, it is designed to streamline order management by offering quick access to order histories and statuses in one consolidated view. Stay tuned for updates as we prepare to launch this valuable addition to our API suite.

Default request:

Parameters (optional):

If desired, the user can add a parameter to the url to obtain a filtered sales order list on "Sales Order Status". The different sales order statuses available are:

• 'quotation' → Quotation - This concerns a draft quotation that has not been submitted by the user yet.
• 'quotationsubmitted' → Quotation submitted - this concerns a quotation that has been submitted to FincoEnergies. Next step: the commercial team of FincoEnergies converts this quotation into a sales order.
• 'awaitingsignature' → Quotation confirmed, awaiting signature - this concerns a quotation that has been confirmed by FincoEnergies. Next step: the quotation needs to be signed by the user to convert it into a sales order.
• 'invoicing' → Invoicing - an invoice from FincoEnergies team is sent out to the user. The invoice has not yet been paid.
• 'awaitingtobefulfilled' → Awaiting to be fulfilled. The invoice has been paid, waiting for FincoEnergies to fulfill the sales order.
• 'fulfilled' → Fulfilled - the FincoEnergies team has fulfilled the concerning sales order. Awaiting auditing by third party.
• 'audited' → Audited - FincoEnergies' assurance partner has now verified the sales order. The verified client certificate will be released to your sales order.

Request body:

• No input fields needed

Default response:

200: Default response

{
"SalesOrders": [
{
"Customer": "Example customer 1",
"SalesOrderID": "CM000001",
"Reference": "string",
"Status": "Audited",
"AllocationUOM": "tCO2e WtW",
"OrderDate": "2024-06-17T09:50:43.431Z",
"PaymentDate": "2024-06-17T09:50:43.431Z",
"FulfillmentDate": "2024-06-17T09:50:43.431Z",
"AssuranceDate": "2024-06-17T09:50:43.431Z",
"Amount": 1,
"ProductCategory": "GoodShipping Ocean",
"TotalPriceInEUR": 1
},
{
"Customer": "Example customer 2",
"SalesOrderID": "CM000002",
"Reference": "string",
"Status": "Confirmed - awaiting signature",
"AllocationUOM": "tCO2e WtW",
"OrderDate": "2024-06-17T09:50:43.431Z",
"PaymentDate": "2024-06-17T09:50:43.431Z",
"FulfillmentDate": "2024-06-17T09:50:43.431Z",
"AssuranceDate": "2024-06-17T09:50:43.431Z",
"Amount": 1,
"ProductCategory": "Biofuel Swap",
"TotalPriceInEUR": 1
}
]
}

404: No SalesOrders found

{
"Message": "No SalesOrders found"
}

422: Validation error response

{
"error": "Description of validation error."
}

500: Default error response

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response

{
"error": "Timeout waiting for response"
}

The POST Transaction endpoint enables customers to allocate insetting credits to their end customers within the FincoEnergies platform. This functionality is essential for managing the distribution of credits, ensuring that the sustainability efforts of your business are accurately reflected across your supply chain. By using this endpoint, you can specify the amount of credits to be allocated, the end-customer receiving the credits, and other relevant details, streamlining the process and maintaining precise records of all transactions. This feature is designed to support your sustainability strategy by making it easy to allocate and track credits efficiently.

Default request:

Parameters:

• No parameters

Request body:

{
"ProductID": "string"
"Reference": "string",
"EndCustomer": "string",
"AllocationUOM": "tCO2e WtW",
"Amount": 100.1
}

• Reference - your internal reference, e.g. a SO number
• EndCustomer - the name of your EndCustomer, needs to be created first using the POST EndCustomer API.
• EmissionLifecycle - optional field, either 'tCO2e WtW' (Well-to-wake) or 'tCO2e TtW' (Tank-to-wake)
• AmountOfCredits - number (tCO2eq), up to three decimals behind comma.
• ProductID - unique ID, obtain via GET ProductCategories API.
• TransactionID - represents the unique ID used by FincoEnergies, starting with CM2 and adding 5 other numbers.

Default response:

200: Default response:

{
"Message": "Transaction has been received and processed successfully",
"TransactionID": "T-CM200000",
"Reference": "First Transaction",
"AllocationUOM": "tCO2e WtW",
"Amount": 100.1,
"ProductID": "GS001"
}

422: Validation error response

{
"error": "Description of validation error."
}

500: Default error response

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response

{
"error": "Timeout waiting for response"
}

The POST EndCustomer endpoint enables customers to create new end-customer profiles within the FincoEnergies platform. This functionality is crucial for businesses looking to allocate insetting credits to specific end-customers, providing a structured way to manage and track these allocations. By setting up end-customer profiles through this endpoint, you’ll streamline the process of distributing credits and ensure accurate record-keeping.

Default request:

Parameters:

• No parameters

Request body:

{
"Name": "string",
"Address": "string",
"Image": "string"
}

• 'Name' - this name will be displayed on the verified client certificate.
• 'Address' - this address will be displayed on the verified client certificate.
• 'Image' - this concerns the company logo (in Base64 code), which will be displayed on the verified client certificate.

Default response:

200: Default response

{
"Message": "EndCustomer succesfully created"
}

422: Validation error response

{
"error": "Description of validation error."
}

500: Default response error

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response

{
"error": "Timeout waiting for response"
}

The GET Transaction/{TransactionID} endpoint allows customers to retrieve more details about a specific allocation transaction made to their end-customers within the FincoEnergies platform. This feature enables you to easily review a transaction.

Default request:

Parameters (required):

• 'TransactionID' - this number starts with CM2 + 5 extra decimals. Obtain the full list using the GET TransactionList API.

Request body:

• No input fields required.

Default response:

200: Default response

{
"TransactionID": "string",
"Reference": "string",
"EndCustomer": "string",
"AllocationUOM": "tCO2e WtW",
"Amount": 10.501,
"From": "string",
"CreationDate": "2024-11-01T10:29:26.912Z",
"TransactionStatus": "string",
"Product": "string",
"TransactionTraceability": [
{
"Message": "string",
"General": {
"BDNID": "string",
"CreditIDStart": "string",
"CreditIDEnd": "string",
"Status": "string",
"GHGReductionPercentage": 0,
"Feedstock": "string",
"EnergyContentMJ": 0,
"BiofuelsVolumeM3": 0,
"VesselType": "string",
"FuelType": "string",
"Modality": "string",
"WtWGHGReduction": 0,
"TtWGHGReduction": 0
},
"AssuranceInformation": {
"PoS_IssuanceDate": "2024-11-01T10:29:26.913Z",
"GenerationDate": "2024-11-01T10:29:26.913Z",
"GenerationAssuranceDate": "2024-11-01T10:29:26.913Z",
"AllocationDate": "2024-11-01T10:29:26.913Z",
"AllocationAssuranceDate": "2024-11-01T10:29:26.913Z",
"ReallocationDate": "2024-11-01T10:29:26.913Z",
"ReallocationAssuranceDate": "2024-11-01T10:29:26.913Z",
"LastBookDate": "2024-11-01T10:29:26.913Z",
"LastClaimDate": "2024-11-01T10:29:26.913Z"
}
}
],
"Certificate": {
"Message": "string",
"Base64String": "string"
}
}

• WtWGHGReduction and TtWGHGReduction are displayed in the respected AllocationUOM (unit of measure).

422: Validation error response

{
"error": "Description of validation error."
}

500: Default error response

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response

{
"error": "Timeout waiting for response"
}

The GET TransactionList endpoint, which will be available soon, will allow customers to retrieve a detailed list of all allocation transactions made to their end customers within the FincoEnergies platform. This feature will provide a comprehensive overview of your insetting credit allocations, enabling you to easily track and review each transaction. By accessing this list, you can monitor the distribution of credits across your end customers, ensuring transparency and accurate record-keeping.

Default request:

Parameters (optional):

If desired, the user can add the following parameters to the url:

• 'Status', filtering on a specific transaction status:
  • awaitingtobefulfilled → Awaiting to be fulfilled by user or by FincoEnergies
  • allocatedunverfiied → Allocated by FincoEnergies, awaiting verification.
  • allocatedverified → Allocated and verified by FincoEnergies.

• 'EndCustomer', filtering on a specific EndCustomer
  • EndCustomer → enter the name of the EndCustomer

Body request:

• No input fields required.

Default response:

200: Default response

{
"Transaction": [
{
"TransactionID": "CM200001",
"Reference": "First transaction",
"EndCustomer": "Example EndCustomer 1",
"AllocationUOM": "tCO2e WtW",
"Amount": 0.5,
"CreationDate": "2024-06-25T08:01:51.652Z",
"TransactionStatus": "Allocated (Verified)",
"Product": "GoodShipping Ocean"
},
{
"TransactionID": "CM200002",
"Reference": "Second transaction",
"EndCustomer": "Example EndCustomer 2",
"AllocationUOM": "tCO2e WtW",
"Amount": 0.5,
"CreationDate": "2024-09-09T11:47:23.234Z",
"TransactionStatus": "Awaiting to be fulfilled",
"Product": "GoodShipping Ocean"
}
]
}

404: Not found error response

{
"Message": "No Transaction found"
}

422: Validation error response

{
"error": "Description of validation error."
}

500: Default error response

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response

{
"error": "Timeout waiting for response"
}

The GET EndCustomerList endpoint allows customers to retrieve a complete list of all end-customers they have created within the FincoEnergies platform. This feature will provide an organized overview of your end-customer profiles, making it easier to manage and allocate insetting credits. By accessing this list, you'll be able to quickly review and select the appropriate end-customer for credit allocations.

Default request:

Parameters:

• No parameters

Request body:

• No input fields required

Default response:

200: Default response

{
"EndCustomer": [
{
"Name": "Example Customer 1",
"Address": "Example Street 1"
},
{
"Name": "Example Customer 2",
"Address": "Example Street 2"
},
{
"Name": "Example Customer 3",
"Address": "Example Street 3"
}
]
}

404: Not found error response

{
"error": "No Customers found."
}

422: Validation error response

{
"error": "Description of validation error."
}

500: Default error response

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response

{
"error": "Timeout waiting for response"
}

The GET Balance endpoint allows customers to review their current inventory within the FincoEnergies platform. This feature provides users with real-time access to their available credits, enabling better management and planning of insetting activities. With this endpoint, you'll be able to monitor your inventory usage and ensure you have sufficient balance for upcoming transactions.

Default request:

Parameters (optional)

• 'ProductID' - allows the user to filter on a specific ProductID

Body request:

• No input fields required.

Default response:

200: Default response

{
"Message": "Response message",
"Balance": [
{
"ProductID": "GS-OCEAN",
"Name": "GoodShipping Ocean",
"Brand": "GoodShipping",
"TotalAmountOfWtWCredits": 87,
"TotalAmountOfTtWCredits": 87.78,
"TotalAmountOfCredits": 0,
"TotalEnergyContentMJ": 1133525.99,
"TotalBiofuelVolumeM3": 34.33
}
]
}

404: Not found error response

{
"error": "No Balances found."
}

422: Validation error response

{
"error": "Description of validation error."
}

500: Integration layer - Default error response

{
"error": "Description of the error(s) that occurred."
}

504: Timeout error response

{
"error": "Timeout waiting for response"
}