Gyldig fra og med: Opter 2023.12.203

Få statistiske data via API

Du kan oprette statistikrapporter på følgende måder:

• Brug Opters statistik-API til at hente valgfrie statistiske data fra Opter og opret derefter selv statistiske rapporter uden for Opter.

  Du kan programmere en løsning, hvor du anvender Opters statistik-API og derefter modtager resultaterne og præsenterer statistikken, som du ønsker. Du kan automatisere flowet, så de ønskede statistikoplysninger hentes fra Opter, så ofte du ønsker det. Hvis statistikken f.eks. skal vises på et dashboard, kan det være en god idé at hente statistikken en gang i timen.

• Udtag en statistikrapport manuelt, når som helst. Du kan finde yderligere oplysninger i Statistikrapporter.

Sådan fungerer Statistik-API'en

• Ved hjælp af statistik-API'en kan du hente data/oplysninger om transportordrer i Opter, f.eks. om leveringstidspræcision. De oplysninger, der returneres af statistik-API'en, er "rådata"/grunddata fra databasen i Opter.

• Brugeren af statistik-API'en skal bruge en API-nøgle (se Trin 2: Opret en API-nøgle nedenfor).

• Når du anvender API'en, får du returneret alle de data, du har valgt at hente, i samme anmodning. (De statistiske data opdeles altså ikke i mindre dele, der sker ingen "sideinddeling".)

• Når du anvender API'en, får du returneret dataene, som de ser ud på det pågældende tidspunkt i Opters database.

• Du kan hente data, så ofte du vil. Vi anbefaler dog, at du ikke henter oftere, end det er nødvendigt til dit formål.

• Når du anvender API'en, er det obligatorisk at angive for hvilken periode, du vil have statistikken (dateFrom og dateTo), og hvilken datotype statistikken skal baseres på (dateType). Du kan finde yderligere oplysninger i tabellen Valg af datotype, der skal danne grundlag for de statistiske data nedenfor.

Trin 1: Planlægning

Nedenstående trin vejleder dig i, hvordan du bruger statistik-API'en, men vi anbefaler, at du gør følgende først:

1. Beslut dig for, hvad du vil opnå, dvs. hvad du vil have ud af det og hvorfor.

2. Bestem, hvor ofte de statistiske data skal hentes fra Opter.

   Hvis du f.eks. vil præsentere statistikken på et dashboard, kan det være en god idé at hente statistiske data en gang i timen. Hvis du vil bruge statistikken til opfølgning sidst på dagen, kan du hente de statistiske data ved udgangen af hver dag.

3. Beslut, hvem der skal have adgang til statistik-API'en. Alle, der har adgang til statistik-API'et, har adgang til alle data, herunder oplysninger om kunder, priser, fakturaer med mere.

Trin 2: Opret en API-nøgle

Brugeren af statistik-API'en skal bruge en API-nøgle. Sådan gør du:

1. Klik på Indstillinger > API-adgang (og fanen Generelt).

2. Klik på for at oprette en ny bruger, og angiv Navn.

   I feltet API-nøgle vises den API-nøgle, der er blevet oprettet.

3. I feltet Beskrivelse kan du beskrive, hvad brugeren får adgang til.

4. Klik på fanen Adgang.

5. Dobbeltklik på Statistik i Ekskluderet-listen, så flyttes Statistik til Inkluderet-listen.

   Det betyder, at brugeren får adgang til alle statistiske data i Opter via statistik-API'en ved hjælp af API-nøglen.

6. Klik på for at gemme alle ændringer.

Trin 3: Gå til swagger-dokumentation

1. Swagger-dokumentationen for statistik-API'en findes på samme URL-adresse som webportalen til kunder, men med "/api" til sidst:

   • Hvis du kører Opter Cloud:

     https://<jeres virksomhedsnavn><land>.opter.cloud/api/index.html

     Eksempel: Hvis jeres virksomhedsnavn i Opter er "budfirman", og landet er Sverige, skal du bruge "https://budfirmanse.opter.cloud/api/index.html"

   • Hvis du har din egen server:

     https://<dit firmanavn eller din IP-adresse>.<land>/api/index.html

     Eksempel: Hvis jeres virksomhedsnavn i Opter er "budfirman", og landet er Sverige, skal du bruge

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

   Hvis du ikke kan finde swagger-dokumentationen for statistik-API'en, bedes du kontakte EDI-teamet på .

2. I øverste højre hjørne af hjemmesiden har du rullemenuen Select a definition. Vælg "Opter API v1".

   

Brug af datamodellen (valgfrit)

Hvis du vil importere API'en til et værktøj som Postman, kan du finde datamodellen for API'en øverst på swagger-hjemmesiden.

Test API'en (valgfrit)

Hvis du vil teste, hvordan du bruger API'en, kan du gøre det på swagger-hjemmesiden eller bruge et testprogram som Postman.

Hvis du vil prøve en anmodning med statistik-API'en på swagger-hjemmesiden og se resultaterne, skal du gøre følgende:

1. I øverste højre hjørne af hjemmesiden har du rullemenuen Select a definition. Vælg "Opter API v1" i rullemenuen.

   

2. Klik på Authorize. Kopier API-nøglen fra vinduet API-adgang i Opter, indsæt den i feltet Value, og klik på Authorize. Nu står der Authorized i vinduet. Klik på Close.

   (Du oprettede API-nøglen i Trin 2: Opret en API-nøgle ovenfor.)

3. Rul ned til Statisticsog klik på GET.

   

   Alle parametre ("queries") vises.

4. Klik på knappen Try it out.

5. Vælg dateType (obligatorisk) i rullemenuen. Du kan se, hvad de forskellige valg indebærer, i tabellen Valg af datotype, der skal danne grundlag for de statistiske data nedenfor.

6. Vælg den periode, du vil have de statistiske data for, ved at vælge dateFrom (obligatorisk) og dateTo (obligatorisk).

   Datoer skrives i formatet "åååå-mm-dd", for eksempel "2024-08-19". Hvis du vil indtaste både dato og klokkeslæt, skal du skrive et mellemrum mellem dato og klokkeslæt, for eksempel "2024-08-19 13:30".

   Hvis du kun indtaster datoen, anvendes standardtiden 00:00.

7. Vælg, hvilke statistiske data du vil have, ved at vælge "true" i rullelisten for de pågældende parametre.

   Hvis du f.eks. indstiller includeDeliveries til "true", vil alle ordredata blive indhentet, og alle scanningsdata vil blive indhentet, hvis du indstiller includeScans til "true".

   (Standardindstillingen er "false", hvilket betyder, at du kun behøver at vælge "true" for de parametre, du vil have med i de statistiske data.)

   Detaljer om, hvilke data der hentes, hvis du f.eks. vælger "true" for includeDeliveries og includeScans, vises længere nede i swagger-dokumentationen under Schemas. Klik på Statistics.Delivery og Statistics.Scan. Klik på "[...]" for at se flere detaljer.

   

8. I feltet api-version kan du vælge at indtaste en bestemt version eller lade feltet stå tomt, hvis du vil have den nyeste version af API'en anvendes. Hvis du vil anvende en bestemt version, skal du f.eks. skrive "1.0" i feltet.

9. Klik på knappen Execute for at sende API-anmodningen. Resultatet vises under Responses.

   Resultatet/svaret vises i JSON-format under Server response. Klik på knappen Download for at downloade JSON-filen.

   Hvis du vil teste den samme API-anmodning i for eksempel Postman-værktøjet, kan du kopiere den API-anmodning, der vises i kodevinduet Curl.

10. Hvis du vil teste den igen (f.eks. med andre parametre), skal du klikke på Clear ved siden af Execute for at rydde under Responses. Du kan derefter anmode API'en igen ved at klikke på Execute og se resultaterne.

Valg af datotype, der skal danne grundlag for de statistiske data

Når du anmoder statistik-API'en, skal du bruge parametrene dateFrom (fra dato og tidspunkt) og dateTo (til dato og tidspunkt) til at vælge den periode, som de statistiske data skal hentes for.

Du bruger parameteren dateType til at vælge den datotype, som de statistiske data skal baseres på, som vist i tabellen nedenfor.

dateType	Beskrivelse
TransportDate	Baseret på ordrer, hvor Ordredato matcher datointervallet. Alle oplysninger om disse ordrer kan medtages, herunder fakturaer, scanninger osv. uden for datoperioden.
ScanDate	Baseret på scanningsrækker (kolliscanninger eller fragtbrevsscanninger). Alle oplysninger om de ordrer, der har scanninger i den valgte periode, kan medtages, uanset ordrernes ordredato, fakturaernes fakturadato osv. Fakturaer og afregninger vil ikke nødvendigvis være komplette. Det er kun de ordrer, der har scanninger i perioden, der vil være inkluderet. I parametrene dateFrom og dateTo kan det være relevant at angive både dato og klokkeslæt. Se eksemplet nedenfor.
InvoiceDate	Baseret på fakturaer, hvor fakturadatoen matcher datoperioden. Alle oplysninger om ordrer, der er inkluderet i fakturaerne, kan medtages. Det gælder også, hvis det bare er en ekstra faktura på ordren (f.eks. en ny artikel eller en kreditnota). Ordrer, som ikke er medtaget på en faktura, der matcher perioden, vil ikke blive medtaget, uanset ordredato, scanningsdato osv.
BillDate	Baseret på afregninger, hvor afregningsdatoen matcher datoperioden på samme måde som ovenfor.
ChangeDate	Henter data om, hvilke ordrer der er ændret i løbet af perioden. Dette gælder ikke kun for ændringer, der foretages ved at åbne ordren, foretage ændringer og derefter gemme den. Det gælder også ændringer i disponeringen og apps, som f.eks.: Hvis en chauffør ændrer status fra Lastet til Leveret i appen Opter Driver, vil statistikken vise, at ordren er ændret. Hvis du ændrer status i disponeringen eller opretter samlastning, vil statistikken vise, at ordren er ændret. I parametrene dateFrom og dateTo kan det være relevant at angive både dato og klokkeslæt. Se eksemplet nedenfor. Hvis en ordre er blevet ændret i perioden, vises dato og klokkeslæt for, hvornår ordren sidst blev ændret (i perioden). Du kan se flere oplysninger om ændringer i ordrerne ved at se på logfilerne i ruden Leveringslog i ordremodtagelsen i Opter.

Begrænsninger

• Der er ingen historik at følge på ordren. Når du anvender API'en, får du returneret dataene, som de ser ud på det pågældende tidspunkt i Opter.

  Det er dog muligt at få statistik over, hvilke ordrer der er blevet ændret i løbet af en bestemt periode. Se ChangeDate ovenfor. Statistikken viser ikke, hvad der er blevet ændret, men kun dato og klokkeslæt for sidste ændring af ordren.

  Du kan se flere oplysninger om ændringer i ordrerne ved at se på logfilerne i ruden Leveringslog i ordremodtagelsen i Opter.

• Opter stiller statistik-API'en til rådighed, men du er selv ansvarlig for, hvordan resultaterne/svarene fra API-anmodningerne håndteres og analyseres. Opter stiller ikke værktøjer til rådighed til det.

Eksempel

Statistik over, hvilke ordrer der er blevet ændret

Hvis du vil hente data om følgende:

• Hvilke ordrer, der er ændret i løbet af en bestemt periode, f.eks. i december 2024. Indtast datointervallet i parametrene dateFrom "2024-12-01" og dateTo "2025-01-01". (Hvis du kun indtaster datoen, anvendes standardtiden 00:00.)

• Hvilke ordrer, der er ændret siden en bestemt dato til og med i dag, f.eks. fra "2024-07-22" til dags dato og klokkeslæt. Indtast datoen i parameteren dateFrom "2024-07-22" og dato og klokkeslæt i parameteren dateTo "2024-07-26 13:30" (dags dato og klokkeslæt).

  Hvis du ikke angiver et tidspunkt, anvendes standardtiden 00:00. Det betyder, at hvis du kun indtaster (dags) dato i dateTo, vil du ikke se, hvilke ordrer der er ændret i dag.

• Hvilke ordrer, der er ændret i løbet af de sidste ti minutter.

  Hvis klokken f.eks. er 10:20, og datoen er 2024-07-26, så indtaster du dags dato og klokkeslættet for 10 minutter siden i parameteren dateFrom "2024-07-26 10:10", og dags dato og det aktuelle klokkeslæt i parameteren dateTo "2024-07-26 10:20".

Vælg "ChangeDate" fra rullelisten dateType. (Du kan finde yderligere oplysninger i tabellen ovenfor. Se ChangeDate).

Vælg "true" i rullemenuen includeDeliveries.

Fejlfinding

• Hvis du ikke kan finde statistik-API'en i swagger-dokumentationen, skal du kontrollere, at du har valgt "Opter API v1" i rullemenuen Select a definition i øverste højre hjørne af hjemmesiden. Se billedet ovenfor.

• Hvis API-nøglen ikke virker, kan du oprette en ny i vinduet API-adgang på fanen Generelt ved feltet API-nøgle. For at oprette en ny API-nøgle skal du klikke på Ny nøgle og derefter på for at gemme den. Du kan derefter bruge den til at få adgang til statistik-API'en.

• Hvis du har spørgsmål eller brug for hjælp til fejlfinding, bedes du kontakte EDI-teamet på .

---