Jump to content

TuCloudAPI: Difference between revisions

From Wiki 7Kas
← Older edit
getpbxs: account-scoped selector (all roles)
Fix {{Note}} 1= (func=help)
 
(13 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, GET, JSON.''' 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


Line 12: Line 12:


== 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), and the extension list (exts, for Enviar a / backup monitor).
* [[TuCloudAPI addextension]] — Create an extension.
* [[TuCloudAPI updateextension]] — Edit an extension.
* [[TuCloudAPI deleteextension]] — Delete an extension after a tenant + dependency check.
* [[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 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.
=== 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 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 admin users (tucloud_sec_users).
* [[TuCloudAPI getadminuser]] — Get one portal admin user by login (_id) within this PBX.
* [[TuCloudAPI getadminuserlookups]] — Picker for the admin-user form: the distinct roles used in this PBX (free-text datalist suggestions).
* [[TuCloudAPI addadminuser]] — Create a portal admin user in THIS PBX.
* [[TuCloudAPI updateadminuser]] — Edit a portal admin user in THIS PBX.
* [[TuCloudAPI deleteadminuser]] — Delete a portal admin user by login within this PBX.
=== 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).
=== 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 setprofileapps]] — Bulk-save a profile's FULL permission matrix in one call (the primary matrix write).
* [[TuCloudAPI setprofileapp]] — Set ONE app's permissions for a profile.
* [[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 161:
* [[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 182:
* [[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 ===
* [[TuCloudAPI simulatecall]] — Simulate how a call routes (inbound DID / outbound / internal) WITHOUT placing a real call, returning the ordered decision trace (flujo).


== Related ==
== Related ==

Latest revision as of 14:51, 3 August 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, GET, JSON. 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). The tasks functions also need 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 the key owns it (SuperRoot any PBX; Operator its own root; Client its own account). It never trusts a numeric tenant from the caller.

Response format

Always HTTP 200. The tasks functions always return a JSON envelope: success {"ok":true, ...}, empty {"ok":true,"rows":[]}, error {"ok":false,"code":...,"message":...} (codes: missing_pbx, unknown_pbx, forbidden, invalid_param, not_found, db_error, server_busy). IDs are exposed as _id. Base/legacy functions return their data object directly, or {} on error/empty.

Functions

Dashboard (landing counts)

Extensions (Extensiones)

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)

PBX settings (Configuracion)

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)

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=936"