Gjelder fra og med: Opter 2023.12.203

Hente statistikkdata via API

Du kan opprette statistikkrapporter på følgende forskjellige måter:

• Bruk Opters statistikk-API til å hente valgfrie statistikkdata fra Opter og deretter selv lage statistikkrapporter utenfor Opter.

  Du kan programmere en løsning der du kaller på Opters statistikk-API og deretter mottar resultatene og presenterer statistikken slik du ønsker. Du kan automatisere flyten slik at ønsket statistikkinformasjon hentes fra Opter så ofte du ønsker det. Hvis statistikken for eksempel skal presenteres på et dashbord, kan det være lurt å hente statistikken en gang i timen.

• Hent ut en statistikkrapport manuelt når du ønsker. Mer informasjon er tilgjengelig i Statistiske rapporter.

Statistikk-API fungerer på følgende måte

• Ved hjelp av statistikk-API kan du hente ut data/informasjon som er knyttet til transportordrer og finnes i Opter, for eksempel leveringstidpresisjon. Informasjonen som returneres fra statistikk-API, er «rådata»/grunndata fra databasen i Opter.

• Brukeren av statistikk-API trenger en API-nøkkel (se Trinn 2): Opprett en API-nøkkel nedenfor).

• Når du kaller på API-et, får du tilbake alle dataene du har valgt å hente i samme kall. (Statistikkdataene deles altså ikke opp i mindre deler, og det foretas ingen «pageing».)

• Når du kaller på API-et, får du dataene tilbake slik de er i databasen i Opter på det aktuelle tidspunktet.

• Du kan hente data så ofte du vil. Vi anbefaler imidlertid at du ikke henter oftere enn det som er nødvendig for ditt formål.

• Når du kaller på API-et, er det obligatorisk å angi perioden du vil ha statistikk for (dateFrom og dateTo) og hvilken datotype statistikken skal baseres på (dateType). Mer informasjon er tilgjengelig i tabellen Velg hvilken type dato statistikkdata skal baseres på, nedenfor.

Trinn 1: Planlegge

Trinnene nedenfor gir instruksjoner om hvordan du bruker statistikk-API, men vi anbefaler at du gjør følgende først:

1. Bestem deg for hva du ønsker å oppnå, dvs. hva du ønsker å hente ut og hvorfor.

2. Bestem hvor ofte statistikkdataene skal hentes ut fra Opter.

   Hvis statistikken for eksempel skal presenteres på et dashbord, kan det være lurt å hente ut statistikken en gang i timen. Hvis du ønsker å bruke statistikken til oppfølging på slutten av hver dag, kan du hente ut statistikkdata på slutten av hver dag.

3. Bestem hvem som skal ha tilgang til statistikk-API. Alle som får tilgang til statistikk-API, vil ha tilgang til alle data, inkludert informasjon om kunder, priser, fakturaer osv.

Trinn 2: Opprett en API-nøkkel

Brukeren av statistikk-API trenger en API-nøkkel. Slik gjør du:

1. Klikk på Innstillinger > API-tilgang (og fanen Standard).

2. Klikk på for å opprette en ny bruker og angi Navn.

   I feltet API-nøkkel vises API-nøkkelen som er opprettet.

3. I feltet Beskrivelse kan du beskrive hva brukeren får tilgang til.

4. Klikk på fanen Tilgang.

5. Dobbeltklikk på Statistikk i Ekskludert-listen, så flyttes Statistikk til Inkluderte-listen.

   Det betyr at brukeren får tilgang til alle statistikkdata i Opter via statistikk-API ved hjelp av API-nøkkelen.

6. Klikk på for å lagre alle endringer.

Trinn 3: Gå til swagger-dokumentasjonen

1. Swagger-dokumentasjonen for statistikk-API finner du på samme nettadresse som kundenettsiden, men med «/api» til slutt:

   • Hvis du kjører Opter Cloud:

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

     Eksempel: Hvis firmanavnet ditt i Opter er «budfirmaet» og landet er Norge, bruker du ”https://budfirmanse.opter.cloud/api/index.html”

   • Hvis du har egen server:

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

     Eksempel: Hvis firmanavnet ditt i Opter er «budfirmaet» og landet er Norge, bruker du

     ”https://budfirmaet.no/api/index.html” eller ”https://123.45.678.901/api/index.html”

   Hvis du ikke finner swagger-dokumentasjonen for statistikk-API, kan du kontakte EDI-teamet på .

2. Øverst i høyre hjørne på nettsiden er rullegardinmenyen Select a definition. Velg «Opter API v1».

   

Bruke datamodellen (valgfritt)

Hvis du vil importere API-et til et verktøy som Postman, finner du datamodellen for API-et øverst på swagger-nettsiden.

Prøve å bruke API-et (valgfritt)

Hvis du vil teste API-et, kan du gjøre det på swagger-nettsiden eller bruke et testprogram som f.eks. Postman.

Hvis du vil prøve å kalle på statistikk-API- på swagger-nettsiden og se resultatene, kan du gjøre følgende:

1. Øverst i høyre hjørne på nettsiden er rullegardinmenyen Select a definition. Velg «Opter API v1» i rullegardinmenyen.

   

2. Klikk på Authorize. Kopier API-nøkkelen fra vinduet API-tilgang i Opter, lim den inn i feltet Value og klikk på Authorize. Nå står det Authorized i vinduet. Klikk på Close.

   (Du opprettet API-nøkkelen i Trinn 2: Opprett en API-nøkkel ovenfor.)

3. Bla ned til Statistics og klikk på GET.

   

   Alle parametere («spørringer») vises.

4. Klikk på knappen Try it out.

5. Velg dateType (obligatorisk) i rullegardinmenyen. Hva de ulike valgene innebærer. vises i tabellen Velg hvilken datotype statistikkdataene skal baseres på nedenfor.

6. Velg hvilken periode du vil ha statistikkdata for ved å velge dateFrom (obligatorisk) og dateTo (obligatorisk).

   Dato skrives i formatet «ååååå-mm-dd», for eksempel «2024-08-19». Hvis du vil angi både dato og klokkeslett, skriver du inn et mellomrom mellom dato og klokkeslett, for eksempel «2024-08-19 13:30».

   Hvis du bare angir datoen, brukes standardtiden 00:00.

7. Velg hvilke statistikkdata du vil ha ved å velge «true» i rullegardinmenyen for de aktuelle parameterne.

   Hvis du for eksempel setter includeDeliveries til "true", hentes alle data om ordrer, og hvis du setter includeScans til "true", hentes alle data om skanninger.

   (Standardinnstillingen er «false», noe som betyr at du bare trenger å velge «true» for de parameterne du ønsker å ha med i statistikkdataene.)

   Detaljer om hvilke data som hentes hvis du for eksempel velger «true» for includeDeliveries og includeScans, vises lenger ned i swagger-dokumentasjonen under Schemas. Klikk på Statistics.Delivery og Statistics.Scan. Klikk på «[...]» for å se flere detaljer.

   

8. I feltet api-version kan du velge å angi en bestemt versjon, eller du kan la feltet stå tomt hvis du vil at den nyeste versjonen av API-et skal brukes. Hvis du vil bruke en bestemt versjon, skriver du f.eks. «1.0» i feltet.

9. Klikk på knappen Execute for å sende API-kallet. Under Responses vises resultatet.

   Under Server response vises resultatet/svaret i JSON-format. Klikk på knappen Download hvis du vil laste ned JSON-filen.

   Hvis du vil teste det samme API-kallet i for eksempel verktøyet Postman, kan du kopiere API-kallet som vises i kodevinduet Curl.

10. Hvis du vil teste på nytt (for eksempel med andre parametere), klikker du på Clear ved siden av Execute for å tømme under Responses. Deretter kan du kalle på API-et på nytt ved å trykke på Execute og se på resultatet.

Velg hvilken datotype statistikkdataene skal baseres på

Når du kaller på statistikk-API, bruker du parameterne dateFrom (fra dato og klokkeslett) og dateTo (til dato og klokkeslett) for å velge hvilken periode statistikkdataene skal hentes for.

Du bruker parameteren dateType til å velge hvilken datotype statistikkdataene skal baseres på, som vist i tabellen nedenfor.

dateType	Beskrivelse
TransportDate	Basert på ordrer der Ordredato samsvarer med datoperioden. All informasjon om disse ordrene kan inkluderes, inkludert fakturaer, skanninger osv. utenfor datoperioden.
ScanDate	Basert på skannelinjer (kolliskanninger eller fraktbrevskanninger). All informasjon om ordrene som har skanninger i den valgte perioden, kan inkluderes, uavhengig av ordredato på ordrene, fakturadato på fakturaene osv. Fakturaer og avregninger vil ikke nødvendigvis være fullstendige, bare de ordrene som har skanninger i perioden vil være inkludert. I parameterne dateFrom og dateTo kan det være aktuelt å angi både dato og klokkeslett. Se Eksempel nedenfor.
InvoiceDate	Basert på fakturaer der fakturadatoen samsvarer med datoperioden. All informasjon om ordrer som er med på fakturaene, kan inkluderes. Dette gjelder selv om det bare er en tilleggsfakturering på ordren (for eksempel en ny artikkel eller en kreditering). Ordrer som ikke er med på en faktura som samsvarer med perioden, vil ikke bli inkludert, uavhengig av ordredato, skannedato osv.
BillDate	Basert på avregninger der avregningsdatoen samsvarer med datoperioden på samme måte som ovenfor.
ChangeDate	Henter data om hvilke ordrer som har blitt endret i løpet av perioden. Dette gjelder ikke bare endringer som gjøres ved å åpne ordren, gjøre endringer og deretter lagre den. Dette gjelder også endringer i for eksempel trafikkledelsen og appene: Hvis en sjåfør endrer status fra Lastet til Losset i appen Opter Driver, vil statistikken vise at ordren er endret. Hvis du endrer status i trafikkledelsen eller kobler til samlasting, vil statistikken vise at ordren er endret. I parameterne dateFrom og dateTo kan det være aktuelt å angi både dato og klokkeslett. Se Eksempel nedenfor. For en ordre som har blitt endret i løpet av perioden, vises dato og klokkeslett for når ordren sist ble endret (i løpet av perioden). Du kan se mer informasjon om endringer i ordrene ved å se på loggene i ruten Hendelseslogg i ordremottaket i Opter.

Begrensninger

• Det er ingen historikk å følge på ordren. Når du kaller på API-et, får du dataene tilbake slik de er i Opter på det aktuelle tidspunktet.

  Det er imidlertid mulig å hente ut statistikk over hvilke ordrer som har blitt endret i løpet av en bestemt periode, se ChangeDate ovenfor. Statistikken viser ikke hva som er endret, bare dato og klokkeslett for når ordren sist ble endret.

  Du kan se mer informasjon om endringer i ordrene ved å se på loggene i ruten Hendelseslogg i ordremottaket i Opter.

• Opter stiller statistikk-API til rådighet, men du er selv ansvarlig for hvordan resultatene/svarene fra API-kallene håndteres og analyseres. Opter tilbyr ikke verktøy for dette.

Eksempel

Statistikk over hvilke ordrer som har blitt endret

Hvis du ønsker å hente data om følgende:

• Hvilke ordrer som har endret seg i løpet av en bestemt datoperiode, for eksempel i løpet av desember måned 2024. Angi datoperioden i parameterne dateFrom «2024-12-01» og dateTo «2025-01-01». (Hvis du bare angir datoen, brukes standardtiden 00:00.)

• Hvilke ordrer som har endret seg siden en bestemt dato, til og med i dag, for eksempel, fra og med «2024-07-22» til dagens dato og gjeldende klokkeslett. Angi datoen i parameteren dateFrom «2024-07-22», og dato og klokkeslett i parameteren dateTo «2024-07-26 13:30» (dagens dato og gjeldende klokkeslett).

  Hvis du ikke angir et klokkeslett, brukes standardtiden 00:00. Det betyr at hvis du bare angir (dagens) dato i dateTo, vil du ikke se hvilke ordrer som har blitt endret i dag.

• Hvilke ordrer som har blitt endret i løpet av de siste 10 minuttene.

  Hvis klokken for eksempel er 10:20 og datoen er 2024-07-26, skriver du inn dagens dato og klokkeslettet som var for 10 minutter siden i parameteren dateFrom «2024-07-26 10:10», og dagens dato og det nåværende klokkeslettet i parameteren dateTo «2024-07-26 10:20».

Velg "ChangeDate" fra rullegardinlisten dateType. (Mer informasjon er tilgjengelig i tabellen over, se ChangeDate.)

Velg «true» i rullegardinmenyen includeDeliveries.

Feilsøking

• Hvis du ikke finner statistikk-API i swagger-dokumentasjonen, må du kontrollere at du har valgt «Opter API v1» i rullegardinmenyen øverst til høyre på nettsiden i rullegardinmenyen Select a definition. Se bildet ovenfor.

• Hvis API-nøkkelen ikke fungerer, kan du opprette en ny i vinduet API-tilgang på fanen Standard ved feltet API-nøkkel. Opprett en ny API-nøkkel ved å klikke på Ny nøkkel og deretter på for å lagre den. Deretter kan du bruke den til å få tilgang til statistikk-API.

• Hvis du har spørsmål eller trenger hjelp med feilsøking, kan du kontakte EDI-teamet på .

---