BT Wholesale B2B

BT Wholesale offer a B2B XML gateway for access to all products/technologies including FTTP, SoGEA, SOGFAST and SOADSL. The B2B gateway uses ebXML standards.

The Fibre Cafe has a connector to integrate with this gateway.

BTWHOLESALEB2B Connector (Tenant API 1.10 / Tenant Updates API 1.8)

The connector has been updated to support the T2R functionality in the Tenant and Tenant Updates API. To update to use this connector version, please contact us.

Service Test

The following parameters are required when requesting a service test:

• serviceId : Identifier of an existing live service.
• problemType : The type of problem being experienced with the service.
• serviceSpecification : Details of a service the supplier provides at the selected address.
• supplier : System identifier for a supplier on the gateway that is associated with this service.

and the following service characteristics are also required when requesting a service test:

• SERVICE _ HAS_WORKED : Indicate if the service has worked at some point
• SERVICE _ LAST _ WORKED : The date when the service was last working. Only required if SERVICE _ HAS_WORKED is set to true.
• EQUIPMENT _ TYPE : The equipment type where the problem is experienced. Only required if ProblemType is CPE.

Service Problem

The following parameters are required when raising a service problem: Please note you cannot raise a service problem when the service test result is 'GREEN'. This is to avoid incurring costs for an engineer site visit where no fault has been found on the line.

• problemType : The type of problem being raised. This will be advised or inferred as part of the service test result.
• problemText : The description of problem being raised as defined by the end user.
• serviceId : Identifier of an existing live service
• serviceSpecification : Details of a service the supplier provides at the selected address.
• supplier : System identifier for a supplier on the gateway that is associated with this service.
• serviceTestId : Identifier of a current service test that has been performed against the service prior to raising the service problem
• primaryContact : Represents a contact available at the given address - primary contact must be provided.
• notes : Notes about the problem which are required by the supplier.

and the following characteristics are also required when raising a service problem:

• TRC_CHARGEBAND : Time related charges - see chargebands
• SERVICE _ HAS_WORKED : Indicate if the service has worked at some point
• SERVICE _ LAST _ WORKED : The date when the service was last working. Only required if SERVICE _ HAS_WORKED is set to true.
• END _ USER _ EQUIPMENT_CHECKED : Confirmation that the end users equipment is connected properly and working.
• END _ USER_CPE : The type of modem or router of the end user.
• CPE _ POWER_ON : Confirm that the end users equipment is powered on.
• USAGE_CHANGES : Indicate if there has been a recent increase in the end users Application or Data.
• PRODUCT_CHANGES : Indicate if there has been any recent product changes or orders for the end user.
• 24HR_ACCESS : Confirm there is 24 hour access to the property | Supplied by tenant when raising service problem.
• REPEAT_PROBLEM : Confirm if this issue has happened before | Supplied by tenant when raising service problem.
• CPE _ SYNC _ LIGHT_STATUS : What is the state of the modem sync light | Supplied by tenant when raising service problem.
• ONT _ POWER_ON : Confirm the ONT power light is on | Supplied by tenant when raising service problem.

BTWHOLESALEB2B Connector (Tenant API 1.7 / Tenant Updates API 1.5)

The initial connector was created for use with the Tenant API version 1.7 and the Tenant Updates API version 1.5

Authentication

Authentication with the gateway is CPA/key based. As part of setting up the connector, we will require the following information:

• Reseller DUNS
• Buyer DUNS
• Account number AKA "SellerAssignedAccountID"
• Private key
• CPA XML file from BT
• Cert and key for BBAC (optional)
• For testing purpose, the BT Wholesale Emulator "Onramp" username/password credentials.

Address Search

Address look up will be available soon.

Service Availability

Only service specifications and information around existing lines are provided.

Additional address information, installation types, constraints, service ready date and unavailability reasons are not provided.

Information on different levels of installation type (e.g. 1 or 2 stage) are not currently returned.

Existing ONT information includes the following (as provided by BT):

• ONT Reference
• ONT Location (Floor/Room/Position)
• ONT Port Type and Status

Stopped date is given for stopped copper lines.

Appointing

When a managed install is required e.g. for a new line or ONT, appointment timeslots can be listed and reserved.

Timeslots are classified as weekday, saturday, sunday and AM/PM.

Expedited appointments and premium site visit reasons can not yet be specified.

Orders

The following service characteristics are required when placing orders:

• LINE_PROFILE : see below for values
• RETAILER_ID : unique identifier for the retailer provided by OFCOM

These service characteristics are optional according to the order:

• MINIMUM_SPEED : requested guaranteed minimum speed (real-time)
• ECC_CHARGEBAND : Excess construction charges - see below for values
• TRC_CHARGEBAND : Time related charges - see below for values
• CARE_LEVEL : see below for values
• COMPANY_NAME : only applicable for SOGEA orders
• PROJECT_REFERENCE : applicable for SOGEA and FTTP provide journeys with Advanced SVR
• ONT_FLOOR
• ONT_ROOM
• ONT_POSITION

Amendment and cancellation requests can be made for inflight orders. There are limitations to what amendments can be done with BTW B2B - the following are permitted:

• Change appointment
• Update contact details
• Update order notes
• Change to ECC _ CHARGEBAND or TRC _ CHARGEBAND characteristics

Line Profiles

For BTW B2B, line profiles map to access technology and downstream/upstream speeds as follows:

(SOADSL line profiles tbc)

Excess Construction Charges

The default chargeband where not provided is 0.

Time Related Charges

The default chargeband where not provided is 0.

Care Levels

The default care level for SOGEA orders is 0; for FTTP orders is 2.

Order updates

BTW provide the SERVICE_ID or the LINE_ID as appropriate in a service characteristic:

{
  "entity": {
    "serviceOrderItem": {
      "serviceCharacteristics": [
        {
          "name": "SERVICE_ID",
          "value": "BBEU12345678"
        }
      ]
    }
  }
}

Supplier notes are attached to KCIs as received from BTW (free text). For example:

{
  "entity": {
    "supplierNotes": [
      {
        "note": "Lorem ipsum dolor sit amet...",
        "type": "Site Visit Notes",
        "created": "2024-05-21T17:02:19.652Z"
      }
    ],
    "information": {
      "type": "ADDITIONAL",
      "text": "Adhoc Note to CP",
      "supplierCode": "550"
    }
  }
}

Unsolicited Ceases

Unsolicited ceases are used by BTW and will be sent as an unsolicited cease KCI.

An initial CREATED KCI will be sent once the gateway has received the unsolicited cease, which will be followed shortly by an acknowledged KCI - and further KCIs as per the usual order flow. Once the switch is complete, a final completed KCI will be sent.

An example of an initial KCI for an unsolicited cease (some metadata fields omitted for brevity):

{
  "id": "12f59a1e-6911-478c-ad5f-12592752990a",
  "updateType": "INFORMATIONAL",
  "entityType": "UNSOLICITED_CEASE_ORDER",
  "entity": {
    "id": "1234567",
    "orderType": "UNSOLICITED_CEASE",
    "supplier": "BTWHOLESALEB2B",
    "supplierOrderNumber": "1-1124746841144665030934",
    "reason": "CHANGE_OF_CP",
    "serviceId": "BBEU12345678",
    "status": "RECEIVED_BY_GATEWAY",
    "requestedCeaseDate": "2024-01-01T09:09:33.001Z"
  },
  "information": {
    "type": "CREATED"
  }
}

Unsolicited reappoints

BTW may on occasion re-appoint the order themselves rather than request the tenant reappoints via an ACTION_REQUIRED : REAPPOINT KCI.

In this scenario, this will come through as an unsolicited reappoint: INFORMATIONAL : REAPPOINTED.

The following fields will be in populated within the KCI order:

{
  "entity": {
    "appointmentSupplierReference": "123456543",
    "appointmentTimeslot": {
      "timeslotStartDateTime": "2022-01-10T08:00:00.000Z",
      "timeslotEndDateTime": "2022-01-10T13:00:00.000Z"
    }
  },
  "information": {
    "type": "REAPPOINTED"
  }
}

• appointmentSupplierReference - new appointment reference from BTW
• appointmentTimeslot - new appointment timeslot

If this is not suitable then it can be treated as a REAPPOINT.