Skip to main content
Belcenter AIHelp center
Administer the platform

Integrate website sign-up

Create the account, bot, and subscription via API, then connect the customer to their number tracking.

Guide for commercial website developers — production release of 22 September 2026.

Objective: after completing the form and payment authorisation on the website, the customer arrives logged into BeAI. They see their assistant being set up, followed by their number and the Edit my bot button. BeAI handles the subscription, initial direct debit, invoice, and number allocation.

This journey applies to a new customer directly attached to the vendor of the integration account: root Beone, or a reseller whose subscriptions are activated by a platform administrator. The reseller itself does not subscribe to a customer plan. The Beone website examples below use the Beone vendor; another vendor must have its own catalogue and its own configuration. For an existing BeAI organisation, use the journey described at the end of this guide.

1. Division of responsibilities

The commercial website does BeAI does automatically
Display public plans obtained via API Administer and version the catalogue
Collect the form, billing details, and acceptance of terms Create the customer organisation and its administrator
Verify that the visitor controls the email address used Reject an address that is already used in BeAI
Have a recurring mandate authorised with Mollie, on the Beone account Read back this mandate from Mollie and verify its validity
Call a single registration endpoint, with a stable idempotency key Create the bot and its contract, then trigger the first charge
Retain the returned identifiers and retry uncertain network responses Activate the contract after confirmed payment and prepare its included number
Request the initial login link and redirect the customer to it Log in the new administrator and display live tracking
Allow the journey to be resumed if the browser was closed Manage monthly instalments, minutes, credit, invoices, and cancellation

Do not create a recurring Mollie subscription or payment for the first monthly instalment on the website side. The website obtains the debit mandate authorisation; BeAI charges the subscription. Do not create the organisation, user, bot, or number order separately: the registration route orchestrates these operations.

The invoice is generated after payment confirmation, asynchronously. An Odoo delay does not trigger a second charge and does not block a bot whose telephony is ready.

2. Prerequisites and environment

On the Beone side, before testing

A platform administrator for Beone, or an authorised administrator of the reseller, prepares:

  • the active and public plans, each linked to an active bot template;
  • a neutral bot template, with a compatible assistant type and voice;
  • the rates for future customers of their vendor organisation: the single voice rate must be defined there;
  • the test Mollie configuration for the same account as the one used by the website;
  • staging Odoo invoicing and the staging email recipient;
  • payment, billing, and number processing jobs, as well as the public Mollie webhook;
  • a BeAI technical account with administrator rights for the vendor organisation, and its API key.

The technical account must administer the vendor, not a customer organisation. A platform admin role is not required for the Beone website: its organisation administrator receives only active public plans and the legacy registration API, without management of private plans. Standard creation retains its usual rights, platform or reseller organisation administration; the website journey adds none. For a reseller, its authorised administrator can manage its own private plans: the website backend must therefore always filter active public plans before displaying them to visitors, regardless of the account used. Customer accounts only receive their vendor's active public catalogue. Creation grants the creator direct access to the new organisation, usable in the GUI and the API to monitor its registration, without exposing organisations outside its scope. A rejected registration does not retain any access or partially created customer. The key inherits its owner's permissions; it must remain exclusively on the website server.

Website server variables

BEAI_BASE_URL=https://ai-dev-public.beone.be
BEAI_API_KEY=<cle_API_du_compte_technique>
MOLLIE_API_KEY=<cle_test_du_compte_Beone>
WEBSITE_BASE_URL=https://<site-de-recette>

The calls below use HTTPS and the following headers:

Authorization: Bearer <BEAI_API_KEY>
Accept: application/json
Content-Type: application/json

Do not send the BeAI key to the browser, in a mobile app, or in URL query parameters. Browser calls go through the website backend; no BeAI CORS enablement is necessary.

In production, the website and BeAI must use the same live Mollie account of the vendor; staging customer IDs and mandates cannot be reused. The billing method can be consulted in subscription settings by an authorised vendor administrator. For a reseller, GET/PATCH /api/v1/organisations/{id}/subscription-settings manages its own configuration; no missing identifiers are retrieved from the Beone account. Without an explicit choice, the bot created uses the standard voice configuration.

In DEV, payments are Mollie test payments and invoices belong to the staging Odoo instance. The phone number nevertheless uses real telephone infrastructure: test reservations remain coordinated with Beone.

Commercial website in production

The beai.beone.be/tarifs website uses the catalogue and registrations of https://ai.beone.be. The three plans are offered in the twelve website languages. Verification codes are sent to the customer's email address; staging notices are no longer displayed. Billing links and initial login lead to the production portal.

The website and BeAI use live Mollie from the same Beone account. The initial card authorisation is for 0 EUR; BeAI then charges the first monthly instalment and generates the invoice once payment is confirmed. A card authorisation does not prove that the subscription is already active: tracking displays the actual status of the payment and the number.

Staging registrations, mandates, and sessions are not transferred to production. An interrupted journey must be resumed in its original environment; do not recreate an order when its outcome is uncertain. The website's technical account keeps the same permissions in the GUI and the API, without access to platform settings or private plans.

3. Journey to implement on the website

  1. The backend reads the catalogue. The visitor selects a plan.
  2. The visitor fills in their company, account, billing, and assistant details. The website verifies their email address and collects their acceptance of the terms.
  3. The backend creates or finds the Mollie customer associated with this registration, then has the mandate authorised.
  4. The backend checks Mollie again and waits for a usable mandate. The browser redirect is not sufficient.
  5. The backend freezes the registration body and its idempotency key, then calls POST /api/v1/website-signups.
  6. Upon receiving data.id, it stores the identifiers and requests POST /api/v1/website-signups/{id}/handoff.
  7. The browser opens the exact URL received. It is logged in as the new administrator and lands on the BeAI welcome page.
  8. This page tracks the stages: Account and bot created → First month paid → Included number assigned → Ready to receive your calls.
  9. When the service is ready, it displays the callable number and Edit my bot. The customer can also open Subscription and billing.

There is no need to wait for number assignment on the website side before redirecting. Provisioning and payment can continue even if the visitor closes their browser.

After the initial login, the customer can find this page again under My subscription → Order tracking and via the View progress button in Subscription and billing. A mini tracker appears in the top bar during provisioning. These access points use the current session, without generating or reusing an SSO ticket.

To retrieve tracking without retaining the registration identifier, use GET /api/v1/organisations/{id}/website-onboarding. The response is {"data": {…}} with the same object as tracking by identifier, or {"data": null} if the current contract has no associated registration. This read access is restricted to authorised administrators of this organisation; access outside this scope is denied. Responses must not be cached. No payment or provisioning is triggered.

Commercial website languages

The commercial website offers pricing, the form, subscription terms, tracking messages, and verification emails in its twelve languages: French, English, Dutch, German, Spanish, Italian, European Portuguese, Russian, Arabic, Turkish, Simplified Chinese, and Japanese. The language selector preserves the selected package. The redirect after payment authorisation also preserves this language.

The preview of the assistant's opening lines is translated and sent via the existing bot.greeting_message field. Information entered by the customer is not automatically translated. The website does not modify language preferences for existing BeAI accounts; after login, the portal applies its own available languages and account preferences.

The payment page hosted by Mollie uses its supported languages. For an unsupported language, Mollie applies its own fallback; the website's return page remains translated. The official Beone terms and conditions PDF remains available in French, which is indicated prior to consent.

A language change does not create a new registration. Contact details, the accepted plan, and payment transactions remain linked to the same reference. Once a payment order is submitted, its content and key remain unchanged during retries, even if the user switches the displayed language.

4. Plan catalogue

GET /api/v1/subscription-plans

Example of abbreviated response — identifiers are for illustrative purposes only:

{
  "data": [
    {
      "id": 1,
      "seller_id": 1,
      "code": "minutes-200",
      "name": "200 minutes",
      "revision": 1,
      "enabled": true,
      "public": true,
      "monthly_eur": "70.00",
      "included_minutes": 200,
      "overage_eur_per_minute": "0.40",
      "max_bots": 1,
      "template_id": 12,
      "currency": "EUR",
      "tax_mode": "HTVA"
    }
  ]
}

Display only enabled === true && public === true items, even if a higher-privileged key is used by mistake. seller_id identifies the seller for each plan; an authorised account can select its context using GET /api/v1/subscription-plans?seller_id={id}. Registration website-signups uses the integration account's seller and rejects any external plan. Do not use template_id to create the bot yourself. Use the id and revision values actually received; they are not identical across environments.

The initial catalogue includes 70 €/200 min/1 bot, 140 €/400 min/2 bots, and 210 €/600 min/5 bots, with 0,40 €, 0,35 €, and 0,30 € excl. VAT per additional minute respectively. The API remains the authoritative source for displayed prices. An update to the catalogue does not alter existing contracts.

Send plan_revision in the registration request. If the plan has changed since it was displayed, BeAI returns 409 prior to creation and debiting. Re-read the catalogue and ask the client to accept the new terms before submitting an updated request.

Catalogue prices are excl. VAT. The total incl. VAT for the billing period is returned by BeAI; do not assume a uniform VAT rate across all clients.

5. Obtaining the Mollie mandate

Use the seller account test key for all acceptance testing Mollie operations. For the Beone website, this is the Beone account. A customer or mandate from another account, or live references used with a test key, are not valid.

The Mollie flow typically consists of creating a customer, followed by an authorisation payment using sequenceType: "first" and customerId. Once approved by the client, re-read the payment and mandates for this customer. Select a valid mandate allowing off-session payments. Refer to Mollie recurring payments and creating a payment for methods enabled on the account.

A 0 € authorisation depends on the method and whether Mollie supports it. Do not replace this authorisation with a 70/140/210 € collection on the website side. If a method requires a small initial authorisation payment, agree on this handling with Beone before presenting it to the client: this amount is not automatically deducted from the BeAI monthly fee.

For registration purposes, the website must retain customer_id and mandate_id. Do not send card numbers, CVCs, or Mollie keys to BeAI.

{
  "customer_id": "cst_example",
  "mandate_id": "mdt_example",
  "status": "valid",
  "expires_at": null
}

status and expires_at may be provided, but BeAI's re-reading of Mollie is authoritative. An absent expiry date is possible depending on the method. A mandate unavailable due to network issues is not marked invalid. See Read a Mollie mandate.

Three distinct URLs

URL Purpose
redirectUrl for the Mollie authorisation payment Browser redirect back to the commercial website; the backend re-reads Mollie before proceeding
webhookUrl for the authorisation payment Webhook notification to the website backend, which re-reads Mollie; it does not create a second registration
data.url of the BeAI operation /handoff Initial client login to BeAI, followed by the welcome page

The first subscription direct debit and subsequent payments are generated by BeAI with its own webhook. The website must neither alter this webhook nor receive BeAI payment secrets. Monitoring bot provisioning is handled via the status API; this provisioning does not send a "bot ready" webhook to the website.

6. Creating the complete registration

POST /api/v1/website-signups
Idempotency-Key: signup-<UUID-stable-de-cette-inscription>

Complete example JSON body:

{
  "plan_id": 1,
  "plan_revision": 1,
  "organisation": {
    "name": "Atelier Exemple",
    "billing": {
      "name": "Atelier Exemple SRL",
      "email": "facturation@example.be",
      "address_line_1": "Rue Exemple 10",
      "address_line_2": "",
      "postal_code": "1000",
      "city": "Bruxelles",
      "country_code": "BE",
      "vat_number": ""
    }
  },
  "user": {
    "email": "client@example.be",
    "password": "<mot-de-passe-choisi-par-le-client>",
    "display_name": "Camille Exemple"
  },
  "bot": {
    "company_description": "Atelier de réparation de vélos. Nous réparons les crevaisons, les freins et les transmissions. Les devis sont établis après diagnostic à l’atelier.",
    "opening_hours": "Du lundi au vendredi de 9 h à 18 h. Fermé le week-end.",
    "website": "https://example.be"
  },
  "payment_method": {
    "customer_id": "cst_example",
    "mandate_id": "mdt_example",
    "status": "valid",
    "expires_at": null
  }
}

Fields and rules

Field Rule
plan_id Integer ID of an active plan accessible to the technical account
plan_revision Recommended integer, matching the accepted catalogue; prevents price changes prior to subscription
organisation.name Business name used to introduce the assistant
organisation.billing Billing name, valid email address, street address, postal code, city, and two-letter country code required; address line 2 and VAT number optional
user.email Unique email address in BeAI; the website must verify ownership before granting access
user.password At least 10 characters; sent strictly over HTTPS, never logged; BeAI hashes it
user.display_name Optional, company name by default
bot Optional; the plan template supplies the voice settings and BeAI generates the business overview
payment_method.customer_id Mollie customer reference cst_…; cannot be assigned to another organisation belonging to the same seller
payment_method.mandate_id Reference mdt_… of this customer's mandate

The public form must not allow users to select roles, a parent organisation, a SIP provider, or administrative options. BeAI determines these settings. Unknown fields are rejected.

First assistant preset

The two text literals below reproduce the French values of this example’s preset. They are not translated when you change the help centre’s language.

If these texts are not customised:

  • the name becomes Assistant IA — Atelier Exemple;
  • the greeting becomes Bonjour, je suis l’assistant IA de Atelier Exemple. Comment puis-je vous aider ?;
  • the instructions require a polite greeting, concise answers based on business information, and never inventing details or promising unconfigured actions;
  • business activity, opening hours, and website are integrated into the bot's knowledge base;
  • recording and self-improvement are enabled;
  • transfer destinations, emails, tags, and external actions from the template are not imported.

The website field is purely informational text: BeAI does not automatically crawl the website during this registration. Send genuinely relevant information in company_description.

The optional fields bot.name (120 characters), bot.company_description (12 000), bot.opening_hours (2 000), bot.website (HTTP/HTTPS URL, 2 048), bot.greeting_message, and bot.extra_infos allow you to customise the preset. The greeting and additional information are limited to 12 000 characters each. The desired tone can be described freely at the start of extra_infos in Markdown. The legacy field temperament is still accepted for writing for backward compatibility and is prefixed into this text. Total compiled knowledge cannot exceed 65 535 bytes. default_lang and voice allow selecting a compatible language and voice; omitting them retains the default choices. ai_model is reserved for platform administrators: including this field in a request from a standard technical account is rejected, even if its value matches the default.

Only submit information confirmed by the client. Number selection, business integrations, documents, and advanced transfers are configured subsequently in Edit my bot.

7. Creation response and payment

An accepted registration returns HTTP 202 with a {"data": ...} wrapper. 202 does not yet mean "payment paid" or "number ready".

Excerpt of response after confirmed payment but before number assignment:

{
  "data": {
    "id": "0123456789abcdef0123456789abcdef",
    "organisation_id": 123,
    "user_id": 456,
    "bot_id": 789,
    "status": "preparing_number",
    "number": null,
    "number_reservation_id": "12345678-1234-4234-8234-123456789abc",
    "error": null,
    "subscription": {
      "id": "abcdef0123456789abcdef0123456789",
      "status": "active"
    },
    "onboarding": {
      "status": "preparing_number",
      "ready": false,
      "title": "Votre bot est en préparation",
      "message": "Nous réservons et raccordons votre numéro inclus. Vous n’avez rien à configurer.",
      "poll_after_seconds": 5
    }
  }
}

The actual response also includes contract details, instalments, and tracking information. At a minimum, keep id, organisation_id, user_id, bot_id, and subscription.id in the website's registration record.

Upon receiving a valid mandate, BeAI generates the first direct debit. Once confirmed, it opens the initial minute allowance, sets the contract dates, prepares the number, and submits the invoice for processing. The number is included in the plan, with no additional rental charge billed to the client. Reserving it is not a credit purchase.

Do not trigger retry-payment or a new registration simply because the response still contains pending, uncertain, awaiting_payment, or preparing_number.

8. Automatic login and welcome page

After recording the registration ID:

POST /api/v1/website-signups/0123456789abcdef0123456789abcdef/handoff

No business body is required; {} is accepted. Response HTTP 200:

{
  "data": {
    "url": "https://ai-dev.beone.be/welcome/0123456789abcdef0123456789abcdef/connect#ticket=<secret-a-usage-unique>",
    "expires_at": "2026-09-21T15:10:00+00:00",
    "single_use": true
  }
}

The backend passes this URL strictly to the browser of the client whose registration has just been verified. Redirect the browser to the full URL, including the fragment. For example, your backend returns {"redirect_url": data.url} with Cache-Control: no-store, and your frontend then executes:

// La réponse provient de VOTRE backend, pour la session du client courant.
window.location.assign(result.redirect_url);

This link is an access secret: do not include it in tracking URLs, marketing emails, logs, analytics tools, support tools, or persistent browser storage. Disable response body capture for this response. Validate server-side that the received URL belongs to the configured BeAI origin before passing it to the browser.

Duration, retries, and security

  • The link expires 10 minutes after issue and can only be used once.
  • Issuing a new link invalidates the previous one. It does not recreate any resources and does not trigger any debit.
  • Issuance is limited to the first 24 hours following registration creation.
  • Only the BeAI account that created this registration, or a platform admin, can issue this link. Another key from the same technical account retains this right; a key from another account does not inherit it.
  • The secret is placed in the #ticket=… fragment, removed from browser history by the BeAI page, and then exchanged via a CSRF-protected POST request. It is not transmitted in the browser GET request.
  • The GET request alone does not log anyone in. There is neither a password nor an API key in this URL.
  • The BeAI session is replaced with that of the new administrator. The former context of any other organisation is cleared.
  • The link stops working if the user is blocked, moved out of the organisation, stripped of their administrator role, or if the contract has ended.
  • After expiry, if a link has already been used, or beyond the 24-hour issuance window, standard log-in using email address and password remains available. Forgot password is accessible on the log-in page.

The website may offer Continue in BeAI when resuming its form, but must re-verify that its session belongs to the correct client. Never create a public endpoint that issues a handoff from a supplied signup_id without ownership verification.

No arbitrary callback_url or return_url parameter is accepted in the registration: the final destination is the BeAI page for this registration. To return to tracking later without automatic log-in, use onboarding.links.self.

9. Track preparation

Full status for the website backend

GET /api/v1/website-signups/{signup_id}

This route is reserved for the authorised Beone account. It returns the registration and its contract; it never provides a new log-in secret.

Status intended for the home page

GET /api/v1/website-signups/{signup_id}/onboarding

This route shares the exact same service and controls as the welcome page. It is accessible to Beone and authorised administrators of the client organisation. For the website, always use your backend; do not expose its API key to the browser.

The response contains status, title, message, ready, number, progress, payment, invoices, links, poll_after_seconds, and checked_at, as well as the IDs and names of the organisation and bot.

onboarding.status Presentation and action
awaiting_payment Initial payment in progress; wait, do not debit again
payment_failed Initial payment refused; offer Subscription and billing to correct mandate and settle
preparing_number Payment confirmed; number allocation and connection in progress
preparing_telephony Number allocated; telephony availability currently being verified
needs_attention Beone verification is required; retain the account and payment, do not restart registration
ready Payment confirmed, active number routed to this bot, and telephony available; display the number and Edit my bot
suspended Settlement of instalments required before service resumption
ended Contract terminated; history and invoices are retained

The legacy data.status field uses fewer statuses. For a new interface, use data.onboarding.status or the /onboarding route. Only display the promise "you can already call it" if ready === true, not merely because a number is present.

progress has four real steps: its percentages are not a duration estimate. The BeAI page updates them automatically, handles network interruptions, and offers to resume connection if the session expires. Do not advertise a guaranteed setup time.

Observe poll_after_seconds (5 seconds during preparation, 30 when ready, null to stop automatic polling). Use exponential backoff up to 30 seconds after a network error, and pause requests when the tab is hidden. The BeAI page already implements this behaviour.

links.edit_bot opens bot editing; links.billing opens the single Subscription and billing page. invoices tracks the invoice independently of the number. The PDF can be viewed in BeAI or, with the required permissions, via:

GET /api/v1/organisations/{organisation_id}/subscription/invoices/{invoice_id}/pdf

Encode the invoice ID as a URL segment and expect pdf_available: true. An invoice marked pending, posted, or error is not an invitation to collect payment again.

10. Idempotency and essential retries

Data to retain on the website side

For each registration, permanently retain:

  • its internal ID, verified owner, and idempotency key;
  • the plan, its revision, and proof of acceptance of its terms;
  • the Mollie customer, authorisation payment, and mandate references;
  • the BeAI request status and BeAI IDs as soon as they are known;
  • the latest tracking statuses useful for support, without sensitive content or log-in tickets.

The BeAI key must contain 8 to 100 characters including letters, digits, ., _, :, and -. An UUID prefixed with signup- is suitable. It is linked to the creator technical account and the request body.

Retry algorithm

Prendre un verrou sur l’inscription du site
Vérifier le propriétaire de la session et son acceptation des conditions
Si signup_id BeAI existe :
    GET /website-signups/{signup_id} si un statut est nécessaire
Sinon :
    Si le mandat n’est pas encore confirmé : attendre sa confirmation Mollie
    Figer une clé d’idempotence et le corps JSON exact
    POST /website-signups avec cette clé et ce corps
    Enregistrer immédiatement les identifiants de la réponse 202
Si la session du client doit entrer dans BeAI :
    POST /website-signups/{signup_id}/handoff
    Retourner son URL à cette seule session, sans cache
Libérer le verrou

Two simultaneous browser requests and the Mollie authorisation webhook must converge towards the same registration. The website can use a row-level lock or a uniqueness constraint on its order.

In the event of a timeout/502/503/dropped connection after the POST, the registration may still have been created. Replay the same key and the same body with the same technical account. BeAI retains the order durably; submitting different data with this key returns 409. Do not generate a new key when clicking "Retry".

The body contains a password. If asynchronous retry requires its temporary retention, use restricted encrypted storage with a short lifespan, then delete this secret as soon as the BeAI ID is recorded. Never store the complete body in plain text in logs, task queues, or observability tools. The password is not required for tracking and handoff calls.

A correction following a definite refusal prior to creation may be submitted under a new key. If the outcome is uncertain, reconcile the original registration first: never bypass a 409 by generating keys until successful.

Mollie also features idempotency keys, with a cache limited to one hour. Use them for your own authorisation operations, but maintain your durable log. BeAI applies the same separation for its direct debits: Mollie idempotency.

11. Errors to handle

The API typically returns a problem object with an HTTP status and detail text. Do not base logic on an exact translation of the text. An infrastructure outage may return HTML or no body at all: cater for this scenario.

Situation Website reaction
401 / 403 Check key and technical account permissions; do not ask the client for a new card
404 Inaccessible/non-existent identifier or private plan not visible; check environment and scope
409, plan modified Reload terms and request new acceptance prior to creation
409, existing user Offer log-in to BeAI and subscription from their existing organisation; do not artificially modify their email address
409, Mollie customer already assigned Find the existing registration or have the reconciliation checked by Beone
409, key reused with a different body Retrieve original body; do not bypass protection with a new key
409 on handoff Initial log-in unavailable, notably after 24 hours or contract termination; offer standard log-in
422 Correct fields, mandate, or invalid model after reading the details
503 during Mollie verification Temporary incident; retain the registration and retry without replacing the mandate with "invalid"
Timeout, 5xx, unreadable response from the creation POST Outcome uncertain: retry with the same body and same key
202 with payment failed Registration exists; direct towards settlement without recreating it
needs_attention or prolonged preparation Display tracking and support, forward IDs to Beone; do not re-order a number

The website can replace a mandate at the client's explicit request via POST /api/v1/organisations/{id}/payment-method/import. This operation is restricted to authorised seller administrators and re-verifies Mollie using that seller's account. Clients also have access to the replacement journey within BeAI.

An explicit settlement uses POST /api/v1/organisations/{id}/subscription/retry-payment with {"charge_id":"..."} and a new idempotency key for this settlement action. It is refused as long as the previous payment remains in progress or uncertain. The normal website flow does not need to call this route automatically.

12. Commercial information to display before confirmation

The website displays the terms and conditions actually accepted, notably:

  • monthly fee excl. VAT and VAT handling, minutes, overage rate, and bot quota;
  • one number included per bot, minutes shared across bots and authorised models, renewed without rollover;
  • first minute indivisible for each started AI call, then charged per second;
  • overage charged against prepaid credit, with optional automatic top-up; transfers, outbound branches, SMS, and text usage maintain their own pricing;
  • 12-month commitment with monthly payment;
  • cancellation during the first month for termination at its end, with no pro-rata refund: this is not a free month;
  • after the first month, payment continues until the end of the commitment period; then a one-calendar-month notice period applies;
  • option to cancel a termination request before the effective end date; after this date, a new subscription is required;
  • plan upgrades upon quote and pro-rata payment, without extending the commitment period; downgrades are prohibited;
  • number preparation after payment confirmation, with progress displayed to the client.

Subsequent management is handled on BeAI's single page: plan, minutes, automatic top-ups, alerts, payment method, and invoices. See Subscription and billing.

13. Client already present in BeAI

Do not put an existing client through the website-signups creation route. Their administrator can subscribe from Subscription and billing, or an authorised integration can call:

POST /api/v1/organisations/{organisation_id}/subscription
Idempotency-Key: enrollment-<UUID-stable>
{"plan_id": 1, "plan_revision": 1, "confirmed": true}

This journey preserves existing users, bots, and credit. It does not automatically create a new bot or number. It checks quotas and waits for a payment method if necessary. The handoff described in this guide applies only to the account created via a website registration; it cannot be used to log in to an arbitrary BeAI account.

14. UAT checklist to validate together before public launch

  • Catalogue retrieved via API, private and deactivated plans excluded, revision submitted.
  • Visitor email address verified and terms accepted before direct debit.
  • Test Mollie authorization attached to the same Beone account; browser return alone is insufficient.
  • A valid registration creates a single organisation, an administrator, a bot, and an initial billing due date.
  • Double-clicking, duplicate webhooks, and POST timeouts do not create duplicates or a second charge.
  • The bot introduces the correct company and its details; no instructions or destinations belonging to another client.
  • Invalid, expired, different customer mandate, and network failure handled distinctly.
  • Pending/refused payment does not prematurely trigger number reservation.
  • Confirmed payment produces an Odoo test invoice, its payment, and an email to the test recipient.
  • An Odoo outage after payment does not trigger a new direct debit and can be resumed.
  • The included number is assigned to the correct bot without additional client rental charges; an actual call verifies caller ID and audio.
  • The handoff logs in the correct user, grants no Beone permissions, expires, and refuses a second use.
  • The website never delivers the link of one registration to another client’s session.
  • The welcome page displays the actual steps, then the number and Edit my bot, on desktop and mobile.
  • Provider errors, expired sessions, and network interruptions retain a clear recovery path.
  • Keys, passwords, tickets, and banking details do not end up in logs/analytics.

The checkboxes above are validation criteria for the integration, not a statement that the external website has already passed its UAT. A technical preparation status does not replace the actual service validation call.

15. GUI equivalence and OpenAPI reference

Internal creation is now done in Organisations → Create, for a platform administrator or an authorised reseller administrator within their scope: prepaid credit by default, or seller plan with confirmation. Its equivalent is POST /api/v1/organisations, with the subscription object and a Idempotency-Key key for selecting a plan. This journey prepares a contract awaiting a payment method, without requiring a user, bot, or mandate, and with no direct debit upon registration. Users and bots can be created afterwards.

The complete POST /api/v1/website-signups journey described in this guide remains compatible with existing integrations. Its bot data, mandate, payment, and number preparation remain explicit. The old GUI link Register a website client redirects to standard creation; it no longer displays a separate wizard. For a registration originating from the website, tracking retains View client home page and Create customer login link, with the same permissions and timeframes as /handoff.

The /welcome/{id}/connect and /welcome/{id}/session routes are browser login transports protected by CSRF; the website does not need to call them directly. The business operations for issuing links and consulting tracking have their /api/v1 equivalents.

The OpenAPI documentation accessible via Profile → API documentation describes the WebsiteSignupWrite, WebsiteSignup, WebsiteHandoff, and WebsiteOnboarding schemas, their envelopes, and the routes visible for the logged-in account. The examples in this guide are fictional and must be replaced with values from the catalogue and responses of the chosen environment.

16. Journey deployed on the BeAI website (OVH UAT)

The commercial website's form now offers plan selection, email confirmation via code, billing and assistant information, followed by card authorisation at 0 € on Mollie. BeAI creates and debits the first monthly instalment; the website then redirects to the logged-in home page. For this release, other language entry points join the same French journey.

UAT is limited to the authorised test address, with test Mollie and BeAI DEV. The catalogue continues to be fetched via the API. An interrupted session can be resumed with the same address and a new code. Double clicks and webhooks do not start a new order. If a Mollie response remains uncertain after the recovery window, the website retains the request and indicates that verification is required.

On DEV, external hosting uses https://ai-dev-public.beone.be; the private address cannot be reached from OVH. The login destination is set by BeAI (BEAI_WEBSITE_PUBLIC_URL, HTTPS origin configured by the operator), never by a browser field. The same service generates the link from both the GUI and the API; neither its expiration nor its permissions change. The form's internal backend is a transport for the commercial website, not a new BeAI business API.

Try 50 EUR of prepaid credit

The website also offers Prepaid: a one-off purchase of 50 EUR excluding VAT in credit and voice at 0.50 EUR excluding VAT/minute, with no automatic credit expiry or renewal. This signup is for new customers directly under Beone. A BeAI number is optional and charged separately at the price shown before reservation; this signup does not reserve a number. Other usage and options consume credit at their applicable rates.

Choose Prepaid alongside the subscriptions, confirm your email, enter your company details and choose your password. The review separates the one-off payment from monthly charges and shows any VAT at checkout. You accept prepaid terms; this offer creates neither a recurring mandate nor a zero-euro card authorisation.

BeAI prepares the account and a first bot without granting credit before confirmed payment. Confirmation adds the 50 EUR once, then the Odoo billing flow produces the invoice. Sign in with your chosen email and password to configure telephony or reserve an optional number. A browser return is not proof of payment.

You can later subscribe from Subscription and billing in the existing account: bots and balance are preserved, and the accepted plan rates apply after activation. Existing accounts top up from their space instead of creating another signup.

The website backend uses the following operations, restricted to a platform administrator or an authorised Beone administrator. The key stays on the server. The catalogue returns a disabled offer when required payment or billing configuration is missing.

GET /api/v1/prepaid-offer
POST /api/v1/prepaid-signups
GET /api/v1/prepaid-signups/{id}

To create, send the organisation, user and optional bot objects, with offer_revision: 1 and a stable Idempotency-Key header. BeAI enforces the price and rate. The API returns 202 with awaiting_payment, ready or needs_attention; reading status creates no payment. A changed offer or existing email returns 409; invalid data returns 422.

After an uncertain response, repeat the exact same object and key. Keep the displayed reference. The needs_attention state requires checking the existing order with Beone instead of restarting payment. Do not create duplicate credit or invoices to unblock signup.

Documentation updated with the application