GraphQL API

Une requête.
Une piste d'audit complète.

Récupérez actifs, produits, calculs, facteurs d'émission et leur registre de sources en un seul aller-retour. Conçu pour les auditeurs CSRD, les tableaux de bord BI et les intégrations LLM qui ont besoin du graphe complet.

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

Nativement graphe

Actif → produit → calcul → facteur → registre parcourus en une seule requête, pas cinq.

Références sources enregistrées

Les fiches conservent les entrées et hypothèses. Un facteur original est lié uniquement si son identifiant enregistré est univoque ; une provenance manquante renvoie null.

Mutations de scénario

Simulez le reconditionnement à service égal ou l’arrêt au prochain trimestre. L’inventaire reste inchangé ; l’exécution est journalisée.

Démarrage rapide

Utilisez n'importe quelle clé API depuis votre page de paramètres. Les clés de test (ct_test_*) renvoient des données sandbox afin de développer sans toucher aux données réelles.

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 } }"
  }'

Exemples de requêtes

Chaque exemple ci-dessous est pré-approuvé sur les plans free et pro (liste blanche de requêtes persistées). Les plans business et enterprise peuvent soumettre des requêtes personnalisées.

Parcours méthodologique

Consultez actif, calcul et références électriques enregistrées disponibles. Un lien au registre ne constitue pas une assurance indépendante.

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
        }
      }
    }
  }
}

Détail d'un actif

Récupérez un actif avec son produit lié et une correspondance optionnelle dans le catalogue global (données PCF si disponibles).

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
    }
  }
}

Vue d'ensemble de l'organisation

Totaux actuels du cycle de vie des actifs ; pas automatiquement un inventaire pour une période de déclaration.

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

Facteur par région + date

Recherche de référence par région et date ; elle ne prouve pas qu’un facteur a servi à un calcul enregistré.

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

Simuler un reconditionnement (mutation)

Comparez un achat neuf et un reconditionnement sur le même trimestre à venir. La production initiale est passée ; la fin de vie commune est exclue.

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

Limites et pièges

  • Les limites de débit sont partagées avec l'API REST — mêmes quotas par minute et par jour selon le plan. Free: 25/day, Pro: 1000/day, Business: 10000/day, Enterprise: 100000/day.
  • Les plans free et pro ne peuvent exécuter que les requêtes de la liste blanche (les 5 ci-dessus). Les plans business et enterprise peuvent soumettre n'importe quelle requête.
  • Les requêtes sur les actifs renvoient au maximum 100 lignes par page. Utilisez le curseur after pour la pagination.
  • Les mutations de scénario sont plafonnées à 500 actifs par appel. Les portefeuilles plus importants doivent être traités par lots côté client.
  • Consultez methodology_card, boundary et assumptions si accessibles. Le moteur v4 utilise le traitement brut modélisé en fin de vie, des scénarios de récupération séparés et une sensibilité non statistique. Un delta négatif signifie moins d’émissions estimées, pas une déduction d’inventaire. Ajouter des champs aux cinq modèles exige une requête approuvée ou un abonnement ad hoc.

Référence complète

L'API REST reste la surface principale. GraphQL est destiné aux lectures en forme de graphe et aux scénarios hypothétiques.

Documentation de l'API RESTNouveau sur GraphQL ?