====== API pro práci s veřejnými čísly ======

Součást [[:api|Odorik.cz API]], poskytuje volání umožňující práci s veřejnými čísly.

===== Seznam veřejných čísel =====

=== GET /public_numbers.json ===
  * vrací všechna veřejná čísla asociována s daným účtem
  * vyžaduje [[:api#autentizace|autentizaci]]
  * nepovinné parametry:
    * **include_sip_names** - v případě hodnoty "true" budou v seznamu i registrovaná SIP jména
    * **include_shared_numbers** - v případě hodnoty "true" budou v seznamu i sdílená telefonní čísla (rozsah 533 533 4xy) využitelná pro routování hovorů
  * existující typy čísel:
    * geographic
    * nomadic
    * mobile
    * sip_name
    * shared
  * příklad odpovědi:
<code javascript>
[ { "public_number": "00420533533533", "type": "geographic" },
  { "public_number": "00420910110910", "type": "nomadic" },
  { "public_number": "00420799799799", "type": "mobile" } ]
</code>

===== Paralelní zvonění =====

Všechna níže zmíněná volání pro nastavení paralelního zvonění jsou speciálním případem [[api:public_numbers#routovani|routování]], kde atribut source_number je nastavován na "*".

=== GET /public_numbers/<verejne_cislo>/ringings.json ===
  * vrací všechna čísla, na kterých bude vyzvánět hovor na <verejne_cislo>
  * <verejne_cislo> musí být v mezinárodním formátu (česká čísla tedy musí začínat 00420), <verejne_cislo> je i SIP jméno
  * vyžaduje [[:api#autentizace|autentizaci]]
  * možné chybové stavy:
    * //unauthorized//
    * //nonexisting_public_number//
  * příklad odpovědi pro číslo (00420) 539 085 858
<code javascript>
[ { "public_number": "00420539085858", "ringing_number": "*100" } ]
</code>

=== POST /public_numbers/<verejne_cislo>/ringings.json ===
  * přidání nového čísla pro paralení vyzvánění na čísle <verejne_cislo>
  * <verejne_cislo> musí být v mezinárodním formátu (česká čísla tedy musí začínat 00420), <verejne_cislo> je i SIP jméno
  * povinné parametry:
    * **ringing_number**: číslo na které bude hovor směrován
  * vyžaduje [[:api#autentizace|autentizaci]]
  * možné chybové stavy
    * //unauthorized//
    * //nonexisting_public_number//
    * //invalid_ringing_number//
    * //redirection_loop//

=== DELETE /public_numbers/<verejne_cislo>/ringings/<cilove_cislo>.json ===
  * odstranění paralelního zvonění z čísla <verejne_cislo> na čísle <cilove_cislo>
  * <verejne_cislo> musí být v mezinárodním formátu (česká čísla tedy musí začínat 00420), <verejne_cislo> je i SIP jméno
  * vyžaduje [[:api#autentizace|autentizaci]]
  * možné chybové stavy:
    * //unauthorized//
    * //nonexisting_public_number//
    * //nonexisting_ringing_number//

===== Routování =====

Routování je speciální případ paralelního zvonění, kdy se hovor směruje též podle čísla volajícího. V paralelním zvonění na webových stránkách uvidíte číslo volajícího od čísla na kterého se hovor směruje oddělené znakem ">". 

Routováním lze také nastavovat směrování hovorů na sdílených číslech. Tedy nahrazuje to nastavování, které je na webu přístupné v menu 
"Průvodce nastavením"->"Vlastní telefonní číslo/..."->"Sdílená telefonní čísla"->"Sdílená telefonní čísla"
Umožní pak využít neomezené hovory např. v rámci ČR pro spojení s ústřednou, kdy si předem přesměrujete např. české telefonní číslo tak, aby vás spojilo kam potřebujete. (např. do zahraničí). Seznam sdílených telefonních čísel zjistíte pomocí api výše a parametru **include_shared_numbers**.

Pomocí routování lze též nastavovat a číst hodnoty, co lze nastavit pomocí paralelního zvonění výše. Navíc lze nastavovat i číslo volajícího jiné než '*'.

=== GET /public_numbers/<verejne_cislo>/routes.json ===
  * vrací všechna pravidla určující směrování hovorů na <verejne_cislo>
  * <verejne_cislo> musí být v mezinárodním formátu (česká čísla tedy musí začínat 00420), <verejne_cislo> je i SIP jméno
  * vyžaduje [[:api#autentizace|autentizaci]]
  * možné chybové stavy:
    * //unauthorized//
    * //nonexisting_public_number//
  * příklad odpovědi pro číslo (00420) 539 085 858
<code javascript>
[ { "id": 123, "public_number": "00420539085858", "source_number": "*", "ringing_number": "*100" } ]
</code>

=== POST /public_numbers/<verejne_cislo>/routes.json ===
  * přidání nového pravidla pro vyzvánění na čísle <verejne_cislo>
  * <verejne_cislo> musí být v mezinárodním formátu (česká čísla tedy musí začínat 00420), <verejne_cislo> je i SIP jméno
  * povinné parametry:
    * **source_number**: číslo, ze kterého hovor přijde na ústřednu Odorik.cz; znak '*' reprezentuje všechna čísla a má nižší prioritu než konkrétní číslo
    * **ringing_number**: číslo, na které bude hovor směrován
  * volitelné parametry:
    * **replace_by_source_number**: v případě hodnoty "true" jsou odstraněny všechna ostatní pravidla se shodným source_number
  * vyžaduje [[:api#autentizace|autentizaci]]
  * možné chybové stavy
    * //unauthorized//
    * //nonexisting_public_number//
    * //invalid_ringing_number//
    * //invalid_source_number//
    * //redirection_loop//
    * //shared_number_conflict// - kombinaci sdíleného čísla <verejne_cislo> a ringing_number již používá jiný uživatelský účet

=== DELETE /public_numbers/<verejne_cislo>/routes/<id>.json ===
  * odstranění routovacího pravidla
  * <id> odpovídá hodnotě získané voláním GET /public_numbers/<verejne_cislo>/routes.json
  * <verejne_cislo> musí být v mezinárodním formátu (česká čísla tedy musí začínat 00420), <verejne_cislo> je i SIP jméno
  * vyžaduje [[:api#autentizace|autentizaci]]
  * možné chybové stavy:
    * //unauthorized//
    * //nonexisting_route//
    * //nonexisting_public_number//