Korte inhoud
Vooraf
De Skarabee VoIP-api stelt VoIP-integrators in staat om op een eenvoudige manier vanuit een cloud applicatie of een on-premise PBX infrastructuur HTTP Post Request aan te leveren op een Skarabee webservice. Verdere afhandeling naar de Skarabee eindgebruiker toe wordt via onze webservers afgehandeld.
In de http request worden volgende parameters verwacht:
- Bid: unieke Skarabee Id van het kantoor
- Phonefrom: telefoon nummer die de oproep initieert
- Phoneto: telefoon nummer die wordt opgeroepen
- Timestamp: tijdstip van de oproep
- Hash: encryptie van de bovenstaande gegevens.
Voor ieder kantoor wordt bij activatie een private key bezorgd voor het berekenen van de hash.
Overview
- Oproep wordt opgepikt door de PBX
- Pbx relayed de call naar een sip/tel account. Op hetzelfde moment lanceert de pbx-applicatie een http post request naar voip.skarabee.net
- Via het Skarabee datacenter wordt de call doorgegeven aan de skarabee client op basis van een KantoorId en een telefoonummer die gekoppeld is aan een skarabee profiel
Detail van de parameters
Endpoint url:
https://voip.skarabee.net/api/?businessid=&phoneto=&phonefrom=×tamp=&hash=
Parameters:
- Businessid: unieke Skarabee Id van het kantoor bv 8103
- Phonefrom: telefoon nummer die de oproep initieert, gebruik bij voorkeur een genormaliseerd nummer
- Phoneto: telefoon nummer die wordt opgeroepen, dit kan ook een sipaccount zijn (string-waarde)
- Timestamp: tijdstip van de oproep (epoch unix) in seconden.
- Hash: Encodering (HMAC256) en publieke key
Demo gegevens:
Een voorbeeld met volgende demo-gegevens
- businessid = 8103
- phoneTo = 056528998
- phonefrom = 056528999
- timestamp = 03-05-2019T13:57:00 (convert to epoch unix local time in seconds !)
- Key = 326C4EA6636911C0537F
Demo & Test
converteren van datetime
eerst berekenen we de timestamp van het moment van de post request timestamp en hashing:
vb. datetime 2019-5-3T12:18:9 via epoch converter naar epoch unix local time levert 1556891830
hashing van alle parameters
hashing van concatenated parameters “81030565289980565289991556885889” met key “326C4EA6636911C0537F” levert hash “fce3bd3536e69f7fe78b15db89464f1979d06beef6d33f2477e641fbecd61d43”
Opbouw van de post request:
https://voip.skarabee.net/api/?businessid=8103&phoneto=056528998&phonefrom=056528999×tamp=1556885889&hash= fce3bd3536e69f7fe78b15db89464f1979d06beef6d33f2477e641fbecd61d43
Mogelijke response van de service :
Timestamp fout:
{"Message":"The timestamp difference is bigger than the maximum timestamp.","Status":"TIMESTAMP_MISMATCH"}
=> De service laat een verschil toe van 15 min. tussen de meegeleverde timestamp en de servertime.
Hashing fout:
{"Message":"The hash provided doesn't match the parameters.","Status":"HASH_MISMATCH"}
Verifieer het algoritme (sha256) en de output hash (hex-waardes)