Jump to content

TuCloudAPI: Difference between revisions

From Wiki 7Kas
← Older edit
getpbxs: account-scoped selector (all roles)
TuCloudAPI calendar: year-end periods (year_wrap) and 29/02
 
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Note|New here? Start with '''[[TuCloudAPI help|the self-discovery endpoint]]'''. This reference is generated from <code>func=help</code>, so it never drifts.}}
{{Note|1=New here? Start with '''[[TuCloudAPI help|the self-discovery endpoint]]'''. This reference is generated from <code>func=help</code>, so it never drifts.}}


== Overview ==
== Overview ==
'''TuCloudAPI''' is the REST API to manage '''tucloud''' (the multi-tenant PBX, a.k.a. futurepbx). '''HTTPS, GET, JSON.''' Base URL:
'''TuCloudAPI''' is the REST API to manage '''FuturePBX''' (the multi-tenant cloud PBX). '''HTTPS + JSON''', GET or POST (parameters form-urlencoded; audio uploads POST the file as the body). Base URL:
  https://tucloudapi.7kas.com:9087/tucloud?func=NAME&ukey=YOUR_KEY&pbx=PBX_NAME
  https://tucloudapi.7kas.com:9087/tucloud?func=NAME&ukey=YOUR_KEY&pbx=PBX_NAME


== Authentication & tenant ==
== Authentication & tenant ==
Every call needs an '''API key''' (<code>ukey</code>). The '''tasks''' functions also need <code>pbx</code> — the PBX '''name''' (e.g. <code>tucall</code>). The <code>(ukey, pbx)</code> pair is the tenant boundary: the server resolves the PBX name to its id and verifies the key owns it ('''SuperRoot''' any PBX; '''Operator''' its own root; '''Client''' its own account). It never trusts a numeric tenant from the caller.
Every call needs an '''API key''' (<code>ukey</code>). Every PBX-scoped function also needs <code>pbx</code> — the PBX '''name''' (e.g. <code>tucall</code>). The <code>(ukey, pbx)</code> pair is the tenant boundary: the server resolves the PBX name to its id and verifies that the key's OWN account owns it — for every role, SuperRoot included. A PBX that does not exist and one the key does not own both answer <code>forbidden</code>. It never trusts a numeric tenant from the caller.


== Response format ==
== Response format ==
'''Always HTTP 200.''' The '''tasks''' functions always return a JSON envelope: success <code>{"ok":true, ...}</code>, empty <code>{"ok":true,"rows":[]}</code>, error <code>{"ok":false,"code":...,"message":...}</code> (codes: <code>missing_pbx, unknown_pbx, forbidden, invalid_param, not_found, db_error, server_busy</code>). IDs are exposed as <code>_id</code>. Base/legacy functions return their data object directly, or <code>{}</code> on error/empty.
'''Always HTTP 200.''' Every PBX-scoped function always returns a JSON envelope: success <code>{"ok":true, ...}</code>, empty <code>{"ok":true,"rows":[]}</code>, error <code>{"ok":false,"code":...,"message":...}</code> (common codes: <code>missing_pbx, forbidden, invalid_param, not_found, conflict, in_use, db_error, server_busy</code>). IDs are exposed as <code>_id</code>. A missing or invalid <code>ukey</code> answers a bare <code>{}</code> and nothing else. The legacy account functions return their data object directly, <code>{}</code> when there is nothing.


== Functions ==
== Functions ==
=== Dashboard (landing counts) ===
* [[TuCloudAPI getdashboard]] — Landing-page dashboard: per-tenant object counts + a cheap health metric, in one call.
=== Extensions (Extensiones) ===
* [[TuCloudAPI getextensions]] — List the PBX extensions (safe display fields; NEVER the SIP password).
* [[TuCloudAPI getextension]] — Get one extension with all editable fields (NO password).
* [[TuCloudAPI getextlookups]] — Tenant-scoped option lists for the extension form selects: caller IDs (clis), music-on-hold (music), outgoing services (outs), the extension list (exts, for Enviar a / backup monitor), registration servers (servers) and next_free: the create-form number prefill for a REGISTERED extension (3-4 digits, the same check as checkextnum), a string, or null when no number is free.
* [[TuCloudAPI checkextnum]] — Is this number free for a NEW extension of this PBX? The same check addextension runs under its lock, so the two never disagree.
* [[TuCloudAPI addextension]] — Create an extension.
* [[TuCloudAPI updateextension]] — Edit an extension.
* [[TuCloudAPI deleteextension]] — Delete an extension after a tenant + dependency check.
* [[TuCloudAPI setextpassword]] — Rotate ONE extension's SIP password.
* [[TuCloudAPI getextpassword]] — Plaintext SIP password for ONE extension (the portal's «Clave SIP» eye toggle).
* [[TuCloudAPI getextqr]] — SIP provisioning QR for one extension, rendered server-side to a PNG (base64).
=== CLIs / DIDs (Numeracion) ===
* [[TuCloudAPI getclis]] — List the PBX CLIs / DIDs (inbound numbers) with the grid fields.
* [[TuCloudAPI getcli]] — Get one CLI with all editable fields, including the full 192-key timer matrix under "timers".
* [[TuCloudAPI getclilookups]] — Tenant-scoped option lists for the CLI form: routes (all route selects), schedule profiles (template_h), and defined calendar templates (template_c helper).
* [[TuCloudAPI addcli]] — Create a CLI / DID.
* [[TuCloudAPI updatecli]] — Edit a CLI.
* [[TuCloudAPI deletecli]] — Delete a CLI after a tenant + dependency check.
=== Routes (Rutas) ===
* [[TuCloudAPI getroutes]] — List inbound routes for the PBX with step counts.
* [[TuCloudAPI getroute]] — Get one route header plus its ordered steps (destinations).
* [[TuCloudAPI getroutelookups]] — Tenant-scoped destination pickers for the step editor: the app enum plus extensions, groups, locutions, schedules, calendars, routes and queues (app=10 "Cola": _id = the stable voip_queue.id stored in the step appdata, label = the queue title).
* [[TuCloudAPI addroute]] — Create an inbound route (header only; add steps with addroutestep).
* [[TuCloudAPI updateroute]] — Rename/annotate a route header.
* [[TuCloudAPI deleteroute]] — Delete a route.
* [[TuCloudAPI addroutestep]] — Append a step to a route (priority = max+1).
* [[TuCloudAPI updateroutestep]] — Change a step's app/appdata/timer (and optionally priority).
* [[TuCloudAPI deleteroutestep]] — Remove a step; the remaining steps' priorities are auto-compacted to 1..N by the DB trigger.
=== Blacklist (inbound intercept) ===
* [[TuCloudAPI getblacklist]] — List the inbound-intercept rules for the PBX.
* [[TuCloudAPI getblacklistlookups]] — Tenant-scoped pickers for the rule form: routes (the divert target) and CLIs/DIDs (cli_id; 0 = all DIDs / generic rule).
* [[TuCloudAPI addblacklist]] — Create an inbound-intercept rule.
* [[TuCloudAPI updateblacklist]] — Edit an inbound-intercept rule.
* [[TuCloudAPI deleteblacklist]] — Delete an inbound-intercept rule.
=== Contacts (Agenda) ===
* [[TuCloudAPI getcontacts]] — List the PBX contacts (address book).
* [[TuCloudAPI addcontact]] — Create a contact.
* [[TuCloudAPI updatecontact]] — Edit a contact.
* [[TuCloudAPI deletecontact]] — Delete a contact.
=== Calendar (date overrides) ===
* [[TuCloudAPI getcalendars]] — List the PBX calendar date-overrides (one row = one recurring month/day + time window that reroutes inbound to a route for CLIs on that template).
* [[TuCloudAPI getcalendar]] — Get one calendar row.
* [[TuCloudAPI getcalendarlookups]] — Tenant-scoped pickers: routes (the destination) and the set of template values already in use (suggestions for the template spinner).
* [[TuCloudAPI addcalendar]] — Create a calendar date-override.
* [[TuCloudAPI updatecalendar]] — Edit a calendar row (same fields and period rule as addcalendar).
* [[TuCloudAPI deletecalendar]] — Delete a calendar row.
=== Ring groups (Grupos) ===
* [[TuCloudAPI getgroups]] — List the PBX ring/hunt groups with a member count.
* [[TuCloudAPI getgroup]] — Get one group.
* [[TuCloudAPI getgrouplookups]] — Tenant-scoped pickers: extensions (members), music (MOH), and CLIs (for the admin forward caller-id).
* [[TuCloudAPI addgroup]] — Create a ring group.
* [[TuCloudAPI updategroup]] — Edit a ring group (same fields as addgroup; gr editable, conflict on collision).
* [[TuCloudAPI deletegroup]] — Delete a ring group.
=== Locutions / IVR (Locuciones) ===
* [[TuCloudAPI getlocutions]] — List the PBX locutions / IVR prompts.
* [[TuCloudAPI getlocution]] — Get one locution with its DTMF digit->route map (+ resolved route names), has_audio and audio_url.
* [[TuCloudAPI getlocutionlookups]] — Tenant-scoped route picker for the 11 DTMF digit destinations.
* [[TuCloudAPI addlocution]] — Create a locution / IVR.
* [[TuCloudAPI updatelocution]] — Edit a locution (name, waitext, digit routes).
* [[TuCloudAPI deletelocution]] — Delete a locution.
* [[TuCloudAPI getlocutionvoices]] — Catalogo para el selector de texto a voz: voces disponibles e idiomas admitidos.
* [[TuCloudAPI synthlocution]] — Genera el audio de una locucion a partir de un texto y lo deja PENDIENTE DE ACEPTAR: NO sustituye la locucion.
* [[TuCloudAPI uploadlocution]] — Sube un fichero de audio y lo deja COMO el audio de una locucion.
* [[TuCloudAPI commitlocution]] — Acepta el audio pendiente (el generado por synthlocution o subido por uploadlocution) y lo convierte en la locucion.
* [[TuCloudAPI discardlocution]] — Tira el audio pendiente sin tocar la locucion.
=== Music on hold (MOH) ===
* [[TuCloudAPI getmusics]] — List the PBX music-on-hold classes with has_audio (whether the track exists) and audio_url (the getaudio player URL).
* [[TuCloudAPI getmusic]] — Get one MOH class (+ has_audio, audio_url).
* [[TuCloudAPI addmusic]] — Create a MOH class.
* [[TuCloudAPI uploadmusic]] — Sube un fichero de audio para una clase de musica y lo deja PENDIENTE DE ACEPTAR: NO sustituye la que suena.
* [[TuCloudAPI commitmusic]] — Acepta el audio pendiente y lo convierte en la musica que suena.
* [[TuCloudAPI discardmusic]] — Tira el audio pendiente sin tocar la musica.
* [[TuCloudAPI deletemusic]] — Delete a MOH class.
=== Schedules (Horarios) ===
* [[TuCloudAPI getschedules]] — List the PBX weekly schedules (the WHEN grid a CLI's schedule profile points at).
* [[TuCloudAPI getschedule]] — Get one schedule with the full 84-cell weekly grid under "slots".
* [[TuCloudAPI addschedule]] — Create a weekly schedule.
* [[TuCloudAPI updateschedule]] — Edit a schedule (template/name/grid).
* [[TuCloudAPI deleteschedule]] — Delete a schedule.
=== Outbound routing (Rutas de salida) ===
* [[TuCloudAPI getoutgoings]] — List the outbound-routing profiles (Servicios de salida) with rule counts.
* [[TuCloudAPI getoutgoing]] — Get one outbound profile plus its ordered allow/deny rules (longest-prefix first).
* [[TuCloudAPI getoutgoinglookups]] — Tenant-scoped route picker for a rule's divert destination (route_id; 0 = block).
* [[TuCloudAPI addoutgoing]] — Create an outbound-routing profile (header; add rules with addoutrule).
* [[TuCloudAPI updateoutgoing]] — Rename/annotate an outbound profile.
* [[TuCloudAPI deleteoutgoing]] — Delete an outbound profile.
* [[TuCloudAPI addoutrule]] — Append an allow/deny rule to a profile.
* [[TuCloudAPI updateoutrule]] — Edit an outbound rule (dst/denyallow/route_id/nota).
* [[TuCloudAPI deleteoutrule]] — Remove an outbound rule.
=== Phonebooks (Agendas) ===
* [[TuCloudAPI getphonebooks]] — List the PBX phonebooks (address books) with contact counts.
* [[TuCloudAPI getphonebook]] — Get one phonebook plus its contacts.
* [[TuCloudAPI addphonebook]] — Create a phonebook.
* [[TuCloudAPI updatephonebook]] — Edit a phonebook.
* [[TuCloudAPI deletephonebook]] — Delete a phonebook and all its contacts (DB cascade).
* [[TuCloudAPI addphonebookcontact]] — Add a contact to a phonebook.
* [[TuCloudAPI updatephonebookcontact]] — Edit a phonebook contact (tenant-checked via the row).
* [[TuCloudAPI deletephonebookcontact]] — Remove a phonebook contact (tenant-checked).
=== Call queues / ACD (Colas) ===
* [[TuCloudAPI getqueues]] — List the PBX call queues (ACD) with member counts.
* [[TuCloudAPI getqueue]] — Get one queue's config.
* [[TuCloudAPI getqueuelookups]] — Tenant-scoped pickers for the queue form: music (MOH classes), the strategy enum, and next_free (the create-form exten prefill = first free 3-digit queue number, null if 900-999 full).
* [[TuCloudAPI addqueue]] — Create a call queue.
* [[TuCloudAPI updatequeue]] — Edit a queue's config.
* [[TuCloudAPI deletequeue]] — Delete a queue.
=== Agents / queue members (Agentes) ===
* [[TuCloudAPI getagents]] — List the PBX agents (queue members) with the queue title and the agent's extension name resolved.
* [[TuCloudAPI getagentlookups]] — Dropdown data for the agent screens: this PBX's queues (assign an agent to a queue) and its extensions {_id,num,name}.
* [[TuCloudAPI addagent]] — Add an extension to a queue as a static member.
* [[TuCloudAPI updateagent]] — Update a queue member's penalty / paused / reason_paused (partial — only the fields sent are changed).
* [[TuCloudAPI deleteagent]] — Remove a queue member (agent) by _id.
=== Portal admin users (Usuarios) ===
* [[TuCloudAPI getadminusers]] — List this PBX's portal users (tucloud_sec_users).
* [[TuCloudAPI getadminuser]] — Get one portal user by login (_id) within this PBX.
* [[TuCloudAPI getadminuserlookups]] — Picker for the user form: the distinct roles used in this PBX (free-text datalist suggestions), and invite:true: users are created by email invitation, with no username and no password (always true on this build).
* [[TuCloudAPI addadminuser]] — Invite a new portal user to THIS PBX.
* [[TuCloudAPI updateadminuser]] — Edit a portal user in THIS PBX: name, active, priv_admin, role and phone are replaced as sent; disable_2fa=1 turns 2FA off and clears the secret (never enables).
* [[TuCloudAPI requestadminuseremail]] — Ask to change a portal user's EMAIL (their magic-link login), the twin of requestpbxemail.
* [[TuCloudAPI resendadminuseremail]] — Mail again the link of the user's open email change (the invitation of an invited user, or a change), pending or expired, with a fresh 24 hours; the previous link is then ignored.
* [[TuCloudAPI canceladminuseremail]] — Drop the user's open email change (pending, or expired): its link is then ignored.
* [[TuCloudAPI getadminuseremailchange]] — Status of the user's latest email change, from tucloudapi's own state (never magiclogin): none | pending (email, expires_in) | expired (until resent or cancelled) | done (notice: sent|failed|skipped, the informational mail to the old address) | failed (reason taken|error) | cancelled, with invite (true when it is the invitation) and its Spanish message.
* [[TuCloudAPI deleteadminuser]] — Delete a portal user by login within this PBX; their open email change is cancelled with them.
=== PBX settings (Configuracion) ===
* [[TuCloudAPI getpbxconfig]] — Get this PBX's settings (single record, no id needed, tenant from the binding).
* [[TuCloudAPI getpbxconfiglookups]] — Picker for the admin_ext_id field: this PBX's extensions.
* [[TuCloudAPI updatepbxconfig]] — Update this PBX's settings (strict set).
* [[TuCloudAPI requestpbxemail]] — Ask to change this PBX's MASTER EMAIL (tucloud_pbx.email: the administrator's magic-link and password login).
* [[TuCloudAPI getpbxemailchange]] — Status of this PBX's latest master-email change, from tucloudapi's own state (never magiclogin): none | pending (email, expires_in) | done (email, notice: sent|failed|skipped, the informational mail to the old address) | expired | failed (reason taken|error) | cancelled, each with its Spanish message.
* [[TuCloudAPI cancelpbxemail]] — Cancel this PBX's pending master-email change (its link is then ignored).
=== Security profiles / ACL (Perfiles) ===
* [[TuCloudAPI getprofiles]] — List this PBX's security profiles (Perfiles) with member counts.
* [[TuCloudAPI getprofile]] — Get one profile + its full app-permission matrix (all catalog apps, with app_type).
* [[TuCloudAPI getprofileapps]] — Get a profile's app-permission matrix only (the Aplicaciones/Perfiles editor).
* [[TuCloudAPI getseclookups]] — Pickers for the security section: the global app catalog (matrix columns) + this PBX's profiles (membership picker).
* [[TuCloudAPI getprofileusers]] — List the admin users assigned to a profile (read-only "Miembros" list; edits stay per-user via setuserprofiles).
* [[TuCloudAPI getuserprofiles]] — Get an admin user's profile membership + the profile picker (this PBX only).
* [[TuCloudAPI addprofile]] — Create a security profile in this PBX.
* [[TuCloudAPI updateprofile]] — Rename a profile (description).
* [[TuCloudAPI deleteprofile]] — Delete a profile.
* [[TuCloudAPI getsections]] — The catalog of portal sections (login v2, 2026-10-31): one row per section of the new web, in sidebar order, from the NEW table tucloud_sec_sections (24 rows; pbx_config is the PBX administrator's and has no row).
* [[TuCloudAPI getprofilesections]] — One profile's section access (login v2): every catalog section with access Y/N, from the NEW table tucloud_sec_groups_sections; a section without a row answers N.
* [[TuCloudAPI setprofilesections]] — FULL replace of one profile's section access (login v2; the «mantenimiento de accesos de los grupos» the operator asked for on 2026-10-31).
* [[TuCloudAPI setprofileapps]] — RETIRED 2026-10-31 (operator: the legacy matrix is never altered again).
* [[TuCloudAPI setprofileapp]] — RETIRED 2026-10-31 (operator: the legacy matrix is never altered again).
* [[TuCloudAPI setuserprofiles]] — Full-replace an admin user's profile membership (this PBX only).
=== Call detail records (CDR) ===
* [[TuCloudAPI getcdr]] — List a period of this PBX's call detail records (Registro de llamadas), newest first.
* [[TuCloudAPI getcdrlookups]] — CDR form pickers: the selectable years + the result (disposition) label set.
=== Reports / statistics (Informes) ===
* [[TuCloudAPI getreports]] — Call-volume statistics (Informes / Estadisticas de Llamadas) for a month — VOLUME ONLY, no prices.
=== AI assistant (Asistente IA) ===
* [[TuCloudAPI aichat]] — AI assistant for this PBX (Spanish).
=== Scheduled tasks (Tareas programadas) ===
=== Scheduled tasks (Tareas programadas) ===
* [[TuCloudAPI gettasks]] — List scheduled tasks (tareas programadas) for the PBX, with schedule + status labels and step counts.
* [[TuCloudAPI gettasks]] — List scheduled tasks (tareas programadas) for the PBX, with schedule + status labels and step counts.
Line 28: Line 182:
* [[TuCloudAPI updatetaskstep]] — Change a step's value (blank -> NULL).
* [[TuCloudAPI updatetaskstep]] — Change a step's value (blank -> NULL).
* [[TuCloudAPI deletetaskstep]] — Remove a step.
* [[TuCloudAPI deletetaskstep]] — Remove a step.
=== Tucloud PBX ===
=== Call simulator ===
* [[TuCloudAPI getpbxloclog]] — Tucloud PBX IVR/locution DTMF key-press log for a period.
* [[TuCloudAPI simulatecall]] — Simulate how a call routes (inbound DID / outbound / internal) WITHOUT placing a real call, returning the ordered decision trace (flujo).
=== Audio files ===
* [[TuCloudAPI getaudio]] — General-purpose audio file server (not only for the simulator): serve a locution or music-on-hold audio file base64-encoded (audio/wav) — for hover-preview, players, downloads, etc.
=== FuturePBX ===
* [[TuCloudAPI getpbxloclog]] — FuturePBX IVR/locution DTMF key-press log for a period.
=== Meta / discovery ===
=== Meta / discovery ===
* [[TuCloudAPI help]] — Lists the API functions available to the role of the calling ukey, with each function's description, parameters (meaning, optional/default), an example call and the response format.
* [[TuCloudAPI help]] — Lists the API functions available to the role of the calling ukey, with each function's description, parameters (meaning, optional/default), an example call and the response format.
Line 45: Line 203:
* [[TuCloudAPI addaccountcode]] — Creates a new account (client) under the caller.
* [[TuCloudAPI addaccountcode]] — Creates a new account (client) under the caller.
* [[TuCloudAPI getcredit]] — Returns credit and status (credit, credit_limit, creditalarm, email, blocked).
* [[TuCloudAPI getcredit]] — Returns credit and status (credit, credit_limit, creditalarm, email, blocked).
=== simulator ===
=== auth ===
* [[TuCloudAPI simulatecall]] — Simulate how a call routes (inbound DID / outbound / internal) WITHOUT placing a real call, returning the ordered decision trace (flujo).
* [[TuCloudAPI authrequest]] — Ask for a magic-link e-mail.
* [[TuCloudAPI authpoll]] — Has the user authorized the magic link? PUBLIC, like authrequest.
* [[TuCloudAPI authchallenge]] — A proof-of-work captcha challenge (ALTCHA protocol, SHA-256).
* [[TuCloudAPI authlogin]] — The password door.
* [[TuCloudAPI authwhoami]] — The current session context, and it refreshes the idle timer.
* [[TuCloudAPI authlogout]] — Destroy the session and clear the cookie.
=== queue_live ===
* [[TuCloudAPI getqueueevents]] — Today's events of ONE queue (local day), newest first, at most 200, with the same deduplication as getqueuestats (core events; module EXITQUEUE FULL/JOINEMPTY kept as refused).
* [[TuCloudAPI getlivestatus]] — LIVE state of the PBX as ONE snapshot of the presence feed: each extension's state (unregistered/idle/ringing/busy, "unknown" when it is not published) and its calls in progress (ringing/talking/hold/dialing, the other party, seconds since start and since answer), and each queue's live picture (agents logged in / available / paused, the waiting calls in queue order with their wait, every member with its status).
=== queue_stats ===
* [[TuCloudAPI getqueuestats]] — Call-center history from voip_queue_log (gabpbx contract v1, 2026-10-31): totals, per interval, per queue and per agent between two local days (Europe/Madrid, inclusive).


== Related ==
== Related ==

Latest revision as of 14:20, 5 November 2026

ℹ New here? Start with the self-discovery endpoint. This reference is generated from func=help, so it never drifts.

Overview

TuCloudAPI is the REST API to manage FuturePBX (the multi-tenant cloud PBX). HTTPS + JSON, GET or POST (parameters form-urlencoded; audio uploads POST the file as the body). Base URL: 

https://tucloudapi.7kas.com:9087/tucloud?func=NAME&ukey=YOUR_KEY&pbx=PBX_NAME

Authentication & tenant

Every call needs an API key (ukey). Every PBX-scoped function also needs pbx — the PBX name (e.g. tucall). The (ukey, pbx) pair is the tenant boundary: the server resolves the PBX name to its id and verifies that the key's OWN account owns it — for every role, SuperRoot included. A PBX that does not exist and one the key does not own both answer forbidden. It never trusts a numeric tenant from the caller.

Response format

Always HTTP 200. Every PBX-scoped function always returns a JSON envelope: success {"ok":true, ...}, empty {"ok":true,"rows":[]}, error {"ok":false,"code":...,"message":...} (common codes: missing_pbx, forbidden, invalid_param, not_found, conflict, in_use, db_error, server_busy). IDs are exposed as _id. A missing or invalid ukey answers a bare {} and nothing else. The legacy account functions return their data object directly, {} when there is nothing.

Functions

Dashboard (landing counts)

Extensions (Extensiones)

  • TuCloudAPI getextensions — List the PBX extensions (safe display fields; NEVER the SIP password).
  • TuCloudAPI getextension — Get one extension with all editable fields (NO password).
  • TuCloudAPI getextlookups — Tenant-scoped option lists for the extension form selects: caller IDs (clis), music-on-hold (music), outgoing services (outs), the extension list (exts, for Enviar a / backup monitor), registration servers (servers) and next_free: the create-form number prefill for a REGISTERED extension (3-4 digits, the same check as checkextnum), a string, or null when no number is free.
  • TuCloudAPI checkextnum — Is this number free for a NEW extension of this PBX? The same check addextension runs under its lock, so the two never disagree.
  • TuCloudAPI addextension — Create an extension.
  • TuCloudAPI updateextension — Edit an extension.
  • TuCloudAPI deleteextension — Delete an extension after a tenant + dependency check.
  • TuCloudAPI setextpassword — Rotate ONE extension's SIP password.
  • TuCloudAPI getextpassword — Plaintext SIP password for ONE extension (the portal's «Clave SIP» eye toggle).
  • TuCloudAPI getextqr — SIP provisioning QR for one extension, rendered server-side to a PNG (base64).

CLIs / DIDs (Numeracion)

Routes (Rutas)

Blacklist (inbound intercept)

Contacts (Agenda)

Calendar (date overrides)

Ring groups (Grupos)

Locutions / IVR (Locuciones)

Music on hold (MOH)

Schedules (Horarios)

Outbound routing (Rutas de salida)

Phonebooks (Agendas)

Call queues / ACD (Colas)

Agents / queue members (Agentes)

Portal admin users (Usuarios)

  • TuCloudAPI getadminusers — List this PBX's portal users (tucloud_sec_users).
  • TuCloudAPI getadminuser — Get one portal user by login (_id) within this PBX.
  • TuCloudAPI getadminuserlookups — Picker for the user form: the distinct roles used in this PBX (free-text datalist suggestions), and invite:true: users are created by email invitation, with no username and no password (always true on this build).
  • TuCloudAPI addadminuser — Invite a new portal user to THIS PBX.
  • TuCloudAPI updateadminuser — Edit a portal user in THIS PBX: name, active, priv_admin, role and phone are replaced as sent; disable_2fa=1 turns 2FA off and clears the secret (never enables).
  • TuCloudAPI requestadminuseremail — Ask to change a portal user's EMAIL (their magic-link login), the twin of requestpbxemail.
  • TuCloudAPI resendadminuseremail — Mail again the link of the user's open email change (the invitation of an invited user, or a change), pending or expired, with a fresh 24 hours; the previous link is then ignored.
  • TuCloudAPI canceladminuseremail — Drop the user's open email change (pending, or expired): its link is then ignored.
  • TuCloudAPI getadminuseremailchange — Status of the user's latest email change, from tucloudapi's own state (never magiclogin): none | pending (email, expires_in) | expired (until resent or cancelled) | done (notice: sent|failed|skipped, the informational mail to the old address) | failed (reason taken|error) | cancelled, with invite (true when it is the invitation) and its Spanish message.
  • TuCloudAPI deleteadminuser — Delete a portal user by login within this PBX; their open email change is cancelled with them.

PBX settings (Configuracion)

  • TuCloudAPI getpbxconfig — Get this PBX's settings (single record, no id needed, tenant from the binding).
  • TuCloudAPI getpbxconfiglookups — Picker for the admin_ext_id field: this PBX's extensions.
  • TuCloudAPI updatepbxconfig — Update this PBX's settings (strict set).
  • TuCloudAPI requestpbxemail — Ask to change this PBX's MASTER EMAIL (tucloud_pbx.email: the administrator's magic-link and password login).
  • TuCloudAPI getpbxemailchange — Status of this PBX's latest master-email change, from tucloudapi's own state (never magiclogin): none | pending (email, expires_in) | done (email, notice: sent|failed|skipped, the informational mail to the old address) | expired | failed (reason taken|error) | cancelled, each with its Spanish message.
  • TuCloudAPI cancelpbxemail — Cancel this PBX's pending master-email change (its link is then ignored).

Security profiles / ACL (Perfiles)

Call detail records (CDR)

  • TuCloudAPI getcdr — List a period of this PBX's call detail records (Registro de llamadas), newest first.
  • TuCloudAPI getcdrlookups — CDR form pickers: the selectable years + the result (disposition) label set.

Reports / statistics (Informes)

  • TuCloudAPI getreports — Call-volume statistics (Informes / Estadisticas de Llamadas) for a month — VOLUME ONLY, no prices.

AI assistant (Asistente IA)

Scheduled tasks (Tareas programadas)

Call simulator

  • TuCloudAPI simulatecall — Simulate how a call routes (inbound DID / outbound / internal) WITHOUT placing a real call, returning the ordered decision trace (flujo).

Audio files

  • TuCloudAPI getaudio — General-purpose audio file server (not only for the simulator): serve a locution or music-on-hold audio file base64-encoded (audio/wav) — for hover-preview, players, downloads, etc.

FuturePBX

Meta / discovery

  • TuCloudAPI help — Lists the API functions available to the role of the calling ukey, with each function's description, parameters (meaning, optional/default), an example call and the response format.

Diagnostics

Administration

Account management (inherited)

auth

queue_live

  • TuCloudAPI getqueueevents — Today's events of ONE queue (local day), newest first, at most 200, with the same deduplication as getqueuestats (core events; module EXITQUEUE FULL/JOINEMPTY kept as refused).
  • TuCloudAPI getlivestatus — LIVE state of the PBX as ONE snapshot of the presence feed: each extension's state (unregistered/idle/ringing/busy, "unknown" when it is not published) and its calls in progress (ringing/talking/hold/dialing, the other party, seconds since start and since answer), and each queue's live picture (agents logged in / available / paused, the waiting calls in queue order with their wait, every member with its status).

queue_stats

  • TuCloudAPI getqueuestats — Call-center history from voip_queue_log (gabpbx contract v1, 2026-10-31): totals, per interval, per queue and per agent between two local days (Europe/Madrid, inclusive).

Related

Full technical reference (architecture, auth model, side effects): see the project repo doc/TUCLOUDAPI_REFERENCE.md. Scheduled-tasks engine: the 6 tucloud_pbx_tasks* tables + the .231 crontab trigger.

Retrieved from "https://wiki.7kas.com/index.php?title=TuCloudAPI&oldid=1350"