Services¶

L'API /api/v2/services/ permet de récupérer les liens livrés par Covage.

Note

Cette API (dite v2) remplace l'API v1, désormais dépréciée. Vous êtes invités à migrer vers cette API unifiée dès à présent. L'API est directement compatible avec l'ancienne API fibre.

L'URL de base de cette API est : https://extranet.kosc-telecom.fr/api/v2/services/.

Les services sont en lecture-seule.

Récapitulatif des API¶

Action	Méthode	URL
Lister les services	`GET`	`/api/v2/services/`
Récupérer un service	`GET`	`/api/v2/services/{uuid}/`

Migrer un Service Cuivre vers du FTTH¶

Pour migrer un service cuivre vers du FTTH, il est nécessaire de créer une nouvelle commande FTTH et de résilier la commande cuivre indépendamment.

Créer une commande de migration à partir du Service¶

Requête POST:

POST api/v2/services/<service_uuid>/migrate_to_ftth/ HTTP/1.1
Host: extranet.kosc-telecom.fr

{
  "imb": ""
}

Réponse :

Si une Order est créée avec succès

HTTP/1.1 200 OK
Content-Type: application/json

{
    "eligible":true,
    "data":"OXXXXXX_XXXXX"
}

Si une Order existe déjà pour ce Service

HTTP/1.1 200 OK
Content-Type: application/json

{
  "eligible": false,
  "data": "Already have an order to migrate OXXXXXX_XXXXX"
}

Si l'adresse du Service n'est pas éligible

HTTP/1.1 200 OK
Content-Type: application/json

{
  "eligible": false,
  "data": "FIBER_NOT_YET_DEPLOYED, Available around 2024-12-31"
}

Si l'adresse du service possède plusieurs IMB

HTTP/1.1 200 OK
Content-Type: application/json

{
    "eligible":true,
    "data":["IMB1", "IMB2"]
}

Dans ce cas, reprendre la requête en spécifiant l'IMB à utiliser.

Si l'adresse ne possède pas d'IMB

HTTP/1.1 500 Internal server error
Content-Type: application/json

{
  "error": "Building not found.",
  "details": null,
  "apirequest_uuid": "KOSC_4f0a5d33-1071-452c-ad72-0881b340be39"
}

Champs¶

Cette section décrit les champs d'un objet service.

Nom du champ	Type	Description
uuid	string	Identifiant universel unique (32 caractères hexadécimaux sous forme canonique).
reference	string	Référence commerciale Covage du service au format SYYMMDD_XXXXX.
status	string	Statut du service. Valeurs possibles : - `active` : service actif - `terminated` : service résilié
activate_order_ref	string	Référence commerciale Covage de la commande qui a servi à créer ce service.
activate_order_uuid	string	Identifiant de la commande qui a servi à créer ce service.
activation_date	ISO datetime	Date d'activation du service.
starting_date	ISO datetime	Date de début de facturation.
creation_date	ISO datetime	Date de création du service.
modification_date	ISO datetime	Date de dernière modification du service.
current_order_uuid	string	Identifiant de la commande de résiliation en cours sur ce service le cas échéant, `null` autrement.
current_order_type	string	Type de la commande en cours sur le service (`null` ou `terminate`).
product	object	Informations sur le produit du service. Définit le type de service, la technologie, le débit, les options possibles.
product[uuid]	string	Référence du produit.
product[code]	string	Code du produit.
product[name]	string	Nom du produit.
product[description]	string	Description du produit.
product[line]	object	Ligne du produit.
product[line][uuid]	string	Référence de la ligne de produit.
product[line][code]	string	Code de la ligne de produit.
product[line][name]	string	Nom de la ligne de produit.
product[line][description]	string	Description de la ligne de produit.
product[line][family]	object*	Famille de produit.
product[line][family][uuid]	string	Référence de la famille de produit.
product[line][family][code]	string	Code de la famille de produit.
product[line][family][name]	string	Nom de la famille de produit.
product[line][family][description]	string	Description de la famille de produit
end_customer[type]	string	Type de client final. Valeurs possibles : - `registered` : entreprise avec un numéro de SIRET, - `unregistered` : entreprise sans numéro de SIRET, - `individual` : client particulier.
end_customer[name]	string	Nom du client final (entreprise). À renseigner si end_customer[type]``est ``registered ou `unregistered`.
end_customer[first_name]	string	Prénom du client final. À renseigner si `end_customer[type]` est `individual`.
end_customer[last_name]	string	Nom de famille du client final. À renseigner si `end_customer[type]` est `individual`.
end_customer[siret]	string	Numéro SIRET de l'entreprise. À renseigner si `end_customer[type]` est `registered`.
end_customer[contact]	string	Informations de contact du client final, utilisées pour le contacter en cas de nécessité.
end_customer[contact][first_name]	string	Prénom du contact.
end_customer[contact][last_name]	string	Nom de famille du contact
end_customer[contact][email]	string	E-mail du contact.
end_customer[contact][phone_number]	string	Téléphone principal du contact.
end_customer[contact][cell_phone_number]	string	Téléphone portable du contact.
operator_info	object	Informations relatives à l'opérateur.
operator_info[contact_uuid]	string	Référence du contact de l'opérateur à contacter concernant ce service.
bounds	list	Points de livraison de la commande (extrémité de la ligne). Pour les commandes cuivre et fibre, cette liste ne comprend qu'un seul élément.
bounds[uuid]	string	Identifiant unique de l'extrémité (32 caractères hexadécimaux sous forme canonique).
bounds[address]	string	Adresse de l'extrémité. Cette adresse ne peut être modifiée que si le type d'éligibilité le permet.
bounds[address][street_number]	string	Numéro de rue.
bounds[address][street_name]	string	Nom de la rue.
bounds[address][kosc_street_code]	string	Identifiant Covage de la voie.
bounds[address][kosc_insee_code]	string	Code INSEE Covage de la commune.
bounds[address][zipcode]	string	Code postal.
bounds[address][city]	string	Ville.
bounds[address][housing_complex]	string	Ensemble de bâtiments ou nom de la résidence (le cas échéant).
bounds[address][building_code]	string	Code immeuble (le cas échéant).
bounds[address][building]	string	Nom du batiment (le cas échéant).
bounds[address][stairs]	string	Escalier (le cas échéant).
bounds[address][floor]	string	Étage (le cas échéant).
bounds[address][door]	string	Porte (le cas échéant).
bounds[address][logo]	string	Cuivre : Logo (plaque de cuivre France Telecom ou Orange) sur la porte du client (le cas échéant).
bounds[information]	string	Informations supplémentaires sur l'extrémité (spécifique au produit et à la technologie).
bounds[information][co]	string	Nom du NRO ou du NRA (si cette information est disponible).
bounds[endpoints]	list	Liste des endpoints sur une extrémité. Cette liste comprend plusieurs éléments dans le cas d'un produit cuivre multipaires, un seul sinon.
bounds[endpoints][n][uuid]	string	Identifiant d'un endpoint (32 caractères hexadécimaux sous forme canonique)
bounds[endpoints][n][reference]	string	Référence d'un endpoint
bounds[endpoints][n][type]	string	Type d'endpoint. Valeurs possibles : - `OTP` (fibre) - `line_number` (cuivre)
bounds[endpoints][n][locked]	boolean	Indique si l'utilisateur peut modifier ou non l'endpoint (déterminé par le type d'éligibilité qui a permis de créer la commande).
bounds[endpoints][n][information]	object	Informations supplémentaires sur l'endpoint (spécifique au produit et à la technologie).
options	object	Options activées sur le service. Consultez l'API orders pour une liste indicative.
information	object	Informations supplémentaires sur le service (spécifique au produit).
information.profile	object	Cuivre : profil DSL en vigueur sur le service.
ticket_uuid	String	Identifiant unique du ticket ouvert sur le service le cas échéant, `null` sinon.

Services de collecte¶

Certains champs sont spécifiques aux produits de type collecte :

Nom du champ	Type	Description
information[ennis][0][reference]	string	Produits entreprise (E-Access Fiber et SDSL) : référence Covage du service ENNI sur lequel est livré le trafic
information[ennis][0][uuid]	string	Produits entreprise (E-Access Fiber et SDSL) : identifiant du service ENNI sur lequel est livré le trafic
information[ennis][0][vlan]	string	Produits entreprise (E-Access Fiber et SDSL) : référence du VLAN utilisé sur l'ENNI

Portes de collecte¶

Certains champs sont spécifiques aux produits de type ENNI (portes de collecte) :

Nom du champ	Type	Description
information[pop]	object	Informations du Point-of-Presence (POP) sur lequel est livrée la porte
information[pop][code]	String	Code du POP
information[pop][address]	String	Adresse du POP
information[pop][housing]	String	Nom de l'hébergeur
information[pop][interface]	String	Type d'interface de l'ENNI, null sinon.

Lister les services¶

L'endpoint api/v2/services/ permet de lister tous les services.

Il est possible de filtrer sur plusieurs champs :

reference: rechercher par référence de service

status: rechercher par statut: active, terminated

endpoint_ref: rechercher par référence d'endpoint

end_customer: rechercher par nom de client final

product: rechercher par code produit

product_family: rechercher par famille de produit

product_line: rechercher par ligne de produit

Requête :

GET /api/v2/services/?&owner=KOSC&status=active&endpoint_ref=0492271978&alias=S191011_59827&product_line=AM&product_family=A  HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json

[
{
    "activation_date": "2019-10-11T15:05:01.945031Z",
    "activate_order_ref": "O191011_58179",
    "activate_order_uuid": "05d3d27d-97ba-4ade-beb4-fe051cd3c540",
    "creation_date": "2019-10-11T15:05:01.760889Z",
    "current_order_type": null,
    "current_order_uuid": null,
    "end_customer": {
        "siret": "81352886600029",
        "contact": {
            "first_name": "Titien",
            "last_name": "Atom",
            "phone_number": "0626082019",
            "email": "lepetitnageur@4ev.er"
        },
        "type": "registered",
        "name": "Minas Tirith"
    },
    "modification_date": "2019-10-11T15:05:01.945306Z",
    "operator_info": {
        "contact_uuid": "108este8",
        "contact": {
            "first_name": "Support de la Comté",
            "last_name": "Support de la Comté",
            "phone_number": "0298712291",
            "cell_phone_number": "0298712291",
            "email": "shire@middle.earth",
            "creation_date": "2017-05-18T12:08:35.324243Z"
        }
    },
    "options": {
        "gtr": {
            "enabled": false,
            "default_value": "standard"
        },
        "portability": {
            "enabled": false
        },
        "unlisted_number": {
            "enabled": false
        },
        "internal_cabling": {
            "enabled": false,
            "value": "0-5m",
            "default_value": "0-5m"
        },
        "contract_term": {
            "enabled": true,
            "value": "36_months",
            "default_value": "12_months"
        }
    },
    "product": {
        "uuid": "b9snx9ba",
        "code": "AM01",
        "name": "ADSL-Max_FULL_BE_KOSC",
        "description": "ADSL Max * FULL unbundling * Best Effort * KOSC",
        "line": {
            "uuid": "flfwzx11",
            "name": "ADSL-Max",
            "code": "AM",
            "description": "ADSL-MAX * Best of ADSL products",
            "family": {
                "uuid": "rsvjvpsy",
                "name": "ADSL",
                "code": "A",
                "description": "ADSL * technology : ADSL, VDSL, READSL"
            }
        }
    },
    "reference": "S191011_59827",
    "starting_date": "2019-10-18T15:05:01.945031Z",
    "status": "active",
    "uuid": "ba471191-ad86-4f5a-ad39-95e1a178d82e",
    "provider_service_uuid": "edf852c0-d9d4-4939-9f47-4f6ae3e2a799",
    "bounds": [
        {
            "uuid": "2755ed3a-0872-402d-aa53-45e45355632e",
            "endpoints": [
                {
                    "uuid": "b0c73edb-a4b1-4332-9fe7-065e39c7e266",
                    "reference": "0492271978",
                    "type": "line_number",
                    "locked": true,
                    "information": {
                        "status": "active",
                        "unlisted_number": true,
                        "available_pairs": 11,
                        "max_available_pairs": 11,
                        "under_construction": false,
                        "sections_lengths": [
                            {
                                "diameter": 4,
                                "length": 1425
                            }
                        ],
                        "head": "D/31605",
                        "starter": 2,
                        "pair": 1,
                        "concentration_point": {
                            "latlng": {
                              "latitude": 48.827525,
                              "longitude": 2.454530
                            },
                            "address": {
                                "kosc_street_code": "0608859150",
                                "kosc_insee_code": "06088",
                                "street_number": "1710",
                                "street_name": "RUE DU PARADIS",
                                "city": "NICE"
                            }
                        }
                    }
                }
            ],
            "address": {
              "zipcode": "06000",
              "street_name": "RUE DU PARADIS",
              "street_number": "1710",
              "city": "NICE",
              "kosc_street_code": "0608859150",
              "kosc_insee_code": "06088",
              "housing_complex": "Gouffre de Helm"
            },
            "information": {
                "co": "06088CAR"
            }
        }
    ],
    "information": {
        "profile": "ADSL_24M"
    },
    "ticket_uuid": null
}
]

Récupérer un service¶

L'endpoint /api/v2/services/{uuid}/ permet de récupérer un service avec son identifiant uuid.

Requête :

GET /api/v2/services/52682fb7-69f1-486b-9a1f-e69c56a2d38d/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

La réponse est identique à la section précédente, avec un seul objet directement à la racine.

Actions¶

Il est possible d'exécuter des actions sur un service pour en modifier la configuration.

Liste des actions disponibles¶

Type d'action	Familles	Paramètres	Description
`change_profile`	A	profile	Changement de profil: Permet de définir un profil sur l'ensemble des ports du service (uniquement en cuivre)

Création d'une action¶

Pour créer une action, vous devez effectuer un POST sur l’url api/v2/services/{service_uuid}/actions/.

Requête :

POST /api/v2/services/f351fe3b-5721-4768-b843-e89e0228bf5b/actions/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
    "params": {
        "profile": "VDSL_17a"
    },
    "type": "change_profile"
}

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json

{
    "type": "change_profile",
    "params": {
        "profile": "ADSL_PERF2"
    },
    "status": "submitted",
    "uuid": "b815b149-14d0-48b3-b17f-320b1a21b9ff",
    "creation_date": "2019-09-13T09:40:38.838231Z",
    "termination_date": null,
    "results": {}
}

Nom du champ	Type	Description
type	string	Le type de l'action
params	dict	Les paramètres passés a l'action
uuid	string	L'UUID de l'action
status	string	Le statut de l'action (submitted\|running\|completed\|error)
creation_date	string	La date de création de l'action
termination_date	string	La date à laquelle l'action s'est terminée
results	list	La liste des erreurs ou des messages retournés.

Lister les actions d'un service¶

Pour récupérer les action d'un service, vous devez effectuer un GET sur l’URL /api/v2/services/{service_uuid}/actions/.

Requête :

GET /api/v2/services/f351fe3b-5721-4768-b843-e89e0228bf5b/actions/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "type": "change_profile",
        "params": {
            "profile": "VDSL_17a"
        },
        "uuid": "843c0s480xnuj78j9ggasrncaitsixbb",
        "status": "completed",
        "creation_date": "2018-07-02T17:14:46.7845194Z",
        "termination_date": "2018-07-02T17:15:02.214521Z",
        "results": [
            {}
        ]
    }
]

Récupération d'une action¶

Pour récupérer une action en particulier, vous devez effectuer un GET sur l'URL /api/v2/services/{service_uuid}/actions/{action_uuid}/.

Requête :

GET /api/v2/services/f351fe3b-5721-4768-b843-e89e0228bf5b/actions/b815b149-14d0-48b3-b17f-320b1a21b9ff HTTP/1.1
Host: extranet.kosc-telecom.fr

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json

{
    "type": "change_profile",
    "params": {
        "profile": "ADSL_PERF2"
    },
    "status": "submitted",
    "uuid": "b815b149-14d0-48b3-b17f-320b1a21b9ff",
    "creation_date": "2019-09-13T09:40:38.838231Z",
    "termination_date": null,
    "results": {}
}

Profils¶

Pour récupérer la liste des profils disponible sur un service (cuivre uniquement), vous devez effectuer un GET sur l'URL api/v2/services/{service_uuid}/profiles/.

Requête :

GET api/v2/services/f351fe3b-5721-4768-b843-e89e0228bf5b/profiles/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "name": "ADSL_24M"
    },
    {
        "name": "ADSL_2M"
    },
    {
        "name": "ADSL_512K"
    },
    {
        "name": "ADSL_SAFE1"
    },
    {
        "name": "ADSL_SAFE2"
    },
    {
        "name": "ADSL_PERF1"
    },
    {
        "name": "ADSL_PERF2"
    }
]

Service DLM (Dynamic Line Management)¶

Pour récupérer (consultation) le statut DLM d'un service ADSL actif Orange, vous devez effectuer un GET sur l'URL api/v2/services/{service_uuid}/dlm/.

Pour activer le blacklistage DLM d'un service ADSL actif Orange, vous devez effectuer un PUT sur l'URL api/v2/services/{service_uuid}/dlm/.

Pour désactiver le blacklistage (dé-blacklistage) le DLM d'un service ADSL actif Orange, vous devez effectuer un DELETE sur l'URL api/v2/services/{service_uuid}/dlm/.

Codes Retour

Lorsque la requête se déroule normalement, un status HTTP 200 ainsi qu'une payload sont retournés.

Requête	Code	Detail
Blacklistage	B00	Le blacklistage du ND % à bien été transmit
Dé-blacklistage	D00	Le dé-blacklistage du ND % à bien été transmit
Consultation	C00	Le ND % est inclus dans la liste d’exclusion
Consultation	C02	Le ND % n’est pas inclus dans la liste d’exclusion

Requête GET:

GET api/v2/services/f351fe3b-5721-4768-b843-e89e0228bf5b/dlm/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "C00",
    "detail": "The ND 0123456789 is blacklisted",
}

Requête PUT:

PUT api/v2/services/f351fe3b-5721-4768-b843-e89e0228bf5b/dlm/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "B00",
    "detail": "The ND 0123456789 has been blacklisted",
}

Requête DELETE:

DELETE api/v2/services/f351fe3b-5721-4768-b843-e89e0228bf5b/dlm/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Réponse :

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": "D00",
    "detail": "The ND 0123456789 has been unblacklisted",
}

Codes Erreurs

Dans l'un des cas suivants :

Aucun service actif ADSL Orange avec cet UUID,
Le ND associé au service est inconnu du service DLM,
Le ND associé au service est mal formé,

la requête renvoie un statut 404, le champ error de la payload contient une description de l'erreur

Dans le cas suivant :

Le service DLM renvoie une erreur,

la requête renvoie un statut 404, le champ code de la payload contient le code erreur DLM, le champ error de la payload contient une description de l'erreur.

Requête	Code	Detail
Blacklistage	B01	Le ND % n’appartient pas à l’opérateur
Blacklistage	B02	L’offre du ND n’est pas compatible avec DLM
Blacklistage	B03	Une signalisation est en cours pour le ND %
Blacklistage	B04	Le quota contrôle par minute a été dépassé (appel IpSite)
Blacklistage	B05	Le quota contrôle par jour a été dépassé (appel IpSite)
Blacklistage	B06	Le ND % est déjà blacklisté
Blacklistage	B07	Le quota de blacklistage par minute a été dépassé (appel Gamba)
Blacklistage	B08	Le quota de blacklistage par jour a été dépassé (appel Gamba)
Blacklistage	B09	Le ND % renseigné est inconnu pour l’opérateur
Blacklistage	B96	Erreur interne
Blacklistage	B97	Erreur interne
Blacklistage	B98	Erreur interne
Blacklistage	B99	Erreur interne
Dé-blacklistage	D01	Le ND % n’appartient pas à l’opérateur
Dé-blacklistage	D02	L’offre du ND % n’est pas compatible avec DLM
Dé-blacklistage	D03	Une signalisation est en cours (%état%) pour le ND %
Dé-blacklistage	D04	Le quota par minute n été dépassé
Dé-blacklistage	D05	Le quota par jour n été dépassé
Dé-blacklistage	D06	Le ND % n’est pas blacklisté
Dé-blacklistage	D96	Erreur interne
Dé-blacklistage	D97	Erreur interne
Dé-blacklistage	D98	Erreur interne
Dé-blacklistage	D99	Erreur interne
Consultation	C01	Le ND % n’appartient pas à l’opérateur
Consultation	C04	Le quota par minute à été dépassé
Consultation	C05	Le quota par jour à été dépassé
Consultation	C09	Le ND % n’appartient pas à l’opérateur
Consultation	C96	Erreur interne
Consultation	C98	Erreur interne
Consultation	C99	Erreur interne