Introduktion
GelatoConnect API gør det nemt for dig at koble dine systemer sammen med GelatoConnect, så du kan sende ordrer, følge deres status og styre leveringsoplysninger – helt automatisk. Denne guide hjælper dig med at komme i gang med API’et og lave din første integration.
Forudsætninger
Før du går i gang med GelatoConnect API, skal du have:
Din API-nøgle og hemmelige kode (du får dem, når du opretter en connector til din kunde)
Grundlæggende forståelse for REST API'er og HTTP-metoder
Kendskab til JSON-dataformatet
Et udviklingsmiljø, hvor du kan sende HTTP-forespørgsler
API – det grundlæggende
GelatoConnect Order Management API er bygget op omkring REST-principper og bruger standard HTTP-metoder til at arbejde med ressourcer. Alle API-forespørgsler skal bruge HTTPS, og alle svar returneres i JSON-format – også fejlmeddelelser.
Base-URL
Basis-URL'en for GelatoConnect API'en er:
https://api.partner-connect.io/api/{partner-prefix}/Du får dit unikke partnerpræfiks, når du bliver onboardet.
Godkendelse
Alle API-forespørgsler skal have dine loginoplysninger med i headeren. Sådan logger du ind:
Tilføj
X-API-KEY-headeren til din forespørgselIndtast din nøgle og hemmelighed i formatet
key:secret
Eksempel:
X-API-KEY: your-api-key:your-api-secret
Sådan laver du din første API-forespørgsel
Lad os tage dig med trin for trin gennem, hvordan du laver en simpel API-anmodning for at sende en ordre.
1. Gør din ordre klar
Lav et JSON-objekt med ordredetaljerne. Her er et simpelt eksempel:
{
"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]",
"phone": "1234567890"
},
"items": [
{
"itemReferenceId": "item-123",
"productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
"quantity": 1,
"files": [
{
"type": "default",
"url": "https://example.com/path/to/printfile.pdf"
}
]
}
]
}
2. Send bestillingen afsted
Send en POST-anmodning til endpointet for at indsende en ordre:
POST https://api.partner-connect.io/api/{partner-prefix}/orderHusk at tilføje din godkendelsesheader og JSON-ordredata i selve forespørgslen.
3. Sådan håndterer du svaret
Hvis det lykkes, får du et svar, der ser sådan ud:
{
"id": "32884a3e-bd09-42be-8225-c5cea7d24611",
"orderReferenceId": "your-order-ref-123",
"createdAt": "2025-04-12T10:23:28+00:00"
}Feltet id indeholder GelatoConnect ordre-ID'et, som du bør gemme til fremtidig reference.
Almindelige API-handlinger
Når du har styr på at sende ordrer ind, kan du begynde at udforske de andre API-muligheder:
Se ordreoplysninger
Hent oplysninger om en eksisterende ordre:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Annuller en ordre
Annuller en ordre, der endnu ikke er sendt afsted:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancel
Søg ordrer
Find ordrer ud fra bestemte kriterier:
POST https://api.partner-connect.io/api/{partner-prefix}/search
Opdater levering
Rediger leveringsoplysninger for en ordre:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Implementering af kundetilpassede produkter
I stedet for at bruge produkt-UID'er, kan du bruge kundeprodukter for en mere overskuelig og brugervenlig løsning:
{
"productName": "Business Card",
"productVariant": {
"Size": "Standard",
"Paper": "Premium Matte",
"Color": "Full Color Both Sides"
}
}Du skal først oprette kundeprodukter i GelatoConnect, før du kan bruge dem i API-kald.
Sådan tester du din integration
Før du går live med din integration, så test den grundigt med disse metoder:
Test med prøveordrer: Opret testordrer med små mængder og bekræft, at de vises korrekt i GelatoConnect.
Tjek opdateringer på ordrestatus: Følg dine ordrer hele vejen, så du er sikker på, at dit system får og håndterer statusændringer rigtigt.
Fejlhåndtering: Lav med vilje ugyldige ordrer for at teste, hvordan du håndterer fejl.
End-to-End Testing: Gennemfør hele ordreprocessen fra start til slut med et lille antal testordrer – så er du sikker på, at alt spiller fra bestilling til levering.
Bedste fremgangsmåder
For at sikre den bedste integration med GelatoConnect API'et:
Gem ordre-ID'er: Husk altid at gemme GelatoConnect ordre-ID'et, som du får, når du opretter en ordre.
Indfør fejlhåndtering: Tilføj solid fejlhåndtering, så du er klar, hvis der opstår uventede svar eller API'en er nede.
Brug idempotens: Lav unikke ordre-ID’er, så du undgår at lave den samme ordre to gange.
Brug eksponentiel ventetid: Hvis du får fejl om for mange forespørgsler (429), så vent lidt længere for hver gang, du prøver igen.
Hold øje med dit API-forbrug: Følg med i dit API-forbrug, så du ikke rammer grænserne.
Sådan løser du de mest almindelige problemer
Godkendelsesfejl
Hvis du får en 401 Unauthorized-fejl, så tjek om:
Din API-nøgle og hemmelige kode er korrekte
Formatet er
key:secreti X-API-KEY headerenDu bruger HTTPS og ikke HTTP
Ugyldige forespørgselsfejl
Hvis du får en 400 Bad Request-fejl:
Tjek fejlbeskeden for at se, hvilke felter der driller
Tjek at alle nødvendige felter er udfyldt
Bekræft, at JSON-formatet er gyldigt
Fejl på grund af for mange forsøg
Hvis du får en 429-fejl om for mange forespørgsler:
Brug en smart pause-strategi, så du ikke sender alle forespørgsler på én gang
Prøv at samle dine forespørgsler, når det er muligt
Gennemgå din integration for unødvendige gentagelser
Hvad sker der nu?
Nu hvor du forstår det grundlæggende i GelatoConnect API'en, er du klar til at:
Læs den fulde API-dokumentation for detaljeret information om endpoints
Lær om API best practices for autentificering, rate limits og fejlhåndtering
Udforsk arbejdet med API-endepunkter for detaljerede eksempler på operationer
For yderligere support med din API-integration kan du kontakte vores supportteam på [email protected].