Generalitati API MerchantPro

Acesta este sectiunea de help pentru versiunea Legacy a panoului de control. Daca utilizati panoul de control Flex, puteti gasi aici sectiunea de help relevanta.

API-ul MerchantPro este un API de tip REST. Pentru a putea folosi resursele API ai nevoie de un cont VIP, certificat HTTPS instalat si va trebui sa iti activezi cheia API din pagina Acces API. Vezi sectiunile de mai jos pentru mai multe informatii privind modul de utilizare.

Conventii

Endpoint-urile API sunt descrise cu o metoda HTTP si un path. Exemplu:

GET /api/v2/products HTTP/1.1

Prefixeaza path-ul cu URL-ul domeniului tau (inclusiv protocolul https) pentru a obtine URL-ul final. De exemplu daca domeniul tau este example.com atunci URL-ul final al endpoint-ului va fi:

https://www.example.com/api/v2/products

Acoladele, {}, in URL-uri indica o valoare care trebuie inlocuita:

GET /api/v2/products/{id} HTTP/1.1

Toate proprietatile JSON ale API-ului, URL-urile precum si parametrii din URL sunt case senstive.

Versiuni

API-ul MerchantPro foloseste un sistem de versiuni pentru a acomoda upgrade-urile asigurand compatibilitatea cu variantele actuale.

Versiunea actuala, disponibila public este v2, asa cum indica prefixul path-ului /api/v2/.

Autentificare

Pentru a putea accesa API-ul MerchantPro va trebui sa te autentifici folosind basic authentication pe baza de API Key si Api Secret. Autentificarea unui request API implica trimiterea unui header de autorizare. Pentru a te autentifica trebuie sa urmezi pasii de mai jos:

  • Combina API Key si Api Secret in forma urmatoare key:password
  • Aplica base64_encode pe stringul rezultat, ex a2V5OnNlY3JldA==
  • Include headerul HTTP de autorizare basic
Authorization: Basic {base64-encoded-string}
Authorization: Basic a2V5OnBhc3M=

Autentificarea cu credentiale invalide va returna 401 Unauthorized, iar incercarile repetate vor returna 403 Forbidden.

Trimitere date

Accesarea API-ului se face pe domeniul magazinului tau, pe baza de HTTPS. Toate datele trimise sunt in format JSON.

Este necesar sa trimiti headerul Accept: application/json pentru a confirma ca aplicatia ta se asteapta la un raspuns in format JSON de la API.

Este necesar sa trimiti request-uri de tip POST sau PUT insotite de headerul Content-Type: application/json iar continutul trimis trebuie sa fie format JSON valid.

Format raspuns

API-ul raspunde cu continut in format JSON, reprezentat de string-uri, numere, obiecte, array-uri, valori booleane sau null.

API-ul MerchantPro va returna coduri HTTP 200 si 300 in cazul raspunsurilor cu succes, iar in cazul erorilor va returna coduri HTTP 400 si 500.

In general raspunsul API-ul poate contine urmatoarele:

  • Eroare (insotitat de cod si mesaj de eroare)
  • Date in format de resursa individuala
  • Date in format colectie (lista de resurse)

Resurse individuale

Cand accesezi o resursa individuala se va returna un set extins de date (toate atributele specifice resursei respective). In plus resursele secundare care apartin de aceasta resursa vor fi incluse in lista (variantele unui produs sau toate imaginile produsului).

Format colectie (lista de resurse)

Cand accesezi o lista de resurse un set sumar al fiecarei resurse individuale va fi returnat. In marea majoritate a cazurilor, lista contine suficiente informatii pentru a permite utilizarea in cadrul altei aplicatii fara a fi necesar un apel individual catre fiecare resursa.

HTTP Verbs

Iata un rezumat al verbelor HTTP pe care le poti utiliza si scopul fiecaruia:

Verb Scop Exemplu
GET Folosit pentru extragerea de date GET /products sau GET /products/123
POST Folosit pentru crearea de noi resurse POST /products
PUT Folosit pentru updatarea unor resurse existente cu date partiale PUT /products/123
DELETE Folosit pentru stergerea de resurse DELETE /products/123

Parametrii de filtrare

Anumite endpoint-uri, in special cele de tip colectie iti permit sa folosesti parametrii specifici pentru a putea filtra rezultatele cautarii.

Metadata

Informatii despre numarul total de resurse care indeplinesc criteriile de filtrare sunt oferite in metadata, impreuna cu informatiile necesare despre existenta unor resurse suplimentare si URL-urile de accesare ale acestora (acolo unde e cazul).

"meta": {
  "count": {
    "total": 8219,
    "current": 20,
    "start": 0,
    "limit": 20
  },
  "links": {
    "prev": null,
    "current": "/api/v2/products",
    "next": "/api/v2/products?start=20&limit=20"
  },
  "has_more": true
}

Paginatia

Paginatia anumitor resurse de tip colectie are loc in mod automat. In mod implicit majoritatea endpoint-urilor returneaza 20 de inregistrari pe pagina. Poti modifica numarul de inregistrari pe pagina folosind parametrul limit (ex limit=50), insa nu poti depasi 100 de inregistrari pe pagina in majoritarea cazurilor.

Cand raspunsul depaseste limita de inregistrari pe pagina, poti naviga pe paginile succesive folosind parametrul start (ex start=20)

Raspunsul include atributele next si previous pentru a facilita navigarea.

"meta": {
  ...
  "links": {
    "prev": "/api/v2/products",
    "current": "/api/v2/products?start=20&limit=20",
    "next": "/api/v2/products?start=40&limit=20"
  }
}

Opreste navigarea pe pagini succesive atunci cand atributul next este null.

Codurile de status HTTP

Codurile de status HTTP pe care API-ul le intoarce sunt importante si iti permit sa interpretezi mai bine raspunsul primit. Mai jos regasesti un sumar al acestora:

Cod Semnificatie
200 Found and returned
201 Resource created
204 Resource deleted
400 Bad Request
401 Unauthorized
403 Forbidden
404 Resource not found
405 Method not allowed
429 Too many requests
500 Internal server error

Raspunsurile de eroare

Raspunsurile de eroare sunt de asemenea in format JSON si au urmatoarea forma:

{
  "error": {
    "name": "unauthorized",
    "message": "Authentication required"
  }
}

Codul de eroare si mesajul aferent sunt denumiri specifice MerchantPro pentru reprezentarea erorii.

Side Loading

In cazul colectiilor este posibila incarcarea suplimentara de date ca parte a aceluiasi request. De exemplu in mod normal un request catre /products va returna datele intr-o structura similara celei de mai jos:

{
  "data": [
    {
      "id": 7,
      "name": "Smartwatch GARMIN Vivoactive",
      ...
    },
    {
      "id": 7,
      "name": "Samsung Galaxy Smartwatch",
      ...
    }
  ]
}

Pentru a putea extrage anumite informatii suplimentare care in mod normal nu s-ar regasi in acest raspuns (cum ar fi imaginile sau variantele) ar fi necesar sa faci un alt request catre /products/7

Folosind side-loading, poti sa fortezi incarcarea unor date suplimentare in acelasi request. Pentru asta va fi necesara apendarea parametrului include cu o lista de variabile suplimentare (separate prin virgula) pe care doresti sa le apendezi.

Exemple:

.../products?include=variants .../orders?include=products

Raspunsul va include datele solicitate in exact aceeasi structura in care ar fi incluse daca ar fi solicitate printr-un request catre o resursa individual.

{
  "data": [
    {
      "id": 7,
      "name": "Smartwatch GARMIN Vivoactive",
      "variants": [
        ...
      ],
      ...
    },
    {
      "id": 7,
      "name": "Samsung Galaxy Smartwatch",
      "variants": [
        ...
      ],
      ...
    }
  ]
}

Limitele unui API Key

Pentru a mentine optime performantele API-ul, MerchantPro impune o serie de limite globale de request-uri pe minut si/sau ora. Cand se depasesc aceste limite request-urile vor incepe sa esueze cu un cod de status HTTP 429 You have exceeded your request quota for this API. Poti mari aceasta limita la cerere contactandu-ne la support@merchantpro.ro.

Ultima modificare: 20 Dec 2023
Te-a ajutat acest articol?
Mai ai nevoie si de alte informatii?