Appointments

For the creation of an xDSL or FttH line, an appointment must be set.

Covage allows you to list the available time slots and make a reservation.

Note

If an order is placed via API, the appointment is optional, on all FttH products.

Listing the available time slots

To retrieve the list of available time slots, you can do GET on the /api/v2/appointment/slots/ URL.

If an order has already been created

The following parameters can be provided to the API:

Parameter name	Type	Mandatory	Description
order_uuid	query param	Yes	order identifier
start_date	query param	No	Search start date
end_date	query param	No	Search end date
level	query param	No	Level type: standard (default) or premium

If no order has been created yet

Note

This API (said v2) replaces API v1, now deprecated. Parameters kosc_insee_code and kosc_street_code replace parameters insee_code and rivoli_code to be compatible with eligibility API.

The following parameters can be provided to the API:

Parameter name	Type	Mandatory	Description
building_ref	query param	Fibre : mandatory. xDSL : no	- FttH only : required
endpoint_ref	query param	Fibre : no. xDSL : mandatory	- xDSL : Reference of the endpoint (mandatory) - FttH Please use the building_ref parameter instead
kosc_insee_code	query param	Yes	endpoint kosc insee code (from eligibility)
kosc_street_code	query param	Yes	endpoint kosc rivoli code (from eligibility)
product_code	query param	Yes	Selected product code
start_date	query param	No	Search start date
end_date	query param	No	Search end date
vt	query param	Non	Technical visit (vt_simple or vt_complexe)
otp or pto	query param	Non	reference of the OTTP
level	query param	No	Level type: standard (default) or premium

There are four types of ‘erdv’: creation, overwrite (activate_defined), simple technical visit, and complex technical visit.

The type of ‘erdv’ is determined based on the product code, the ‘vt’ key, and the pto/otp.

If the product code corresponds to a “comfort” product, then the ‘erdv’ type is a complex technical visit.

If the ‘vt’ parameter is specified with one of the two accepted values, then the ‘erdv’ type corresponds to that value (simple technical visit / complex technical visit).

Finally, the otp/pto parameter allows the selection of an ‘erdv’ of type overwrite, provided that none of the previous cases apply and that the pto exists.

Appointment dates

For xDSL, the date ranges where you can book an appointment depend on the service level.

• standard: start_date = request date + 8 days | end_date = request date + 26 days

• premium: start_date = request date + 6 days | end_date = request date + 26 days

For FttH, date ranges are processed this way : Depending on the product and location, there is a default interval. Therefore, start_date and end_date are optional. If either one is specified, the resulting interval will automatically be adjusted to remain within the default interval.

Response

The API response is a dictionary containing the list of available time slots.

Field name	Type	Description
available_slots	dictionary list	List of available time slots
postponed	boolean	Availability of a postponed appointment (xDSL only)

available_slots field

The available_slots field contains a list of dictionaries that represent the available time slots.

Field name	Type	Description
start_date	string	Appointment start date
end_date	string	Appointment end date
slot_id	string	Id to be used when booking an appointment (FTTH AI only)
orange_ui_code	string	Id provided by the local loop operator to be used when booking an appointment (sDSL only)

xDSL Example

Request:

GET /api/v2/appointment/slots/?endpoint_ref=0472078025&kosc_insee_code=06036&kosc_street_code=06036109P0&product_code=AM01&start_date=2019-06-16T00:00:00Z&end_date=2019-06-17T18:00:00Z&level=standard HTTP/1.1
Host: extranet.kosc-telecom.fr

Response:

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

{
  "available_slots": [
    {
      "start_date": "2017-06-17T12:00:00Z",
      "end_date": "2017-06-17T14:00:00Z",
      "orange_ui_code": "EH1"
    },
    {
      "start_date": "2017-06-17T12:30:00Z",
      "end_date": "2017-06-17T14:30:00Z",
      "orange_ui_code": "EH1"
    },
    {
      "start_date": "2017-06-17T13:00:00Z",
      "end_date": "2017-06-17T15:00:00Z",
      "orange_ui_code": "EH1"
    },
  ],
  "postponed": false
}

FttH Example, eRDV (type 1)

Request:

GET /api/v2/appointment/slots/?kosc_insee_code=06036&kosc_street_code=06036109P0&product_code=FP01 HTTP/1.1
Host: extranet.kosc-telecom.fr

Response:

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

{
  "available_slots": [
    {
      "start_date": "2021-06-17T06:00:00Z",
      "end_date": "2021-06-17T10:00:00Z",
      "slot_id": "38-191-6096-20210617"
    },
    {
      "start_date": "2021-06-17T12:00:00Z",
      "end_date": "2021-06-17T16:00:00Z",
      "slot_id": "38-191-6097-20210617"
    },
    {
      "start_date": "2021-06-18T06:00:00Z",
      "end_date": "2021-06-18T10:00:00Z",
      "slot_id": "38-191-6098-20210618"
    },
    {
      "start_date": "2021-06-18T12:00:00Z",
      "end_date": "2021-06-18T16:00:00Z",
      "slot_id": "38-191-6099-20210618"
    }
  ]
}

FttH AI Example, wished Appointment (type 2)

Request:

GET /api/v2/appointment/slots/?kosc_insee_code=06036&kosc_street_code=06036109P0&product_code=FP04 HTTP/1.1
Host: extranet.kosc-telecom.fr

Response:

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

{
  "available_slots": [
    {
      "start_date": "2021-06-17T06:00:00Z",
      "end_date": "2021-06-17T10:00:00Z"
    },
    {
      "start_date": "2021-06-17T12:00:00Z",
      "end_date": "2021-06-17T16:00:00Z"
    },
    {
      "start_date": "2021-06-18T06:00:00Z",
      "end_date": "2021-06-18T10:00:00Z"
    },
    {
      "start_date": "2021-06-18T12:00:00Z",
      "end_date": "2021-06-18T16:00:00Z"
    }
  ]
}

Note

slot_id format is unspecified and depends on the geographic zone. This field can be up to 80 chars long.

Note

Having a response of type 1 or 2 depends on the disponibility of type 1.

Booking or modifying an appointment

To book or modify an appointment, you must perform a PUT on the /api/v2/orders/{order_uuid}/appointment/ URL.

Note

You can only book or modify an appointment when the order is in the draft state.

Note

The end_customer[contact] parameter of an order must be filled in before booking an appointment.

The following parameters can be provided to the API:

Parameter name	Type	Mandatory	Description
start_date	string	Yes	Appointment start date
end_date	string	Yes	Appointment end date
slot_id	string	Conditional (mandatory for FTTH eRDV)	Provided by type 1 response
orange_ui_code	string	Conditional (mandatory for Copper Orange)	Orange code
level	string	No	Level type: standard (default) or premium (copper only)
postponed	boolean	No	Default: False - Postponed appointment (xDSL only)
comment	string	No	Comment on the appointment sent to the local loop operator

Request (xDSL):

PUT /api/v2/orders/6d1f0d8a-de30-465b-b2f8-8a324e1c9398/appointment/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "start_date": "2017-06-17T12:00:00Z",
  "end_date": "2017-06-17T14:00:00Z",
  "level": "standard",
  "postponed": false,
  "orange_ui_code": "EH1",
  "comment": "Comments on the appointment go here"
}

Request (FttH eRDV):

PUT /api/v2/orders/6d1f0d8a-de30-465b-b2f8-8a324e1c9398/appointment/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "start_date": "2019-06-17T12:00:00Z",
  "end_date": "2019-06-17T14:00:00Z",
  "comment": "Comments on the appointment go here",
  "slot_id": "38-191-6099-20190617",
  "status": "confirmed",
  "booking_date": "202019-06-10:25:09.021719Z"
}

Request (FttH wished Appointment):

PUT /api/v2/orders/6d1f0d8a-de30-465b-b2f8-8a324e1c9398/appointment/ HTTP/1.1
Host: extranet.kosc-telecom.fr
Content-Type: application/json

{
  "start_date": "2019-06-17T12:00:00Z",
  "end_date": "2019-06-17T14:00:00Z",
  "comment": "Comments on the appointment go here"
}

Note

Once the appointment is booked, you have 40 hours before it expires. If it does, you will have to book a new appointment.

Retrieving an appointment

To retrieve the appointment associated with an order, you can do GET on the /api/v2/orders/{order_uuid}/appointment/ URL.

The API response is a dictionary.

Field name	Type	Description
type	string	Appointment type (erdv)
start_date	string	Appointment start date
end_date	string	Appointment end date
level	string	Level type (standard or premium) (copper only)
status	string	Appointment state (initialized, postponed, confirmed or cancelled)
provider_appoint_ref	string	Reference of the appointment with the local loop operator (copper)
erdv_id	string	Reference of the appointment (FTTH eRDV)
comment	string	Comments on the appointment
creation_date	string	Date of the appointment booking

Request::

GET /api/v2/orders/6d1f0d8a-de30-465b-b2f8-8a324e1c9398/appointment/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Response (copper):

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

{
    "type": "erdv",
    "start_date": "2017-06-17T12:00:00Z",
    "end_date": "2017-06-17T14:00:00Z",
    "level": "standard",
    "status": "confirmed",
    "provider_appoint_ref": "R10-DGT-19667000-0200000001000-ERDV",
    "comment": "Comments on the appointment"
    "creation_date": "2017-06-07T14:12:06.149000"
}

Response (Fiber eRDV):

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

{
    "type": "erdv",
    "start_date": "2017-06-17T12:00:00Z",
    "end_date": "2017-06-17T14:00:00Z",
    "erdv_id": "38-191-6097-20210617",
    "status": "confirmed",
    "comment": "Comments on the appointment"
    "creation_date": "2017-06-07T14:12:06.149000"
}

Cancelling an appointment

To cancel an appointment associated with an order, you can do DELETE on the /api/v2/orders/{order_uuid}/appointment/ URL.

Request:

DELETE /api/v2/orders/6d1f0d8a-de30-465b-b2f8-8a324e1c9398/appointment/ HTTP/1.1
Host: extranet.kosc-telecom.fr

Note

You can only cancel an appointment when the order is in the draft state.