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

Orders¶

API Summary¶

Common Fields activate and terminate¶

Order Creation¶

Order activate¶

Options¶

Bounds¶

ONT installation intervention.¶

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

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

Example of copper order creation¶

Example of creation of a fiber pro order¶

Order terminate¶

Example of creation of termination order¶

Modify an order¶

Update the address of an order¶

Update the OTP reference of an order¶

Submit an order¶

List the orders¶

Sorting¶

Filter¶

Pagination¶

Available fields¶

Après order submit¶

Common Fields `activate` and `terminate`¶

Order `activate`¶

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

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

Order `terminate`¶