Services

The API /api/v2/services/ allows you to retrieve the links delivered by Kosc.

Note

This API (known as v2) replaces: ref:API v1 <services_v1>, now deprecated. You are welcome to migrate to this unified API now. The API is directly compatible with the old fiber API.

The base URL for this API is : https://extranet.kosc-telecom.fr/api/v2/services/.

Services are read-only.

API Summary

Action	Method	URL
List the services	GET	/api/v2/services/
Retrieve a service	GET	/api/v2/services/{uuid}/

Migrate a service copper to FTTH

To mmigrate a copper service to FTTH, it is necessary to create a new FTTH order and terminate the copper order independently.

Create an order to migrate from the Service

Request POST:

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

{
  "imb": ""
}

Response :

• If an Order is created successfully

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

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

• If an Order already exists for this Service

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

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

• If the address of the Service is not eligible

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

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

• If the address of the Service has multiple IMB

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

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

In this case, resume the Request specifying the IMB to use.

• If the address does not have an 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"
}

Fields

This section describes the fields of an object service.

Field Name	Type	Description
uuid	string	Unique universal identifier (32 hexadecimal characters in canonical form).
reference	string	Kosc commercial reference of the service in format SYYMMDD_XXXXX.
status	string	Service status. Possible values : - active : service active - terminated : service terminated
activate_order_ref	string	Kosc commercial reference of the order that was used to create this service.
activate_order_uuid	string	Order identifier that was used to create this service.
activation_date	ISO datetime	Service activation date.
starting_date	ISO datetime	Billing start date.
creation_date	ISO datetime	Service creation date.
modification_date	ISO datetime	Last modification date of the service.
current_order_uuid	string	Identifier of the cancellation order in progress on this service, if applicable, null autrement.
current_order_type	string	Type of current order on the service (null or terminate).
product	object	Product information of the service. Defines the type of service, the technology, the speed, the possible options.
product[uuid]	string	Product Reference.
product[code]	string	Product Code.
product[name]	string	Product Name.
product[description]	string	Product Description.
product[line]	object	Product Line.
product[line][uuid]	string	Product line reference.
product[line][code]	string	Product Line Code.
product[line][name]	string	Name of the product line.
product[line][description]	string	Description of the product line.
product[line][family]	object*	Product Family.
product[line][family][uuid]	string	Reference of the product family.
product[line][family][code]	string	Code of the product family.
product[line][family][name]	string	Name of the product family.
product[line][family][description]	string	Description of the product family
end_customer[type]	string	Type of end customer. Possible values : - registered : company with SIRET number, - unregistered : company without SIRET number, - individual : particular client.
end_customer[name]	string	Last Name of the end customer (company). To be filled in if end_customer[type] is registered or unregistered.
end_customer[first_name]	string	First Name of the end customer.To be filled in if end_customer[type] is individual.
end_customer[last_name]	string	Last name of end customer. To be filled in if end_customer[type] is individual.
end_customer[siret]	string	SIRET number of the company. To be filled in if end_customer[type] is registered.
end_customer[contact]	string	Contact information of the end customer, used to contact them in case of need.
end_customer[contact][first_name]	string	First Name of the contact.
end_customer[contact][last_name]	string	Last name of Contact
end_customer[contact][email]	string	E-mail du contact.
end_customer[contact][phone_number]	string	Primary Phone Contact.
end_customer[contact][cell_phone_number]	string	Cell phone contact.
operator_info	object	Operator information.
operator_info[contact_uuid]	string	Reference of the operator contact to contact regarding this service.
bounds	list	Order delivery points (end of line). For copper and fiber orders, this listing includes only one item.
bounds[uuid]	string	Unique identifier of the endpoint (32 hexadecimal characters in canonical form).
bounds[address]	string	End address. This address can only be changed if the type of eligibility allows it.
bounds[address][street_number]	string	Street Number.
bounds[address][street_name]	string	Name of the street.
bounds[address][kosc_street_code]	string	Kosc street code identifier.
bounds[address][kosc_insee_code]	string	Kosc INSEE Code of the locality.
bounds[address][zipcode]	string	Code postal.
bounds[address][city]	string	City.
bounds[address][housing_complex]	string	Group of buildings or name of the residence (if applicable).
bounds[address][building_code]	string	Building Code (if applicable).
bounds[address][building]	string	Building Name (if applicable).
bounds[address][stairs]	string	Stairs (if applicable).
bounds[address][floor]	string	Floor (if applicable).
bounds[address][door]	string	Door (if applicable).
bounds[address][logo]	string	Copper : Logo (France Telecom or Orange copper plate) on the customer’s door (if applicable).
bounds[information]	string	Additional endpoint information (product and technology specific).
bounds[information][co]	string	NRO or NRA name (if this information is available).
bounds[endpoints]	list	List of endpoints on one end. This list includes several elements in the case of a multi-pair copper product, only one otherwise.
bounds[endpoints][n][uuid]	string	Identifier of an endpoint (32 hexadecimal characters in canonical form)
bounds[endpoints][n][reference]	string	Endpoint reference
bounds[endpoints][n][type]	string	Endpoint type. Possible values : - OTP (fiber) - line_number (copper)
bounds[endpoints][n][locked]	boolean	Indicates whether or not the user can modify endpoint (determined by the type of eligibility that allowed the order to be created).
bounds[endpoints][n][information]	object	Additional endpoint information (product and technology specific).
options	object	Options activated on the service. Consult API orders for an indicative list.
information	object	Additional service information (product specific).
information.profile	object	Copper : DSL profile in effect on the service.
ticket_uuid	String	Unique identifier of the ticket opened on the service, if applicable, null if not.

ENNI Service

Some fields are specific to products of type enni :

Field Name	Type	Description
information[ennis][0][reference]	string	Company products (E-Access Fiber et SDSL) : Kosc reference of the ENNI service on which the traffic is delivered
information[ennis][0][uuid]	string	Company products (E-Access Fiber et SDSL) : ENNI identifier service on which the traffic is delivered
information[ennis][0][vlan]	string	Company products (E-Access Fiber and SDSL) : VLAN reference used on the ENNI

Collection ports

Some fields are specific to products of type ENNI (collection port) :

Field Name	Type	Description
information[pop]	object	Point-of-Presence (POP) information on which the port is delivered
information[pop][code]	String	POP Code
information[pop][address]	String	POP address
information[pop][housing]	String	Name of the host
information[pop][interface]	String	ENNI interface type, null otherwise.

Lister les services

The endpoint api/v2/services/ allows you to list all the services.

It is possible to filter on several fields :

• reference: search by service reference

• status: search by status: active, terminated

• endpoint_ref: search by endpoint reference

• end_customer: search by end customer name

• product: search by product code

• product_family: search by product family

• product_line: search by product line

Request :

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

Response :

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

Retrieve a service

The endpoint /api/v2/services/{uuid}/ allows you to retrieve a service with its identifier uuid.

Request :

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

The answer is identical to the previous section, with a single object directly at the root.

Actions

It is possible to perform actions on a service to modify its configuration.

List of available action

Type of action	Families	Parameters	Description
change_profile	A	profile	Profile change: Allows you to define a profile on all the ports of the service (copper only)

Creation of an action

To create an action, you must perform a POST on the api/v2/services/{service_uuid}/actions/.

Request :

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

Response :

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": {}
}

Field Name	Type	Description
type	string	The type of action
params	dict	Parameters passed to the action
uuid	string	The UUID of the action
status	string	The status of the action (submitted|running|completed|error)
creation_date	string	Date of creation of action
termination_date	string	The date the action ended
results	list	The list of errors or messages returned.

List the actions of a service

To retrieve an action of an service, you must perform a GET on /api/v2/services/{service_uuid}/actions/.

Request :

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

Response :

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": [
            {}
        ]
    }
]

Retrieving an action

To retrieve an action in particular, you must perform a GET sur l’URL /api/v2/services/{service_uuid}/actions/{action_uuid}/.

Request :

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

Response :

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": {}
}

Profiles

To retrieve the list of profiles available on a service (copper only), you must perform a GET on the URL api/v2/services/{service_uuid}/profiles/.

Request :

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

Response :

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

Dynamic Line Management (DLM) Service

To consult the DLM status of an active ADSL Orange service, you must issue a GET on URL api/v2/services/{service_uuid}/dlm/.

To activate the blacklisting (blacklist) the DLM on an active ADSL Orange service, you must issue a PUT on URL api/v2/services/{service_uuid}/dlm/.

To deactivate the blacklisting (unblacklist) the DLM on an active ADSL Orange service, you must issue a DELETE on URL api/v2/services/{service_uuid}/dlm/.

Response codes

If the request completes normally, a status HTTP 200 and a payload are returned.

Request	Code	Detail
Blacklist	B00	The ND % has been blacklisted
Unblacklist	D00	The ND % has been unblacklisted
Consult	C00	The ND % is blacklisted
Consult	C02	The ND % is not blacklisted

GET request:

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

Response :

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

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

PUT request:

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

Response :

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

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

DELETE request:

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

Response :

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

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

Error codes

In one of these cases :

• Missing active Orange ADSL service with this UUID,

• The associated ND is is unknown to the DLM service,

• The associated ND is malformed,

the request returns a 404 status, the field error of the payload contains a description of the error

In this case :

• The DLM service returns an error,

the request returns a 404 status, the field code of the payload contains the error code DLM, the field error of the payload contains a description of the error.

Request	Code	Detail
Blacklist	B01	The ND % is unknown to the operator
Blacklist	B02	L’offre du ND n’est pas compatible avec DLM
Blacklist	B03	Une signalisation est en cours pour le ND %
Blacklist	B04	The quota per minute has been exceeded
Blacklist	B05	The quota per day has been exceeded
Blacklist	B06	The ND % is already blacklisted
Blacklist	B07	The quota per minute has been exceeded
Blacklist	B08	The quota per day has been exceeded
Blacklist	B09	The ND % is unknown to the operator
Blacklist	B96	Internal error
Blacklist	B97	Internal error
Blacklist	B98	Internal error
Blacklist	B99	Internal error
Unblacklist	D01	The ND % is unknown to the operator
Unblacklist	D02	L’offre du ND % n’est pas compatible avec DLM
Unblacklist	D03	Une signalisation est en cours (%état%) pour le ND %
Unblacklist	D04	The quota per minute has been exceeded
Unblacklist	D05	Le quota par jour n été dépassé
Unblacklist	D06	The ND % is not blacklisted
Unblacklist	D96	Internal error
Unblacklist	D97	Internal error
Unblacklist	D98	Internal error
Unblacklist	D99	Internal error
Consult	C01	The ND % is unknown to the operator
Consult	C04	The quota per minute has been exceeded
Consult	C05	The quota per day has been exceeded
Consult	C09	The ND % is unknown to the operator
Consult	C96	Internal error
Consult	C98	Internal error
Consult	C99	Internal error