Client Registration

8 vues Markdown

The seven endpoints deciding what the registration form asks and which extra fields it carries.

Overview

These seven endpoints decide what a client is asked when they register. There are two layers: the fields the system already has, and the custom ones you add.

On the built-in fields three things are set separately for each question: whether it is asked, whether it is required, and whether the client can change it later. They are independent keys, so making a field required does not start asking for it.

Custom fields belong to a language: the same field is opened as a separate record in each language, with an id of its own.

Reference

Reading the Registration Settings

get/api/v1/admin/settings/client
Settings/GetClientSettings admin all zero or one

Returns which fields the sign-up and sign-in flow asks for, and which are required.

Response fields data — 27
sign_in_statusintWhether signing in is open.
sign_up_statusintWhether registration is open.
sign_up_email_verifyintWhether the e-mail has to be verified.
smart_namingintWhether names are tidied automatically.
crtacwshopintWhether an account is opened automatically during checkout.
sign_up_gsm_statusintWhether the mobile number is asked for.
sign_up_gsm_requiredintWhether the mobile number is required.
sign_up_gsm_checkerintWhether the mobile number is format-checked.
sign_up_gsm_verifyintWhether the mobile number has to be verified.
sign_up_landline_phone_statusintWhether the landline is asked for.
sign_up_landline_phone_requiredintWhether the landline is required.
sign_up_landline_phone_checkerintWhether the landline is format-checked.
sign_up_kind_statusintWhether the personal or business choice is asked for.
sign_up_identity_statusintWhether the identity number is asked for.
sign_up_identity_requiredintWhether the identity number is required.
sign_birthday_statusintWhether the birth date is asked for.
sign_birthday_requiredintWhether the birth date is required.
sign_birthday_adult_verifyintWhether an age limit is enforced.
security_question_statusintWhether the security question is asked.
security_question_requiredintWhether the security question is required.
sign_editable_full_nameintWhether the client can change their name later.
sign_editable_emailintWhether the client can change their e-mail.
sign_editable_gsmintWhether the client can change their mobile number.
sign_editable_landline_phoneintWhether the client can change their landline.
sign_editable_identityintWhether the client can change their identity number.
sign_editable_kindintWhether the client can change their account kind.
sign_editable_birthdayintWhether the client can change their birth date.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/settings/client' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.example.com/api/v1/admin/settings/client', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/client');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Asking for a field and REQUIRING it are separate keys: read them together.
$cfg     = Api::Settings()->GetClientSettings()['data'];
$asksGsm = $cfg['sign_up_gsm_status'] === 1;
$needsIt = $asksGsm && $cfg['sign_up_gsm_required'] === 1;

Writing the Registration Settings

put/api/v1/admin/settings/client
Settings/UpdateClientSettings admin affects the storefront

Applies the keys you send and leaves the rest as they are.

Body 27
sign_in_statusintWhether signing in is open.
sign_up_statusintWhether registration is open.
sign_up_email_verifyintWhether the e-mail has to be verified.
smart_namingintWhether names are tidied automatically.
crtacwshopintWhether an account is opened automatically during checkout.
sign_up_gsm_statusintWhether the mobile number is asked for.
sign_up_gsm_requiredintWhether the mobile number is required.
sign_up_gsm_checkerintWhether the mobile number is format-checked.
sign_up_gsm_verifyintWhether the mobile number has to be verified.
sign_up_landline_phone_statusintWhether the landline is asked for.
sign_up_landline_phone_requiredintWhether the landline is required.
sign_up_landline_phone_checkerintWhether the landline is format-checked.
sign_up_kind_statusintWhether the personal or business choice is asked for.
sign_up_identity_statusintWhether the identity number is asked for.
sign_up_identity_requiredintWhether the identity number is required.
sign_birthday_statusintWhether the birth date is asked for.
sign_birthday_requiredintWhether the birth date is required.
sign_birthday_adult_verifyintWhether an age limit is enforced.
security_question_statusintWhether the security question is asked.
security_question_requiredintWhether the security question is required.
sign_editable_full_nameintWhether the client can change their name later.
sign_editable_emailintWhether the client can change their e-mail.
sign_editable_gsmintWhether the client can change their mobile number.
sign_editable_landline_phoneintWhether the client can change their landline.
sign_editable_identityintWhether the client can change their identity number.
sign_editable_kindintWhether the client can change their account kind.
sign_editable_birthdayintWhether the client can change their birth date.
Response fields data — 27
*intThe whole flag set as it stands after the write, in the same schema as reading the settings. Each one comes back as 0 or 1.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/settings/client' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"sign_up_status":1,"sign_up_email_verify":1,"security_question_status":0}'
const res = await fetch('https://panel.example.com/api/v1/admin/settings/client', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sign_up_status: 1,
    sign_up_email_verify: 1,
    security_question_status: 0,
  }),
});

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

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Making a field required needs it to be ASKED FOR; switch both on together.
Api::Settings()->UpdateClientSettings([
    'sign_up_gsm_status'   => 1,
    'sign_up_gsm_required' => 1,
]);

Listing the Custom Fields

get/api/v1/admin/settings/client-fields
Settings/GetClientFields admin separate per language

Returns the extra fields added to the registration form. They are kept per language.

Query parameters 1
langstringWhich language's fields. Left out, the current language is used.
Response fields data[] — 12
idintId of the field.
langstringThe language the field belongs to.
typestringThe field type.
namestringThe label shown to the client.
statusstringactive or inactive.
requiredboolWhether it has to be filled.
uneditableboolWhether the client can change it later.
client_hiddenboolWhether it is hidden from the client. While hidden it appears in neither the account, the registration form, the invoice, nor the client API.
invoiceboolWhether it shows on the invoice.
sign_formboolWhether it is asked on the registration form.
optionsstringThe values offered on the choice types.
rankintIts position on the form.
Errors 2
invalid_lang422The language code is not valid.
insufficient_scope403The key lacks the required scope.
Request 
curl -G 'https://panel.example.com/api/v1/admin/settings/client-fields' \
  -H "Authorization: Bearer $API_KEY" \
  -d lang=en
const url = new URL('https://panel.example.com/api/v1/admin/settings/client-fields');
url.searchParams.set('lang', 'en');

const res  = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
$url = 'https://panel.example.com/api/v1/admin/settings/client-fields?' . http_build_query(['lang' => 'en']);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The fields BELONG to a language: a separate list, with separate ids, for each.
$en = Api::Settings()->GetClientFields([], ['lang' => 'en'])['data'];
$tr = Api::Settings()->GetClientFields([], ['lang' => 'tr'])['data'];
Response 
{
  "data": [
    {
      "id": 5,
      "lang": "en",
      "type": "text",
      "name": "VAT Number",
      "status": "active",
      "required": false,
      "uneditable": false,
      "client_hidden": false,
      "invoice": true,
      "sign_form": true,
      "options": "",
      "rank": 0
    }
  ],
  "meta": { "lang": "en", "total": 1 }
}

Adding a Custom Field

post/api/v1/admin/settings/client-fields
Settings/CreateClientField admin 201

Adds a new field to the registration form.

Body 10
namestringrequiredThe label to show the client.
langstringThe language to open the field in.
typestringThe field type. It defaults to text.
statusintSwitches the field on or off. It defaults to on.
requiredintMakes the field required.
uneditableintStops the client changing it later.
client_hiddenintHides the field from the client. Only admins see it.
invoiceintShows the field on the invoice.
sign_formintAsks the field on the registration form.
optionsstringThe values to offer on the choice types.
Response fields data — 12
*objectThe field that was created, in the same schema as a list item. The answer carries 201.
Errors 4
invalid_lang422The language code is not valid.
name_required422The field name was empty.
create_failed422The field could not be added.
insufficient_scope403The key lacks the required scope.
Request 
curl -X POST 'https://panel.example.com/api/v1/admin/settings/client-fields' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"lang":"en","name":"VAT Number","type":"text","required":1,"invoice":1,"sign_form":1}'
const res = await fetch('https://panel.example.com/api/v1/admin/settings/client-fields', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    lang: 'en',
    name: 'VAT Number',
    type: 'text',
    required: 1,
    invoice: 1,
    sign_form: 1,
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/client-fields');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'lang'      => 'en',
        'name'      => 'VAT Number',
        'required'  => 1,
        'sign_form' => 1,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The field opens in the GIVEN language only; you have to add it for each one.
foreach (['en', 'tr'] as $lang) {
    Api::Settings()->CreateClientField([
        'lang'      => $lang,
        'name'      => $lang === 'tr' ? 'Vergi No' : 'VAT Number',
        'required'  => 1,
        'sign_form' => 1,
    ]);
}

Ordering the Fields

put/api/v1/admin/settings/client-fields/order
Settings/ReorderClientFields admin

Writes the order the fields appear in on the form, for one language.

Body 2
langstringrequiredWhich language's fields to order.
orderint[]requiredThe field ids, in the order you want.
Response fields data[] — 12
*objectThe reordered list, in the same schema as listing the fields.
rankintRewritten from the order you send. An id you leave out keeps its old rank, which can leave gaps; send the full order for a clean sequence.
Errors 2
invalid_lang422The language code is not valid.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/settings/client-fields/order' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"lang":"en","order":[7,5,9]}'
const res = await fetch('https://panel.example.com/api/v1/admin/settings/client-fields/order', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ lang: 'en', order: [7, 5, 9] }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/client-fields/order');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['lang' => 'en', 'order' => [7, 5, 9]]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The order is PER LANGUAGE: each one has to be ordered separately, with its own ids.
$ids = array_column(
    Api::Settings()->GetClientFields([], ['lang' => 'en'])['data'],
    'id',
);

Api::Settings()->ReorderClientFields(['lang' => 'en', 'order' => array_reverse($ids)]);

Updating a Custom Field

patch/api/v1/admin/settings/client-fields/{id}
Settings/UpdateClientField admin

Changes an existing field. The name cannot be emptied.

Body 10
namestringrequiredThe label to show the client.
langstringThe language to open the field in.
typestringThe field type. It defaults to text.
statusintSwitches the field on or off. It defaults to on.
requiredintMakes the field required.
uneditableintStops the client changing it later.
client_hiddenintHides the field from the client. Only admins see it.
invoiceintShows the field on the invoice.
sign_formintAsks the field on the registration form.
optionsstringThe values to offer on the choice types.
Response fields data — 11
*objectThe updated field, in the shape it was stored in.
Errors 3
not_found404No such field.
name_required422The name you sent was empty.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PATCH 'https://panel.example.com/api/v1/admin/settings/client-fields/5' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Tax ID","required":0}'
const res = await fetch('https://panel.example.com/api/v1/admin/settings/client-fields/5', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Tax ID', required: 0 }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/client-fields/5');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['name' => 'Tax ID', 'required' => 0]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Hiding and requiring CONTRADICT each other: a client cannot fill a field they never see.
Api::Settings()->UpdateClientField([
    'id'            => 5,
    'client_hidden' => 1,
    'required'      => 0,
]);

Deleting a Custom Field

delete/api/v1/admin/settings/client-fields/{id}
Settings/DeleteClientField admin the answers go too

Removes the field. The answers clients gave to it go as well.

Response fields data — 2
deletedboolWhether the delete succeeded.
idintId of the deleted field.
Errors 2
not_found404No such field.
insufficient_scope403The key lacks the required scope.
Request 
curl -X DELETE 'https://panel.example.com/api/v1/admin/settings/client-fields/5' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.example.com/api/v1/admin/settings/client-fields/5', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/client-fields/5');
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);
// Switching it OFF instead of deleting keeps the answers: the field leaves the form, the data stays.
Api::Settings()->UpdateClientField(['id' => 5, 'status' => 0]);

Pitfalls

Requiring does not start asking

Each built-in field has separate keys for being asked and for being required. Switching on the requirement alone does not put the field on the form; the client never sees it and the setting quietly does nothing. Switch both on together.

A custom field opens in one language only

Adding a custom field creates it in the language you gave and nowhere else. With two languages on the site, clients on the second one never see that field. You have to add it for each language, and write the order for each separately.

A hidden field cannot be required

Hiding a field from the client removes it from the account, the registration form, the invoice and the client API. Leaving it required at the same time makes registration impossible: a client cannot fill a field they never see. Clear the requirement when you hide it.

Deleting a field deletes the answers

Deleting a custom field does not merely change the form: every answer clients gave to it goes with it. To stop asking without losing them, switch the field off instead; the form is tidied and the data collected stays.

Closing registration does not close sign-in

Registration and sign-in are separate keys. Closing registration does not stop existing clients signing in, so shutting the system for maintenance means closing both. The reverse also holds: closing sign-in while registration stays open produces clients who can open an account but not get into it.

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