Premiers Pas

Ce guide vous accompagne dans vos premières interactions avec l'API FTTX Covage. Vous apprendrez comment vous authentifier et réaliser une demande d'éligibilité.

1. Authentification

Fonctionnement

L'authentification se fait par un jeton d'accès (access token) qui est à récupérer dans la réponse de la demande d'authentification. Nous utilisons le protocole OAuth2 pour l'authentification.

Il faudra pour cela récupérer un jeton d'accès (access token) en utilisant le flux d'authentification par mot de passe avec le compte de service (service account) de l'API que Covage vous fournira.

sequenceDiagram participant Client participant Keycloak participant API FTTX Client->>Keycloak: POST /token (credentials) Keycloak->>Client: access_token + refresh_token Client->>API FTTX: GET /api/v1/* (Authorization: Bearer token) API FTTX->>Client: Réponse

Récupération du jeton d'accès

Récupération du jeton d'accès (access token) pour l'API Covage.

POST {keycloak-url}/auth/realms/covage/protocol/openid-connect/token

En-tête

Nom	Type	Description
Content-Type	string	Type de contenu de la requête (application/x-www-form-urlencoded)

Paramètres

Nom	Type	Description	Obligatoire
grant_type	string	Type de flux d'authentification (password)	Oui
client_id	string	Identifiant du client (api-client)	Oui
username	string	Nom d'utilisateur du compte de service	Oui
password	string	Mot de passe du compte de service	Oui

Informations d'identification

Le username et le mot de passe sont fournis par Covage.
Le client_id est toujours api-client pour ce flux d'authentification.
Le grant_type est toujours password pour ce flux d'authentification.

Réponse

Nom	Type	Description
access_token	string	Jeton d'accès (access token) à utiliser dans les requêtes suivantes pour s'authentifier auprès de l'API
expires_in	number	Durée de vie du jeton d'accès (en secondes)
token_type	string	Type de jeton (Bearer)
refresh_token	string	Jeton de rafraîchissement (refresh token) à utiliser pour récupérer un nouveau jeton d'accès (access token)
refresh_expires_in	number	Durée de vie du jeton de rafraîchissement (en secondes)
scope	string	Portée du jeton (scope)
session_state	string	État de la session

Exemple de requête

curl -X POST "{keycloak-url}/auth/realms/covage/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=api-client" \
  -d "username=votre_username" \
  -d "password=votre_password"

Exemple de réponse

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "refresh_expires_in": 7200,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "scope": "email profile",
  "session_state": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

2. Réaliser une éligibilité en 3 étapes

Une fois authentifié, vous pouvez interroger l'API pour vérifier l'éligibilité d'un site à une ou plusieurs familles d'offres Covage.

flowchart LR A[1. Obtenir l'eligibility_id] --> B[2. Créer la demande d'éligibilité] B --> C[3. Consulter les résultats] style A fill:#e1f5ff style B fill:#e1f5ff style C fill:#d4edda

Étape 1 : Obtenir l'eligibility_id

L'eligibility_id est un identifiant qui référence un site. Vous pouvez l'obtenir en interrogeant l'endpoint /api/v4/eligibility/site/ avec différents paramètres :

Endpoint : GET /api/v4/eligibility/site/

Par coordonnées GPS

curl -X GET "https://api-client.covage.com/api/v4/eligibility/site/?x=1.091455&y=49.4744077" \
  -H "Authorization: Bearer {votre_access_token}"

Par référence de bâtiment

curl -X GET "https://api-client.covage.com/api/v4/eligibility/site/?building_ref=IMB/31555/X/00RV" \
  -H "Authorization: Bearer {votre_access_token}"

Ou les deux

curl -X GET "https://api-client.covage.com/api/v4/eligibility/site/?building_ref=IMB/31555/X/00RV&x=1.091455&y=49.4744077" \
  -H "Authorization: Bearer {votre_access_token}"

Réponse :

{
  "id": "KHg6MS4wOTE0NTU7eTo0OS40NzQ0MDc3O2I6SU1CLzMxNTU1L1gvMDBSVik=",
  "building_ref": "IMB/31555/X/00RV",
  "location": {
    "x": 1.091455,
    "y": 49.4744077
  }
}

Le champ id de la réponse correspond à l'eligibility_id à utiliser pour la demande d'éligibilité.

Étape 2 : Créer une demande d'éligibilité

Envoyez une demande d'éligibilité pour un ou plusieurs sites avec les familles d'offres souhaitées.

Mode synchrone vs asynchrone

L'API propose deux modes pour créer une demande d'éligibilité :

Mode synchrone (recommandé pour machine à machine) : POST /api/v1/product_offering_qualification/sync/
La réponse contient directement les résultats de l'éligibilité.
Rate limit : 1 requête par seconde
Mode asynchrone : POST /api/v1/product_offering_qualification/
La demande est créée et vous devez ensuite consulter l'étape 3 pour récupérer les résultats une fois le traitement terminé.
Rate limit : 10 requêtes par minute

Mode synchrone (recommandé)

Endpoint : POST /api/v1/product_offering_qualification/sync/

Rate limit

1 requête par seconde maximum

curl -X POST "https://api-client.covage.com/api/v1/product_offering_qualification/sync/" \
  -H "Authorization: Bearer {votre_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1234",
    "project_id": "5678",
    "product_offering_qualification_items": [
      {
        "offer_families": ["BPEA", "BPE"],
        "eligibility_id": "KHg6MS4wOTE0NTU7eTo0OS40NzQ0MDc3O2I6SU1CLzMxNTU1L1gvMDBSVik=",
        "address": {
          "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
          "street_ext": "B",
          "street_nr": "4",
          "city": {
            "city_id": "76451",
            "insee_code": "76451",
            "city_name": "MONT ST AIGNAN",
            "post_code": "76130"
          },
          "street": {
            "street_id": "76451055R",
            "street_name": "Rue Andrei Sakharov"
          }
        }
      }
    ]
  }'

Paramètres :

Paramètre	Type	Description	Obligatoire
external_id	string	Référence client de la demande	Non
project_id	string	Identifiant du projet	Non
product_offering_qualification_items	array	Liste des sites à tester	Oui
↳ eligibility_id	string	Identifiant d'éligibilité	Oui
↳ offer_families	array	Liste des familles d'offres (BPEA, BPE, etc.)	Oui
↳ address	object	Adresse complète du site	Non

Réponse immédiate :

L'API retourne directement les résultats de l'éligibilité :

{
  "id": "c777a051-45ca-463c-b12d-48136bce5598",
  "creation_date": "2025-12-15T11:39:42.035+01:00",
  "external_id": "1234",
  "effective_qualification_date": null,
  "href": "",
  "state": "done.ready",
  "state_change": [
    {
      "change_reason": "",
      "change_date": "2025-12-15T11:39:42.037+01:00",
      "state": "acknowledged"
    },
    {
      "change_reason": "",
      "change_date": "2025-12-15T11:39:42.254+01:00",
      "state": "in_progress.elig"
    },
    {
      "change_reason": "",
      "change_date": "2025-12-15T11:39:42.663+01:00",
      "state": "in_progress.offer"
    },
    {
      "change_reason": "",
      "change_date": "2025-12-15T11:39:45.719+01:00",
      "state": "done.ready"
    }
  ],
  "product_offering_qualification_items": [
    {
      "id": "7ee14cbd-aecd-4f7f-8843-37b622f3b5f1",
      "user": {
        "email": "admin-covage@covage.com",
        "first_name": "Admin",
        "last_name": "Covage"
      },
      "density": "TRESDENSE",
      "offer_families": [
        "BPE",
        "BPEA"
      ],
      "zone_bpe": 1,
      "zone_bpea": 1,
      "bandwidth_max": 10000.0,
      "place": {
        "location": {
          "x": 1.091455,
          "y": 49.4744077
        },
        "building_ref": "IMB/31555/X/00RV",
        "eligibility_id": "KHg6MS4wOTE0NTU7eTo0OS40NzQ0MDc3O2I6SU1CLzMxNTU1L1gvMDBSVik="
      },
      "address": {
        "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
        "street_ext": "B",
        "street_nr": "4",
        "city": {
          "city_id": "76451",
          "insee_code": "76451",
          "city_name": "MONT ST AIGNAN",
          "post_code": "76130"
        },
        "street": {
          "street_id": "76451055R",
          "street_name": "Rue Andrei Sakharov"
        }
      },
      "guaranteed_until_date": null,
      "state": "done.ready",
      "state_change": [
        {
          "change_reason": "",
          "change_date": "2025-12-15T11:39:42.051+01:00",
          "state": "acknowledged"
        },
        {
          "change_reason": "",
          "change_date": "2025-12-15T11:39:42.269+01:00",
          "state": "in_progress.elig"
        },
        {
          "change_reason": "",
          "change_date": "2025-12-15T11:39:42.650+01:00",
          "state": "in_progress.offer"
        },
        {
          "change_reason": "",
          "change_date": "2025-12-15T11:39:45.705+01:00",
          "state": "done.ready"
        }
      ],
      "product_offering_qualification_id": null,
      "products_offering": [
        {
          "product_id": "1765",
          "name": "BPEA 100M _Zone très dense_12 mois",
          "description": "BPEA 100M _Zone très dense",
          "bandwidth": "100M",
          "bandwidth_max": 100.0,
          "bandwidth_guarantee": 100.0,
          "commitment": "12MOIS",
          "offer_technology": "FIBDE",
          "offer_family": "BPEA",
          "tarif_zone": "TRESDENSE",
          "price": 0.0,
          "far": 0.0,
          "fas": 0.0,
          "on_quotation": false
        },
        {
          "product_id": "1766",
          "name": "BPEA 200M _Zone très dense_24 mois",
          "description": "BPEA 200M _Zone très dense",
          "bandwidth": "200M",
          "bandwidth_max": 200.0,
          "bandwidth_guarantee": 200.0,
          "commitment": "24MOIS",
          "offer_technology": "FIBDE",
          "offer_family": "BPEA",
          "tarif_zone": "TRESDENSE",
          "price": 0.0,
          "far": 0.0,
          "fas": 0.0,
          "on_quotation": false
        },
        {
          "product_id": "1680",
          "name": "BPE 100M _Zone très dense_24 mois",
          "description": "BPE 100M _Zone très dense",
          "bandwidth": "100M",
          "bandwidth_max": 100.0,
          "bandwidth_guarantee": 100.0,
          "commitment": "24MOIS",
          "offer_technology": "FIBDE",
          "offer_family": "BPE",
          "tarif_zone": "TRESDENSE",
          "price": 0.0,
          "far": 0.0,
          "fas": 0.0,
          "on_quotation": false
        },
        {
          "product_id": "1681",
          "name": "BPE 1G _Zone très dense_36 mois",
          "description": "BPE 1G _Zone très dense",
          "bandwidth": "1G",
          "bandwidth_max": 1000.0,
          "bandwidth_guarantee": 1000.0,
          "commitment": "36MOIS",
          "offer_technology": "FIBDE",
          "offer_family": "BPE",
          "tarif_zone": "TRESDENSE",
          "price": 0.0,
          "far": 0.0,
          "fas": 0.0,
          "on_quotation": false
        }
      ]
    }
  ]
}

Tableau des statuts :

Statut	Phase	Description
`acknowledged`	Initiale	Demande d'éligibilité reçue et prise en compte
`in_progress.elig`	Traitement	Vérification de l'éligibilité en cours
`in_progress.offer`	Traitement	Recherche des offres disponibles
`done.ready`	Finale	Éligibilité validée avec offres et prix disponibles
`done.unable_to_provide`	Finale	Site non éligible ou nécessite un devis
`terminated_with_error`	Erreur	Erreur lors du contrôle des données fournies

Mode asynchrone

Si vous utilisez le mode asynchrone, la demande est créée mais le traitement se fait en arrière-plan.

Endpoint : POST /api/v1/product_offering_qualification/

Rate limit

10 requêtes par minute maximum

curl -X POST "https://api-client.covage.com/api/v1/product_offering_qualification/" \
  -H "Authorization: Bearer {votre_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1234",
    "product_offering_qualification_items": [
      {
        "offer_families": ["BPEA", "BPE"],
        "eligibility_id": "KHg6MS4wOTE0NTU7eTo0OS40NzQ0MDc3O2I6SU1CLzMxNTU1L1gvMDBSVik=",
        "address": {
          "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
          "street_ext": "B",
          "street_nr": "4",
          "city": {
            "city_id": "76451",
            "insee_code": "76451",
            "city_name": "MONT ST AIGNAN",
            "post_code": "76130"
          },
          "street": {
            "street_id": "76451055R",
            "street_name": "Rue Andrei Sakharov"
          }
        }
      }
    ]
  }'

Réponse initiale :

La réponse contient l'ID de la demande créée, mais pas encore les résultats :

{
  "id": "c777a051-45ca-463c-b12d-48136bce5598",
  "creation_date": "2025-12-15T11:39:42.035+01:00",
  "external_id": "1234",
  "project_id": "",
  "state": "acknowledged",
  "product_offering_qualification_items": [
    {
      "id": "7ee14cbd-aecd-4f7f-8843-37b622f3b5f1",
    }
  ]
}

Vous devez ensuite utiliser l'Étape 3 pour récupérer les résultats une fois le traitement terminé (état done.ready).

Étape 3 : Consulter les résultats de l'éligibilité

Vous pouvez consulter vos demandes d'éligibilité à tout moment. Cette étape est obligatoire en mode asynchrone pour récupérer les résultats.

Lister toutes les éligibilités

Endpoint : GET /api/v1/product_offering_qualification/

curl -X GET "https://api-client.covage.com/api/v1/product_offering_qualification/" \
  -H "Authorization: Bearer {votre_access_token}"

Récupérer une éligibilité spécifique

Endpoint : GET /api/v1/product_offering_qualification/{id}/

curl -X GET "https://api-client.covage.com/api/v1/product_offering_qualification/21675c4c-ae32-4587-bd66-cc66b188ddf0/" \
  -H "Authorization: Bearer {votre_access_token}"

Consulter les détails d'un item d'éligibilité

Endpoint : GET /api/v1/product_offering_qualification_item/{id}/

curl -X GET "https://api-client.covage.com/api/v1/product_offering_qualification_item/d5a4a9aa-ba2c-4f53-95c7-0c1ce6f6e7fa/" \
  -H "Authorization: Bearer {votre_access_token}"

Lister tous les items d'éligibilité

Endpoint : GET /api/v1/product_offering_qualification_item/

curl -X GET "https://api-client.covage.com/api/v1/product_offering_qualification_item/" \
  -H "Authorization: Bearer {votre_access_token}"

Prochaines étapes

Maintenant que vous savez vous authentifier et réaliser une éligibilité, vous pouvez :

📋 Créer des devis : Transformer une éligibilité en devis commercial
🛒 Passer des commandes : Commander un produit éligible
📊 Consulter vos commandes : Suivre l'état d'avancement de vos commandes

Consultez la documentation complète de l'API pour explorer toutes les fonctionnalités disponibles.