Integrációt segítő könyvtár (v1)

Az Utánvét Ellenőr API-jához való könnyebb csatlakozás érdekében elérhető az uvb-connector nevű, integrációt segítő PHP könyvtár.

Telepítés

Legegyszerűbben Composer-rel telepíthető:

composer require webmenedzser/uvb-connector

Használat

Egy vásárló megbízhatóságának lekérdezése API-n keresztül:

<?php 
  use webmenedzser\UVBConnector\UVBConnector;

  $email = '[email protected]';
  $publicApiKey = 'aaaa';
  $privateApiKey = 'bbbb';
  $threshold = 0.5;

  $connector = new UVBConnector(
    $email, 
    $publicApiKey, 
    $privateApiKey
  );
  
  // Set a threshold for the request
  $connector->threshold = $threshold;

  // Get reputation by hash
  $response = $connector->get();

Az API válasza erre az alábbi struktúrájú JSON string lesz:

{
    "status": 200,
    "message": {
        "good": 3,
        "bad": 5,
        "goodRate": 0.375,
        "badRate": 0.625,
        "totalRate": -0.25,
    }
}

Ha ezeket az értékeket valamilyen felhasználói felületen (pl. admin felületen) meg szeretnéd jeleníteni, használd a totalRate és/vagy good és bad értékek számszerű értékét. Próbáld elkerülni, hogy valamilyen leírással elfedd ezeket az értékeket, mert az félrevezetheti a felhasználókat.

Példák az API válaszok felhasználói felületen való megjelenítésére

Jó:

• 3 sikeres, 2 sikertelen (kézbesítés), reputáció: 0.2
• Sikeres kézbesítés: 60%

Rossz:

• A rendelés teljesítése nem javasolt (Miért? Nincs egyértelmű indoklás.)
• Túl sok át nem vett rendelés. (Mi számít túl soknak?)
• Rossz megbízhatósági mutató. (Mi számít "rossznak"?)

Rendelés kimenetel (visszajelzés) küldése az API-nak:

<?php
  use webmenedzser\UVBConnector\UVBConnector;

  $email = '[email protected]';
  $publicApiKey = 'aaaa';
  $privateApiKey = 'bbbb';
  // 1 if good, -1 if bad;
  $outcome = 1;
  $orderId = '#98143';
  $phoneNumber = '+36209238883';
  $countryCode = 'HU';
  $postalCode = '8640';
  $addressLine = 'Szigligeti utca 10.';

  $connector = new UVBConnector(
    $email, 
    $publicApiKey, 
    $privateApiKey
  );

  // Submit order outcome to API
  $response = $connector->post(
    $outcome, 
    $orderId, 
    $phoneNumber, 
    $countryCode, 
    $postalCode, 
    $addressLine
  );

Adatcsomag tagjainak részletei:

• outcome: +1 ha sikeres, -1 ha nem vette át
• orderId: A rendelés nyilvános azonosítója, amit a vásárlóknak is kommunikál a rendszer.
• phoneNumber: Telefonszám nemzetközi formátumban, + jellel kezdve, pl.: +36209238883
• countryCode: Országkód ISO 3166-1 alpha-2 formátumban (pl.: HU)
• postalCode: Irányítószám az adott szállítási ország szokásainak megfelelően írva (pl.: 8640)
• addressLine: Címsor, az ország, országkód, irányítószám nélkül. Több sor esetén egy sorba összefűzve.

A visszajelzések küldésének ideális ideje a rendelés állapotának megváltozása.

Teszt környezet

A konstruktor negyedik paraméterének false-ra állításával a könyvtár a teszt környezetet fogja használni a kérés végrehajtása során.

<?php 
  use webmenedzser\UVBConnector\UVBConnector;

  $email = '[email protected]';
  $publicApiKey = 'aaaa';
  $privateApiKey = 'bbbb';
  $production = false;
  $threshold = 0.5;

  $connector = new UVBConnector(
    $email, 
    $publicApiKey, 
    $privateApiKey,
    $production
  );
  
  // Set a threshold for the request
  $connector->threshold = $threshold;

  // Get reputation by hash
  $response = $connector->get();

A teszt környezet API-ja az élessel megegyezően viselkedik, azonban az általa szolgáltatott adatok véletlenszerűen – semmiképpen se használd éles környezetben!