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

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
bandwidth float Débit maximal de l'offre 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 Oui
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 du produit 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_type_bpe": "FTTO",
        "zone_type_bpea": "FTTO",
        "zone_bpe": 2,
        "zone_bpea": 2,
        "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 Yes
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}/

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/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"
    ]
}

Export des éligibilités

Le processus d'export des éligibilités se déroule en trois étapes :

1. Lancement de l'export CSV

POST /api/v1/product_offering_qualification_item/export/csv/

Lance l'export des éligibilités au format CSV. Cette opération est limitée à une requête toutes les 5 minutes par utilisateur.

Réponse

Champ Type Description
task_id string Identifiant de la tâche d'export

Exemple de réponse

{ 
    "task_id": "550e8400-e29b-41d4-a716-446655440000" 
}

2. Vérification du statut

GET /api/v1/product_offering_qualification_item/export/{task_id}/status/

Permet de suivre l'état d'avancement de l'export.

Paramètres URL

Paramètre Type Description
task_id string Identifiant de la tâche d'export

Réponse

Champ Type Description
task_id string Identifiant de la tâche
success boolean État de la tâche (null si en cours)
started datetime Date de début
stopped datetime Date de fin

Le champ success dans la réponse du statut d'export peut avoir trois états possibles :

Valeur Description
null La tâche est toujours en cours d'exécution ou n'a pas encore démarrée
true La tâche s'est terminée avec succès, le fichier CSV est prêt
false La tâche s'est terminée en échec

Exemple de réponse

{
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "success": true,
    "started": "2025-07-08T10:30:00Z",
    "stopped": "2025-07-08T10:31:00Z"
}

3. Téléchargement du fichier

GET /api/v1/product_offering_qualification_item/export/{task_id}/download/

Télécharge le fichier CSV généré une fois l'export terminé.

Paramètres URL

Paramètre Type Description
task_id string Identifiant de la tâche d'export

Réponse

Fichier CSV contenant les données exportées.

En-têtes de réponse

En-tête Valeur
Content-Type text/csv

Gestion des erreurs

Code HTTP Description
401 Utilisateur non authentifié
403 Permission refusée
404 Tâche ou fichier non trouvé
429 Trop de requêtes (limitation de débit atteinte)