GraphQL API

Eine Abfrage.
Vollständiger Audit-Trail.

Rufen Sie Assets, Produkte, Berechnungen, Emissionsfaktoren und deren Quellenregister in einem einzigen Round-Trip ab. Entwickelt für CSRD-Prüfer, BI-Dashboards und LLM-Integrationen, die den gesamten Graphen benötigen.

POST https://carbontrace.cloud/api/v1/graphql

Graph-nativ

Asset → Produkt → Berechnung → Faktor → Register in einer Abfrage durchlaufen, nicht in fünf.

Gespeicherte Quellenverweise

Berechnungskarten speichern Eingaben und Annahmen. Ein ursprünglicher Faktor wird nur bei einer eindeutigen gespeicherten ID verknüpft; fehlende Herkunft ergibt null.

Szenario-Mutationen

Simulieren Sie Aufbereitung bei gleicher Nutzleistung oder Abschaltung im nächsten Quartal. Der Bestand bleibt unverändert; die Ausführung wird protokolliert.

Schnellstart

Verwenden Sie einen beliebigen API-Schlüssel von Ihrer Einstellungsseite. Test-Schlüssel (ct_test_*) liefern Sandbox-Daten zurück, sodass Sie entwickeln können, ohne auf Live-Daten zuzugreifen.

curl -X POST https://carbontrace.cloud/api/v1/graphql \
  -H "Authorization: Bearer ct_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query OrgOverview { organization { id name plan asset_count total_kg_co2e } }"
  }'

Beispielabfragen

Jedes der folgenden Beispiele ist auf den Free- und Pro-Plänen vorab freigegeben (Whitelist für Persisted Queries). Business- und Enterprise-Pläne können eigene Abfragen einreichen.

Methodik-Durchlauf

Lesen Sie Gerät, Berechnung und verfügbare gespeicherte Stromfaktorverweise. Ein Registerverweis belegt keine unabhängige Prüfung.

query MethodologyAudit($assetId: ID!) {
  asset(id: $assetId) {
    id
    brand
    mpn
    total_kg_co2e
    production_kg
    use_phase_kg

    active_calculation {
      id
      created_at
      total_kg_co2e
      emission_factor(type: GRID) {
        value
        unit
        source
        source_version
        source_url
        source_license
        registry {
          display_name
          current_version
          next_check_after
        }
      }
    }
  }
}

Asset-Detail

Rufen Sie ein Asset mit seinem verknüpften Produkt und einem optionalen Treffer im globalen Katalog ab (PCF-Daten, falls verfügbar).

query AssetDetail($id: ID!) {
  asset(id: $id) {
    id
    brand
    mpn
    serial_number
    status
    purchase_date
    country
    total_kg_co2e
    product {
      id
      brand
      mpn
      name
      category
    }
  }
}

Organisationsübersicht

Aktuelle Lebenszyklussummen der Geräte; nicht automatisch eine Emissionsbilanz für einen Berichtszeitraum.

query OrgOverview {
  organization {
    id
    name
    plan
    asset_count
    total_kg_co2e
  }
}

Faktor nach Region + Datum

Referenzsuche nach Region und Datum; sie belegt nicht die Verwendung eines Faktors in einer gespeicherten Berechnung.

query FactorLookup($region: String!, $atDate: DateTime) {
  factorByRegion(type: GRID, regionCode: $region, atDate: $atDate) {
    value
    unit
    source
    source_version
    valid_from
    valid_to
  }
}

Refurbishment simulieren (Mutation)

Vergleichen Sie Neukauf und Aufbereitung für dasselbe nächste Quartal. Die ursprüngliche Produktion liegt in der Vergangenheit; die gemeinsame Entsorgung ist ausgeschlossen.

mutation Refurbish($ids: [ID!]!) {
  simulateRefurbish(assetIds: $ids) {
    current_quarterly_co2e
    scenario_quarterly_co2e
    delta_kg_co2e
    delta_percentage
    affected_assets_count
  }
}

Grenzen und Stolperfallen

  • Rate-Limits werden mit der REST-API geteilt — dieselben Pro-Minute- und Pro-Tag-Kontingente je Plan. Free: 25/day, Pro: 1000/day, Business: 10000/day, Enterprise: 100000/day.
  • Free- und Pro-Pläne können nur Abfragen aus der Whitelist ausführen (die 5 oben). Business und Enterprise dürfen beliebige Abfragen einreichen.
  • Asset-Abfragen liefern maximal 100 Zeilen pro Seite zurück. Verwenden Sie den Cursor after für die Paginierung.
  • Szenario-Mutationen sind auf 500 Assets pro Aufruf begrenzt. Größere Portfolios müssen clientseitig gebündelt werden.
  • Lesen Sie methodology_card, boundary und assumptions, soweit zugänglich. Engine v4 nutzt modellierte Bruttoentsorgung, getrennte Rückgewinnungsszenarien und nichtstatistische Sensitivität. Ein negatives Szenariodelta bedeutet weniger geschätzte Emissionen, keinen Bilanzabzug. Zusätzliche Felder der fünf Vorlagen benötigen eine genehmigte Abfrage oder einen Ad-hoc-Tarif.

Vollständige Referenz

Die REST-API bleibt die primäre Schnittstelle. GraphQL ist für graphförmige Lesezugriffe und Was-wäre-wenn-Szenarien gedacht.

REST-API-DokumentationNeu bei GraphQL?