Module Catalogue

8 vues Markdown

The five endpoints managing which modules exist and which ones run.

Overview

Everywhere WISECP speaks to the outside world is a module: taking payment, registering domains, sending mail and messages, checking for fraud, and the product types. This article answers which modules exist and which are running.

Six groups exist and they are not picked the same way. The payment and product groups run several modules at once, while the mail, domain and message groups pick one. The fraud group turns each module on by itself.

That difference reaches the endpoints: the group-wide pick sits on one and the per-module switch on another. Which applies is decided by the group.

Reference

Listing a Group's Modules

get/api/v1/admin/modules/{group}
Modules/GetModules admin

Returns the modules in a group along with the group's live picks.

Query 2
statusstringThe filter: active or passive.
searchstringSearches the module name and key.
Response fields data[] — 8 + meta — 6
keystringThe module key. This is what the addresses carry.
namestringThe module name.
descriptionstringA short description.
authorstringWho wrote it.
versionstringIts version.
activeboolWhether the installation uses it.
premiumboolWhether it is a paid module.
logostringThe full address of its logo.
countintHow many came back. It comes back under meta.
groupstringThe group key.
activestring[]The module keys the installation uses.
card_storage_modulestringThe payment module keeping cards. It comes on the payment group alone.
default_modulestringThe group's single pick. It comes on the mail, message and domain groups.
intl_modulestringThe module for messages abroad. It comes on the message group alone.
Errors 2
unknown_group404No such module group.
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/modules/payment?status=active' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.example.com/api/v1/admin/modules/payment?status=active', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data, meta } = await res.json();
console.log(meta.active, meta.card_storage_module);
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/payment?status=active');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Six groups exist: payment, registrars, mail, sms, fraud, product. Anything else gives 404.
foreach (['payment', 'registrars', 'mail', 'sms', 'fraud', 'product'] as $g)
    $all[$g] = Api::Modules()->GetModules(['group' => $g])['meta']['active'];

Reading One Module

get/api/v1/admin/modules/{group}/{module}
Modules/GetModule admin

Returns a module's summary, its fields and what it can do.

Response fields data — 11
keystringThe module key. This is what the addresses carry.
namestringThe module name.
descriptionstringA short description.
authorstringWho wrote it.
versionstringIts version.
activeboolWhether the installation uses it.
premiumboolWhether it is a paid module.
logostringThe full address of its logo.
fieldsobjectThe configuration fields. A password field has its value masked.
typestringThe field type.
namestringThe field label.
descriptionstringWhat the field is for.
valuestringIts current value.
optionsarrayThe choices on a field that has them.
checkedboolWhether a tick field is ticked.
capabilitiesobjectWhat the module supports: configuration fields, a connection test and keeping records.
payment_optionsobjectThe payment settings. They come on the payment group alone.
Errors 3
unknown_group404No such module group.
module_not_found404No such module.
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/modules/payment/Stripe' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
if (data.capabilities.has_test_connection) showTestButton();
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Build a form from the capabilities first: not every module has fields or a connection test.
$m = Api::Modules()->GetModule(['group' => $group, 'module' => $key])['data'];
if (! $m['capabilities']['has_config_fields']) $form = null;

Choosing a Group's Live Modules

put/api/v1/admin/modules/{group}/activation
Modules/UpdateModuleActivation admin the set is replaced

Writes which modules a group uses.

Body 8
modulesstring[]The keys to make live. On the payment and product groups; the list you send replaces what was there.
card_storage_modulestringThe payment module to keep cards. It joins the live list when it is not in it.
modulestringThe single pick. On the mail, domain and message groups; sending it empty clears the pick.
module_intlstringThe module for messages abroad.
intl_sms_serviceintThe channel for messages abroad.
sms_api_serviceintThe channel for the message interface.
turkey_sms_serviceintThe channel for messages inside Turkey. It applies when the installation's default language is Turkish.
Response fields data — 6
groupstringThe group key.
activestring[]The keys now live.
activatedstring[]What this call turned on.
deactivatedstring[]What this call turned off.
card_storage_modulestringThe payment module keeping cards.
modulestringThe single module picked.
Errors 5
unknown_group404No such module group.
module_not_found422One of the keys you sent is absent from that group.
activation_not_supported422The group does not take a group-wide pick.
blocked_by_gate422A hook refused to turn it on.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/modules/payment/activation' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"modules":["Free","Stripe"],"card_storage_module":"Stripe"}'
const now = await fetch('https://panel.example.com/api/v1/admin/modules/payment', {
  headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());

const res = await fetch('https://panel.example.com/api/v1/admin/modules/payment/activation', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ modules: [...now.meta.active, 'Stripe'] }),
});
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/payment/activation');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['modules' => $keys]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The list REPLACES the set: sending one key turns every other payment module off.
$live = Api::Modules()->GetModules(['group' => 'payment'])['meta']['active'];
Api::Modules()->UpdateModuleActivation([
    'group' => 'payment', 'modules' => array_values(array_unique([...$live, 'Stripe'])),
]);

Turning One Module On and Off

put/api/v1/admin/modules/{group}/{module}/status
Modules/SetModuleStatus admin two groups

Turns a fraud or product module on and off one at a time.

Body 1
enabledintreqThe new state: 1 for on and 0 for off.
Response fields data — 11
dataobjectThe module read afresh. Same shape as the read endpoint.
Errors 6
unknown_group404No such module group.
enabled_required422The state field is missing.
not_supported422The group does not take a per-module switch.
module_error422The module refused to open. Usually a missing credential.
blocked_by_gate422A hook refused to turn it on.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/modules/fraud/MaxMind/status' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":1}'
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}/status`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ enabled: 1 }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key . '/status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['enabled' => 1]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// On a fraud module OPENING checks the credentials first; write the settings BEFORE that.
Api::Modules()->UpdateModuleSettings([
    'group' => 'fraud', 'module' => $key, 'settings' => ['license_key' => $lic],
]);
Api::Modules()->SetModuleStatus(['group' => 'fraud', 'module' => $key, 'enabled' => 1]);

Removing a Module

delete/api/v1/admin/modules/{group}/{module}
Modules/DeleteModule admin it deletes files

Takes a module's files off the server.

Response fields data — 3
deletedboolWhether the delete ran.
groupstringThe group key.
keystringThe key of the module removed.
Errors 5
unknown_group404No such module group.
module_not_found404No such module.
blocked_by_gate422A hook refused the delete.
removal_failed422The files could not be removed. What is left needs clearing by hand.
insufficient_scope403The key lacks the required scope.
Request 
curl -X DELETE 'https://panel.example.com/api/v1/admin/modules/payment/Stripe' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// It takes the settings and the credentials too; export the configuration and keep it first.
$cfg = Api::Modules()->GetModuleConfig(['group' => $group, 'module' => $key])['data'];
file_put_contents("$key.json", json_encode($cfg));

Api::Modules()->DeleteModule(['group' => $group, 'module' => $key]);

Pitfalls

The group pick replaces the set

On the payment and product groups the list you send replaces the old one. Sending only the module you meant to add turns the others off, and clients stop seeing those payment methods. Read the list first and add to it.

Not every group opens from the same endpoint

The fraud modules refuse the group-pick endpoint and answer activation_not_supported; they open one at a time. The product group takes both roads. Sort the group first when writing a general management tool.

Picking a card keeper also turns it on

Naming the payment module that keeps cards adds it to the live list even when it was not there. Writing one field can open a payment method to clients. Read the live list in the answer and compare it against the set you expected.

Opening wants a credential

Opening a fraud module checks its credentials, and the call comes back with module_error when one is missing. Order matters during setup: write the settings first and open afterwards. The other way round fails, and the error comes from the module itself.

Removing takes the files off the server

The removal endpoint deletes the module's directory, and the settings and credentials go with it. When the files come away only in part the answer is removal_failed and a half-removed directory stays behind. Export the configuration before removing.

Cet article vous a-t-il été utile ?

Merci pour votre retour !

Besoin d'aide supplémentaire ?

Notre équipe d'assistance est disponible 24h/24 pour tout ce que vous ne trouvez pas ci-dessus.

Nous contacter Ouvrir un ticket

Nous utilisons des cookies pour vous garder connecté, mémoriser votre langue et votre devise, et améliorer le site. Politique relative aux cookies