Aller au contenu

Demande d'éligibilité

Fonctionnement

sequenceDiagram participant Client participant Covage API participant Covage Backend Client->>Covage API: Demande des familles d'offres vendues par Covage Covage API-->>Client: Liste des familles d'offres Client->>Covage API: Demande d'éligibilité d'un site à plusieurs famille d'offres Covage API-->>Client: Identifiant de la demande d'éligibilité Covage API->>Covage Backend: Demande d'éligibilité d'un site à plusieurs offres Covage Backend-->>Covage API: Liste des offres éligibles à cette adresse Client->>Covage API: Récupération des résultats d'éligibilité Covage API-->>Client: Résultats d'éligibilité Client->>Covage API: Détail d'une offre Covage API->>Covage Backend: Demande de détail d'un pack avec détail et prix Covage Backend-->>Covage API: Détail du pack Covage API-->>Client: Détail de l'offre

Cycle de vie d'une éligibilité

flowchart LR A[<a href='/api-eligibilite-offres/#demande-deligibilite-dun-site-a-plusieurs-offres'>Création d'une\n demande d'éligibilité</a>] -->B(<i>acknowledged</i>) B -->|Début du\n traitement| C(<i>in_progress.elig</i>) C -->D{Contrôle\n données\n OK ?} D -->|non| T[<i>terminated_with_error</i>] D -->|oui| F(<i>in_progress.offer</i>) F -->K{éligible ?} K -->|non| U[<i>done.unable_to_provide</i>] K -->|oui| G{Calcul des\n prix ?} G -->|non| H{Sur devis ?} H -->|oui| U H -->|non| R G -->|oui| P(<i>in_progress.price</i>) P -->R[<i>done.ready</i>]

Demande des familles d'offres vendues par Covage

Récupération des familles d'offres vendues par Covage

GET /api/v1/catalog/category/

Réponse

Nom Type Description Obligatoire
name string Nom de la famille d'offres ('BPE','BPEA') Oui
type string Type de famille d'offres ('OFFER_FAMILY') Oui
description string Description de la famille d'offres Non
Exemple
    {
        "name": "BPE",
        "type": "OFFER_FAMILY",
        "description": ""
    }

Demande d'éligibilité d'un site à plusieurs offres

Création d'une demande d'éligibilité pour vérifier l'éligibilité d'une adresse à une ou plusieurs offres.

POST /api/v1/product_offering_qualification/

Paramètres de la requête

Nom Type Description Obligatoire
external_id string Identifiant externe pour la demande Non
project_id string Identifiant du projet associé Non
product_offering_qualification_items array Liste des éléments de qualification d'offre Oui
Exemple
  {
  "external_id": "123",
  "project_id": "456",
  "product_offering_qualification_items": [...]
  }

Détail des éléments de qualification d'offre

Nom Type Description Obligatoire
offer_families array Familles d'offres demandées Oui
eligibility_id string Identifiant de l'éligibilité (issu de l'API de recherche d'adresse) Oui
resolve_pricing bool Récupérer les prix des articles (par défaut non) Non
address object Détail de l'adresse à vérifier Non
Exemple
  "product_offering_qualification_items": [
    {
      "offer_families": ["BPEA","BPE"],
      "eligibility_id": "{eligibility_id}",
      "resolve_pricing": false,
      "address": {}
    }]

Détail de l'adresse

Nom Type Description Obligatoire
label string Étiquette de l'adresse Non
street_ext string Extension de la rue Non
street_nr string Numéro de la rue Non
city object Détail de la ville Non
street object Détail de la rue Non
Exemple
"address": {
    "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
    "street_ext": "B",
    "street_nr": "4",
    "city": {},
    "street": {}
    }

Détail de la ville

Nom Type Description Obligatoire
city_id string Identifiant de la ville Non
insee_code string Code INSEE de la ville Non
city_name string Nom de la ville Non
post_code string Code postal de la ville Non
Exemple
"city": {
    "city_id": "76451",
    "insee_code": "76451",
    "city_name": "MONT ST AIGNAN",
    "post_code": "76130"
    }

Détail de la rue

Nom Type Description Obligatoire
street_id string Identifiant de la rue Non
street_name string Nom de la rue Non
Exemple
"street": {
    "street_id": "76451055R",
    "street_name": "Rue Andrei Sakharov"
    }

Exemple de param de la requête finale

{
  "external_id": "123",
  "project_id": "456",
  "product_offering_qualification_items": [
    {
      "offer_families": [
        "BPEA","BPE"
      ],
      "eligibility_id": "KHg6MS4wOTIxMDgxO3k6NDkuNDc0Mzk3MTtiOklNQi83NjQ1MS9DLzAwMTkp",
      "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

Nom Type Description
id string Identifiant de la demande d'éligibilité
creation_date string Date de création 
{
    "id": "2eaf7b5b-384d-4cb7-8d9b-09ac712354d7",
    "creation_date": "2025-04-04T10:07:24.274+02:00",
}

Demande d'éligibilité d'un site à plusieurs offres (synchrone)

POST /api/v1/product_offering_qualification/sync/

Identique à l'endpoint asynchrone POST /api/v1/product_offering_qualification/, mais retourne les résultats directement dans la réponse sans passer par le mécanisme de polling.

Limitations

Cet endpoint est soumis à des limites de débit plus strictes. Préférer la version asynchrone pour les usages en production.

Les paramètres et la réponse sont identiques à POST /api/v1/product_offering_qualification/.

Liste des demandes d'éligibilité

GET /api/v1/product_offering_qualification/

Liste ou recherche les demandes d'éligibilité soumises par le client.

Filtres disponibles (query params) :

Paramètre Type Description
state string Filtre par état (pending, done, failed…)
external_id string Filtre par identifiant externe
project_id string Filtre par identifiant de projet
creation_date_gt datetime Demandes créées après cette date (ISO 8601)
creation_date_lt datetime Demandes créées avant cette date (ISO 8601)

Réponse : Liste paginée de demandes d'éligibilité (mêmes champs que GET /product_offering_qualification/{id}/).

Récupération des résultats d'éligibilité

Récupération des résultats d'éligibilité d'une demande d'éligibilité.

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

Paramètres de la requête

Nom Type Description Obligatoire
id string Identifiant de la demande d'éligibilité Oui

Réponse

Nom Type Description Obligatoire
id string Identifiant de la demande d'éligibilité Oui
user object Utilisateur qui a fait la demande d'éligibilité Oui
creation_date string Date de création de la demande Oui
external_id string Identifiant externe pour la demande Non
project_id string Identifiant du projet associé Non
effective_qualification_date string Date d'éligibilité effective Non
href string Lien vers la ressource Non
state string État actuel de la demande Oui
state_change array Historique des changements d'état Oui
product_offering_qualification_item_detail array Liste des éléments de qualification d'offre Non
Exemple
{
    "id": "2eaf7b5b-384d-4cb7-8d9b-09ac712354d7",
    "user": {
        "email": "anonymous@example.fr",
        "first_name": "Ano",
        "last_name": "Nymous"
    },
    "creation_date": "2025-04-04T10:07:24.274+02:00",
    "external_id": "987654",
    "project_id": "456789",
    "effective_qualification_date": null,
    "href": "",
    "state": "done.ready",
    "state_change": [...],
    "product_offering_qualification_item_detail": [...]
}

Détail d'un utilisateur

Nom Type Description Obligatoire
email string Email de l'utilisateur Oui
first_name string Prénom de l'utilisateur Oui
last_name string Nom de l'utilisateur Oui
Exemple
    "user": {
        "email": "anonymous@example.fr",
        "first_name": "Ano",
        "last_name": "Nymous"
    }

Détail des changements d'état

Nom Type Description Obligatoire
change_reason string Raison du changements d'état Oui
change_date string Date du changements d'état Oui
state string Nouvel état Oui
Exemple
    "state_change": [
        {
            "change_reason": "",
            "change_date": "2025-04-04T10:07:24.276+02:00",
            "state": "acknowledged"
        },
        {
            "change_reason": "",
            "change_date": "2025-04-04T10:07:24.678+02:00",
            "state": "in_progress.elig"
        },
        {
            "change_reason": "",
            "change_date": "2025-04-04T10:07:24.791+02:00",
            "state": "in_progress.offer"
        },
        {
            "change_reason": "",
            "change_date": "2025-04-04T10:07:26.332+02:00",
            "state": "done.ready"
        }]

Détail des éléments de qualification d'offre

Nom Type Description Obligatoire
id string Identifiant de l'élément de qualification Oui
user object Utilisateur qui a fait la demande d'éligibilité Oui
tarif_zone string Zone tarifaire Oui
offer_families array Familles d'offres disponibles Oui
zone_bpe number Zone BPE (ex: 1 correspond à THD ZONE 1) Oui
zone_bpea number Zone BPEA (ex: 3 correspond à THD ZONE 3) Oui
zone_dia number Zone DIA (ex: 2 correspond à THD ZONE 2) Oui
estimated_delivery_date_BPE string Date de livraison prévue BPE (ex: "T0 + 33 SEMAINES") Oui
estimated_delivery_date_BPEA string Date de livraison prévue BPEA (ex: "T0 + 33 SEMAINES") Oui
estimated_delivery_date_DIA string Date de livraison prévue DIA (ex: "T0 + 34 SEMAINES") Oui
bandwidth_max float Débit maximal disponible sur le site Non
density string Densité de la zone Oui
place object Détail du lieu Oui
address object Détail de l'adresse Non
guaranteed_until_date string Date jusqu'à laquelle l'offre est garantie Non
price number Prix produit Non
far number Prix FAR Non
fas number Prix FAS Non
state string État actuel de l'élément Oui
state_change array Historique des changements d'état Oui
product_offering_qualification_id string Identifiant de la demande d'éligibilité parente Non
products_offering array Liste des offres éligibles Oui
resolve_pricing boolean Indique si les prix ont été calculés pour cette demande Oui
Exemple
"product_offering_qualification_item_detail": [
    {
        "id": "a4517ca6-1f13-42a2-9359-4ff3cc21785b",
        "user": {
            "email": "anonymous@example.fr",
            "first_name": "Ano",
            "last_name": "Nymous"
        },
        "tarif_zone": "",
        "offer_families": ["BPEA","BPE"],
        "zone_bpe": 2,
        "zone_bpea": 2,
        "zone_dia": 2,
        "estimated_delivery_date_BPE": "T0 + 33 SEMAINES",
        "estimated_delivery_date_BPEA": "T0 + 33 SEMAINES",
        "estimated_delivery_date_DIA": "T0 + 34 SEMAINES",
        "bandwidth_max": 1000,
        "density": "TRESDENSE",
        "place":{},
        "address": {},
        "guaranteed_until_date": null,
        "price": 145.0,
        "far": 0.0,
        "fas": 0.0,
        "state": "done.ready",
        "state_change": [...],
        "product_offering_qualification_id": null,
        "products_offering": [...]

Détail du lieu

Nom Type Description Obligatoire
location object Coordonnées géographiques Oui
building_ref string Référence du bâtiment Non
eligibility_id string Identifiant de l'éligibilité Oui
Exemple
"place": {
    "location": {
        "x": 1.0741197,
        "y": 49.4629709
    },
    "building_ref": "",
    "eligibility_id": "KHg6MS4wNzQxMTk3O3k6NDkuNDYyOTcwOTtiOk5vbmUp"
    }

Détail de l'adresse

Nom Type Description Obligatoire
label string Étiquette de l'adresse Non
street_ext string Extension de la rue Non
street_nr string Numéro de la rue Non
city object Détail de la ville Non
street object Détail de la rue Non
Exemple
"address": {
    "label": "4bis Rue Andrei Sakharov 76130 Mont-Saint-Aignan",
    "street_ext": "B",
    "street_nr": "4",
    "city": {},
    "street": {}
    }

Détail de la ville

Nom Type Description Obligatoire
city_id string Identifiant de la ville Non
insee_code string Code INSEE de la ville Non
city_name string Nom de la ville Non
post_code string Code postal de la ville Non
Exemple
"city": {
    "city_id": "76451",
    "insee_code": "76451",
    "city_name": "MONT ST AIGNAN",
    "post_code": "76130"
    }

Détail de la rue

Nom Type Description Obligatoire
street_id string Identifiant de la rue Non
street_name string Nom de la rue Non
Exemple
"street": {
    "street_id": "76451055R",
    "street_name": "Rue Andrei Sakharov"
    }

Détail des offres

Nom Type Description Obligatoire
product_id string Identifiant de l'offre (product_offering) Oui
name string Nom du produit Oui
description string Description du produit Oui
bandwidth string Bande passante du produit Oui
bandwidth_guarantee float Bande passante garantie Oui
bandwidth_max float Bande passante maximale Oui
commitment string Engagement du produit Oui
offer_technology string Technologie de l'offre Oui
offer_family string Famille de l'offre Oui
tarif_zone string Zone tarifaire Oui
price number Prix du produit Non
far number Prix du FAR Non
fas number Prix du FAS Non
on_quotation boolean Indique si l'offre est sur devis Oui
Exemple
"products_offering": 
    [{
    "product_id": "2173",
    "name": "BPEA 20M/100M_24 mois",
    "description": "BPEA 20M/100M",
    "bandwidth": "20M",
    "bandwidth_guarantee": 20.0,
    "bandwidth_max": 20.0,
    "commitment": "24MOIS",
    "offer_technology": "FIBDE",
    "offer_family": "BPEA",
    "tarif_zone": ""
    "price": null,
    "far": null,
    "fas": null,
    "on_quotation": false
    }]

Liste d'offres

Récupération d'une liste d'offres.

GET /api/v1/catalog/product_offering/

Détail d'une offre

Récupération du détail d'une offre.

GET /api/v1/catalog/product_offering/{id}/

Liste d'offres avec prix

POST /api/v1/catalog/product_offering/

Récupère une liste d'offres de produits par identifiant, enrichie de leurs tarifs (far/fas/prix).

Corps de la requête : Liste d'identifiants d'offres (list[string])

["BPE_100M_24MOIS", "BPEA_20M_24MOIS"]

Réponse :

Champ Type Description
id string Identifiant de l'offre
name string Nom de l'offre
description string Description de l'offre
bandwidth string Bande passante
bandwidth_max float Bande passante max
bandwidth_guarantee float Bande passante garantie
commitment string Durée d'engagement
tarif_zone string Zone tarifaire
far float Frais d'accès au réseau
fas float Frais d'accès au service
price float Prix mensuel récurrent
offer_family string Famille d'offre (BPE, BPEA, DIA…)
offer_technology string Technologie d'offre
last_update datetime Date de dernière mise à jour (ISO 8601)

Paramètres de la requête

Nom Type Description Obligatoire
id string Identifiant de l'offre (product_offering) Oui
zone integer Zone tarifaire (provenant de l'éligibilité) Non

Réponse

Nom Type Description Obligatoire
id string Identifiant de l'offre Oui
href string Lien vers la ressource Oui
name string Nom de l'offre Oui
description string Description de l'offre Oui
bandwidth string Bande passante Oui
bandwidth_guarantee float Bande passante garantie Oui
bandwidth_max float Bande passante maximum Oui
commitment string Engagement de l'offre Oui
tarif_zone string Zone tarifaire Oui
far number Valeur FAR Oui
fas number Valeur FAS Oui
price number Prix de l'offre Oui
recurring boolean Indique si l'offre est récurrente Oui
offer_family string Famille de l'offre Oui
offer_technology string Technologie de l'offre Oui
available_options array Options disponibles pour l'offre Oui
last_update string Date de la dernière mise à jour Oui
Exemple
{
    "id": "1765",
    "href": "",
    "name": "BPE 20M _Zone dense_24 mois ",
    "description": "description",
    "bandwidth": "20M",
    "bandwidth_guarantee": 20.0,
    "bandwidth_max": 20.0,
    "commitment": "24MOIS",
    "tarif_zone": "DENSE",
    "far": 240.0,
    "fas": 360.0,
    "price": 155.0,
    "recurring": true,
    "offer_family": "BPE",
    "offer_technology": "FIBDE",
    "available_options": [...],
    "last_update": "2024-06-22T08:28:06Z"
}

Détail des options disponibles

Nom Type Description Obligatoire
name string Nom de l'option Oui
type string Type de l'option Oui
values array Valeurs associées à l'option Oui
Exemple
{
    "name": "SECURISATIONCOLLECTE",
    "type": "Option",
    "values": []
}

Détail des valeurs d'option

Nom Type Description Obligatoire
option_id string Identifiant de l'option Oui
label string Étiquette de l'option Oui
price number Prix de l'option Oui
recurring boolean Indique si l'option est récurrente Oui
Exemple
{
    "option_id": "241",
    "label": "SECURISATION COLLECTE Active - Passive",
    "price": 10.0,
    "recurring": true
}

Demande des types de site de raccordement disponibles

Récupération des types de site de raccordement disponibles

GET /api/v1/referential/site_connection/

Réponse

Nom Type Description Obligatoire
available_site_connection_types array Liste des types de site de raccordement disponibles Oui
Exemple
{
    "available_site_connection_types": [
        "Standard ou non-catégorisé",
        "Centre commercial",
        "Datacenter",
        "Zone d'activité ZA",
        "Aéroport",
        "Zone maritime",
        "Centre de santé ou hôpital",
        "Etablissement haute sécurité",
        "Etablissement patrimoine",
        "Prison",
        "Cimetière"
    ]
}

Liste des éléments d'éligibilité

GET /api/v1/product_offering_qualification_item/

Liste ou recherche les éléments d'éligibilité (résultats individuels par site).

Filtres disponibles (query params) :

Paramètre Type Description
state string Filtre par état
density string Filtre par densité (préfixe, ex : T)
building_ref string Filtre par référence bâtiment (préfixe)
offer_technologies string Filtre par technologie(s) (valeurs séparées par virgule)
creation_date_gt datetime Éléments créés après cette date (ISO 8601)
creation_date_lt datetime Éléments créés avant cette date (ISO 8601)
search string Recherche textuelle libre
sort string Champ de tri

Réponse : Liste paginée d'éléments (mêmes champs que GET /product_offering_qualification_item/{id}/).

Détail d'un élément d'éligibilité

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

Récupère le détail d'un élément d'éligibilité individuel.

Paramètre URL :

Nom Type Obligatoire Description
id UUID ✅ Identifiant de l'élément

Réponse :

Champ Type Description
id UUID Identifiant unique
creation_date datetime Date de création (ISO 8601)
density string Densité de la zone
offer_families array Familles d'offres demandées
offer_families_eligibility array Familles d'offres éligibles
offer_technologies array Technologies éligibles
zone_bpe string Zone tarifaire BPE
zone_bpea string Zone tarifaire BPEA
zone_dia string Zone tarifaire DIA
estimated_delivery_date_BPE string Date de livraison estimée pour BPE
estimated_delivery_date_BPEA string Date de livraison estimée pour BPEA
estimated_delivery_date_DIA string Date de livraison estimée pour DIA
bandwidth_max float Bande passante maximale disponible
place object Localisation (coordonnées, building_ref, eligibility_id)
address object Adresse postale
state string État de l'élément
product_offering_qualification_id UUID Identifiant de la demande d'éligibilité parente
guaranteed_until_date datetime Date de validité de l'éligibilité