Koppla ihop dina system med API:et och webhooks

7 steg7 min läsning

För utvecklare som ansluter en webbutik, ett affärssystem eller WMS. Ägaren, eller en teammedlem med behörigheten Utvecklare, behöver skapa nyckeln, och du behöver en publik HTTPS-adress för att ta emot webhooks.

1. 1

   Steg 1: Skapa en API-nyckel

   Ge nyckeln ett namn (där den används) under Inställningar → API-nycklar och klicka på Skapa nyckel. Kopiera den direkt: den visas bara en gång. Skicka den med varje anrop som Authorization: Bearer <key>.

   app.afi.io

   

2. 2

   Steg 2: Prova innan du kodar

   Klicka på Testa nyckeln och skicka ett färdigt anrop (kontrollera nyckeln, dagens order, skapa en testorder och läs tillbaka den) eller ett eget. Du ser svaret, statusen och tiden, med ett curl-kommando att kopiera. Ladda ner Postman-samlingen som gjorts för ditt företag och öppna API-anropsloggen för att se varje anrop de senaste 3 dagarna.

   Tips: Ge testorder ett order-ID som börjar med API-TEST-: de planeras aldrig och får inga meddelanden, räknas ingenstans och raderas efter 3 dagar.

3. 3

   Steg 3: Läs referensen

   API:et finns på din Afi Planner-adress under /api/v1. Den fullständiga beskrivningen finns på /api/v1/openapi.json (OpenAPI 3.1), som de flesta verktyg kan importera för att generera en klient.

4. 4

   Steg 4: Skicka order

   POST /api/v1/orders med ditt order-ID som ref, leveransdagen, adressen (eller latitud och longitud), tidsfönster, kollin och vikt. En ref pekar ut en öppen order över alla dagar: skickar du den igen uppdateras den ordern och behåller sin dag (en ref vars order misslyckades de senaste 14 dagarna blir dess nästa försök, med samma spårningslänk), tills en förare har arbetat med den: då blir svaret 409 order_worked med orderns id, och PATCH /api/v1/orders/{id} ändrar dess fält. Använd /api/v1/orders/batch för upp till 1 000 order åt gången; en dags plan rymmer ändå högst paketets antal stopp per plan (500 i den kostnadsfria provperioden), och en batch med fler nya order än som ryms nekas helt.

   Tips: Lägg till en Idempotency-Key-header i POST-anrop: om ett anrop görs om efter ett nätverksfel får du tillbaka det första svaret i stället för att åtgärden utförs två gånger.

5. 5

   Steg 5: Planera och skicka ut

   Välj dagens förare med PUT /api/v1/days/{day}/drivers, starta planeringen med POST /api/v1/days/{day}/optimize, följ jobbet med GET /api/v1/jobs/{id} och skicka sedan rutterna med POST /api/v1/days/{day}/dispatch. Dina trafikledare kan fortfarande justera rutterna i appen. Läsningar ger alltid rutterna så som de skickades till förarna, samma som dina kunder ser; medan trafikledarens tavla skiljer sig från det som skickades har ordrarna även draftRoute och dagens plan draft. Om en trafikledare delar upp en dag i flera planer i appen använder nya order och dessa endpoints dagens första plan.

6. 6

   Steg 6: Lägg till en webhook

   Lägg till din HTTPS-endpoint och välj händelserna under Inställningar → Webhooks. Kopiera signeringshemligheten och klicka sedan på Skicka test: resultatet och varje senare leverans syns i loggen, med payload, headers och din servers svar, och en knapp Skicka igen.

7. 7

   Steg 7: Verifiera varje händelse

   Varje anrop har headern Afi-Signature: t=<time>,v1=<signature>. Beräkna HMAC-SHA256 av ”t.body” med din hemlighet, jämför med v1 och avvisa händelser som är äldre än fem minuter. Svara med en 2xx-status inom 10 sekunder och gör arbetet efteråt; misslyckade leveranser försöks igen i ungefär ett dygn. Händelser som uppstår medan en endpoint är avstängd sparas inte för den: läs ordrarna med GET /api/v1/orders?day= när du har slagit på den igen.