# Suppliers - Getting Started ## Service Availability Service availability is the typical entry point for tenants to begin ordering from suppliers. This determines: 1. Can the supplier provide service at this address? 2. What can be ordered? First, refer to [Service Availability](/pages/serviceavailability) to get an understanding of concepts such as service specifications and line profiles, and then review the Supplier API specification for Service Availability using the Supplier API menu at the top of this page. The key sections are: ### Service specifications **serviceSpecifications** - what service is available e.g. FTTP and what speeds (line profiles). You will need to determine what these are (e.g. product id, code or name) to allow tenants to select an appropriate product/service in the order: ```json "serviceSpecifications": [ { "id": "FTTP", "serviceCharacteristics": [ { "name": "LINE_PROFILE", "values": [ .. ] } ] } ] ``` ### Site Information **siteInformation** - what is available at the address. At a minimum you will need to state if a new line can be installed, if installation/engineer visit is required (presence of `installationType` dictates this) and any existing lines (active or not - and whether they need an engineer visit): ```json "siteInformation": { "newLine": true, "installationType": "STANDARD", "existingLines": [ { "ont": { "ontReference": "ONT0000123123", "ports": [ { "portNumber": 1, "status": "ACTIVE", } ] } }, { "installationType": "STANDARD", "ont": { "ontReference": "ONT0000789000", "ports": [ { "portNumber": 1, "status": "STOPPED", } ] } } ] } ``` Note: in the second existing line example, the presence of `installationType` indicates that an engineer visit would be required e.g. where the ONT is not responding. If the line can be started without an engineer visit then `installationType` should be omitted. There are other fields that should be filled as appropriate/available e.g. - Any constraints or LOCs that apply: ```json "constraints": [ … ], ``` - Handover point information: ```json "enniId": "S1889", "siteName": "string", "siteLocation": "string", ``` - ONT ancillary information: ```json "serialNumber": "1234567890", "manufacturer": "Nokia", "floor": "1", "room": "Reception", "position": "string", ``` - ONT port information including indication that the port is in use by the current tenant: ```json "tenantActive": false, "stoppedDate": "2022-01-01T13:45:00.000Z" ``` - Additional [line characteristics](/pages/linecharacteristics): ```json "lineCharacteristics": [ … ] ``` ### Unavailability Reasons If you cannot provide service it is expected that you populate `unavailabilityReasons` and do not return any `serviceSpecifications` (i.e. empty array). ```json "serviceSpecifications": [], "unavailabilityReasons": [ { "code": "NOT_PLANNED", "text": "Outside coverage area" } ] ``` ## Appointments Refer to [Appointing](/pages/appointing) for more details - pay particular attention to date-time format to ensure timeslots are correct throughout the year. ## Ordering Tenants will expect to be able to place new and existing line orders. - New - install of a service to replace or add to existing service(s) - Start - use an existing inactive service e.g. stopped ONT port - Transfer - also known as a switch or migration - change of CP. - Takeover - Working Line Takeover (WLTO) - customer change of address - Modify - change an existing service e.g. line profile/speed change - Cease - end an active service Additionally, if applicable a swap order may be supported: - Swap - change to an existing service requiring engineer visit Refer to [Service Characteristics](/pages/service-orders/servicecharacteristics) for a full set of available characteristics that the tenant can send on the order. The supported characteristics should be listed on the onboarding template for tenants to later consume. Common service characteristics sent on orders: - LINE_PROFILE - line speed/product being ordered - REMOTE_ID - remote identifier for authentication - RETAILER_ID - end-party buying the service - ONT_REFERENCE - reference to an existing service where appropriate Note: RETAILER_ID is particularly important when the tenant is a reseller or wholesaler/aggregator. Where supported, tenants can send [Engineer Tasks](/pages/service-orders/engineertasks) to request additional work to be carried out in the engineer appointment. When placing an order, the Fibre Cafe can handle synchronous or asynchronous responses to handle the older 2 stage order confirmation that BT/Openreach use or a single synchronous confirmation. ### Synchronous (201) Returning 201 from the `POST /orders` endpoint will instruct the Fibre Cafe that the order has been validated and accepted. The returned order status will determine whether the order is ACKNOWLEDGED (KCI1) or COMMITTED (KCI2). The Fibre Cafe will send appropriate KCIs based on this. If the order was ACKNOWLEDGED, the supplier will need to send the COMMITTED KCI once any pre-processing is complete and the order is now committed for delivery. ### Asynchronous (202) Returning 201 from the `POST /orders` endpoint will instruct the Fibre Cafe that the supplier will be taking care of KCIs. The supplier will need to send appropriate KCIs to acknowledge (KCI1) and commit (KCI2) the order. ## KCIs [KCIs](/pages/service-orders/orderkciflows) (Keep Customer Informed) are updates about the progress of an order and must be sent to the Fibre Cafe Supplier Updates API. More details of [these updates](/pages/suppliers/supplierupdates) are available along with full [example KCIs](/pages/suppliers/supplierkciexamples). It is mandatory to send some service characteristics before an order completes e.g. SERVICE_ID. You can view the OpenAPI description for Supplier Updates API using the Supplier API menu at the top of this page. There are payload examples provided for a range of different programming languages/tools and the ability to download the OpenAPI schema. ## Testing/Onboarding For testing purposes, a test tenant can be created so that you can check end-to-end requests via the Fibre Cafe to your API - i.e. as if you are a tenant of the Fibre Cafe ordering your service. To receive KCIs, you can either use the Tenant API GET endpoint to receive the order and KCIs - or optionally create a simple KCI receiver. The appropriate API to implement in this case is the Tenant Updates API. You can download the OpenAPI schema using the Tenants API menu at the top of the page and load into tools such as Postman or [Swagger Editor](https://editor.swagger.io/) to create a simple mock server implementation for the Tenants Updates API. Now refer to [Supplier Onboarding](/pages/testing/supplieronboarding) for test scenarios and sign off details.