SupportHub Ticketing

SupportHub is Flowe's ticketing platform that enables partners to manage reports and requests related to their customers' wallets. The integration between the partner's system and SupportHub is built on two complementary channels:

• REST APIs — allow the partner to create tickets, add comments, query status, and update reports in a synchronous, on-demand manner.
• Business Events — asynchronous notifications sent automatically by SupportHub via Azure Service Bus whenever a relevant lifecycle event occurs on a ticket, removing the need for continuous polling.

All communication is secured via HTTPS and OAuth 2.0, and data is exchanged in JSON format.

Authentication and Access

To interact with the SupportHub APIs, the partner system must first obtain a JWT access token through the OAuth 2.0 client_credentials flow with Microsoft Entra ID.

The flow works as follows:

1. The partner authenticates against Microsoft Entra ID using application credentials (client_id and client_secret provided by Flowe for each environment).
2. A Bearer token is returned, valid for approximately 1 hour.
3. The token is included in every API call via the Authorization header.

---

Creating a Ticket

The Create Ticket API is the entry point for any issue or request the partner wants to report to the Flowe team. A unique caseNumber is returned on success and must be retained for all subsequent operations on that ticket.

Three types of ticket are supported:

• Consumer — a report concerning a specific end customer's wallet (e.g. balance not updated, top-up not visible). Requires a walletid.
• Alert — a generalised service unavailability affecting all end customers (priority 0, blocking and widespread outage). Use category Indisponibilità del servizio.
• Business — a B2B issue between the partner's systems and SupportHub. Use category Segnalazioni B2B.

Key fields to provide:

• type — nature of the report (Consumer, Alert, Business). Required.
• category — issue category. Required. Must be one of the recognised values; unrecognised categories are rejected.
• description — detailed description of the problem. Required. Must not contain unsafe HTML content (scripts, iframes, PHP).
• walletid — wallet identifier. Mandatory for Consumer type; omit for Alert and Business.
• externalid — optional partner-side identifier used to correlate the SupportHub ticket with internal systems.

API REFERENCE

SupportHub: CreateTicket

---

Adding a Comment to a Ticket

The Post Comment API lets the partner add a free-text update to the timeline of an existing ticket — for example, to provide new information, respond to a Flowe request, or report a development on the partner side.

Special behaviour — WaitingForCustomer status:

If the ticket is waiting for a partner response when this API is called, two automatic effects are triggered:

1. The ticket status is automatically moved to In progress, without requiring a separate status-update call. The transition is recorded in the timeline as performed by SystemDaemon.
2. The SLA Validity Date is recalculated based on the call time and the Italian working-day calendar:

Condition	New Validity Date
Working day, 09:00–16:00	Date and time of the API call
Working day, before 09:00	Call date at 09:00
Working day, after 16:00	Next working day at 09:00
Public holiday	First available working day at 09:00

This ensures the SLA timer restarts correctly from the moment the partner provides its update.

API REFERENCE

SupportHub: PostComment

---

Listing Tickets

The Get Partner Tickets API returns a paginated list (10 tickets per page) of the partner's tickets, filtered by status and optionally by type.

The partner specifies the status to filter on (e.g. InProgress, Resolved) and, optionally, the ticket type (Wallet or Management). Results are paginated — use the page query parameter (0-based) to scroll through pages.

Important: the {status} path parameter must be written without spaces in the URL (e.g. InProgress, not In Progress). A request with spaces returns HTTP 400.

Each ticket in the response includes: case number, external ID, type, associated wallet, creation and closure dates, priority, and taken-in-charge date.

API REFERENCE

SupportHub: GetPartnerTickets

---

Viewing a Single Ticket

The Get Ticket API returns the complete detail of a ticket — useful to check current status, verify SLA dates, or inspect resolution and closure information after receiving an update event.

Information returned includes:

• Current status and ticket type
• Partner name and associated wallet ID
• Opening date, expiration date (SLA deadline), resolution date, and closure date
• Closure response (when provided by the partner at closing)
• Priority and taken-in-charge date

API REFERENCE

SupportHub: GetTicket

---

Viewing Tickets by Wallet

The Get Tickets by Wallet ID API returns the full history of tickets linked to a given wallet. This is particularly useful to:

• Check for existing open reports before creating a new ticket, avoiding duplicates.
• Support the customer by reviewing past interactions before taking action.
• Perform operational analysis on a specific wallet.

The partner provides the walletID (UUID format) in the URL path and receives all associated tickets in return.

API REFERENCE

SupportHub: GetTicketsByWalletID

---

Viewing the Ticket Timeline

The Get Ticket Timeline API returns the complete, ordered sequence of all events recorded on a ticket from opening to closure. Each timeline entry includes:

• createdby — the author of the action:
  • Partner user name for manual actions
  • SystemDaemon for automated transitions (e.g. status change from WaitingForCustomer to In progress triggered by a PostComment call)
• createdon — timestamp of the event (UTC ISO 8601)
• text — free-text description of the event or comment (e.g. [Partner] User changed status from [New] to [Canceled])

API REFERENCE

SupportHub: GetTicketTimeline

---

Updating Ticket Status

The Update Ticket Status API allows the partner to transition a ticket to a new state. Only specific transitions are permitted by the operational contract:

Current status	New status	Notes
New	Canceled	Direct cancellation
In progress	Canceled	Cancellation during processing
WaitingForCustomer	Canceled	Cancellation while awaiting partner response
Resolved	Closed	closingResponse is mandatory

Any other transition is rejected with HTTP 422.

When transitioning from Resolved to Closed, the closingResponse field is mandatory. It must contain a textual confirmation and must not include scripts, iframes, or PHP content.

Two equivalent endpoint variants are available — one where the new status is passed as a path parameter, and one where it is passed in the request body. Both enforce the same transition rules.

API REFERENCE

SupportHub: UpdateTicketStatusPathSupportHub: UpdateTicketStatusBody

---

Listing Ticket Attachments

The List Attachments API returns the metadata of every file attached to a ticket. It does not include the file binary; use the single attachment download endpoint to retrieve filecontent.

APIM validates the casenumber before forwarding the request to the backend.

API REFERENCE

SupportHub: GetTicketAttachments

---

Uploading an Attachment

The Upload Attachment API uploads a binary file to an existing ticket. The request body must be raw binary data and the file name is provided through the filename query parameter.

APIM behaviour:

Check	Behaviour
casenumber and filename	Both are required; missing values return HTTP 400
Extension whitelist	Images, pdf, csv, rtf, and Word/Excel formats including .docx, .docm, .xlsx, .xlsm are allowed
Size limit	Maximum size is 5 MB (5242880 bytes); larger files return HTTP 413
Ticket state	Upload is rejected with HTTP 409 when the ticket is Closed or Canceled

Flow expectations:

• Power Automate receives the binary body through @triggerBody().
• The forwarded casenumber and filename headers are parsed in the backend flow.
• The backend returns a JSON object, not a plain string.

Test checklist:

• upload without filename -> 400
• upload with unsupported extension -> 415
• upload larger than 5 MB -> 413
• upload to a closed ticket -> 409
• list and download on a non-existent ticket -> 404
• valid upload -> 200 with a numeric id

API REFERENCE

SupportHub: PostAttachment

---

Downloading an Attachment

The Get Attachment API returns a single attachment by attachmentid. The filecontent field is returned as Base64, so the caller must decode it to obtain the original file.

The response also includes the contentType when available. If direct streaming is needed, consider a presigned upload/download flow or a streaming response alternative.

API REFERENCE

SupportHub: GetAttachment

---

Business Events – System Notifications

Business Events are automatic notifications that SupportHub publishes on Azure Service Bus whenever a relevant event occurs in the lifecycle of a ticket. Unlike APIs, Business Events arrive asynchronously and proactively — no polling is required.

SupportHub publishes each event to a topic (Business-wb). The partner subscribes to the topic to receive messages. Each message consists of:

• Properties (headers): message metadata — destination partner, publication timestamp, publisher name, contract version.
• Content (JSON payload): event-specific data (ticket state, dates, identifiers).

Operational characteristics:

Property	Value
Format	JSON
Delivery	at-least-once — partner systems must be idempotent
Security	Microsoft Entra ID or SAS; TLS encryption in transit; data encrypted at rest
Namespace (UAT)	sb://t2walletpublicsbns01.servicebus.windows.net/
Namespace (PROD)	sb://t3walletpublicsbns01.servicebus.windows.net/
Topic	Business-wb

Contract versioning (EventVersion): every message includes an integer EventVersion property, incremented by 1 only on breaking changes. Adding optional fields does not trigger an increment. Partner systems should always check this field to handle contract evolution.

---

Event: Ticket Created

The TicketCreated event is published as soon as a new ticket is created in SupportHub.

Label / Subject: TicketCreated

Purpose for the partner:

• Automatically receive the CaseNumber assigned by SupportHub to correlate it with internal systems.
• Trigger internal processes (notifications, workflows) in response to the opening of a new report.
• Monitor new ticket creation in real time.

Key fields in the event payload:

Field	Description
CaseNumber	Unique ticket identifier assigned by SupportHub (e.g. TK-000001234)
ExternalID	Partner's internal ID, if provided at creation
Status	Initial status (typically New)
Category	Report category
WalletID	Customer wallet involved (if applicable)
CreationDate	Ticket creation date and time (UTC ISO 8601)
ValidityDate	SLA expiry date and time (UTC ISO 8601)
TakenInChargeOn	Date/time of take-in-charge (populated in case of service unavailability)

---

Event: Ticket Status Updated

The TicketStatusUpdate event is published every time a ticket's status changes in SupportHub — for example, New → In progress, In progress → Resolved, or Resolved → Closed.

Label / Subject: TicketStatusUpdate

Purpose for the partner:

• Keep the partner's systems aligned with the current ticket status, with no polling required.
• Automatically trigger internal actions based on specific status transitions (e.g. notify the end customer when the ticket is Resolved, start internal closure procedures when Closed is received).
• Track resolution and closure times for SLA reporting.

Key fields in the event payload:

Field	Description
CaseNumber	Unique ticket identifier
Status	New status of the ticket
Category	Report category
Priority	Ticket priority (if set)
CreationDate	Original ticket opening date
ResolutionDate	Populated when status becomes Resolved
ClosureDate	Populated when status becomes Closed or Canceled
timestamp	Exact moment the status update occurred (UTC ISO 8601)
TakenInChargeOn	Date/time of take-in-charge (populated in case of service unavailability)

Possible values for Status:

New · In progress · WaitingForCustomer · Resolved · Closed · Canceled · Rejected