Podrobný popis API

Vzorový příklad - formát JSON

Příklad spuštění služby (věta A:Call):

Tento příklad můžete použít přesně v této podobě (a to buď za pomoci http adapteru, a nebo jej zašlete mailem - adresy naleznete zde). Při použití tohoto příkladu se spustí simulace služby a cca po 1 minutě je služba dokončena a je dostupné summary. To si necháte buď aktivně zaslat (viz. SendSummary), a nebo se můžete na výsledek dotazovat příkladem ve větě E - zde pak ale nezapomeňte změnit ID běžící služby (ServiceExecutionID).

{
     "MessageType":"call",
     "InterfaceID":"intkeyu3b",
     "M2Mpswd":"wdcgh92kp",
     "ServiceID":"srv3n8yf3",
     "ExternalID":"your_ID",
     "InputParameters":{
          "<:Appeal>":"The production line ASX8 is out of order. We are calling critical code for support team.",
          "<:Caller>":"Tato e-mailová adresa je chráněna před spamboty. Pro její zobrazení musíte mít povolen Javascript.",
          "<:Instruction>":"My ability is:",
          "<:Subject>":"Urgent calling for support team",
          "<:Users>":[
               "Tato e-mailová adresa je chráněna před spamboty. Pro její zobrazení musíte mít povolen Javascript.",
               "Tato e-mailová adresa je chráněna před spamboty. Pro její zobrazení musíte mít povolen Javascript.",
               "Tato e-mailová adresa je chráněna před spamboty. Pro její zobrazení musíte mít povolen Javascript."
          ],
          "<:Options>":{
               "1":{
                    "Text":"to be within max 10 min on place",
                    "Order":1
               },
               "2":{
                    "Text":"to be within max 30 min on place",
                    "Order":2
               },
               "3":{
                    "Text":"to make support by phone",
                    "Order":3
               },
               "4":{
                    "Text":"i'm out",
                    "Order":4
               }
          }
     },
     "SendSummary":1
}

Kde:

InterfaceID - obdrží vývojář Interface externí aplikace při zaregistrování interface - popis naleznete zde.

MessageType - jedná se o příklad zprávy A - call  viz. sekvenční diagram

SeviceID - identifikátor komunikační služby, která má být spuštěna. Údaj je definován pro konkrétního zákazníka a konkrétní službu Maatrix. Údaj zjistí administrátor služby Maatrix.

M2Mpswd - M2M heslo, které generuje systém Maatrix pro konkrétní komunikační službu. Údaj zjistí administrátor služby Maatrix, ten také může kdykoli vygenerovat nové M2M heslo.

ExternalID - identifikátor, který definuje externí aplikace.

SendSummary - v tomto případě systém Maatrix pošle externí aplikaci aktivně zprávu o dokončení běhu komunikační služby.

Pokud je věta A zaslána pomocí smtp, je v případě SendSummary defaultně odeslána odpověď (věta X) na stejnou mailovou adresu, ze které přišla zpráva A. Pokud byla zpráva zaslána pomocí http nebo pokud chcete summary zaslat na jinou mailovou adresu, než je odesílající, je potřeba doplnit vlastnost SummaryChanel:

...
  "SummaryChannel": {
"Technology": "email",
"Format": "json",
"EmailRecipient": "your@mail"
}
...

Vstupní parametry - tato konkrétní služba vyžaduje při svém spuštění tři vstupní parametry:

<:Subject> - vstupní parametr typu string

<:Appeal> - vstupní parametr typu string

<:Instruction> - vstupní parametr typu string

<:Caller> - vstupní parametr typu string - emailová adresa odesilatele zprávy (bude kontrolována na povolené volající uživatele)

<:Users> - vstupní parametr typu ListOfK, tj. seznam klíčů (viz. typy dat). Seznam oslovovaných uživatelů je tedy poslán jako list jejich mailových adres.

<:Options> - vstupní parametr typu ArrayOfTO, kde 1,2,3 a 4 jsou klíči jednotlivých položek pole (viz. typy dat), které obsahují texty (v tomto případě připravené volby pro uživatele) a pořadí, ve kterém budou zobrazovány.

 

Příklad chybové odpovědi (věta B:call_response) systému Maatrix (služba nebyla spuštěna):

{
"Response":"error",
"Reason":"users",
"MessageType":"call_response",
"ServiceID":"srv3n8yf3",
"ExternalID":"your_ID",
"Errors":[
{
"Code":"405",
"Description":"Wrong value of a parametr",
"Details":["<:Caller>"]
}
],
"Timestamp":"2015-04-14 09:12:10"
}

Příklad pozitivní odpovědi (věta B:call_response) systému Maatrix (služba byla spuštěna):

{
     "Response":"OK",
     "ServiceID":"srv3n8yf3",
     "MessageType":"call_response",
     "ExternalID":"your_ID",
     "ServiceExecutionID":"0019B45E-D77F-11E4-B9DD-540000270300",
     "SummaryExecutionID":"001F6C5A-D77F-11E4-8A86-540000270300",
"Timestamp":"2015-04-14 09:12:10"
}

Příklad dotazu na běh služby (věta E:app_query):

{
"MessageType": "app_query",
"InterfaceID": "intkeyu3b",
"M2Mpswd": "wdcgh92kp",
"ServiceID": "srv3n8yf3",
"ExternalID": "your_ID_query",
"ServiceExecutionID": "0019B45E-D77F-11E4-B9DD-540000270300",
"Subject": "Service"
}

Ve výše uvedeném příkladu je nutné použít správné ID běhu služby (ServiceExecutionID), které zasílá věta B: call_response

Příklad předání výsledku služby (věta X:summary nebo věty F a Y:app_query_response):

 {
"ExternalID": "your_ID",
"MessageType": "summary",
"QueryExecutionID": "F286B7B8-D799-11E4-8A86-540000270300",
"Results": {
"<:ResultValue>": [
"Tato e-mailová adresa je chráněna před spamboty. Pro její zobrazení musíte mít povolen Javascript.",
"Tato e-mailová adresa je chráněna před spamboty. Pro její zobrazení musíte mít povolen Javascript.",
"Tato e-mailová adresa je chráněna před spamboty. Pro její zobrazení musíte mít povolen Javascript."
]
},
"ServiceExecutionID": "8BC9DEAC-D798-11E4-B374-540000270300",
"ServiceID": "srv3n8yf3",
"Subject": "Service",
"SubjectResult": 1,
"SubjectStatus": "closed",
"Timestamp": "2015-04-14 09:12:10"
}

Vzorový příklad mailu obsahující zprávu A-call:

interface json mail3

 

Mail musí v Předmětu obsahovat klíčový výraz "callAPI-Maatrix", jinak je mail ignorován.