Skip to content

Latest commit

 

History

History
880 lines (747 loc) · 22.1 KB

guide.fr-fr.md

File metadata and controls

880 lines (747 loc) · 22.1 KB
title excerpt updated
Utiliser l'API Connectivity
Développez en utilisant notre API connectivity
2023-04-03

[!primary] Une version en langue anglaise de ce guide est disponible ici

Objectif

Cette documentation a pour objectif d'aider les développeurs à utiliser nos API, afin de créer leurs propres applications.

Prérequis

En pratique

Offres Internet

OVHcloud propose différentes offres d'accès à Internet par le biais de packages contenant au moins un accès Internet mais aussi des lignes VoIP, des e-mails, des noms de domaine.

Les offres sont visibles ici.

Les services peuvent être gérés à l'aide de ces points de terminaison d'API :

  • /pack/xdsl : Gérer les packages d'offres Internet;
  • /xdsl : Gérer les accès Internet, les sous-services et les options;
  • /connectivity : va remplacer /xdsl. Pour l'instant il permet de faire l'éligibilité aux offres cuivre et fibre.

Éligibilité

Aperçu

Les méthodes d'éligibilité sont disponibles sur le chemin d'accès /connectivity/eligibility/.

L'objectif de l'éligibilité est de renvoyer les offres Internet éligibles pour un endpoint (point de livraison) donné, afin de commander cette offre. Un endpoint peut être une adresse ou une ligne existante, identifiée par le numéro de ligne et son état (actif ou inactif).

Les méthodes retournent une structure xdsl.AsyncTask en asynchrone, telle que :

{
  "status" : une chaîne de caractères, le statut de la tâche ("pending" (en attente), "done" (terminé) ou "error" (erreur))
  "result" : un objet, en cas de succès, le résultat de la méthode
  "error" : une chaîne de caractères, le message d'erreur en cas d'erreur
}

Voici un exemple de tâche en attente :

{
  "status": "pending",
  "result": null,
  "error": null
}

Un exemple de tâche réussie :

{
  "status": "success",
  "result": {"une clé": "une valeur"},
  "erreur": null
}

Et enfin un exemple de tâche qui a échoué :

{
  "status": "error",
  "result": null,
  "error": "L'action a échoué, voici pourquoi"
}

[!primary]

Vous devez vérifier l'état de la tâche, et réessayer quelques secondes plus tard si la tâche est toujours en état "doing" (en attente).

Trouver les endpoints (points de livraison)

Pour une ligne cuivre, le point de livraison est une ligne identifiée par son numéro et son état. Si aucune ligne n'existe, vous devrez faire un test par adresse pour voir si vous êtes éligible à la création d'une ligne voisine.

Pour la fibre, le point de livraison peut être identifié par un identifiant building (bâtiment) ou un identifiant OTP (PTO : Point de Terminaison Optique).

Une adresse est identifiée par un numéro de rue et un code de rue. Pour les trouver, utilisez ce processus :

  1. Obtenir la liste des localités à partir d'un code postal
  2. Obtenir la liste des rues d'une localité
  3. Obtenir les numéros de rue disponibles pour un code de rue donné
  4. Obtenir la liste des bâtiments pour une adresse
  5. Obtenir la liste des bâtiments pour une ligne
Pour obtenir la liste des localités à partir d'un code postal

Exemple : nous voulons rechercher dans les localités pour le code postal "91400".

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/search/cities

avec les données suivantes :

{
  "zipCode": "91400"
}

La réponse :

{
  "error": null,
  "result": [
    {
      "inseeCode": "91471",
      "zipCode": "91400",
      "locality": "ORSAY",
      "city": "ORSAY"
    },
    {
      "inseeCode": "91471",
      "zipCode": "91400",
      "locality": "ORSIGNY",
      "city": "ORSAY"
    },
    {
      "inseeCode": "91534",
      "zipCode": "91400",
      "locality": "SACLAY",
      "city": "SACLAY"
    }
  ],
  "status": "ok"
}
Pour obtenir la liste des rues d'une localité

Exemple : Nous voulons obtenir la liste des rues de la localité "ORSAY" identifiée par le code INSEE "91471".

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/search/streets

avec les données suivantes :

{
  "inseeCode": "91471"
}

La réponse :

{
  "result": [
    {
      "streetName": "ALLEE ALFRED POHU",
      "streetCode": "9147134101"
    },
    {
      "streetCode": "9147132200",
      "streetName": "RUE DU VERGER"
    },
    {
      "streetName": "RUE ELISA DESJOBERT",
      "streetCode": "9147111200"
    },
    {
      "streetName": "RUE ETIENNE BAUER",
      "streetCode": "9147102180"
    },
    {
      "streetName": "RUE FACULTE D ORSAY",
      "streetCode": "9147110752"
    }
  ],
  "status": "ok",
  "error": null
}
Pour obtenir les numéros de rue disponibles pour un code de rue donné

Exemple : nous voulons les numéros de la rue "RUE DU VERGER", identifiée par le code de rue "9147132200".

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/search/streetNumbers

avec les données suivantes :

{
  "streetCode": "9147132200"
}

La réponse :

{
  "status": "ok",
  "result": [
    "1",
    "1B",
    "2",
    "2B",
    "3",
    "5",
    "6",
    "7",
    "9",
    "10",
    "11",
    "13",
    "15",
    "17",
    "19"
  ],
  "error": null
}
Pour obtenir tous les bâtiments pour une adresse spécifique

Exemple : nous voulons la liste des bâtiments pour l'adresse "2 RUE DU VERGER, 91400 ORSAY", identifiée par le code de rue "9147132200" et le numéro "2".

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/search/buildings

avec les données suivantes :

{
  "streetCode": "9147132200",
  "streetNumber": "2"
}

La réponse:

{
  "status": "ok",
  "error": null,
  "result": [
    {
      "stairs": [],
      "reference": "IMB/91471/C/NT8X",
      "type": "HOUSE",
      "name": "",
      "nro": "91122BUR"
    }
  ]
}
Pour obtenir les références de bâtiment à partir d'un numéro de ligne donné

Exemple : nous voulons la liste des bâtiments pour le numéro de ligne inactive "0123456789".

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/search/buildingsByLine

avec les données suivantes :

{
  "lineNumber": "0123456789",
  "status": "inactive"
}

La réponse :

{
  "error": null,
  "result": [
    {
      "nro": "91122BUR",
      "name": "",
      "stairs": [],
      "type": "HOUSE",
      "reference": "IMB/91471/C/NT8X"
    }
  ],
  "status": "ok"
}

Nous avons trouvé un seul bâtiment qui est une maison.

Rechercher une éligibilité cuivre (ADSL, VDSL)

Les cas possibles sont :

Faire une éligibilité sur une ligne

Si vous connaissez le numéro et l'état de la ligne, vous pouvez vérifier son éligibilité. La différence entre une ligne active et une ligne inactive est qu'une ligne active a un accès Internet actif, alors que la ligne inactive est juste un identifiant à utiliser pour commander un accès Internet (il s'agit généralement de l'ancien numéro du dernier propriétaire, qui a déménagé avec sa ligne).

Warning

Il est important de distinguer la ligne active d'une ligne inactive. Vérifiez toujours que l'adresse renvoyée est la véritable adresse de l'installation.

Voici la requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/test/line

avec les données POST suivantes :

{
  "lineNumber": "0123456789",
  "status": "active"
}

Voici un retour partiel pour l'exemple :

{
  "status": "ok",
  "error": null,
  "result": {
    "offers": [
      {
        "eligibility": {
          "reasons": [
            {
              "message": "Copper not currently available in this area.",
              "code": "COPPER_NOT_YET_AVAILABLE",
              "availabilityDate": null
            }
          ],
          "estimatedUploadRate": 1,
          "activationTypes": [
            "activate"
          ],
          "eligible": false,
          "estimatedDownloadRate": 8.17,
          "underConditions": []
        },
        "product": {
          "uploadRate": 1,
          "pairs": 1,
          "downloadRate": 20,
          "name": "ADSL-Max with shared unbundling",
          "provider": "KOSC",
          "code": "ADSL-MAX_SHARED",
          "guaranteed": false,
          "type": "ADSL",
          "grt": []
        }
      },
      {
        "product": {
          "guaranteed": false,
          "type": "VDSL",
          "grt": [],
          "pairs": 1,
          "uploadRate": 1,
          "provider": "KOSC",
          "code": "VDSL-MAX_FULL",
          "name": "VDSL-Max with full unbundling",
          "downloadRate": 20
        },
        "eligibility": {
          "estimatedUploadRate": 0,
          "reasons": [
            {
              "code": "TOO_MUCH_ATTENUATION",
              "message": "Too much attenuation to deliver the product.",
              "availabilityDate": null
            }
          ],
          "underConditions": [],
          "estimatedDownloadRate": 0,
          "eligible": false,
          "activationTypes": [
            "activate",
            "create"
          ]
        }
      },
      {
        "eligibility": {
          "estimatedUploadRate": 0.9970703125,
          "reasons": [],
          "underConditions": [],
          "estimatedDownloadRate": 8.173828125,
          "activationTypes": [
            "create",
            "activate"
          ],
          "eligible": true
        },
        "product": {
          "name": "ADSL-Max full unbundling",
          "downloadRate": 20,
          "provider": "KOSC",
          "code": "ADSL-MAX_FULL",
          "uploadRate": 1,
          "pairs": 1,
          "grt": [],
          "type": "ADSL",
          "guaranteed": false
        }
      },
      {
        "eligibility": {
          "activationTypes": [
            "activate"
          ],
          "eligible": false,
          "estimatedDownloadRate": 0,
          "underConditions": [],
          "reasons": [
            {
              "message": "Too much attenuation to deliver the product.",
              "code": "TOO_MUCH_ATTENUATION",
              "availabilityDate": null
            }
          ],
          "estimatedUploadRate": 0
        },
        "product": {
          "code": "VDSL-MAX_SHARED",
          "provider": "KOSC",
          "downloadRate": 20,
          "name": "VDSL-Max with shared unbundling",
          "pairs": 1,
          "uploadRate": 1,
          "type": "VDSL",
          "grt": [],
          "guaranteed": false
        }
      }
    ],
    "endpoint": {
      "portability": {
        "type": null,
        "eligibility": {
          "underConditions": [],
          "eligible": false,
          "reasons": [
            {
              "availabilityDate": null,
              "code": "3049",
              "message": "L opérateur détient le parc à modifier"
            }
          ]
        },
        "quarantineEndDate": null
      },
      "referenceType": "lineNumber",
      "fiberInfo": null,
      "copperInfo": {
        "sectionsLengths": [
          {
            "diameter": 4,
            "length": 3010
          }
        ],
        "maxAvailablePairs": 1,
        "status": "active",
        "underConstruction": false,
        "unlistedNumber": false,
        "availablePairs": 1,
        "nra": "90123ABC"
      },
      "reference": "0123456789",
      "address": {
        "door": "00002",
        "city": "PARIS",
        "floor": null,
        "stairs": null,
        "streetName": "RUE DES JARDINS",
        "housingComplex": "",
        "zipCode": "94123",
        "building": null,
        "streetCode": "9412301234",
        "streetNumber": "4",
        "ownerName": null,
        "inseeCode": "94321"
      }
    },
    "eligibilityReference": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz01"
  }
}

La réponse est composée de :

  • un tableau result.offers listant toutes les offres et indiquant si la ligne donnée est éligible ou non;
  • une structure result.endpoint qui donne des informations sur la ligne : adresse et caractéristiques.

Voici une description des codes d'offre:

code type description
ADSL-MAX_SHARED ADSL ADSL dégroupage partiel
ADSL-MAX_FULL ADSL ADSL dégroupage total
VDSL-MAX_SHARED VDSL VDSL dégroupage partiel
VDSL-MAX_FULL VDSL VDSL dégroupage total
Rechercher une ligne active ou inactive pour une adresse

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/search/lines

avec les données POST suivantes :

{
    "streetCode": "123456789",
    "streetNumber": "2"
}

La réponse :

{
  "status": "ok",
  "error": null,
  "result": [
    {
      "copperInfo": {
        "underConstruction": null,
        "availablePairs": null,
        "status": "inactive",
        "unlistedNumber": false,
        "maxAvailablePairs": null,
        "nra": null,
        "sectionsLengths": []
      },
      "address": {
        "streetCode": "123456789",
        "stairs": null,
        "floor": null,
        "city": "ROUBAIX",
        "door": null,
        "streetName": "RUE DES JARDINS",
        "zipCode": "94123",
        "building": null,
        "housingComplex": "",
        "inseeCode": "94123",
        "streetNumber": "4",
        "ownerName": "J*** D**"
      },
      "lineNumber": "0123456789"
    }
  ]
}

Pour cette adresse, nous avons trouvé une seule ligne inactive avec le numéro 0123456789.

Vous pouvez désormais utiliser l'éligibilité par ligne.

[!primary]

Les numéros sur liste rouge ne peuvent pas être récupérés à l'aide de cette méthode.

Rechercher une éligibilité pour une adresse

Cela retournera une éligibilité par adresse, à utiliser pour la création d'une ligne voisine. Une création de ligne voisine consiste à vérifier la disponibilité de nouvelles lignes cuivre en recherchant les informations de la ligne voisine la plus proche.

[!primary]

Si vous avez déjà une ligne active ou inactive, vous devez utiliser le test de ligne à la place de cette méthode.

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/test/address

avec les données suivantes :

{
  "streetCode": "94123001234",
  "streetNumber": "4"
}

La réponse :

{
  "status": "ok",
  "result": {
    "eligibilityReference": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz01",
    "endpoint": {
      "referenceType": "lineNumber",
      "portability": {
        "quarantineEndDate": null,
        "type": null,
        "eligibility": {
          "underConditions": [],
          "reasons": [],
          "eligible": false
        }
      },
      "address": {
        "city": "PARIS",
        "zipCode": "94123",
        "stairs": null,
        "door": null,
        "streetCode": "94123001234",
        "inseeCode": "94123",
        "ownerName": null,
        "streetName": "RUE DES JARDINS",
        "housingComplex": "",
        "building": null,
        "floor": null,
        "streetNumber": "4"
      },
      "fiberInfo": null,
      "copperInfo": {
        "sectionsLengths": [
          {
            "diameter": 4,
            "length": 1239
          }
        ],
        "underConstruction": false,
        "maxAvailablePairs": 6,
        "unlistedNumber": false,
        "nra": "59512PIL",
        "availablePairs": 6,
        "status": "active"
      },
      "reference": "0123456789"
    },
    "offers": [
      {
        "eligibility": {
          "activationTypes": [
            "createNeighbour"
          ],
          "estimatedDownloadRate": 20.04,
          "underConditions": [],
          "reasons": [
            {
              "message": "Too much attenuation to deliver the product.",
              "availabilityDate": null,
              "code": "TOO_MUCH_ATTENUATION"
            }
          ],
          "eligible": false,
          "estimatedUploadRate": 1.48
        },
        "product": {
          "provider": "KOSC",
          "downloadRate": 20,
          "pairs": 1,
          "name": "VDSL-Max with full unbundling",
          "uploadRate": 1,
          "guaranteed": false,
          "type": "VDSL",
          "grt": [],
          "code": "VDSL-MAX_FULL"
        }
      },
      {
        "product": {
          "provider": "KOSC",
          "pairs": 1,
          "downloadRate": 20,
          "name": "ADSL-Max full unbundling",
          "uploadRate": 1,
          "guaranteed": false,
          "type": "ADSL",
          "code": "ADSL-MAX_FULL",
          "grt": []
        },
        "eligibility": {
          "eligible": true,
          "estimatedUploadRate": 1.16796875,
          "underConditions": [],
          "reasons": [],
          "estimatedDownloadRate": 18.935546875,
          "activationTypes": [
            "createNeighbour"
          ]
        }
      }
    ]
  },
  "error": null
}

Rechercher une éligibilité fibre (FTTH)

Pour une éligibilité fibre, nous avons deux cas de figure :

  • J'ai un identifiant fibre OTP (Optical Termination Point), que je vais utiliser pour tester l'éligibilité;
  • Je n'ai pas d'identifiant OTP fibre et utiliserai un identifiant * bâtiment * pour vérifier l'admissibilité.

Un building peut être une maison ou un immeuble à logements multiples. Le building peut être trouvé à partir d'une adresse ou d'une ligne de cuivre existante.

Le processus d'éligibilité à partir d'une adresse est le suivant :

  1. Obtenir la liste des localités à partir d'un code postal
  2. Obtenir la liste des rues d'une localité
  3. Obtenir les numéros de rue disponibles pour un code de rue donné
  4. Obtenir tous les bâtiments pour une adresse spécifique
  5. Faire le test d'éligibilité pour le bâtiment sélectionné

À partir d'une ligne, nous avons à :

  1. Obtenir les références de bâtiment à partir d'un numéro de ligne donné
  2. Faire le test d'éligibilité pour le bâtiment sélectionné

Pour un OTP, c'est le plus simple :

  1. Faire le test d'éligibilité pour l'identifiant PTO

Voici les détails de chaque type de demande.

Pour faire l'éligibilité sur un bâtiment

Exemple : nous voulons vérifier l'éligibilité des offres FTTH pour l'immeuble identifié par la référence "IMB/91471/C/NT8X".

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/test/building

avec les données suivantes :

{
  "building": "IMB/91471/C/NT8X"
}

La réponse :

{
  "error": null,
  "status": "ok",
  "result": {
    "offers": [
      {
        "product": {
          "pairs": null,
          "uploadRate": 800,
          "guaranteed": false,
          "code": "PROFIBER",
          "type": "FTTH",
          "grt": [],
          "name": "PRO FIBER with 1G download and 800M upload",
          "provider": "KOSC",
          "downloadRate": 1000
        },
        "eligibility": {
          "estimatedDownloadRate": null,
          "estimatedUploadRate": null,
          "underConditions": [],
          "activationTypes": [],
          "reasons": [],
          "eligible": true
        }
      }
    ],
    "endpoint": {
      "referenceType": "building",
      "portability": null,
      "address": {
        "door": null,
        "floor": null,
        "stairs": null,
        "zipCode": "91400",
        "city": "ORSAY",
        "streetNumber": "2",
        "housingComplex": null,
        "inseeCode": "91471",
        "ownerName": null,
        "streetName": "RUE DU VERGER",
        "building": null,
        "streetCode": "9147123456"
      },
      "fiberInfo": {
        "nro": "91122ABC",
        "operatorCode": "FI",
        "buildingType": "HOUSE",
        "buildingName": "",
        "buildingReference": "IMB/91234/A/NT6Z",
        "operatorName": "ORANGE"
      },
      "reference": "IMB/91234/A/NT6Z",
      "copperInfo": null
    },
    "eligibilityReference": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz01"
  }
}

Dans le résultat pour le tableau "offers", l'attribut booléen eligible.eligible nous indique que nous sommes éligibles à l'offre "PRO FIBER with 1G download and 800M upload".

Pour rechercher l'éligibilité à partir d'un identifiant PTO

Exemple : nous voulons vérifier l'éligibilité pour la PTO "OO-XXXX-XXXX/C".

La requête :

[!api]

@api {v1} /connectivity POST /connectivity/eligibility/test/otp

avec les données suivantes :

{
  "otp": "OO-XXXX-XXXX/C"
}

La réponse sera identique à celle de l'exemple précédent.

Aller plus loin

Échangez avec notre communauté d'utilisateurs.