Introduksjon
GelatoConnect API lar deg koble systemene dine sammen med GelatoConnect, så du kan sende inn bestillinger, følge med på status og håndtere fraktinformasjon – alt automatisk. Denne veiledningen viser deg hvordan du Kom i gang med API-et og setter opp din første integrasjon.
Forutsetninger
Før du setter i gang med GelatoConnect API, bør du ha:
Din API-nøkkel og hemmelige kode (du får dem når du setter opp en kobling for kunden din)
Grunnleggende forståelse av REST-API-er og HTTP-metoder
Kjennskap til JSON-dataformatet
Et utviklingsmiljø hvor du kan sende HTTP-forespørsler
Grunnleggende om API
GelatoConnect Order Management API er bygget på REST-prinsipper og bruker vanlige HTTP-metoder for å samhandle med ressurser. Alle API-forespørsler må bruke HTTPS, og alle svar returneres i JSON-format, også feilmeldinger.
Base-URL
Grunnadressen for GelatoConnect API er:
https://api.partner-connect.io/api/{partner-prefix}/Du får ditt unike partnerprefiks når du kommer i gang.
Autentisering
Alle API-forespørsler må ha med autentiseringsinformasjonen din i headeren. For å logge inn:
Legg til
X-API-KEY-headeren i forespørselen dinSkriv inn nøkkelen og hemmeligheten din i formatet
key:secret
Eksempel:
X-API-KEY: your-api-key:your-api-secret
Slik sender du din første API-forespørsel
La oss ta en enkel gjennomgang av hvordan du sender inn en bestilling med et API.
1. Gjør klar bestillingsdataene dine
Lag et JSON-objekt med ordreopplysningene. Her er et enkelt 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 inn bestillingen
Send en POST-forespørsel til endepunktet for innsending av ordre:
POST https://api.partner-connect.io/api/{partner-prefix}/orderTa med autentiseringsheaderen og JSON-bestillingsdataene i forespørselens brødtekst.
3. Slik går du videre
Hvis alt går som det skal, får du et svar som dette:
{
"id": "32884a3e-bd09-42be-8225-c5cea7d24611",
"orderReferenceId": "your-order-ref-123",
"createdAt": "2025-04-12T10:23:28+00:00"
}Feltet id inneholder GelatoConnect-ordrenummeret, som du bør lagre for senere referanse.
Vanlige API-operasjoner
Når du har blitt trygg på å sende inn bestillinger, kan du utforske flere muligheter med API-et:
Se ordreopplysninger
Hent informasjon om en eksisterende bestilling:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Avbryt en bestilling
Avbryt en bestilling som ikke er sendt ennå:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancel
Søk etter bestillinger
Finn ordre basert på det du leter etter:
POST https://api.partner-connect.io/api/{partner-prefix}/search
Oppdater frakt
Endre leveringsdetaljer for en bestilling:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Slik får du kundetilpassede produkter
I stedet for å bruke produkt-UID-er, kan du bruke kundeprodukter for en løsning som er enklere å forstå:
{
"productName": "Business Card",
"productVariant": {
"Size": "Standard",
"Paper": "Premium Matte",
"Color": "Full Color Both Sides"
}
}Du må først opprette personlig tilpassede produkter i GelatoConnect før du kan bruke dem i API-kall.
Slik tester du integrasjonen din
Før du lanserer integrasjonen din, test den grundig med disse metodene:
Test med eksempelordrer: Opprett testordrer med lave antall og sjekk at de vises riktig i GelatoConnect.
Sjekk oppdateringer på ordrestatus: Følg med på ordrene fra start til slutt, så du er sikker på at systemet ditt får med seg og håndterer endringer i status på riktig måte.
Feilhåndtering: Lag med vilje ugyldige bestillinger for å teste hvordan du håndterer feil.
Helhetlig testing: Gå gjennom hele bestillingsprosessen fra start til levering med et lite utvalg testordrer.
Gode vaner
For å få best mulig integrasjon med GelatoConnect API:
Lagre ordre-ID-er: Husk alltid å lagre GelatoConnect ordre-ID-en som du får når du oppretter en ordre.
Legg til feilhåndtering: Sørg for god feilhåndtering slik at du er forberedt på uventede svar eller nedetid på API-et.
Bruk idempotens: Lag unike referanse-ID-er for bestillinger, så du unngår dobbeltbestillinger.
Bruk gradvis lengre ventetid: Hvis du får feilmeldinger om for mange forespørsler (429), vent litt lenger for hver gang du prøver på nytt.
Følg med på API-bruken: Ha oversikt over hvor mye du bruker API-et, så slipper du å møte på begrensninger.
Løsning av vanlige problemer
Feil ved innlogging
Hvis du får en 401-autorisasjonsfeil, sjekk at:
API-nøkkelen og hemmeligheten din er riktige
Formatet er
key:secreti X-API-KEY-headerenDu bruker HTTPS, ikke HTTP
Ugyldige forespørselsfeil
Hvis du får en 400 Bad Request-feil:
Se på feilmeldingen for å finne ut hva som er galt med feltene
Sjekk at alle nødvendige felt er med
Bekreft at JSON-formatet er gyldig
Feil på grunn av for mange forespørsler
Hvis du får en 429-feil om for mange forespørsler:
Bruk en ventestrategi for å spre forespørslene jevnt
Tenk på å samle flere forespørsler når det er mulig
Se over integrasjonen din for unødvendige gjentatte forespørsler
Hva skjer nå
Nå som du forstår det grunnleggende i GelatoConnect API, er du klar til å:
Les hele API-dokumentasjonen for detaljert informasjon om endepunkter
Lær om beste praksis for API-er for autentisering, raterestriksjoner og feilhåndtering
Utforsk hvordan du kan jobbe med API-endepunkter for konkrete eksempler på bruk
For mer hjelp med API-integrasjonen din, kontakt brukerstøtte på [email protected].