Writing a platform adapter
For developers connecting something that is not Blesta.
A “platform” is whatever system your clients’ accounts live in: a billing system, a control panel, your own portal. The desk ships a first-party Blesta module, and everything it does is plain HTTP that anything can answer.
Connecting a platform is two directions, and they are independent:
| Direction | What it is | Needed for |
|---|---|---|
| Platform → desk | Your code calls the integration API with a per-brand token | Clients seeing and opening tickets, the chat identity, status, reports |
| Desk → platform | The desk calls a lookup address you host, signed | Services, invoices, account details, mass-mail audiences, signals |
You can do the first without the second. A desk with no lookups still works; the client pane just shows less.
Platform → desk
Covered in The integration API. Briefly: hold a per-brand token on your server, pass your own id for each client, and render whatever you like around the JSON.
Desk → platform: the lookups
Per brand you configure a lookup base address, a secret, and which capabilities it answers. Every request the desk makes is signed with a timestamp, a one-time nonce and an HMAC over the method, path, query, timestamp and nonce. There is no secret in the URL, so nothing sensitive lands in a proxy log, and a captured request cannot be replayed.
Your endpoint should: check the signature, check the clock window, refuse a nonce it has seen, and scope every answer to the company the key belongs to.
What the desk asks for
Each is optional. Answer what you can; the desk declares capabilities and hides the blocks you do not support, so an older or simpler adapter shows less rather than erroring.
The account: name, company, email, postal address, telephone numbers, status, client group, your client code, signed-up date, and a link into your admin. Plus, where you have them: balance per currency with the overdue part and any credit, recent sign-ins with addresses and failed attempts, payment methods (type, last four digits, expiry, which is default, but never the full number or a gateway token), and the other contacts on the account with their roles.
Services, invoices and transactions: paged, with the statuses you name (the desk shows the filter you give it rather than a list of its own) and a total per side. Page them properly: an account with four thousand services must not be one response.
One service in detail: everything you hold about it, fetched only when a row is opened. Withhold what you withhold from your own staff: a password-style field comes back masked, a hidden field is not reported at all.
Recipients: may these particular addresses still be emailed about this account.
Audience filters and audiences: two calls that let the desk build mass-mail lists from your data: one declaring the filters you offer (with types and options), one resolving a criteria set page by page into recipients with attributes.
Signals: things happening in your system the desk should notice: a cancellation, a failed payment, a suspension. The desk polls, opens a ticket where a rule says so, and files the rest for staff to see.
Shapes and rules
- Identifiers are strings, unique per brand, so any system’s ids fit.
- Return what you have, omit what you do not. Every block is optional.
- Never return anything that could be used to charge: no full card numbers, no gateway tokens, no routing numbers.
- Answer quickly or page. The desk fetches one small page per block for the assistant and the console; a slow answer shows as a retryable error rather than hanging the pane.
Portal links
The desk builds links back into your system: the client’s ticket page, the guest ticket page, the admin record. Each is a pattern on the brand, so an adapter names its own URL shapes rather than the desk guessing.
Registering a platform
A platform declares its label, its module, its portal URL patterns and its connection fields. The label is what the interface calls it everywhere: the client pane says “Acme Billing”, not “Blesta”, when that is what the brand is connected to.
A sensible order to build in
- Integration API first: client upsert, departments, list, open, reply, close. That is a working support area.
- The chat identity if you use live chat: one call, and chats attach to accounts properly.
- The account lookup, then services and invoices. This is where the client pane becomes useful.
- Audiences, if you want mass mail against your own data.
- Signals last, once you know which events are worth a ticket.