Introduktion
Med GelatoConnect API kan du enkelt koppla ihop dina system med GelatoConnect för att skicka in beställningar, följa deras status och hantera leveransuppgifter. Den här guiden visar dig hur du kommer igång med API:et och gör din första integration.
Förutsättningar
Innan du börjar arbeta med GelatoConnect API bör du ha:
Din API-nyckel och hemlighet (du får dem när du sätter upp en connector åt din kund)
Grundläggande koll på REST API:er och HTTP-metoder
Känna till hur JSON-data fungerar
En utvecklingsmiljö som kan göra HTTP-förfrågningar
API-grunder
GelatoConnect Order Management API är organiserad enligt REST-principer och använder standardiserade HTTP-metoder för att interagera med resurser. Alla API-förfrågningar måste använda HTTPS, och alla svar returneras i JSON-format, inklusive felmeddelanden.
Bas-URL
Bas-URL:en för GelatoConnect API är:
https://api.partner-connect.io/api/{partner-prefix}/Du får din unika partnerprefix när du kommer igång.
Autentisering
Alla API-förfrågningar måste innehålla dina autentiseringsuppgifter i headern. Så här gör du för att logga in:
Lägg till
X-API-KEY-huvudet i din förfråganAnge värdet för din nyckel och hemlighet i formatet
nyckel:hemlighet
Exempel:
X-API-KEY: your-api-key:your-api-secret
Göra din första API-förfrågan
Vi tar det steg för steg och kollar hur du enkelt skickar en API-förfrågan för att lägga en beställning.
1. Förbered din beställningsdata
Skapa ett JSON-objekt med orderdetaljerna. Här är ett enkelt exempel:
{\"orderReferenceId\": \"your-order-ref-123\","orderType": "order","currency": "USD","shippingAddress": {"country": "US","firstName": "John","lastName": "Doe","addressLine1": "123 Main St",\"city\": \"New York\","postCode": "10001",\"state\": \"NY\",\"email\": \"[email protected]\","telefon": "1234567890"},"artiklar": [{"itemReferenceId": "item-123","productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor","antal": 1,\"filer\": [{\"type\": \"default\",\"url\": \"https://example.com/path/to/printfile.pdf\"}]}]}2. Skicka in beställningen
Gör en POST-begäran till submit order-endpointen:
POST https://api.partner-connect.io/api/{partner-prefix}/orderLägg till din autentiseringsheader och JSON-orderdata i begärans kropp.
3. Ta hand om svaret
Om det lyckas kommer du att få ett svar som ser ut så här:
{"id": "32884a3e-bd09-42be-8225-c5cea7d24611",\"orderReferenceId\": \"your-order-ref-123\","createdAt": "2025-04-12T10:23:28+00:00"}Fältet id innehåller GelatoConnect-ordernumret, som du bör spara för framtida referens.
Vanliga API-åtgärder
När du känner dig trygg med att lägga en beställning kan du börja utforska andra saker du kan göra med API:et:
Hämta orderdetaljer
Hämta information om en befintlig beställning:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}Avboka en order
Avbryt en beställning som ännu inte har skickats:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancelSök efter beställningar
Hitta beställningar baserat på specifika kriterier:
POST https://api.partner-connect.io/api/{partner-prefix}/searchUppdatera leverans
Ändra leveransuppgifter för en beställning:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}Implementera kundprodukter
I stället för att använda produkt-UID:er kan du använda kundprodukter för ett mer lättförståeligt sätt:
{"productName": "Visitkort","productVariant": {"Storlek": "Standard","Papper": "Premium matt","Färg": "Fullfärg på båda sidor"}}Du behöver först lägga upp kundprodukter i GelatoConnect innan du kan använda dem i API-anrop.
Testa din integration
Innan du går live med din integration, testa den noggrant med hjälp av dessa metoder:
Testa med provbeställningar: Skapa några testbeställningar med små kvantiteter och kolla att de syns som de ska i GelatoConnect.
Verifiera orderstatusuppdateringar: Följ ordrar genom hela livscykeln för att säkerställa att ditt system tar emot och hanterar statusändringar korrekt.
Felsökning: Skapa medvetet ogiltiga beställningar för att testa hur du hanterar fel.
End-to-end-testning: Testa hela beställningsresan från start till mål med några få testbeställningar.
Bästa praxis
För att allt ska flyta på smidigt med GelatoConnect API:
Order-ID för butiken: Spara alltid GelatoConnect-order-ID:t som du får när du skapar en order.
Inför smart felhantering: Lägg till pålitlig felhantering så att du är redo om något oväntat händer eller om API:et ligger nere.
Använd idempotens: Skapa unika orderreferenser så att du slipper dubbletter av beställningar.
Implementera exponentiell backoff: När du får felmeddelanden om hastighetsbegränsning (429), använd ökande väntetider mellan återförsök.
Håll koll på din API-användning: Se till att du har ögonen på hur mycket du använder API:et så att du inte slår i taket för gränserna.
Felsök vanliga problem
Problem med inloggning
Om du får ett 401 Unauthorized-fel, kontrollera att:
Din API-nyckel och ditt hemliga lösenord är rätt
Formatet är
key:secreti X-API-KEY-headernDu kör på HTTPS, inte HTTP
Fel vid ogiltig begäran
Om du får ett felmeddelande om 400 Bad Request:
Kolla felmeddelandet för att se vad som är fel med fälten
Dubbelkolla att du har fyllt i alla obligatoriska fält
Bekräfta att JSON-formatet är giltigt
Felmeddelanden om för många försök
Om du får ett felmeddelande om för många förfrågningar (429):
Implementera en backoff-strategi för att sprida ut förfrågningar
Fundera på att samla flera förfrågningar och skicka dem samtidigt när det går
Granska din integration för onödiga upprepade anrop
Nästa steg
Nu när du förstår grunderna i GelatoConnect API är du också redo att läsa den fullständiga API-dokumentationen för detaljerad information om endpoints 🔗 [Orderintag - GCW] Dokumentation för Order Management API