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
- Versiuni
- Autentificare
- Trimitere date
- Format raspuns
- Resurse individuale
- Format colectie (lista de resurse)
- HTTP Verbs
- Parametrii de filtrare
- Metadata
- Paginatia
- Codurile de status HTTP
- Raspunsurile de eroare
- Side Loading
- Limitele unui API Key
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.