Skip to content

Request Handling

This section describes how the NSPS connector should process incoming HTTP requests from NSPS, including header requirements, request body structure, and an overview of supported event types.

Request Headers

NSPS sends the following HTTP headers to the connector, which are crucial for tracing and debugging distributed systems:

  • Authorization: Bearer <YOUR_API_TOKEN>: A mandatory header containing the Bearer token for request authentication. The connector must validate this token for every incoming request.
  • x-b3-traceid: A trace identifier that allows tracking the full path of a request through various services.
  • x-request-id: A unique identifier for a specific request.

Connector Requirements:

  • Authentication: The connector must validate Bearer token for every incoming request. If the token is invalid or missing, a 401 Unauthorized response must be returned. For more details, refer to the Authorization section.
  • Logging: It is recommended to log the values of x-b3-traceid and x-request-id in all log messages related to the processing of a specific request. This enables effective event tracking and simplifies debugging.
  • ID Generation: If x-b3-traceid or x-request-id headers are not provided by NSPS, the connector should generate unique identifiers (e.g., using UUIDs) for internal logging and tracing.

Request Body

NSPS sends HTTP POST requests to the connector with a JSON body that contains enriched event data. This means that, in addition to the basic ESPF event data, NSPS adds extended information from PortaBilling.

The connector must be capable of parsing a JSON body that conforms to the following general structure:

{
    "event_id": "a3623086-24c2-47fb-a17f-929d9e542ed2",
    "data": {
        "event_type": "SIM/Updated",
        "variables": {
            // ... basic ESPF variables
        }
    },
    "handler_id": "wtl",
    "created_at": "2025-06-09T17:44:21.207629+00:00",
    "updated_at": "2025-06-09T17:44:22.125109+00:00",
    "status": "queued",
    "pb_data": {
        // ... enriched data from PortaBilling
    }
}

Structure of pb_data

The pb_data (PortaBillingData) object contains detailed information received from PortaBilling. Its structure reflects the main entities that may be associated with the event:

  • account_info: Account information (AccountInfo), including:
  • sim_info: SIM card information (SimInfo).
  • prev_sim_info: Previous SIM card information (SimInfo). This field is present only for SIM/Replaced events.
  • access_policy_info: Access policy information (AccessPolicyInfo), containing:
    • attributes (list of AccessPolicyAttribute).
  • product_info: Product information (ProductInfo).
  • full_vd_counter_info: Volume Discount counter information (VDCounterInfo).

Data Structure Details

For detailed information on all fields, their types, possible values, and complete JSON examples for the objects within pb_data (e.g., AccountInfo, SimInfo, AccessPolicyInfo, ProductInfo, VDCounterInfo, and their sub-structures), please refer to the Output Data Structure section in the NSPS documentation.

The connector must implement logic for validating the incoming JSON and extracting only those parameters required for its business logic and interaction with the ES. Unnecessary fields should be ignored.

Event Types

NSPS generates and sends four primary event types to the connector, signaling changes in SIM cards and associated accounts. The connector must be capable of distinguishing and processing these events according to integration requirements.

Here is the complete list of supported event types:

  • SIM/Updated: This event is triggered by changes in SIM card details or the associated account (e.g., SIM card status change, account product update, add-on addition/removal).
  • SIM/Created: Indicates the addition of a new SIM card to the PortaBilling inventory.
  • SIM/Deleted: Signals the removal of a SIM card from the PortaBilling inventory.
  • SIM/Replaced: This event occurs when a SIM card is assigned, removed, or changed for an account.

For detailed information on the trigger conditions for each event type, as well as the most relevant fields they contain, please refer to the Event Types section.

The connector must be designed to effectively process these specific event types, translating the corresponding changes to the target external system.