API - navodila za razvijalce

Minimax API

Minimax API je RESTful spletna storitev, ki omogoča povezavo z zunanjimi aplikacijami za različne namene uporabe. Omogoča uporabo določenega omejenega nabora funkcij, ki so vgrajene v programu Minimax.

Tehnična dokumentacija za Minimax API je na voljo na naslednji povezavi: https://moj.minimax.si/SI/API.

Z uporabo API-ja se strinjate z Minimax API pogoji uporabe.

Naslovi

API:  https://moj.minimax.si/si/api 

AUTH:  https://moj.minimax.si/si/aut/oauth20/token 

Novi razvijalci

Če sami razvijate povezavo, se po uspešni registraciji v Minimax obrnite na podporo (preko zahtevka po pomoči), da pridobite podatke za odjemalca.

Če želite uporabiti katero do obstoječih rešitev, ki so že povezane z Minimaxom (vtičniki za spletne trgovine) ali pa se za implementacijo povezave poslužujete zunanjega razvijalca, ki že dela povezave, ta korak ni potreben.

Podatki za prijavo

  1. Za avtentikacijo poleg podatkov odjemalca potrebujemo še podatke za prijavo uporabnika.
  2. Prijavimo se v SAOP uporabniški račun in v poglavju GESLA ZA DOSTOP ZUNANJIH APLIKACIJ (na dnu strani) kliknemo na gumb NOVA APLIKACIJA
  3. V pojavnem oknu, ki se odpre, vnesemo:
    • naziv aplikacije, 
    • novo uporabniško ime in geslo s katerim se bomo kot uporabnik prijavljali v API.

POZOR! Pri večkratnem zaporednem izvajanju klicev za avtentikacijo z napačnim geslom, se nam APLIKACIJA zaklene in jo moramo ponovno ustvariti.

Primer

  1. Za avtentikacijo uporabljamo protokol OAuth2 (članek OAuth 2 Simplified).
  2. Najprej se prijavimo v AUT :
    • s podatki odjemalca (ID-jem odjemalca in geslom odjemalca)
    • in z uporabniškim imenom in geslom, ki smo ga sami poljubno določili v SAOP uporabniškem računu (glej Podatki za prijavo), 
    • da dobimo žeton (token). 
  3. Pridobljeni žeton posredujemo pri vsakem klicu metode API.
  4. Primer v PHP:
<?php

$params = array(
    'client_id'=> 'ClientId',
    'client_secret'=> 'ClientPassword',
    'grant_type'=> 'password',
    'username'=> 'UserName',
    'password'=> 'UserPassword',
    'scope' => 'minimax.si');

$request = array(
    'http' => array(
        'method'=> 'POST',
        'header'=> array(
            'Content-type: application/x-www-form-urlencoded',
            ),
        'content'=> http_build_query($params),
        'timeout'=> 10
        )
    );

if (!$response = @file_get_contents('https://moj.minimax.si/SI/aut/oauth20/token', false, stream_context_create($request))) {        
    die('Authentication error!');
}
else{
    print ("===============================================================\n");
    print("TOKEN:\n");
    print ("===============================================================\n");
    print_r ($response);
    print ("===============================================================\n\n");
}

$token = json_decode($response);
$request = array(
    'http' => array(
        'method'=> 'GET',
        'header'=> 'Authorization: Bearer ' . $token->access_token,
        'timeout'=> 10
        )
    );
if (!$response = @file_get_contents('https://moj.minimax.si/SI/api/api/currentuser/orgs', false, stream_context_create($request))) {
    die('Call to User -> MyOrganisations failed!');
}
else{
    print ("===============================================================\n");
    print("Call to User -> MyOrganisations:\n");
    print ("===============================================================\n"); 
    $orgs = json_decode($response, true);
    print_r($orgs);
    print ("===============================================================\n");
}
?>

Uporaba podatka RowVersion

Pri posodabljanju zapisov in pri nekaterih akcijah, nastopa podatek RowVersion, s katerim zagotavljamo, da posodabljamo zadnjo različico zapisa. Podatek pridobimo z branjem objekta preko pripadajoče GET metode za branje posameznega zapisa.

V primeru, da se je zapis vmes spremenil, nam vmesnik vrne s tem povezano napako:

Concurrency error - record changed by another action (RowVersion)

Informacija o ustvarjenem objektu - Headers.Location

Vse metode za vpis (npr. AddCustomer) v odgovoru vračajo informacijo o ustvarjenem objektu. To informacijo nosi podatek v odgovoru:

  •  Headers.Location - dobimo url ustvarjenega objekta. Url vsebuje tudi ID ustvarjenega objekta.

Klic na url ustvarjenega objekta (GET) , nam vrne vse podatke objekta.

V tem prispevku