Hämta statistikdata via API

Du kan skapa statistikrapporter på följande olika sätt:

• Använda Opters statistik-API för att hämta valfria statistikdata från Opter och sedan själv skapa statistikrapporter utanför Opter.

  Ni kan programmera en lösning där ni anropar Opters statstik-API och sedan tar emot resultatet och presenterar statistiken som ni själva önskar. Ni kan automatisera flödet så att önskad statistikinformation hämtas från Opter så ofta ni önskar. Till exempel, om statistiken ska presenteras på en dashboard så kanske ni vill hämta statistik en gång varje timme.

• Manuellt ta ut en statistikrapport när ni önskar. Mer information finns i Statistikrapporter.

Statistik-API:et fungerar så här

• Med hjälp av statistik-API:et kan du hämta ut data/information som har med transportordrar att göra och finns i Opter, till exempel leveranstidsprecision. Informationen som statistik-API:et returnerar är ”rådata”/grunddata ur databasen i Opter.

• Den som ska använda statistik-API:et behöver en API-nyckel (se Steg 2: Skapa en API-nyckel nedan).

• När du anropar API:et får du tillbaka all data du valt att hämta i samma anrop. (Statistikdatan delas alltså inte upp i mindre delar, ingen ”pageing” sker.)

• När du anropar API:et får du tillbaka datan som den ser ut just i det ögonblicket i databasen i Opter.

• Du kan hämta data hur ofta du vill. Vi rekommenderar dock att du inte hämtar oftare än nödvändigt för ditt ändamål.

• När du anropar API:et så är det obligatoriskt att ange för vilken period du vill ha statistiken (dateFrom och dateTo) och vilken datumtyp statistiken ska baseras på (dateType). Mer information finns i tabellen Välja vilken typ av datum statistikdatan ska baseras på nedan.

Steg 1: Planera

I stegen nedan finns instruktioner för hur du använder statistik-API:et, men vi rekommenderar att du först gör följande:

1. Bestäm vad det är du vill åtadkomma, det vill säga vad vill du ha ut och varför.

2. Bestäm hur ofta statistikdatan ska hämtas ut från Opter.

   Till exempel, om du vill presentera statistiken på en dashboard så kanske du vill hämta statistikdata en gång varje timme. Om du vill använda statistiken för uppföljning i slutet av varje dag, så kan du hämta statistikdata i slutet av varje dag.

3. Bestäm vem som ska få tillgång till statistik-API:et. Den som får tillgång till statistik-API:et får tillgång till all data, inklusive information om kunder, priser, fakturor, med mera.

Steg 2: Skapa en API-nyckel

Den som ska använda statistik-API:et behöver en API-nyckel. Gör så här:

1. Klicka på Inställningar > API-tillgång (och fliken Allmänt).

2. Klicka på för att skapa en ny användare och ange Namn.

   I fältet API-nyckel visas API-nyckeln som har skapats.

3. I fältet Beskrivning kan du beskriva vad användaren får tillgång till.

4. Klicka på fliken Tillgång.

5. Dubbelkicka på Statistik i Exkluderade-listan så flyttas Statistik till Inkluderade-listan.

   Det betyder att användaren får tillgång till all statistikdata i Opter via statistik-API:et, med hjälp av API-nyckeln.

6. Klicka på för att spara alla ändringar.

Steg 3: Gå till swagger-dokumentationen

1. Swagger-dokumentationen för statistik-API:et hittar du på samma webbadress som kundwebben, men med ”/api” på slutet:

   • Om ni kör Opter Cloud:

     https://<ert företagsnamn><land>.opter.cloud/api/index.html

     Exempel: Om ert företagsnamn i Opter är ”budfirman” och landet Sverige använder du ”https://budfirmanse.opter.cloud/api/index.html”

   • Om ni har egen server:

     https://<ert företagsnamn eller IP-adress>.<land>/api/index.html

     Exempel: Om ert företagsnamn i Opter är ”budfirman” och landet Sverige använder du

     ”https://budfirman.se/api/index.html” eller ”https://123.45.678.901/api/index.html”

   Om du inte hittar swagger-dokumentationen för statistik-API:et, kontakta EDI-teamet på .

2. Högst upp i högra hörnet på webbsidan finns listrutan Select a definition. Välj ”Opter API v1”.

   

Använda datamodellen

Om du vill importera API:et till ett verktyg som till exempel Postman hittar du datamodellen för API:et högt upp på swagger-webbsidan.

Testa att använda API:et

Om du vill testa att använda API:et kan du göra det på swagger-webbsidan eller använda något testprogram som till exempel Postman.

Om du vill testa att anropa statistik-API:et på swagger-webbsidan och se resultatet, gör så här:

1. Högst upp i högra hörnet på webbsidan finns listrutan Select a definition. Välj ”Opter API v1” i listrutan.

   

2. Klicka på Authorize. Kopiera API-nycken från fönstret API-tillgång i Opter, klistra in den i fältet Value och klicka på Authorize. Nu står det Authorized i fönstret. Klicka på Close.

   (API-nyckeln skapade du i Steg 2: Skapa en API-nyckel ovan.)

3. Skrolla ner till Statistics och klicka på GET.

   

   Alla parametrar (”queries”) visas.

4. Klicka på knappen Try it out.

5. Välj dateType (obligatoriskt) i listrutan. Vad de olika valen innebär visas i tabellen Välja vilken typ av datum statistikdatan ska baseras på nedan.

6. Välj för vilken period du vill ha statistikdatan genom att välja dateFrom (obligatoriskt) och dateTo (obligatoriskt).

   Datum skrivs i formatet ”åååå-mm-dd”, till exempel ”2024-08-19”. Om du vill ange både datum och tidpunkt, så skriver du ett mellanslag mellan datum och tid, till exempel ”2024-08-19 13:30”.

   Om du bara anger datum så används standardtiden 00:00.

7. Välj vilka statistikdata du vill ha genom att välja ”true” i listrutan för de parametrarna.

   Till exempel så hämtas all data om ordrar om du sätter includeDeliveries till ”true”, och all data om skanningar hämtas om du sätter includeScans till ”true”.

   (Standardinställningen är ”false”, vilket innebär att du bara behöver välja ”true” för de parametrar du vill ha med i statistikdatan.)

   Detaljer om vilka data som hämtas om du väljer ”true” för till exempel includeDeliveries och includeScans visas längre ner swagger-dokumentationen under Schemas. Klicka på Statistics.Delivery och Statistics.Scan. Klicka på ”[...]” för att se mer detaljer.

   

8. I fältet api-version kan du välja att ange en specifik version eller lämna fältet tomt om du vill att den senaste versionen av API:et används. Om du vill använda en specifik version så skriver du till exempel ”1.0” i fältet.

9. Klicka på knappen Execute för att skicka API-anropet. Under Responses visas resultatet.

   Under Server response visas resultatet/svaret i JSON-format. Klicka på knappen Download om du vill ladda ner JSON-filen.

   Om du vill testa samma API-anrop i till exempel verktyget Postman så kan du kopiera API-anropet som visas i kod-fönstret Curl.

10. Om du vill testa igen (till exempel med andra parametrar) klickar du på Clear bredvid Execute för att rensa under Responses. Därefter kan du anropa API:et på nytt genom att trycka på Execute och titta på resultatet.

Välja vilken typ av datum statistikdatan ska baseras på

När du anropar statstik-API:et använder du parametrarna dateFrom (fråndatum och tid) och dateTo (tilldatum och tid) för att välja för vilken period statistikdatan ska hämtas.

Du använder parametern dateType för att välja vilken typ av datum som statistikdatan ska baseras på enligt tabellen nedan.

dateType	Beskrivning
TransportDate	Utgår från ordrar där Orderdatum matchar datumperioden. All information om de ordrarna kan komma med, även fakturor, skanningar m.m. utanför datumperioden.
ScanDate	Utgår från skanningsrader (kolliskanningar eller fraktsedelsskanningar). All information om de ordrar som har skanningar i vald period kan komma med, oavsett ordrarnas orderdatum, fakturornas fakturadatum, osv. Fakturor och avräkningar kommer inte nödvändigtvis att vara kompletta, det är bara sådana ordrar som har skanningar i perioden kommer att vara med. I parametrarna dateFrom och dateTo kan det vara relevant att ange både datum och tidpunkt. Se Exempel nedan.
InvoiceDate	Utgår från fakturor där fakturadatum matchar datumperioden. Alla information om ordrar som är med på fakturorna kan inkluderas. Detta gäller även om det bara är tilläggsfakturering på ordern (en ny artikel eller en kreditering exempelvis). Ordrar som inte är med på en faktura som matchar perioden kommer inte med, oavsett orderdatum, skanningsdatum, osv.
BillDate	Utgår från avräkningar där avräkningsdatum matchar datumperioden på motsvarande sätt som ovanstående.
ChangeDate	Hämtar data om vilka ordrar som har ändrats under perioden. Detta gäller inte bara ändringar man har gjort genom att öppna ordern, göra ändringar och sedan spara den. Detta gäller även ändringar gjorda i trafikledningen och apparna till exempel: Om en förare ändrar status från Lastad till Lossad i appen Opter Driver, så kommer det att visas i statistiken att ordern har ändrats. Om man i trafikledningen ändrar status eller ansluter till samlastning så kommer det att visas i statistiken att ordern har ändrats. I parametrarna dateFrom och dateTo kan det vara relevant att ange både datum och tidpunkt. Se Exempel nedan. För en order som har ändrats under perioden, så visas datum och tidpunkt för när ordern senast ändrades (under perioden). Du kan se lite mer information om ändringar på ordrarna genom att titta i loggarna i rutan Händelselogg i ordermottagningen i Opter.

Begränsningar

• Det finns ingen historik att följa på ordern. När du anropar API:et får du tillbaka datan som den ser ut just i det ögonblicket i Opter.

  Det går dock att få ut statistik på vilka ordrar som har ändrats under en viss period, se ChangeDate ovan. Statistiken visar inte vad som har ändrats, och man ser bara vilket datum och tidpunkt ordern senast ändrades.

  Du kan se lite mer information om ändringar på ordrarna genom att titta i loggarna i rutan Händelselogg i ordermottagningen i Opter.

• Opter tillhandahåller statistik-API:et, men du får själv ansvara för hur API-anropens resultat/svar ska hanteras och analyseras. Opter tillhandahåller inte verktyg för det.

Exempel

Statistik om vilka ordrar som har ändrats

Om du vill hämta data om följande:

• Vilka ordrar som har ändrats under en viss datumperiod, till exempel under december månad 2024. Ange datumperioden i parametrarna dateFrom ”2024-12-01” och dateTo ”2025-01-01”. (Om du bara anger datum används standardtiden 00:00.)

• Vilka ordrar som ändrats sedan ett visst datum, fram till och med hittills idag, till exempel, från och med ”2024-07-22” till dagens datum och aktuell tid. Ange datum i parametern dateFrom ”2024-07-22”, och datum och tidpunkt i parametern dateTo ”2024-07-26 13:30” (dagens datum och aktuell tid).

  Om du inte anger tid, så används standardtiden 00:00. Det betyder att om du bara anger (dagens) datum i dateTo, så kommer du inte att se vilka ordrar som har ändrats idag.

• Vilka ordrar som har ändrats under de senaste 10 minuterna.

  Till exempel, om klockan är 10:20 och datumet 2024-07-26, så anger du dagens datum och tidpunkten som var för 10 minuter sedan i parametern dateFrom ”2024-07-26 10:10”, och dagens datum och aktuell tidpunkt i parametern dateTo ”2024-07-26 10:20”.

Välj ”ChangeDate” i listrutan dateType. (Mer information finns i tabellen ovan, se ChangeDate.)

Välj ”true” i listrutan includeDeliveries.

Felsökning

• Om du inte hittar statistik-API:et i swagger-dokumentationen kontrollerar du att du har valt ”Opter API v1” i listrutan högst upp i högra hörnet på webbsidan i listrutan Select a definition. Se bild ovan.

• Om API-nyckeln inte fungerar kan du skapa en ny i fönstret API-tillgång på fliken Allmänt vid fältet API-nyckel. Skapa en ny API-nyckel genom att klicka på Ny nyckel och sedan på för att spara den. Därefter kan du använda den för att få tillgång till statistik-API:et.

• Om du har frågor eller vill ha hjälp med felsökning, kontakta EDI-teamet på .

Se även