# CityFibre - Ticketing API # Introduction This documentation provides information on the Ticketing API and how to access it. **Please note:** * Ticket requests for multiple ServiceID’s at the same time is not currently catered for. * When Tickets are raised, they will then be handled by CityFibre, and updates will be provided to a previously configured endpoint provided by the Ticket **Reporter**. * In this document, we use **Buyer** and **Supplier** for the Service Provider / CityFibre respectively and Reporter as the person within the **Buyers** Organisation. * This document describes the messages which can pass between **Buyer** and **Supplier**, and the various status changes and updates for ticket requests throughout the process. * We recommend that you always perform the **Supplier** Service Diagnostic request before you raise a Ticket, this will ensure the **Buyer** is not charged for faults on their own network. You can find the Service Diagnostics API document here.   # Design Overview See diagram Ticketing_API_v1.1 for an overview of the flow.
Ticketing API v1.1
Ticketing API v1.1
1. The **Buyer** detects or is informed of a problem on the network. **Reporter** gathers any relevant information. The fault is then determined to be within **Suppliers** network. 2. The **Reporter** on the **Buyer** side can call the API _addFaultReport_ which will validate the details and the ServiceID, once the issue is confirmed a Ticket is raised automatically and then progresses through the workflow until it is resolved. 3. The **Reporter** on the **Buyer** side initiates the process by calling the ticketing API (_addFaultReport_) to raise a ticket with the **Supplier**. This ticket should include all relevant information that could be gathered at the time and can include the details for the files to upload. a. The ticketing API responds with the message ID and status “Pending”. b. The ticketing API may also respond with a status “Rejected” if the ticket is missing mandatory information or the Service ID is not valid. c. The ticketing API may also respond with a status “Rejected” if the fault detail type is **"Service Outage"** _(TLOS: Total Loss Of Service)_ **without** an Appointment Reservation Key or any other types _(Non-TLOS)_ **with** an Appointment Reservation Key. 4. The **Supplier** stores the ticket information. 5. Once validated and stored, a notification is sent to the **Buyer** saying that the ticket status is “Accepted” and has been successfully created. This notification also includes the _maintainerFaultReference_, which is used along with the _buyerFaultReference_ to identify the ongoing fault. Please note the change from ‘Pending’ to ‘Accepted’ is almost instant if no issues are identified. 6. At this point the **Suppliers** Triage is performed on the Service and the fault details are confirmed to the **Buyer** in the Triage section of the XML using the _NotifyFaultReportUpdate_. If a fault is found on the **Suppliers** network, it continues in the Workflow. 7. When there is more information available, the **Supplier** can add this information to the ticket. A notification will be sent to the **Buyer’s** notification endpoint containing a full update using the _notifyFaultReportUpdate_ API. 8. If the **Reporter** finds more information, they too can add it using the _amendFaultReport_ API. The **Buyer** will get a confirmation message for each amendment received by the **Supplier**. 9. The **Supplier** continues to update the **Buyer** with ticket progress until resolved. 10. When the ticket is deemed resolved, **Supplier** will update the ticket status to “Resolved”. 11. The **Buyer** should respond with a _resolveResponse_ either accepting or rejecting the solution. If the resolution is rejected, the ticket will be re-opened with status “Re-Opened”. 12. Once confirmed ‘Resolved’ the ticket can be closed. 13. If no reply is received from the **Buyer** after a fault is resolved for 48 hours, then the fault status is changed to ‘Closed’ and it is automatically Accepted from the **Suppliers** standpoint. # Contacting the Customer If the **Supplier** needs more information from either the **Buyer** or the **Buyer’s** End User the Ticket is put into an ‘on-hold’ status that will pause the SLA. The reasons for pausing are only when delays are out of the Suppliers hands. To contact the **Buyer’s** End User, the **Suppliers** NOC (Network Operational Centre) team makes the appointment, they would call the Customer and make arrangements if a site visit is needed. They follow the process of leaving a message if possible and a further two call attempts. Once the information is received or the appointment is booked the SLA can be aligned to start again and the Ticket status will be moved back to ‘In Progress’. # Accessing the API The API is accessed via HTTPS. Calls are made by POST, sending XML as the HTTP body. Messages are exchanged using SOAP exchanges over HTTPS POST, where the request is in the POST body and the response is in the HTTP response body. Messages are encapsulated in a SOAP envelope using Document/Literal style following WS-Basic Profile 1.0. ```xml ... single request or response element goes here ... ``` ## Authentication Authentication is by means of HTTPS client certificate. It is also restricted to pre-agreed source IP addresses. ## Integration Environments CityFibre provides two pre-production environments for the **Buyer** to integrate with, to allow the **Buyer** to test the API endpoint before going live. Below are the details for these environments: **CFSIT:** [https://api-gw.cityfibre.com:41223/cfsit/api2](https://api-gw.cityfibre.com:41223/cfsit/api2) **CFStaging:** [https://api-gw.cityfibre.com:41223/cfstaging/api2](https://api-gw.cityfibre.com:41223/cfstaging/api2) **Production:** [https://api-gw.cityfibre.com:41223/prod/api2](https://api-gw.cityfibre.com:41223/prod/api2)

Ticketing Notification End Point

**Buyer** must provide the endpoint to receive Ticket update notifications. # Closure Code Reference | Code | Description | | --- |----------------------------------------| |FR| Fault Resolved | |FNR| Fault Not Resolved | |HAZ| Site Unsafe | |NA| No access | |NAPUV| No Access Possible Hazard | |ASQ| Sales Query | |NDT| No dial tone | |UNF| Unforeseen Circumstance e.g. Asbestos | |MBORC| Matters Beyond Reasonable Control | |FTA| Failed to Attend | |SREQ| Service Request | License: Apache 2.0 ## Servers Main (production) server ``` https://api-gw.cityfibre.com:41223/prod/api2 ``` CFStaging server ``` https://api-gw.cityfibre.com:41223/cfstaging/api2 ``` CFSit server ``` https://api-gw.cityfibre.com:41223/cfsit/api2 ``` ## Security ### Certificate MutualTLS Certificate Type: mutualTLS ## Download OpenAPI description [CityFibre - Ticketing API](https://ticketing.docs.cityfibre.com/_bundle/openapi.yaml) ## Appointments The buyer can query appointment availability, reserve an appointment and include the reservation key in the order request. If this is not done, the order will go into a waiting state and not progress, the buyer will need to reserve an appointment and then amend the order to include the appointment reservation key before the order can complete. Reappoint is an additional query and reserve, then an amend with the new CAMS ID on the appointment reservation key field. # Appointing flow Where the ticketing flow says "get appointment info" this flow describes all the appointment related steps.
AppointingDiagram
AppointingDiagram
### Query Appointment Availability - [POST /queryAppointmentAvailability](https://ticketing.docs.cityfibre.com/openapi/appointments/queryappointmentavailability.md): To check the availability for an appointment on a given location, timeframe, and product, the buyer should send a request containing a UPRN. The seller is then going to respond with detailed information about available appointment slots. ### Reserve Appointment - [POST /reserveAppointment](https://ticketing.docs.cityfibre.com/openapi/appointments/reserveappointment.md): In order to reserve an appointment, the buyer should provide the UPRN, product and the appointment slot that they desire to the seller. ## Fault Report ### Add a fault report - [POST /addFaultReport](https://ticketing.docs.cityfibre.com/openapi/fault-report/receivedfaultreportrejected.yaml.md): Creates a new fault Report. ### Amend a fault report - [POST /amendFaultReport](https://ticketing.docs.cityfibre.com/openapi/fault-report/amendfaultreport.md): Amend a Fault Report. ## Resolve Response ### Report the response - [POST /resolveResponse](https://ticketing.docs.cityfibre.com/openapi/resolve-response/resolveresponse.md): Reporting an Accept or Reject status from the Fault Report. ## Request Update ### Request fault report update - [POST /requestFaultReportUpdate](https://ticketing.docs.cityfibre.com/openapi/request-update/requestfaultreportupdate.md): Request an update from the Supplier. ## FaultReport ### Notify Fault Report Accepted - [POST /notifyAccepted](https://ticketing.docs.cityfibre.com/openapi/faultreport/notifyfaultreportupdateaccepted.yaml.md): Update Buyer on whether the fault report has been accepted ### Notify Fault Report Cancelled - [POST /notifyCancelled](https://ticketing.docs.cityfibre.com/openapi/faultreport/notifyfaultreportupdatecancelled.yaml.md): Update Buyer when a fault report is cancelled ### Notify Fault Report Closed - [POST /notifyClosed](https://ticketing.docs.cityfibre.com/openapi/faultreport/notifyfaultreportupdateclosed.yaml.md): Update Buyer when a fault report is closed ### Notify Fault Report In Progress - [POST /notifyInProgress](https://ticketing.docs.cityfibre.com/openapi/faultreport/notifyfaultreportupdateinprogress.yaml.md): Update Buyer when progress has been started on a fault report ### Notify Fault Report On Hold - [POST /notifyOnHold](https://ticketing.docs.cityfibre.com/openapi/faultreport/notifyfaultreportupdateonhold.yaml.md): Update Buyer if a fault report is put on hold ### Notify Fault Report Rejected - [POST /notifyRejected](https://ticketing.docs.cityfibre.com/openapi/faultreport/notifyfaultreportupdaterejected.yaml.md): Update Buyer when and why the fault report is rejected ### Notify Fault Report Resolved - [POST /notifyResolved](https://ticketing.docs.cityfibre.com/openapi/faultreport/notifyfaultreportupdateresolved.yaml.md): Update Buyer on the resolution of a ticket ## Appointment ### Notify Appointment Cancelled - [POST /notifyAppointmentCancelled](https://ticketing.docs.cityfibre.com/openapi/appointment/notifyfaultreportupdateappointmentcancelled.yaml.md): Update Buyer if an appointment gets cancelled ### Notify Appointment Completed - [POST /notifyAppointmentCompleted](https://ticketing.docs.cityfibre.com/openapi/appointment/notifyfaultreportupdateappointmentcompleted.yaml.md): Update Buyer when and how an appointment has been completed ### Notify Appointment Confirmation - [POST /notifyAppointmentConfirmation](https://ticketing.docs.cityfibre.com/openapi/appointment/notifyfaultreportupdateappointmentconfirmation.yaml.md): Update Buyer on confirmation status of appointment ### Notify Appointment Missed - [POST /notifyMissedAppointment](https://ticketing.docs.cityfibre.com/openapi/appointment/notifyfaultreportupdatemissedappointment.yaml.md): Update Buyer when and why an appointment is missed ## Amendment ### Notify Fault Report Amended - [POST /notifyAmended](https://ticketing.docs.cityfibre.com/openapi/amendment/notifyfaultreportupdatemissedappointmentamended.yaml.md): Update Buyer on any amendments made to the fault report ## XSD File ### Get the XSD for the Fault Report - [GET /faultReport.txt](https://ticketing.docs.cityfibre.com/openapi/xsd-file/getfaultreportxsd.md): Download XSD ## Revision History ### Revision history for the Documentation - [GET /changeLog.txt](https://ticketing.docs.cityfibre.com/openapi/revision-history/getrevisionhistory.md): #### Ten most recent changes made to these docs | Date | Change | |------------|------------------------------------------------------------------------------| | 28/05/2025 | Update the 'type' attribute to 'Service Outage' in the add/amend fault example | | 19/09/2024 | Corrected grammatical issues and spelling mistakes | | 25/07/2024 | Added appointments to Notify Appointment Missed | | 25/07/2024 | Added appointments to Notify Fault Report In Progress. Added appointment confirmation status, cancelld and closure code. Added open and canceled statuses | | 24/07/2024 | Updated optional fields, non-empty strings. Added 'updates' and 'attachments' in fault repors | | 12/04/2024 | Updated 40x and added 500 response schema for several requests | | 09/04/2024 | Added notification for Fault cancellation and removed maintainerfault reference from notify fault report rejected | | 03/04/2024 | Removed unused certificate and request section from XSD component | | 27/03/2024 | Updated 400 response schema from amend fault | | 25/03/2024 | Fixed the 'appointment' tag for addfault and amendfault | #### Download full change log here: Download Change Log