Documentation

Votre standard en cinq minutes

Tout ce qui suit existe déjà dans votre compte. Rien ici ne demande un installateur, la visite d'un technicien ni un appareil à acheter.

• Vous avez déjà des numéros et des postes. Ils sont créés avec votre compte, avec les identifiants SIP dont chaque appareil a besoin. Un poste, c'est une personne ou un bureau ; un numéro, c'est ce que compose le monde extérieur.
• Faites pointer un numéro quelque part. Dans l'onglet Numéros, vous dites ce qu'un appel arrivant sur ce numéro doit faire : sonner un poste, sonner un groupe, ouvrir un menu, entrer dans une file ou suivre vos horaires.
• Répondez depuis le navigateur. Ouvrez l'onglet Téléphone, autorisez le micro, et cet onglet devient un poste qui fonctionne. Appelez le test d'écho en composant *43 et vous vous entendrez revenir.
• Ensuite, réglez vos horaires et votre messagerie. Ce sont ces deux-là qui empêchent un appel de se perdre à sept heures du soir, et ce sont les deux choses qui manquent le plus souvent à un standard tout neuf.

Pressé ? Il existe cinq modèles de démarrage — un cabinet médical, un cabinet d'avocats, un atelier, une boutique et une ligne de maison — qui créent vos horaires, votre route entrante et votre messagerie hors horaires en une seule requête. Ils n'écrasent jamais ce que vous avez déjà configuré.

Comment entrer dans votre panneaupar l'API

Le panneau vit sur votre page VOICE et n'apparaît qu'avec une session. Cette session est émise par votre espace client ; ici, on ne saisit rien.

Pour qui construira ce bouton, voici tout le contrat :

POST /inquilinos/:inquilino/sesiones     # portée système : seul le portail peut en émettre
{ "minutos": 15 }
→ { "clave": "pbx_ses_…", "caduca": "…", "ambito": "sesion", "minutos_max": 60 }

/telephonie#t=<clave>&exp=<ISO>&v=<inquilino>

La clé voyage dans le fragment et non dans la query, volontairement : un fragment n'est jamais envoyé à un serveur, il ne finit donc ni dans un en-tête Referer, ni dans les journaux d'accès, ni chez un intermédiaire du chemin. Elle expire en quelques minutes, elle est plafonnée, et elle ne peut jamais fabriquer de clé permanente.

Le panneau, onglet par ongletpar l'API

16 sections, les mêmes 16 dans les huit langues. Tout ce qui est ici existe aussi dans l'API.

Le téléphone dans votre navigateurappel réel

Un onglet est un poste. Rien à installer, aucun téléphone de bureau à acheter, aucun numéro à porter : c'est un poste de votre propre standard, enregistré depuis le navigateur.

• C'est un vrai poste. Le navigateur s'enregistre sur votre standard comme le ferait un téléphone de bureau, et l'audio passe par une liaison chiffrée. Qui appelle votre numéro peut atteindre l'onglet, et l'onglet peut appeler dehors.
• L'onglet doit rester ouvert. Un onglet fermé est un téléphone débranché. C'est la limite honnête d'un téléphone dans le navigateur, et la raison pour laquelle il accompagne un poste de bureau au lieu de le remplacer partout.
• Vous voyez qui est en ligne.appel réel Les voyants de vos collègues se mettent à jour en direct — libre, sonne, en conversation —, vous savez donc s'il y a quelqu'un à qui passer l'appel avant d'essayer.
• Vous pouvez déplacer un appel en cours vers un autre appareil.pas encore exercé « Je dois partir et je suis en pleine conversation » : l'appel passe sur votre mobile sans raccrocher. C'est un bouton et non un code de clavier, volontairement — qui déplace un appel a un écran devant lui.
• Transférer, mettre en garde et enregistrer sont les mêmes codes que sur n'importe quel poste. Ils se composent, ils ne se cliquent pas : ce que vous apprenez sur le téléphone du navigateur vous sert sur le poste de bureau et sur votre mobile.

Le téléphone du navigateur n'enregistre jamais sur votre ordinateur. L'enregistrement se fait dans le standard, là où s'appliquent les règles sur qui peut être enregistré et qui doit en être averti — voyez « Enregistrer, et la loi ».

Codes composés depuis un poste

On garde les classiques là où une convention existe (*72 renvoi, *78 ne pas déranger, *97 messagerie, *8 interception, *69 qui vient d'appeler). C'est tout le sens d'un code de clavier : la fonction est déjà dans le panneau, et le code est ce qui fait qu'une personne qui compose *72 depuis vingt ans croit le panneau.

Composés poste au repos

Composés pendant une conversation

Pendant la consultation, dans un transfert supervisé

Dans une salle de conférence

Certains codes veulent dire deux choses et elles ne se percutent pas : *1 dans une conversation normale, c'est « enregistrer maintenant » ; pendant la consultation, c'est « terminer le transfert » ; et dans une salle, c'est « verrouiller la salle ». Ce sont des états différents du même poste, traités par du code différent.

Avant de faire confiance à un poste neuf : Les téléphones de bureau et les adaptateurs traitent leurs propres codes étoile et ne les transmettent jamais. Si vous composez un code et que vous entendez le silence puis la tonalité, c'est l'appareil qui l'a avalé et le standard n'a rien vu. Demandez-nous de vérifier un nouveau modèle contre la liste du jour avant de le déployer.

La messagerie depuis n'importe quel postebanc d'essai

Composez *97, saisissez votre code, et toute la messagerie est là — sans application et sans navigateur. C'est écrit pour le patron qui appelle depuis un téléphone emprunté.

Menu principal

Pendant l'écoute d'un message

Menu des annonces

Traiter l'appel lui-même

Un groupe d'appel dit « que ça sonne à plusieurs endroits ». Tout ce qui suit fait quelque chose qu'un groupe d'appel ne sait pas faire.

• Files d'attente.par l'API Une file sait combien de personnes attendent devant et combien de temps cela prend d'habitude, elle peut donc le dire. L'attente est mesurée sur vos propres appels récents, jamais inventée — avec moins de trois échantillons, elle ne dit rien. Sans personne en poste, personne n'est mis en attente.
• Rappel depuis la file.par l'API Proposé après un moment d'attente, et pas proposé si l'appel va de toute façon être pris tout de suite. La demande survit à un redémarrage, puisque celui qui la fait raccroche, et le rappel entre en tête de file — c'est ce qui a été promis.
• Salles de conférence.par l'API Une salle avec son numéro et deux clés : une pour entrer, une pour l'animer. Personne n'a besoin de compte nulle part. Les entrées et les sorties sont annoncées avec le nom que chacun a enregistré lui-même.
• L'annuaire par le nom.banc d'essai L'appelant épelle un nom sur le clavier et il est mis en relation. Chaque mot du nom est indexé séparément, parce qu'ici deux noms de famille sont la norme et ne chercher que le premier trouve la moitié de la maison. Les accents et le ñ sont normalisés : « Muñoz » se trouve en composant 686.
• Le zéro pour la standardiste.par l'API Sans doute l'attente la plus universelle qui existe à propos d'un téléphone : pouvoir joindre une personne. Le zéro descend en cascade de votre standardiste vers la messagerie générale, puis vers une phrase dite à voix haute — jamais un raccroché muet.
• Mettre en garde et reprendre.par l'API Mettez un appel en garde et il attend avec de la musique sur un emplacement numéroté pendant que vous marchez jusqu'à un autre bureau. N'importe qui le reprend en composant cet emplacement. Intercepter le téléphone qui sonne à côté de vous, c'est *8.

Canaux : garantie, prêt et restitutionpar l'API

C'est la partie du produit qu'un plafond dur ne sait pas faire, et il vaut mieux la comprendre avant de choisir un forfait.

• Garantis. Les appels simultanés que vend votre forfait. Ils passent toujours, quoi que fasse le standard, et personne ne peut vous les retirer.
• En prêt. Au-dessus de votre garantie, vous utilisez ce que le standard a de libre. La plupart des jours, vous serez là, et cela ne coûte rien de plus.
• La réserve. Un matelas de canaux qui n'est prêté à personne, pour que chacun puisse atteindre sa propre garantie à tout moment.
• La restitution. Quand le standard est sous tension, les appels empruntés peuvent être rendus pour protéger la garantie d'un autre. Cela ne concerne que les comptes qui l'ont activé, jamais un appel à l'intérieur d'une garantie, jamais un appel d'urgence et jamais en silence : le standard parle avant de libérer.
• Impossible de survendre. La somme de toutes les garanties plus la réserve doit tenir. La mise en service le vérifie et refuse un forfait qui ne tient pas, et c'est ce qui donne un sens au mot « garanti ».
• Et vous voyez quand ça a mordu. La congestion est signalée par épisodes avec leur heure, pas comme un total mensuel. « Douze refus en trente jours » se lit comme du bruit ; « mardi dernier, entre dix et onze heures, cinq personnes ont eu l'occupation » est quelque chose sur quoi on peut décider.

Ce qui se passe quand quelque chose casse

Un standard se juge le jour où le courant saute, pas le jour où tout marche.

• Plus d'une sortie. Le standard atteint le monde extérieur par plusieurs liaisons indépendantes et choisit entre elles tout seul. Vous ne configurez pas cela et vous ne le voyez pas se produire.
• « Ça marche » se mesure contre la bonne chose. Une liaison n'entre dans la rotation que si elle atteint à la fois l'internet et le réseau téléphonique. Ne vérifier que le premier, c'est ainsi qu'un standard se retrouve sans ligne avec tous les voyants au vert.
• Il se relève seul après une coupure de courant. Quand le courant revient, le standard et les équipements réseau démarrent en même temps et pas toujours dans le bon ordre. Plutôt que de se fier à cet ordre, le standard compare sans cesse ce qu'il a vraiment avec ce qu'il devrait avoir, et se répare — avec un plafond sur le nombre de tentatives, pour qu'une vraie panne soit remontée au lieu de tourner en boucle.
• Il ne coupe pas un appel pour se réparer. Toute réparation qui interromprait des conversations attend qu'il n'y en ait plus.

Les enregistrements et les messages vocaux sont stockés hors du standard : ils survivent donc à la machine elle-même.

Forfaits et minutes

5 forfaits, de $100 à $300 par an, et un numéro par licence. La minute entrante sur un numéro du Costa Rica est à $0.00.

Minutes

Prix en dollars, taxes comprises. L'opérateur mesure les appels vers mobile à la seconde. Chaque licence inclut 1 numéro ; les numéros supplémentaires partagent le même standard, les mêmes flux et le même panneau.

Enregistrer, et la loipar l'API

Un enregistrement, c'est la voix d'autres personnes. La loi costaricienne 8968 la protège, et la conception découle de là plutôt que de ce qui serait commode.

• Vous décidez ce qui est enregistré.par l'API Tout, ou seulement certains postes, ou seulement les appels arrivant sur un certain numéro. Ou rien, ce qui est une réponse légitime.
• La conservation vient avec votre forfait. Les enregistrements sont purgés d'eux-mêmes à l'échéance : celle du forfait, ou 90 jours pour ceux demandés pendant l'appel (avec *1) et ceux d'une salle de conférence. La seule exception est un enregistrement rattaché à un dossier d'appel malveillant, qui cesse d'expirer jusqu'à ce que vous fermiez le dossier — et le fermer redonne un délai normal, jamais un « supprimez-le tout de suite ».
• En partager un ne revient pas à donner un accès. Un lien signé joue un seul enregistrement, expire de lui-même et peut être révoqué. La personne à qui vous l'envoyez ne voit jamais votre compte.
• Chaque écoute est journalisée. Qui a joué quel enregistrement, et quand. C'est la voix de quelqu'un d'autre : savoir qui l'a entendue fait partie du fait de la détenir.
• Vous pouvez les classer. Client, prospect ou interne. Il n'y a volontairement pas de valeur par défaut : non classé est honnête, et une étiquette devinée par la machine ne se distingue plus, après coup, d'une étiquette choisie par une personne.

Les deux parties sont toujours averties. Demander au standard d'enregistrer rend aussi l'obligation de l'annoncer : les deux ne se séparent pas, parce que les séparer est précisément la façon dont quelqu'un finit enregistré sans le savoir. Dans une salle de conférence, l'annonce est faite à chaque personne au moment où elle entre.

Limites, protection et retour arrière

Ce qui décide jusqu'où va une mauvaise journée : une clé volée, une erreur d'acheminement, un numéro qui n'arrête pas d'appeler.

• Un plafond de dépense, journalier et mensuel.banc d'essai C'est ce qui empêche une clé volée de coûter de l'argent. Le plafond atteint, les appels s'arrêtent.
• Ce que chaque poste a le droit de composer.par l'API Interne seulement, national, mobile, ou tout. Le téléphone de l'entrepôt n'a aucune raison de pouvoir appeler un numéro surtaxé. Les appels d'urgence ne passent jamais par là.
• Le prix avant de composer.par l'API Demandez ce que coûterait un numéro donné : la réponse est calculée par la même mécanique que celle qui acheminera vraiment l'appel, et non par une grille tarifaire qui pourrait ne pas être celle appliquée.
• Une alarme de fraude qui regarde le comportement.pas encore exercé Une cadence inhabituelle, un pays que vous n'avez jamais appelé, une heure où personne ne travaille. Elle prévient et ne coupe pas : un faux positif ici n'est pas une alerte agaçante, c'est un appel qui n'a pas eu lieu. Il lui faut deux signaux avant de dire quoi que ce soit, parce qu'une alarme qui se déclenche tous les jours finit ignorée.
• Celui qui insiste trop est signalé.pas encore exercé Le même numéro cinq fois en deux minutes, ce n'est pas un client insistant : c'est un automate d'appel. En sortie d'usine, cela ne fait qu'avertir ; bloquer automatiquement est une case que vous cochez, parce qu'un faux positif coûte un client qui ne pourra plus jamais appeler.
• Un dossier pour un appel malveillant.pas encore exercé L'heure, la route et l'audio, gardés ensemble pour une plainte. En ouvrir un ne bloque pas l'appelant : chaque nouvel appel est une preuve de plus, et cette décision est la vôtre, pas la nôtre.
• À quel point vos postes ont été joignables.par l'API Pas notre disponibilité : la vôtre. Et on montre toujours quelle part de la période a réellement été mesurée, parce qu'un pourcentage qui avale en silence les heures que personne n'a regardées se trompe toujours du côté confortable.
• Ce qui a changé, qui l'a changé, et le retour arrière.par l'API « Hier ça marchait » est une question qui a une réponse. Chaque changement de configuration est consigné et peut être annulé, et l'annulation vérifie que personne d'autre n'a touché à ces champs entre-temps au lieu de les écraser en silence.

Ce qui est éteint, et pourquoi

Un manuel qui ne décrit que ce qui marche vous oblige à découvrir le reste tout seul, et on le découvre toujours au pire moment. Cette liste est engendrée par l'interrupteur lui-même : elle ne peut pas décrire comme éteint ce qui vient d'être allumé.

L'APIpar l'API

Le panneau n'est qu'un client de cette API. Tout ce que vous changez à la main peut se changer par programme, avec une clé qui appartient à votre compte.

curl -H "authorization: Bearer <clave>" \
  https://api.voice.forhosting.com/inquilinos/<cuenta>/numeros

Portées

Quand quelque chose se passe mal

Tout ce que l'API peut répondre lorsqu'elle refuse

Ce sont les chaînes exactes que l'API renvoie dans le champ error, lues dans le code source du standard. Elles sortent en espagnol et sont affichées ici telles quelles, à dessein : ce que vous devez reconnaître, c'est ce qui arrive, pas une traduction. Un … marque l'endroit où une valeur est insérée.

Chaque erreur porte un code stable. Appuyez-vous sur codigo, pas sur le message. Il est toujours présent : ce qui ne déclare pas de code propre reçoit celui de sa classe, dérivé du statut HTTP. Le texte de error est destiné à être lu par une personne et peut être reformulé ; le code, non.

{ "error": "…", "codigo": "de_otra_cuenta" }

336 messages distincts sur 407 points du code source du standard. Dérivé à chaque compilation : un message qui change là-bas change ici.

Il n'y a presque pas de limitation de débit aujourd'hui. La seule est une attente de quelques secondes entre deux tentatives d'ouvrir le téléphone du navigateur. Il n'y a pas de quota général, et nous préférons le dire plutôt que vous le laisser découvrir après avoir bâti sur une hypothèse. Restez raisonnable, et si vous préparez quelque chose de lourd, prévenez-nous avant : nous le mesurerons avec vous plutôt qu'après vous.

Jusqu'où on va

304 endpoints au total, lus sur le standard lui-même le 2026-10-21.

Ce tableau est un résumé. La liste qui ne peut pas vieillir est celle que le standard génère sur lui-même : GET /api.

Chaque point d'accès, un par un

Lu directement dans le routeur du standard : il ne peut donc ni décrire une route qui n'existe pas, ni en oublier une qui existe. Seule la portée de votre compte figure ici ; les routes de provisionnement appartiennent au portail et aucune clé qui y accède ne vous sera remise.

Exemples enregistrés

Ils n'ont pas été rédigés. Ils ont été enregistrés lors d'une exécution réelle contre cette API, dans un compte jetable supprimé ensuite — requête, statut et réponse, tels qu'ils ont circulé. Les identifiants de compte et d'objet sont remplacés par des marqueurs ; rien d'autre n'est modifié. Un exemple rédigé prouve ce que croyait son auteur ; un exemple enregistré prouve ce que le standard a fait.

24 routes sur 226 disposent d'un exemple enregistré, issu de l'exécution du 2026-10-16. Les autres figurent ci-dessus mais n'ont pas encore été éprouvées ainsi — nous préférons vous montrer le chiffre plutôt que vous laisser supposer qu'elles y sont toutes.

{
  "plazas": []
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "cancelada",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.942Z"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "pendiente",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.732Z"
}

{
  "numero": "50688889999",
  "cuando": "2026-10-16T22:44:57.219Z",
  "texto": "ensayo"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "50688889999",
  "nombre": null,
  "cuando": "2026-10-16T22:44:57.219Z",
  "avisar_el": "2026-10-15T22:44:57.219Z",
  "guion": null,
  "estado": "pendiente",
  "intentos": 0,
  "ultimo_intento": null,
  "respondido_el": null,
  "nota": null,
  "creado": "2026-10-16T21:44:58.732Z",
  "actualizado": "2026-10-16T21:44:58.732Z"
}

[]

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Soporte",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:57.230Z",
  "actualizado": "2026-10-16T21:44:57.230Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

{
  "nombre": "Ya editada"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Ya editada",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:59.058Z",
  "actualizado": "2026-10-16T21:44:59.287Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Soporte",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:57.230Z",
    "actualizado": "2026-10-16T21:44:57.230Z",
    "version": "\"v1-73d179cfb86c534a9bfccc\""
  }
]

{
  "nombre": "Soporte",
  "estrategia": "todos"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Soporte",
  "numero": null,
  "estrategia": "todos",
  "timbrado_s": 20,
  "espera_max_s": 600,
  "decir_posicion": 1,
  "decir_espera": 1,
  "anuncio_cada_s": 30,
  "musica": "default",
  "callback": 1,
  "callback_min_espera_s": 45,
  "agotada_tipo": "buzon",
  "agotada_id": "<id>",
  "vacia_tipo": null,
  "vacia_id": null,
  "creado": "2026-10-16T21:44:57.230Z",
  "actualizado": "2026-10-16T21:44:57.230Z",
  "miembros": [],
  "estado": {
    "de_turno": 0,
    "miembros": 0,
    "espera_estimada_s": null,
    "callbacks_pendientes": 0,
    "atendidas_hoy": 0,
    "abandonos_hoy": 0
  }
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Sala 1",
  "numero": null,
  "max_personas": 10,
  "esperar_organizador": 0,
  "anunciar_entradas": 1,
  "pedir_nombre": 1,
  "bloqueada": 0,
  "grabar": 0,
  "musica": "default",
  "activa": 1,
  "creado": "2026-10-16T21:44:57.733Z",
  "actualizado": "2026-10-16T21:44:57.733Z",
  "tiene_pin": false,
  "tiene_pin_organizador": false,
  "dentro": 0,
  "grabando": false
}

{
  "nombre": "Sala 1",
  "clave": "<secreto>"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "nombre": "Sala 1",
  "numero": null,
  "max_personas": 10,
  "esperar_organizador": 0,
  "anunciar_entradas": 1,
  "pedir_nombre": 1,
  "bloqueada": 0,
  "grabar": 0,
  "musica": "default",
  "activa": 1,
  "creado": "2026-10-16T21:44:57.733Z",
  "actualizado": "2026-10-16T21:44:57.733Z",
  "tiene_pin": false,
  "tiene_pin_organizador": false
}

{}

{
  "ticket": "<secreto>",
  "eventos": [
    "wss://<puerta>:<puerto>/eventos",
    "wss://<puerta>:<puerto>/eventos",
    "wss://<puerta>:<puerto>/eventos"
  ],
  "inquilino": "<cuenta>"
}

{
  "instalacion": "ejercicio-api-ventana-tranquila"
}

{
  "id": "<id>",
  "clave": "<secreto>",
  "caduca": "2026-10-16T22:00:02.449Z",
  "segundos": 900,
  "ambito": "dispositivo",
  "vinculo": {
    "inquilino": "<cuenta>",
    "extension": "<id>",
    "dispositivo": "<id>"
  },
  "extension": {
    "id": "<id>",
    "numero": "100",
    "nombre": "Ejercicio API"
  },
  "dispositivo_nuevo": true,
  "minutos_max": 60,
  "resumen": "credencial de UN aparato de UNA extensión, que caduca; para la app móvil"
}

{
  "numero": "100"
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "numero": "100",
    "nombre": "Ejercicio API",
    "correo": null,
    "cid_saliente": null,
    "timbrado_s": 25,
    "estado": "activa",
    "creado": "2026-10-16T21:45:00.167Z",
    "actualizado": "2026-10-16T21:45:00.167Z",
    "nombre_audio": null,
    "en_directorio": 1,
    "departamento": null,
    "version": "\"v1-a1a25e330e8bc32c8289ab\""
  }
]

{
  "nombre": "Ejercicio API",
  "numero": "100"
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "numero": "100",
  "nombre": "Ejercicio API",
  "correo": null,
  "cid_saliente": null,
  "timbrado_s": 25,
  "estado": "activa",
  "creado": "2026-10-16T21:45:00.167Z",
  "actualizado": "2026-10-16T21:45:00.167Z",
  "nombre_audio": null,
  "en_directorio": 1,
  "departamento": null,
  "reglas": {
    "extension_id": "<id>",
    "dnd": 0,
    "dnd_hasta": null,
    "sigueme": 0,
    "sigueme_numeros": [],
    "sigueme_modo": "tras",
    "sigueme_confirmar": 1,
    "sigueme_s": 20,
    "desvio_siempre": null,
    "desvio_ocupado": null,
    "desvio_nocontesta": null,
    "fallo_tipo": "buzon",
    "fallo_id": "<id>",
    "actualizado": "2026-10-16T21:45:00.168Z",
    "desvio_confirmar": 1,
    "screening": 0,
    "clase_servicio": "todo",
    "supervisar": 0,
    "transferencia_retorno": 0
  },
  "dispositivos": [
    {
      "id": "<id>",
      "etiqueta": "principal",
      "usuario_sip": "tf3zfmm96cfq100",
      "transporte": "udp",
      "estado": "activo",
      "ultimo_registro": null,
      "ultima_ip": null,
      "creado": "2026-10-16T21:45:00.168Z",
      "rotado": null,
      "instalacion": null
    }
  ],
  "buzon": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "extension_id": "<id>",
    "nombre": "Buzón de Ejercicio API",
    "saludo_texto": "Ha llamado a Ejercicio API. Deje su mensaje después del tono.",
    "saludo_audio": null,
    "correo": null,
    "enviar_correo": 1,
    "adjuntar": 1,
    "transcribir": 1,
    "max_s": 120,
    "creado": "2026-10-16T21:45:00.168Z",
    "actualizado": "2026-10-16T21:45:00.168Z",
    "max_mensajes": 50,
    "aviso_activo": 0,
    "aviso_numero": null,
    "revisar": 0,
    "ofrecer_operadora": 1,
    "guion": null,
    "aviso_numeros": null,
    "aviso_modo": "tras",
    "reintentar": 0,
    "reintentos_max": 2,
    "compartido": 0,
    "extensiones_acceso": null,
    "abrir_caso": 1,
    "tiene_pin": false
  },
  "credencial": {
    "id": "<id>",
    "usuario_sip": "tf3zfmm96cfq100",
    "clave": "<secreto>",
    "realm": "pbx.forhosting.com",
    "transporte": "udp"
  }
}

{}

{
  "revertido": "<id>",
  "tabla": "colas",
  "fila_id": "<id>",
  "columnas": [
    "nombre"
  ],
  "fila": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Para editar",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.671Z"
  }
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "tabla": "colas",
  "fila_id": "<id>",
  "columna_clave": "id",
  "antes": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Para editar",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.058Z"
  },
  "despues": {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "nombre": "Ya editada",
    "numero": null,
    "estrategia": "todos",
    "timbrado_s": 20,
    "espera_max_s": 600,
    "decir_posicion": 1,
    "decir_espera": 1,
    "anuncio_cada_s": 30,
    "musica": "default",
    "callback": 1,
    "callback_min_espera_s": 45,
    "agotada_tipo": "buzon",
    "agotada_id": "<id>",
    "vacia_tipo": null,
    "vacia_id": null,
    "creado": "2026-10-16T21:44:59.058Z",
    "actualizado": "2026-10-16T21:44:59.287Z"
  },
  "actor": "apikey:<id> primera clave de sistema (sistema)",
  "origen": "api",
  "revertido_de": null,
  "creado": "2026-10-16T21:44:59.287Z",
  "cambios": {
    "nombre": {
      "antes": "Para editar",
      "despues": "Ya editada"
    }
  }
}

{
  "inquilino": "<cuenta>",
  "cambios": [
    {
      "id": "<id>",
      "tabla": "colas",
      "fila_id": "<id>",
      "actor": "apikey:<id> primera clave de sistema (sistema)",
      "origen": "api",
      "revertido_de": null,
      "creado": "2026-10-16T21:44:59.287Z",
      "cambios": {
        "nombre": {
          "antes": "Para editar",
          "despues": "Ya editada"
        }
      }
    }
  ]
}

{
  "activas": []
}

{}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "motivo": "ensayo",
  "desde": "2026-10-16T21:44:58.365Z",
  "hasta": "2026-10-16T21:44:58.588Z",
  "avisar": 1,
  "activo": 0,
  "creado": "2026-10-16T21:44:58.365Z"
}

[
  {
    "id": "<id>",
    "inquilino": "<cuenta>",
    "motivo": "ensayo",
    "desde": "2026-10-16T21:44:58.365Z",
    "hasta": null,
    "avisar": 1,
    "activo": 1,
    "creado": "2026-10-16T21:44:58.365Z"
  }
]

{
  "motivo": "ensayo",
  "minutos": 5
}

{
  "id": "<id>",
  "inquilino": "<cuenta>",
  "motivo": "ensayo",
  "desde": "2026-10-16T21:44:58.365Z",
  "hasta": null,
  "avisar": 1,
  "activo": 1,
  "creado": "2026-10-16T21:44:58.365Z"
}

[]

{
  "destino": "buzon"
}

{
  "operadora": null
}

{
  "borrado": "<cuenta>"
}

{
  "nombre": "Ejercicio API 2026-10-16T21:44:54"
}

{
  "id": "<cuenta>",
  "nombre": "Ejercicio API 2026-10-16T21:44:54",
  "cuenta_portal": null,
  "cedula": null,
  "correo": null,
  "telefono": null,
  "plan": "zero",
  "zona": "America/Costa_Rica",
  "idioma": "es",
  "estado": "activo",
  "canales_max": 4,
  "notas": null,
  "creado": "2026-10-16T21:44:56.852Z",
  "actualizado": "2026-10-16T21:44:56.852Z",
  "canales_garantizados": 2,
  "modo_presion": "firme",
  "presion_canales": 1,
  "duracion_max_s": null,
  "operadora_tipo": null,
  "operadora_id": null,
  "filtro_anonimas": 0,
  "cdr_retencion_dias": null,
  "codigo_asunto_digitos": 0,
  "supervision_activa": 0,
  "canales_troncal": null,
  "limites": {
    "canales": 2,
    "canales_max": 4,
    "extensiones": 3,
    "retencion": 30,
    "tope_diario": 3,
    "tope_mensual": 25
  },
  "canales": {
    "existe": true,
    "garantizados": 2,
    "max": 4,
    "modo": "firme",
    "presion_canales": 1,
    "por_troncal": null
  }
}

Sessions : le navigateur ne détient jamais de clé permanente

Une clé courte, plafonnée à 60 minutes, qui ne peut pas en fabriquer une permanente. Voici le contrat si c'est vous qui construisez le bouton.

• Seul le portail peut en émettre une. Émettre une session exige une clé de mise en service, parce que seul le portail peut affirmer qu'il y a un client connecté derrière la requête. VOICE ne connaît pas les mots de passe des clients et n'a aucune raison de les connaître.
• Elle ne naît jamais sans échéance. Si personne ne demande de durée, on lui en applique une. Une portée qui existe pour expirer et qui pourrait naître éternelle est pire que rien, parce qu'on lui fait confiance.
• Demander plus longtemps ne sert à rien. Il y a un plafond dur. Qu'un appelant demande huit heures ne rend pas la clé sûre.
• Elle ne peut pas se promouvoir. La gestion des clés vit entièrement derrière la portée de mise en service : une session ne peut donc pas fabriquer de clé permanente. C'est imposé dans le routeur, avant tout traitement.
• Vous pouvez la fermer avant l'heure. L'identifiant revient au moment de l'émission, justement pour que vous puissiez la révoquer avant son échéance.

Notifications vers votre système (webhooks)par l'API

Vos systèmes apprennent ce qui s'est passé au lieu de le demander toutes les quelques secondes. 31 événements, signés, réessayés, et aucun ne tombe en silence.

x-pbx-evento: llamada.entrante
x-pbx-marca:  1755300000
x-pbx-firma:  <hex>

{ "evento": "llamada.entrante", "inquilino": "…", "cuando": "…", "datos": { … } }

Chaque livraison est signée : la signature couvre l'horodatage et le corps exact que vous avez reçu, vérifiez-la donc contre les octets bruts et non contre une copie re-sérialisée. Le secret n'est montré qu'une fois, à la création de l'abonnement, et il peut tourner sans interrompre les livraisons.

Une livraison qui échoue est réessayée au bout de 10 · 30 · 60 · 300 · 900 · 3600 secondes, et chaque tentative dispose de 10 secondes. Un abonnement qui continue d'échouer est mis en pause après 20 échecs consécutifs, au lieu d'être abandonné en silence — et vous pouvez voir chaque tentative.

Les événements

Le canal en directappel réel

Les notifications voyagent par lots et arrivent en quelques secondes. Certaines choses doivent être à l'écran tout de suite : un voyant qui indique qu'un collègue est en ligne ne peut pas avoir quinze secondes de retard.

• Ce qu'il transporte. Les appels à mesure qu'ils se produisent, les nouveaux messages, et l'état du voyant de chaque poste — c'est ce qui rend un tableau de voyants vraiment vivant à l'écran.
• Il est en lecture seule.par l'API On peut ouvrir un laissez-passer pour le canal sans confier un téléphone : regarder ce qui se passe ne devrait pas exiger une clé capable, en plus, de changer les choses.
• Il ne remplace pas les notifications. Le canal en direct est fait pour un écran que quelqu'un regarde. S'il importe que votre système l'apprenne, prenez une notification : elle réessaie, et elle ne dépend pas d'une socket ouverte.

Comment lire les mentions

Chaque fonction de cette page porte une mention qui dit comment elle a été vérifiée. Nous publions aussi celles qui n'ont pas encore été exercées, en le disant, parce que vous le découvrir seul serait pire.

114 fonctions, comptées sur le standard le 2026-09-19.

La mention appartient à une fonction, pas à une ligne isolée : là où une fonction couvre plusieurs codes, tous affichent le niveau du groupe. Cela veut dire qu'une mention peut rester EN DEÇÀ de ce qui a réellement été testé — jamais au-delà, qui est la seule direction dans laquelle nous acceptons de nous tromper sur une page que vous lisez comme une promesse.

Glossaire

Les mots qu'emploie un standard téléphonique et que rien d'autre n'emploie.