API Documentation | Developer Resources

🚀 Introductie

De CarbonScope API is een RESTful API die toegang biedt tot al uw carbon footprint data. Gebruik onze API om:

Emissies automatisch registreren vanuit uw systemen
Real-time carbon data ophalen voor dashboards
Rapporten genereren via geautomatiseerde workflows
Supplier emissions data integreren in uw procurement systeem
Science-Based Targets progress monitoren

Base URL

https://api.carbonscope.nl/v1

Response Format

Alle responses zijn in JSON format met UTF-8 encoding.

🔐 Authenticatie

CarbonScope gebruikt API keys voor authenticatie. Voeg uw API key toe aan elke request via de Authorization header:

HTTP Header

Authorization: Bearer sk_live_your_api_key_here

API Keys Beheren

U kunt API keys aanmaken en beheren in uw CarbonScope dashboard onder Settings → API Keys. Gebruik altijd:

sk_live_ voor productie environment
sk_test_ voor test environment

⚡ Quickstart

Registreer uw eerste emissie in minder dan 5 minuten:

cURL

curl -X POST https://api.carbonscope.nl/v1/emissions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "electricity",
    "amount": 1500,
    "unit": "kWh",
    "date": "2025-01-15",
    "location": "Netherlands"
  }'
                

Response

JSON

{
  "id": "em_1234567890",
  "activity_type": "electricity",
  "amount": 1500,
  "unit": "kWh",
  "co2_kg": 675.0,
  "emission_factor": 0.45,
  "scope": "scope_2",
  "date": "2025-01-15",
  "location": "Netherlands",
  "created_at": "2025-01-16T10:30:00Z"
}
                

📊 Emissions Endpoints

POST /v1/emissions

Registreer een nieuwe emissie activiteit met automatische CO₂ berekening.

Request Parameters

Parameter	Type	Beschrijving
activity_type Required	string	Type activiteit: electricity, natural_gas, fuel_diesel, flight, etc.
amount Required	number	Hoeveelheid verbruik
unit Required	string	Eenheid: kWh, m³, liters, km, etc.
date Required	date	Datum van activiteit (YYYY-MM-DD)
location Optional	string	Land of regio voor location-based emissions
metadata Optional	object	Custom metadata voor filtering en rapportage

GET /v1/emissions

Haal een lijst op van alle geregistreerde emissies met filtering opties.

Query Parameters

Parameter	Type	Beschrijving
start_date	date	Filter vanaf datum
end_date	date	Filter tot datum
scope	string	Filter op scope: scope_1, scope_2, scope_3
limit	integer	Aantal resultaten (max 100, default 20)
offset	integer	Paginatie offset

GET /v1/emissions/:id

Haal details op van een specifieke emissie registratie.

PUT /v1/emissions/:id

Update een bestaande emissie registratie.

DELETE /v1/emissions/:id

Verwijder een emissie registratie.

📄 Reports Endpoints

GET /v1/reports/summary

Genereer een samenvatting rapport met totale emissies per scope, trend analyse en key metrics.

Response Example

JSON

{
  "period": {
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  },
  "total_emissions_kg_co2": 125847.5,
  "scope_breakdown": {
    "scope_1": { "kg_co2": 32145.2, "percentage": 25.5 },
    "scope_2": { "kg_co2": 41235.8, "percentage": 32.8 },
    "scope_3": { "kg_co2": 52466.5, "percentage": 41.7 }
  },
  "trend": {
    "vs_previous_period": -12.5,
    "status": "on_track"
  },
  "top_emission_sources": [
    { "source": "electricity", "kg_co2": 41235.8 },
    { "source": "business_travel", "kg_co2": 28450.3 },
    { "source": "natural_gas", "kg_co2": 22180.0 }
  ]
}
                

POST /v1/reports/export

Exporteer een compleet GHG Protocol of CSRD-compliant rapport als PDF of Excel.

Request Body

JSON

{
  "report_type": "ghg_protocol",
  "format": "pdf",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "include_verification": true,
  "language": "nl"
}
                

🔔 Webhooks

Ontvang real-time notificaties wanneer events plaatsvinden in uw CarbonScope account.

Supported Events

emission.created - Nieuwe emissie geregistreerd
emission.updated - Emissie gewijzigd
goal.threshold_reached - Reductie doelstelling bereikt
report.generated - Nieuw rapport beschikbaar
supplier.data_received - Supplier emissie data ontvangen

Webhook Payload

JSON

{
  "id": "evt_1234567890",
  "type": "emission.created",
  "created_at": "2025-01-16T10:30:00Z",
  "data": {
    "object": {
      "id": "em_1234567890",
      "activity_type": "electricity",
      "amount": 1500,
      "co2_kg": 675.0,
      "scope": "scope_2"
    }
  }
}
                

Webhook Configuratie

Webhooks kunnen geconfigureerd worden in uw dashboard onder Settings → Webhooks. Zorg ervoor dat uw endpoint:

HTTPS gebruikt (TLS 1.2+)
Binnen 5 seconden een 200 OK response teruggeeft
De webhook signature verifieert voor security

🐍 Python SDK

Installeer de officiële CarbonScope Python library:

bash

pip install carbonscope

Quick Example

Python

import carbonscope

# Initialize client
client = carbonscope.Client(api_key="sk_live_your_api_key")

# Create emission
emission = client.emissions.create(
    activity_type="electricity",
    amount=1500,
    unit="kWh",
    date="2025-01-15",
    location="Netherlands"
)

print(f"CO2 emitted: {emission.co2_kg} kg")

# Get summary report
report = client.reports.summary(
    start_date="2024-01-01",
    end_date="2024-12-31"
)

print(f"Total emissions: {report.total_emissions_kg_co2} kg CO2")
                

📖 API Documentation & Developer Resources

🔑 Uw API Key:

🚀 Introductie

Base URL

Response Format

🔐 Authenticatie

API Keys Beheren

⚡ Quickstart

Response

📊 Emissions Endpoints

Request Parameters

Query Parameters

📄 Reports Endpoints

Response Example

Request Body

🔔 Webhooks

Supported Events

Webhook Payload

Webhook Configuratie

🐍 Python SDK

Quick Example

💡 Hulp nodig met de API?