Orders

The API /api/v2/orders/ allows to order in a unified way the Copper and Fiber products of Covage. To get started, see the description of the order process which explains the different concepts needed to get started with the API.

Note

This API (known as v2) replaces l’API v1, which is now deprecated. You are welcome to migrate to this unified API. The API is directly compatible with the old fiber API, unlike the URL. To facilitate your development, all orders placed on one of the two versions of the API are available and modifiable via the other.

The base URL for this API is : https://extranet.kosc-telecom.fr/api/v2/orders/. This page refers to the product families defined in the product cataog.

API Summary

Action

Method

URL

Order Creation

POST

/api/v2/orders/

Modify an order

PATCH

/api/v2/orders/{uuid}/

Modify an endpoint reference or the OTP of an order

PATCH

/api/v2/orders/{uuid}/endpoints/{endpoint_uuid}/

Modify the address of an order

PATCH

/api/v2/orders/{uuid}/bounds/{bounds_uuid}/

Submit the order

PATCH

/api/v2/orders/{uuid}/

List of orders

GET

/api/v2/orders/

Retrieving an order

GET

/api/v2/orders/{uuid}/

Common Fields activate and terminate

This section describes the fields of an order object (modeling an order)

The third column indicates if the parameter is mandatory when creating the draft (O), if it should have been completed before submitting the order (S), if it is optional/facultative (F), if it can be mandatory depending on the type of product, the options chosen or another parameter (C), or if it is read-only (R).

Name of the parameter

Type

Mandatory

Description

type

string

O

activate ou terminate

uuid

string

R

Unique universal identifier (32 hexadecimal characters in canonical form).

reference

string

R

Kosc commercial reference of the order in format OYYMMDD_XXXXX.

status

string

R

Order status. Can only be changed when submitting an order.

comment

string

F

Specific information for Kosc to facilitate the processing of the order.

product

object

C

Information on the chosen product. Defines the type of service, the technology, the speed, the possible options.

product[code]

string

C

Product Code.

product[name]

string

R

Name of the product.

product[description]

string

R

Description of product.

product[line]

object

R

Product Line.

product[line][code]

string

R

Code of Product Line.

product[line][name]

string

R

Name of product Line.

product[line][description]

string

R

Description of Product Line.

product[line][family]

object

R

Product Family.

product[line][family][code]

string

R

Code of Product Family.

product[line][family][name]

string

R

Name of product family.

product[line] family[description]

string

R

Description of product family

end_customer

object

S

Information on the end customer. Pre-filled in case of order cancellation.

end_customer[type]

string

S

Type of end customer. Possible values :
- registered : entreprise having a SIRET number,
- unregistered : entreprise without a SIRET number,
- individual : particular client.

end_customer[name]

string

C

Name of end customer (entreprise). To be filled in if end_customer[type]``is ``registered or unregistered.

end_customer[first_name]

string

C

First Name of the end customer. To be filled in if end_customer[type] is individual.

end_customer[last_name]

string

C

Last Name of the end customer. To be filled in if end_customer[type] is individual.

end_customer[siret]

string

C

SIRET number of the company. To be filled in if end_customer[type] is registered.

end_customer[contact]

object

C

Contact information of the end customer, used to contact them in case of need.

end_customer[contact][first_name]

string

S

First Name of the contact.

end_customer[contact][last_name]

string

S

Last Name of the contact

end_customer[contact][email]

string

S

E-mail of contact.

end_customer[contact][phone_number]

string

C

Telephone number of the contact.

end_customer[contact][cell_phone_number]

string

C

Mobile phone number of the contact.

operator_info

object

S

Operator Information.

operator_info[order_ref]

string

S

Order reference in your information system. This reference must be unique for all orders placed with Kosc.

operator_info[order_name]

string

S

Name of the order displayed on the extranet.

operator_info[contact_uuid]

string

S

Reference of the operator contact to be contacted regarding this order. Prefilled in case of an order cancellation. The value is pre-filled if the operator has a default contact.

options

dictionary

F

The value of the options depends on the type of order and the product chosen. The API products allows you to retrieve the available values.

information

object

C

Additional ordering information (particularly product and technology).

submission_date

ISO datetime

R

Date of order submission

acknowledged_date

ISO datetime

R

Date of consideration of the order by Kosc

processing_date

ISO datetime

R

Start date of effective processing of the order.

completion_date

ISO datetime

R

Date of placing the order in status completed

cancellation_date

ISO datetime

R

Date of placing the order in status cancelled

rejection_date

ISO datetime

R

Date of placing the order in status rejected

creation_date

ISO datetime

R

Date of draft creation of the order

modification_date

ISO datetime

R

Date of order modification

updated_status_date

ISO datetime

R

Date of last modification of the status of the order

allow_second_rdv

Only to “FP05” products: set to false for create commands (default value), set to true or false for activate_defined and activate_undefined commands. When set to true, it requires technician intervention for installing the ONT on an FP05 product; when set to false, no intervention is needed.

boolean

F

address_second_rdv

Only to “FP05” products and create commands, this address will be used to deliver the equipment.

object

F

Order Creation

An order is created with a POST on the endpoint /api/v2/orders/.

Note

A number of fields are subject to character restrictions for compatibility with our suppliers. In particular, all the characters used for the end_customer and bounds fields must be part of the following list (space and non-breaking space accepted): () +, -. 0123456789: ABCDEFGHIJKLMNOPQRSTUVWXYZ @ [] _ ​​abcdefghijklmnopqrstuvwxyz {} àâäçèéêëîïôöùûü.

Order activate

Please note that a service creation command is made through an eligibility request.

The third column specifies whether this field is specific to a family of products (if it is empty, it is common to all orders).

Options

A number of options can be specified. Their availability and values depend on the selected product and the order type.

Note

Please note that only the product catalog and products API are evidence of the options available and their values. This list is provided for information only.

Name of the parameter

Type

Family

Description

options[gtr]

object

A/S/M/F/E

Option Garanteed Time to Repair (GTR).

options[contract_term]

object

A/S/M/F/E

Contract term option.

options[internal_cabling]

object

A/S/M/E

Option Internal Cabling (Internal Cabling).

options[portability]

object

A/S/M

Option Number Portability (specific subfields, see below)

options[unlisted_number]

object

A/S/M

Option unlisted number.

options[patch_panel]

object

E

Patch Panel Option (installation in an optical strip).

options[enni_redundancy]

object

S/E

Option ENNI security.

options[cpe_install]

object

F

CPE Install option (boolean)

options[installation_expert]

object

F

Installation Expert option (with value)

options[guaranteed_bandwidth]

object

F

Option Guaranteed Bandwidth (with value)

options[demarcation_device]

object

F

Option demarcation_device (boolean)

options[double_otp]

object

F

Option double OTP (boolean). Only ‘create’ orders

options[otp_displacement]

object

F

Option OTP displacement (boolean). Only ‘activate’ orders

options objects:

There are 2 generic types of options: boolean options (enabled or not) and options with values (enabled or not + value).

Boolean Options:

enabled

boolean

true if option enabled, default false

Options avec valeur :

enabled

boolean

true if option enabled, default false

value

string

value of the option if enabled

default_value

string

default value of the option

Option Portability. This option has specific fields

enabled

boolean

true to activate the option Portability.

prefix_code

string

Fill in the prefix_code.

rio_code

string

Fill in the rio_code.

contract_ref

string

Readonly field. Automatically filled with our portability contract reference.

operator_code

string

Readonly field. Automatically filled with our operator code.

Bounds

For copper orders, field bounds[n][endpoints][m].information contains the following :

Field name

Type

Description

inactive

boolean

Indicates whether the endpoint is inactive

unlisted_number

boolean

Indicates if the phone number is unlisted

dti_presence

boolean

Presence of an Interior Termination Device

available_pairs

Integer

Number of pairs available at the Point of Concentration (PC)

max_available_pairs

Integer

Number of pairs available at the Point of Concentration (PC) serving the address and having the most pairs available

under_construction

boolean

Indicates if the line is under construction

sections_lengths

liste d’objects

List of copper lengths that make up the line

sections_lengths[n][diameter]

float

Diameter (in millimeters) of the copper wire of the section n

sections_lengths[n][length]

float

Length (in meters) of the copper wire of the section n

concentration_point

object

concentration point information

concentration_point[latlng]

object

Geographical coordinates of the point of concentration

concentration_point[address]

object

Address of the concentration point

ONT installation intervention.

For fiber commands on FP05 products:

Field name

Type

Description

allow_second_rdv

boolean

If set to true, allows scheduling an appointment for ONT installation (only for activate_defined and activate_undefined commands). If set to false, no appointment is scheduled.

Example of creating an FP05 fiber command with scheduling a second appointment for ONT installation:

allow_second_rdv option for fiber orders on FP05 products of type activate_defined and activate_undefined :

Request :

POST /api/v2/orders/  HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "eligibility_ref": "elig-0e22a184-1c89-4fc3-ac25-ab3c3b67fa52",
  "product": {
    "code": "FP05"
  },
  "type": "activate",
  "request_type": "activate_defined",
  "allow_second_rdv": true
}

Field name

Type

Description

address_second_rdv

object

Second address for equipment delivery, contains the fields zipcode, city, street_number, street_name

Example of a FP05 fiber order with a second delivery address:

address_second_rdv option for fiber orders on FP05 products:

Request :

POST /api/v2/orders/  HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "eligibility_ref": "elig-0e22a184-1c89-4fc3-ac25-ab3c3b67fa52",
  "product": {
    "code": "FP05"
  },
  "address_second_rdv": {
    "zipcode": "76000",
    "city": "Rouen",
    "street_number": 1,
    "street_name": "Rue de la république"
  }
}

Example of copper order creation

Request :

POST /api/v2/orders/  HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "eligibility_ref": "elig-40ea0561-599a-4850-9add-578ddfafa713",
  "product": {
    "code": "AM01"
  },
  "type": "activate",
  "request_type": "activate"
}

Response :

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

{
  "uuid": "2e4c08a6-17a7-4ed5-97ca-6425301cd96d",
  "reference": "O191016_32563",
  "status": "draft",
  "type": "activate",
  "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"
      }
    }
  },
  "end_customer": {},
  "operator_info": {},
  "bounds": [
    {
      "uuid": "8d581539-29fa-40f8-aa28-2f4bd0275cbb",
      "endpoints": [
        {
          "uuid": "6b9dc5a5-5a21-436e-a6f5-41f2dab96d75",
          "reference": "0417101993",
          "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": 1125
              }
            ],
            "concentration_point": {
              "latlng": {
                "latitude": 43.7701894,
                "longitude": 7.3430288
              },
              "address": {
                "kosc_street_code": "0608859150",
                "kosc_insee_code": "06088",
                "street_number": "00022",
                "street_name": "BD SAINT ROCH",
                "city": "NICE"
              }
            }
          }
        }
      ],
      "address": {
        "kosc_street_code": "0608859150",
        "kosc_insee_code": "06088",
        "zipcode": "06000",
        "street_name": "BOULEVARD SAINT ROCH",
        "street_number": "22",
        "city": "NICE",
        "floor": "00",
        "housing_complex": "SHINOVAR"
      },
      "information": {
        "co": "06088CAR"
      }
    }
  ],
  "options": {},
  "creation_date": "2019-10-16T09:59:04.541090Z",
  "modification_date": "2019-10-16T09:59:04.541120Z",
  "updated_status_date": "2019-10-16T09:59:04.544397Z",
  "information": {},
  "eligibility_ref": "elig-40ea0561-599a-4850-9add-578ddfafa713",
  "request_type": "activate"
}

Example of creation of a fiber pro order

Request :

POST /api/v2/orders/  HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "eligibility_ref": "elig-0e22a184-1c89-4fc3-ac25-ab3c3b67fa52",
  "product": {
    "code": "FP01"
  },
  "type": "activate",
  "request_type": "activate_defined"
}

Response :

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

{
  "uuid": "281a64c0-5cfe-4607-8978-096ac96afa08",
  "reference": "O191008_93792",
  "status": "draft",
  "type": "activate",
  "product": {
    "uuid": "v7cqyjdb",
    "code": "FP01",
    "name": "PROFESSIONAL-FIBER 1000",
    "description": "PROFESSIONAL FIBER 1000/250 Mbit/s",
    "line": {
      "uuid": "5emhd73x",
      "name": "PRO-FIBER",
      "code": "FP",
      "description": "Professional Fiber",
      "family": {
        "uuid": "yy2ekd7i",
        "name": "FIBR",
        "code": "F",
        "description": "Fiber Pro"
      }
    }
  },
  "end_customer": {},
  "operator_info": {},
  "bounds": [
    {
      "uuid": "265bd4ea-5c1f-462d-8689-e75585c0b24f",
      "endpoints": [
        {
          "uuid": "266979a7-16cd-43df-98f0-3fe156dad9cd",
          "reference": "FI-3790-3415",
          "type": "otp",
          "locked": true
        }
      ],
      "address": {
        "kosc_street_code": "9307700800",
        "kosc_insee_code": "93077",
        "zipcode": "93250",
        "street_name": "BOULEVARD D AULNAY",
        "street_number": "78",
        "city": "VILLEMOMBLE",
        "building_name": "6",
        "building_code": "IMB/93077/X/00ZY",
        "stairs": "6",
        "floor": "0"
      },
      "information": {
        "co": "93064RNY"
      }
    }
  ],
  "options": {
    "contract_term": {
      "enabled": true,
      "value": "36_months",
      "default_value": "12_months"
    }
  },
  "creation_date": "2019-10-08T13:14:04.230252Z",
  "modification_date": "2019-10-08T13:14:04.440080Z",
  "updated_status_date": "2019-10-08T13:14:04.440110Z",
  "information": {},
  "eligibility_ref": "elig-0e22a184-1c89-4fc3-ac25-ab3c3b67fa52",
  "request_type": "activate_defined"
}

Order terminate

Please note that a termination order is made from a service reference. Cancellation orders are currently only available on Copper products (families A, S and M) and Fiber Pro products (family F).

Note

Please note that termination orders are taken into account as soon as they are submitted and lead to the immediate termination of the service. Please contact the Delivery service to initiate a notice of termination, then submit the terminate order at the end of this notice to terminate the service.

Name of the parameter

Type

Family

Mandatory

Description

service_ref

string

A/S/M/F

O

Kosc commercial reference of the service to be terminated (mandatory if service_uuid is not provided).

service_uuid

string

A/S/M/F

O

Service ID to be terminated (UUID on 32 hexadecimal characters) (mandatory if service_ref is not provided).

Example of creation of termination order

Request :

POST /api/v2/orders/  HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "service_uuid":"38873eab-b099-4095-9042-91dfd896e225",
  "type": "terminate"
}

Response :

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

{
  "uuid": "7d8e7c90-7705-49d6-8b94-972b04be4313",
  "reference": "O191210_49595",
  "status": "draft",
  "type": "terminate",
  "service_ref": "S191128_21428",
  "service_uuid": "38873eab-b099-4095-9042-91dfd896e225",
  "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"
      }
    }
  },
  "end_customer": {
    "siret": "81352886600029",
    "contact": {
      "first_name": "Titien",
      "last_name": "Atom",
      "phone_number": "0626082019",
      "email": "lepetitnageur@4ev.er"
    },
    "type": "registered",
    "name": "Minas Tirith"
  },
  "operator_info": {
    "contact_uuid": "108este8"
  },
  "bounds": [
    {
      "uuid": "36fbac69-da7e-4573-8e49-95d8b911a44d",
      "endpoints": [
        {
          "uuid": "3b653072-01d0-49ba-8ddb-7c89d3a71d06",
          "reference": "0471494704",
          "type": "line_number",
          "locked": false,
          "information": {
            "dti_presence": false,
            "sections_lengths": [
              {
                "diameter": 60.0,
                "length": 1423.0
              }
            ],
            "head": "D/52621",
            "starter": 20,
            "pair": 7,
            "concentration_point": {
              "latlng": {
                "latitude": 48.827525,
                "longitude": 2.454530
              },
              "address": {
                "kosc_street_code": "0608859150",
                "kosc_insee_code": "06088",
                "street_number": "00000",
                "street_name": "BD SAINT ROCH",
                "city": "NICE"
              }
            }
          }
        }
      ],
      "address": {
        "zipcode": "06000",
        "street_name": "RUE DU PARADIS",
        "street_number": "1710",
        "city": "NICE",
        "kosc_street_code": "0608859150",
        "kosc_insee_code": "06088"
      },
      "information": {
        "co": "06088CAR"
      }
    }
  ],
  "options": {},
  "creation_date": "2019-12-10T16:14:18.128496Z",
  "modification_date": "2019-12-10T16:14:18.128516Z",
  "updated_status_date": "2019-12-10T16:14:18.132325Z",
  "information": {}
}

Modify an order

As long as the order has not been submitted, you can modify its parameters with a request PATCH on the URL /api/v2/orders/{uuid}/.

Request :

PATCH /api/v2/orders/b5866d6b-55af-4085-bc0c-ac8490cae38f/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "end_customer": {
    "type": "unregistered",
    "name": "Alethkar Palace",
    "contact": {
      "first_name": "Adolin",
      "last_name": "Kholin",
      "email": "adolin.kholin@palace.ak",
      "phone_number": "0123456789"
    }
  },
  "operator_info": {
    "order_ref": "STORMLIGHT_1991",
    "order_name": "Alethkar_Palace_Order_1",
    "contact_uuid": "8w10yfnb"
  },
  "options": {
    "contract_term": {
      "enabled": true,
      "value": "36_months"
    }
  }
}

Response :

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

{
  "uuid": "b5866d6b-55af-4085-bc0c-ac8490cae38f",
  "reference": "O191016_58767",
  "status": "draft",
  "type": "activate",
  "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"
      }
    }
  },
  "end_customer": {
    "contact": {
      "first_name": "Adolin",
      "last_name": "Kholin",
      "email": "adolin.kholin@palace.ak",
      "phone_number": "0123456789"
    },
    "type": "unregistered",
    "name": "Alethkar Palace"
  },
  "operator_info": {
    "order_ref": "STORMLIGHT_1991",
    "order_name": "Alethkar_Palace_Order_1",
    "contact_uuid": "8w10yfnb"
  },
  "bounds": [
    {
      "uuid": "e09b71a2-3b37-4ad0-9738-cc35a24bb538",
      "endpoints": [
        {
          "uuid": "7e2eab64-1034-41c3-bfac-dbd4367f66d9",
          "reference": "0417101993",
          "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
              }
            ],
            "concentration_point": {
              "latlng": {
                "latitude": 43.0717135,
                "longitude": 7.2930888
              },
              "address": {
                "kosc_street_code": "0608859150",
                "kosc_insee_code": "06088",
                "street_number": "00022",
                "street_name": "BD SAINT ROCH",
                "city": "NICE"
              }
            }
          }
        }
      ],
      "address": {
        "kosc_street_code": "0608859150",
        "kosc_insee_code": "06088",
        "zipcode": "06000",
        "street_name": "BOULEVARD SAINT ROCH",
        "street_number": "22",
        "city": "NICE",
        "floor": "00",
        "housing_complex": "RADIANT HOUSE"
      },
      "information": {
        "co": "06088CAR"
      }
    }
  ],
  "options": {
    "contract_term": {
      "enabled": true,
      "value": "36_months",
      "default_value": "12_months"
    }
  },
  "creation_date": "2019-10-16T08:08:55.883532Z",
  "modification_date": "2019-10-16T10:15:17.979894Z",
  "updated_status_date": "2019-10-16T10:15:17.979948Z",
  "information": {},
  "eligibility_ref": "elig-6ac6874f-2827-4a26-9875-5b54d09dc900",
  "request_type": "activate"
}

Get the verticality :

The endpoint /api/v2/eligibility/buildings/{building_ref}/?include_stairs=true allows you to retrieve the name of the building, the staircase and the floor of the end customer for fiber orders by entering the building code

Request :

GET /api/v2/eligibility/buildings/{building_ref}/?include_stairs=true HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

Response :

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

{
"operator_code": "FI",
"operator_name": "ORANGE",
"name": "B",
"building_ref": "IMB/76540/X/043X",
"type": "BUILDING",
"nro": "76540ROA",
"stairs": {
    "NA^1": [
        "0",
        "1",
        "2",
        "3",
        "4",
        "5"
    ]
},
"address": {
    "street_number": "7",
    "street_name": "RUE MARTIN FRERES",
    "kosc_street_code": "765405510",
    "kosc_insee_code": "76540",
    "city": "ROUEN",
    "zipcode": "76000"
},
"code_interop": "FTEL",
"code_l331": "FRTE",
"reference_pm": "FI-76540-00AI",
"latitude": "49.448179",
"longitude": "1.076237"
}

Get the verticality with PTO:

The endpoint ``/api/v2/eligibility/buildings/{building_ref}/?include_otp_ref=true``allows you to retrieve the name of the building, the staircase and the floor of the end customer for fiber orders with the PTO per floor by entering the building code

Requête :

GET /api/v2/eligibility/buildings/{building_ref}/?include_otp_ref=true HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

Réponse :

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

{
"operator_code": "FI",
"operator_name": "ORANGE",
"name": "B",
"building_ref": "IMB/76540/X/043X",
"type": "BUILDING",
"nro": "76540ROA",
"stairs_with_otp_ref": {
    "NA^1": {
        "0": [
            "FI-4672-5988",
            "FI-6401-6327",
            "FI-4576-7338",
            "FI-9036-9302",
            "FI-1578-4925",
            "FI-8222-0216",
            "FI-4572-1600"
        ],
        "1": [
            "FI-5453-5482",
            "FI-6023-2052",
            "FI-6250-6687",
            "FI-4645-7016",
            "FI-6149-6667",
            "FI-4574-9232",
            "FI-3649-6891"
        ],
        "2": [
            "FI-4596-2929",
            "FI-5262-3682",
            "FI-4566-4477"
        ],
        "3": [
            "FI-4567-7193",
            "FI-3370-1120",
            "FI-4566-6655",
            "FI-7392-0276",
            "FI-5088-1249",
            "FI-9987-4127",
            "FI-8307-5400"
        ],
        "4": [
            "FI-8403-5645",
            "FI-4565-3752",
            "FI-4941-3838",
            "FI-5749-8255",
            "FI-8543-4933",
            "FI-1683-7394"
        ],
        "5": [
            "FI-4565-9406",
            "FI-4565-8779"
        ]
    }
},
"address": {
    "street_number": "7",
    "street_name": "RUE MARTIN FRERES",
    "kosc_street_code": "765405510",
    "kosc_insee_code": "76540",
    "city": "ROUEN",
    "zipcode": "76000"
},
"code_interop": "FTEL",
"code_l331": "FRTE",
"reference_pm": "FI-76540-00AI",
"latitude": "49.448179",
"longitude": "1.076237"
}

Update the address of an order

The endpoint /api/v2/orders/{order_uuid}/bounds/{bound_uuid}/ allows you to enter the staircase and the floor of the end customer for fiber orders (to be entered when the request_type value is equal to create or activate_undefined), it also allows to update the value of street_number for copper orders (to be informed when the value request_type is equal to create_neighbour Otherwise, these values will be filled in automatically by the platform.

Request :

PATCH /api/v2/orders/e9a9b366-82cf-4712-bf75-7e6fcacdb093/bounds/22036e32-5e6d-4736-9a95-ef0fb800635d/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "address": {
    "stairs": "C",
    "floor": "1"
  }
}

Response :

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

{
    "uuid": "22036e32-5e6d-4736-9a95-ef0fb800635d",
    "endpoints": [
        {
            "uuid": "2a2cd9e7-8310-46eb-80c0-e10cba79e3fa",
            "type": "otp",
            "locked": false,
            "ont": {}
        }
    ],
    "address": {
        "zipcode": "94170",
        "street_name": "AVENUE PIERRE BROSSOLETTE",
        "street_number": "151B",
        "city": "LE PERREUX SUR MARNE",
        "stairs": "C",
        "floor": "1",
        "kosc_street_code": "940587147",
        "building_code": "IMB/94058/C/NGA3",
        "kosc_insee_code": "94058"
    },
    "information": {
        "co": "94033FNY"
    }
}

Request to update the street number :

PATCH /api/v2/orders/06feced5-82bd-4faf-8948-d79fc4b967d3/bounds/ca3ceeaf-b09d-43a2-b614-355baaabe69e/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "address": {
    "street_number": "24"
  }
}

Update the OTP reference of an order

This endpoint, reserved for fiber orders, is used to enter the reference of the OTP socket, to be entered when the value request_type is equal to activate_defined. It is therefore necessary to update the request_type field of the command before being able to update the OTP reference.

When filling in an OTP reference, the platform will query an external service to determine the values for the staircase (stairs) and the floor (floor) associated with this reference. It is strongly recommended to check that these values correspond to the address communicated by the customer to avoid errors and order rejections.

Note

When using a product from the E-Access Fiber family, the OTP format is different
- OTP FIBR : ^[A-Z0-9]{2}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}$ (FI-1234-4234)
- OTP EAF : ^[A-Z0-9]{3}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}$ (FIE-2523-4523)

The endpoint URL is as follows : /api/v2/orders/{order_uuid}/endpoints/{endpoint_uuid}/.

Request :

PATCH /api/v2/orders/f391ecfb-89a0-4680-a5fc-2dd7b94240a7/endpoints/c5156041-bd80-46ab-a9c1-5fa5f4a927bb/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "reference":"FI-3790-3415"
}

Response :

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

{
  "uuid": "c5156041-bd80-46ab-a9c1-5fa5f4a927bb",
  "reference": "FI-3790-3415",
  "locked": false
}

Submit an order

Once the draft is filled with all the necessary information, you must submit the order to Kosc. It will then be taken into account by our services until delivery.

Note

The change to submitted is the only status change you are allowed to make on an order. The other statuses will be triggered by Covage as the order progresses.

Request :

PATCH /api/v2/orders/0cd8d842-b0ca-43c0-8cbc-5d275cbdb1c2/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "status": "submitted"
}

Response (the majority of fields have been omitted for brevity) :

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

{
  "uuid": "0cd8d842-b0ca-43c0-8cbc-5d275cbdb1c2",
  "reference": "O191016_42118",
  "type": "activate",
  "status": "submitted"
}

List the orders

The endpoint /api/v2/orders/ allows you to retrieve the list of orders, whether they are in draft, in progress or completed.

Sorting

The parameter ?sort=<champ> allows you to sort the results. To reverse the sort order, the name of the field can be prefixed by the character -.

Filter

It is possible to retrieve part of the results using a combination of parameters <champ>=<valeur>.

Pagination

The parameters limit and offset allow to recover only part of the results. The parameter limit gives the maximum number of results to return while offset is the starting index of the results (calculated on all the results).

The header X-Total-Count returns indicative the total number of results (excluding pagination)

Available fields

The fields available for filtering and sorting are as follows :

Parameter

Sorting ou filter

Description

reference

T/F

Reference of order

type

F

Type of order : activate ou terminate

status

F

Status of the order : draft, acknowledged, in_progress, submitted, cancelled, rejected, completed

endpoint_ref

F

Reference of the endpoint

end_customer

F

Name of the end customer

product_family

F

Product Family

product_line

F

Product Line

creation_date

T

Order creation date

submission_date

T

Order submission date

Request :

GET /api/v2/orders/?product_family=A&product_line=AM&type=activate&offset=50&limit=50&sort=-creation_date HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

Response : (omitted results)

HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 965

Après order submit

Deferred ~~~

Request :

POST /api/v2/orders/0cd8d842-b0ca-43c0-8cbc-5d275cbdb1c2/events/info/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "message": "Your message",
  "stop_deferred": true
}

Response :

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

{
"info": "Event was successfully created, please wait 5 minutes before trying again on this order"
}