API pro práci s hovory

Součást Odorik.cz API určená pro práci s telefonními hovory.

• požadavek k iniciování zpětného volání (callback)
• povinné parametry:
  • caller: telefonní číslo, se kterým se pokusí spojit ústředna Odorik.cz
  • recipient: telefonní číslo, se kterým budete spojeni po navázání hovoru mezi ústřednou a číslem předanným pomocí parametru caller
• nepovinné parametry:
  • delayed - opožděný callback; možné hodnoty jsou buď jedno číslo určující počet minut, o kolik bude callback zdržen, anebo přesné datum pro vytvoření callbacku ve formátu dateTime z XML Schema (například: 2036-07-16T08:12:14Z); pozor na znak “+” (viz Percent-encoding)
  • line - v případě přihlášení přes API heslo určuje linku, přes kterou bude callback realizován (u této linky bude callback evidován ve výpisu hovorů, příjemci callbacku se zobrazí při volání číslo přiřazené k lince, …)
  • simple - v případě předání hodnoty “true” nebude moci caller pomocí hvězdičky a DTMF tónu vytočit jiné číslo; zároveň nedochází ke snaze využít ke spojení další operátory, pokud první operátor selhal nebo hovor nespojil; implicitní je hodnota “false”. Pokud si tedy někdo objedná hovor a ten hovor pak odmítne, nebude se pokus opakovat.
• formát odpovědi: plain-text
• možné odpovědi:
  • callback_ordered
  • successfully_enqueued
  • error callback_failed - požadavek se nepodařilo předat Odorik.cz ústředně
  • error missing_argument <seznam_chybejicich_argumentu>
  • error invalid_delay_format
  • error delayed_into_past
  • error invalid_line
• POZOR: požadavek se předává ústředně Odorik.cz, a pokud zadáte neexistující číslo, nebude Váš hovor spojen i přesto, že API vrátí odpověď calback_ordered
• vyžaduje autentizaci

• výpis hovorů
• povinné parametry (jedna ze dvou možností níže):
  1. from, to: časové rozmezí hovorů; řetězec formátovaný jako dateTime z XML Schema (například: 2013-06-05T11:15:00+02:00); pozor na znak “+” (viz Percent-encoding)
  2. since_id: ID posledního staženého hovoru - vhodné pro periodické stahování nových záznamů
• nepovinné parametry:
  • direction: in/out/redirected; filtr na příchozí/odchozí/přesměrované hovory
  • line: vrátit jen na hovory na dané lince
  • min_length, max_length: omezit výpis podle délky hovoru v sekundách
  • min_price, max_price: omezit podle ceny hovoru v korunách
  • status: answered/missed; filtr na zvednuté/zmeškané hovory
  • phone_number_filter: prefix nebo celé telefonní číslo (např. 0049 nebo 00420533533533); filtruje podle source_number i destination_number (OR)
  • sip_ids: pokud je předána hodnota true, přidají se k záznamům o hovorech atributy sip_in_call_id a sip_out_call_id
  • include_sms: pokud je předána hodnota true, vrací se zároveň i SMS zprávy a není potřeba načítat SMS samostatně (pomocí GET /sms.csv (/sms.xml, /sms.json))
• stránkování:
  • na jeden dotaz vracíme maximálně 2000 hovorů, při větším počtu je potřeba použít stránkování
  • parametry:
    • page_size: (maximální) počet vracených hovorů na jednu stránku
    • page: vrátit jinou než první stránku (indexujeme od 1)
  • celkový počet stránek pro daný request vracíme v HTTP hlavičce Odorik-Pages
• vyžaduje autentizaci
• příklad odpovědi (JSON):

[{"id": 98292358,
  "redirection_parent_id": 98292356,
  "date": "2014-10-01T11:28:31Z",
  "direction": "redirected",
  "source_number": "00420555444333",
  "destination_number": "*300000",
  "destination_name": "Česká rep. - * v síti",
  "length": 362,
  "ringing_length": 8,
  "status": "answered",
  "price": 0.0,
  "price_per_minute": 0.0,
  "balance_after": 554.0288,
  "line": 403366,
  "recording": null}]

• výpis právě probíhajících hovorů
• vyžaduje autentizaci
• možné chybové stavy:
  • unauthorized
• příklad odpovědi:

[ { "id":14990661,
    "source_number":"00420533533013",
    "destination_number":"00420910110006",
    "destination_name":"Česko v síti 910-test- přesměrováno",
    "start_date":"2013-08-15T06:34:43Z",
    "answer_date":"2013-08-15T06:34:46Z",
    "price_per_minute":0.0,
    "line":403366 } ]

• zavěšení hovoru; <id> je atribut “id” z výpisu právě probíhajících hovorů
• vyžaduje autentizaci
• možné chybové stavy:
  • unauthorized

• statistika hovorů za zvolené období
• povinné parametry:
  • from, to: časové rozmezí hovorů; řetězec formátovaný jako dateTime z XML Schema (například: 2013-06-05T11:15:00+02:00); pozor na znak “+” (viz Percent-encoding)
• nepovinné parametry:
  • direction: in/out/redirected; filtr na příchozí/odchozí/přesměrované hovory
  • line: vrátit jen na hovory na dané lince
  • min_length, max_length: omezit výpis podle délky hovoru v sekundách
  • min_price, max_price: omezit podle ceny hovoru v korunách
• vyžaduje autentizaci
• příklad odpovědi:

{ "incoming":{"count":140,"length":27405,"price":0.0},
  "outgoing":{"count":118,"length":26808,"price":56.9056},
  "redirected":{"count":14,"length":1696,"price":16.6772} }

• statistika hovorů za zvolené období podle destinací
• povinné parametry:
  • from, to: časové rozmezí hovorů; řetězec formátovaný jako dateTime z XML Schema (například: 2013-06-05T11:15:00+02:00); pozor na znak “+” (viz Percent-encoding)
• nepovinné parametry:
  • direction: in/out/redirected; filtr na příchozí/odchozí/přesměrované hovory
  • line: vrátit jen na hovory na dané lince
  • min_length, max_length: omezit výpis podle délky hovoru v sekundách
  • min_price, max_price: omezit podle ceny hovoru v korunách
• vyžaduje autentizaci
• příklad odpovědi:

[ {"destination":"Česká rep. - mobil","count":10,"length":1234,"price":12.1344,"price_per_minute":0.59,"direction":"out"},
  {"destination":"Česká rep. - mobil","count":14,"length":1696,"price":16.6772,"price_per_minute":0.59,"direction":"redirected"},
  {"destination":"Česká rep. - mobil","count":8,"length":307,"price":7.6239,"price_per_minute":1.49,"direction":"out"},
  {"destination":"Česká rep. - odorikmobil","count":3,"length":105,"price":1.0325,"price_per_minute":0.59,"direction":"out"},
  {"destination":"Česká rep. - odorikpevna","count":54,"length":2603,"price":25.5958,"price_per_minute":0.59,"direction":"out"},
  {"destination":"Česká rep. - pevna","count":2,"length":99,"price":2.4585,"price_per_minute":1.49,"direction":"out"},
  {"destination":"Česká rep. - pevná - špička","count":2,"length":987,"price":8.0605,"price_per_minute":0.49,"direction":"out"},
  {"destination":"Česko v síti","count":106,"length":19028,"price":0.0,"price_per_minute":0.0,"direction":"in"},
  {"destination":"Česko v síti","count":39,"length":21473,"price":0.0,"price_per_minute":0.0,"direction":"out"},
  {"destination":"Odorik.cz mobil","count":34,"length":8377,"price":0.0,"price_per_minute":0.0,"direction":"in"} ]

• statistika zmeškaných hovorů za zvolené období
• povinné parametry:
  • from, to: časové rozmezí hovorů; řetězec formátovaný jako dateTime z XML Schema (například: 2013-06-05T11:15:00+02:00); pozor na znak “+” (viz Percent-encoding)
• vyžaduje autentizaci
• příklad odpovědi:

[ {"destination_number":"00420533533533","count":2},
  {"destination_number":"00420533999999","count":3} ]