Integrasjoner, det åpne API-et og tilgang til webtjenesten

Svensk basketball utveksler konkurransedata med Genius Sports, plattformen bak forbundets offentlige statistikk og kringkastingsdata. Dette er en integrasjon på forbundsnivå som driftes av Profixio og forbundet, ikke noe en klubb eller en turneringsadministrator slår på.

Hva som overføres. Profixio sender konkurransestrukturen, lag, kamper, grupper og tabeller til Genius, og henter tilbake resultater for kamper som er spilt, men som ikke har resultat ennå. En serie må kobles til sin motpart hos Genius før noe utveksles; deretter holder den seg oppdatert av seg selv.

Hva brukerne ser. På siden til et lag vises lenkene Open Team Statistics og Open Player Statistics når lagets konkurranse er synkronisert og laget er koblet til sin motpart. De åpner den detaljerte statistikken hos leverandøren. I appen får det samme laget ekstra statistikkfaner. Mangler lenkene, er laget ikke koblet – spør forbundets ansatte som drifter Genius-integrasjonen.

Hvem som drifter det. Det finnes et operatørpanel for forbundsansatte som har rettigheten som Genius-administrator. I panelet kobles sesongens serier, en synkronisering startes eller tvinges, tabeller og puljer sendes over, og synkronisering slås av for en serie.

Hvorfor ikke alt skjer umiddelbart. En endring du gjør nå, sendes normalt over i løpet av noen minutter, ikke umiddelbart.

Den innebygde livestatistikksiden som vises for enkeltkamper, er beskrevet i Liveresultater, livefeeder og strømming.

API-tilgang er ikke noe du kan slå på selv. Det finnes ingen side i Profixio der du oppretter en nøkkel – API-dokumentasjonen sier det rett ut: «Contact Profixio to get an API token».

Slik fungerer det i praksis:

1. Du kontakter Profixio og beskriver hva integrasjonen skal lese eller skrive.
2. Profixio oppretter en applikasjonsnøkkel til deg og setter tilgangsnivået.
3. Du sender nøkkelen med hver forespørsel. Den samme nøkkelen virker både for REST-API-et og for den eldre SOAP-webtjenesten.

Siden hver ekstra rettighet gis eksplisitt, er den vanlige årsaken til «API-et returnerer ingenting / sier at jeg ikke har tilgang» at nøkkelen er riktig, men at akkurat den rettigheten aldri ble lagt til. Be Profixio utvide nøkkelen i stedet for å prøve et annet endepunkt.

Når du ber om en nøkkel, sparer du en runde ved å oppgi: hvilken organisasjon og idrett, hvilke turneringer eller sesonger, bare lesing eller også skriving av resultater, om du trenger fakturaer eller betalinger, om integrasjonen er for et testsystem eller produksjon, og hvem som er teknisk kontaktperson.

Hva en nøkkel er knyttet til. Én nøkkel tilhører én organisasjon – et forbund, eller en krets i forbundet. En nøkkel utstedt til ett forbund kan ikke lese et annet forbunds data, og ber du om en turnering som hører til et annet sted, får du en feilmelding i stedet for en tom liste. Innenfor organisasjonen avgrenses tilgangen ytterligere:

• Nøkler på kretsnivå kan begrenses til én krets. Det brukes for fakturatilgang på kretsnivå.
• Turneringstilgang settes per nøkkel: ingen turneringstilgang, bare lesing, lesing og skriving, eller lesing og skriving i alle turneringer i organisasjonen. Enkeltturneringer kan også gis én og én, hver med lesetilgang eller lese- og skrivetilgang.
• Ekstra rettigheter gis separat og er av som standard: fakturaer, betalinger, hele spillerlisten for en organisasjon, fødselsnumre, dommereksport for divisjoner der dommere ikke vises offentlig, og strømmedata.

Den fullstendige, genererte referansen for REST-API-et ligger på profixio.com/app/docs. Den er åpen – utviklerne dine trenger ingen Profixio-innlogging for å lese den, bare en nøkkel for å faktisk kalle API-et.

Siden inneholder:

• alle endepunkter, med parametere, eksempelforespørsler og eksempelsvar,
• en endringslogg øverst som viser hva som er lagt til eller endret og når, flere år tilbake,
• en oversikt over hvilke REST-endepunkter som erstatter de gamle SOAP-operasjonene, for integrasjoner som flyttes over,
• en Postman-samling og en OpenAPI-spesifikasjon til nedlasting, på samme adresse med .postman og .openapi på slutten.

Noen konvensjoner som gjelder overalt og er lette å overse:

• Autentisering skjer med en header, X-Api-Secret, som inneholder applikasjonsnøkkelen din. Det er ikke brukernavn og passord, og det finnes ikke noe innloggingskall.
• De fleste lister er paginert. page og limit er valgfrie spørreparametere; standard sidestørrelse er 15 og maksimum er 500. Svarene har blokkene meta og links med pagineringsstatus.
• Det er ikke noe versjonsnummer i adressen. API-et utvides bare med nye ting – nye felt dukker opp, eksisterende felt fjernes ikke uten varsel – så lag klienter som ignorerer felt de ikke kjenner igjen.

«Try it out»-knappene i dokumentasjonen kjører mot de dokumenterte eksempeldataene, ikke mot organisasjonens faktiske data.

REST-API-et er bygd rundt tre ting: en organisasjon (et forbund eller en krets), en sesong og en turnering (som i Profixio også er måten en serie lagres på). Alt annet henger på en av disse.

To ting som er greit å vite før du designer mot API-et:

• Troppene åpnes kort tid før planlagt kampstart, ikke tidligere. Hvor lenge før bestemmes per forbund – én time er normalinnstillingen, og svensk håndball bruker 45 minutter. Hver kamp har tidspunktet troppen blir tilgjengelig fra, så les det i stedet for å anta et fast tall.
• Fødselsnumre er ikke med i spillerlistene med mindre akkurat den rettigheten er lagt til nøkkelen for den organisasjonen. Dommereksporten inneholder dommernes fødselsnumre.

Hver applikasjonsnøkkel kan sende 120 forespørsler per minutt. Forespørsler utover det får svaret 429 Too Many Requests i stedet for data.

Hvert svar forteller deg hvor du står:

• X-RateLimit-Limit – taket for inneværende minutt,
• X-RateLimit-Remaining – hvor mye som er igjen,
• Retry-After – hvor mange sekunder du må vente, sendes med en 429.

Les disse headerne i stedet for å hardkode 120: grensen kan justeres.

Praktiske råd for å holde deg godt innenfor:

• Hent kamplisten for sesongen eller turneringen med et fornuftig intervall i stedet for å spørre etter kampene én og én. Én listeforespørsel med høy limit koster det samme som én forespørsel etter en enkelt kamp.
• Under livespill bør du hente turneringens kampliste i stedet for å gå gjennom hver enkelt kamp.
• Betalinger og fakturaer støtter en endringsmarkør, så en synkronisering kan be om «alt etter den siste jeg så» i stedet for å lese hele historikken på nytt.
• Mellomlagre det som sjelden endres – klubber, spillesteder, klasser, sesongtreet.

Hvis en legitim integrasjon virkelig ikke får plass innenfor grensen, snakk med Profixio før du bygger nye forsøk som hamrer løs på API-et. Vedvarende 429-svar fra én nøkkel blir lagt merke til og fulgt opp.

Før REST-API-et fantes det en SOAP-webtjeneste, og den kjører fortsatt. Eksisterende integrasjoner virker som før; det er ikke annonsert noen nedstengingsdato i produktet.

Den er likevel utgått. Forsiden til tjenesten har en melding om at API-et er utgått og viser til REST-dokumentasjonen, og REST-dokumentasjonen har en liste over hvilken SOAP-operasjon hvert nytt endepunkt erstatter.

Dette tilbyr den, grovt gruppert slik tjenesten selv grupperer det:

• Turneringstjenester – søk etter turneringer, turneringsdetaljer, klasser, lag, påmeldinger, klubber, dommere, kampdetaljer, kommende og spilte kamper, tabeller og registrering av kampresultat.
• Forbundstjenester – klubber, spillere, regioner og dommere for et forbund, sesonger, konkurranser for en klubb, lagkontakter for en sesong, lisensnøkler for klubber.
• Gruppeaktivitet / gruppetrening – aktiviteter, økter, aktivitetstyper og en aktivitetskalender for et forbund.

Tilgang. Den samme applikasjonsnøkkelen som Profixio utsteder for REST-API-et, brukes her også; du trenger ikke en nøkkel til. Tjenesten beskriver tre nivåer: bare lesing med applikasjonsnøkkelen alene, lesing og skriving som i tillegg krever brukernavn og passord, og et nivå for turneringseier som krever turneringens egen nøkkel. Profixio setter nivået når nøkkelen opprettes.

Bygger du noe nytt, bruk REST-API-et i stedet. Det er raskere, bedre dokumentert, har en publisert endringslogg og er der nye felt legges til. Vedlikeholder du en gammel SOAP-integrasjon, er overgangslisten i REST-dokumentasjonen den korteste veien over.

Du kan abonnere på kamper som en vanlig kalenderfeed, og ofte er det alt en klubb eller en dommer egentlig trenger – ingen nøkkel og ingen utviklingsarbeid.

Det finnes tre feeder: kampene til et lag, dine egne kamper på tvers av lag og en dommers egne oppdrag. Du får adressen fra knappen Legg dette til i Google Kalender, Outlook eller iCal på den aktuelle siden, som tilbyr Google, Apple og Microsoft Outlook i tillegg til kopiering til utklippstavlen.

Trinn-for-trinn-veiledningen for å legge en feed til i en personlig kalender finner du i Liveresultater, livefeeder og strømming.

For deg som kobler en feed inn i et annet system i stedet for i en personlig kalender:

• Det er et vanlig iCalendar-abonnement, ikke en engangseksport. Flyttede kamper og endrede spillesteder fanges opp når mottakersystemet selv oppdaterer, og for Google og Outlook er det typisk med flere timers mellomrom – det styrer ikke Profixio.
• Hver oppføring har de to lagnavnene som tittel, start- og sluttid, turneringen og banen i beskrivelsen, en lenke tilbake til kampsiden og kartkoordinater der banen eller spillestedet har det.
• En feed inneholder kamper fra omtrent ett år tilbake pluss alt som er satt opp framover, med et tak på 500 oppføringer, og bare kamper som er synlige og har et tidspunkt.
• Kopier adressen bare inn i kalenderen eller systemet som skal vise kampene.
• En dommeradministrators versjon av dommerfeeden kan begrenses til organisasjonene vedkommende administrerer.

For noen forbund sendes det sekretariatet registrerer under en kamp, også live videre til en ekstern partner for livegrafikk, resultattavle og strømming: kampoppsettet når liverapporten klargjøres, når klokken starter og stoppes, og hvert mål, kort og timeout etter hvert som det registreres.

Dette slås på av Profixio per forbund og per idrett i konfigurasjonen og kjører i bakgrunnen uten at noe vises i grensesnittet. Det er i bruk for svensk basketball, svensk håndball inkludert sandhåndball, og norsk fotball. Strømmelenker fra partneren leses tilbake og knyttes til kampen, med hvert forbunds eget merkede spillerdomene.

Rette en kamp: nye hendelser sendes videre, men sletting eller endring av en hendelse i etterkant gjør ikke det. Har en feil allerede gått ut, be Profixio support om å få den rettet hos mottakeren.

For en integrasjon du bygger selv har strømmedelen to elementer på API-nøkkelen:

• En strømmerettighet, som legger felt til kampendepunktene som forteller om en kamp kan strømmes og om en strøm pågår, og som legger hver spillers reservasjon mot visning til i troppen, slik at navn og bilder av personer som har reservert seg, ikke vises på skjermen.
• En callback-adresse, registrert på nøkkelen, som Profixio kaller når strømmestatusen til en kamp endres, slik at en partner ikke trenger å spørre jevnlig.

Begge settes opp av Profixio når nøkkelen opprettes. Hvordan strømming slås på for en kamp, og hvordan en spiller eller et lag reserverer seg, er beskrevet i Liveresultater, livefeeder og strømming.

For norske forbund snakker Profixio direkte med de sentrale systemene til Norges idrettsforbund. Dette kjører etter en tidsplan i bakgrunnen; det er ingen knapp å trykke på.

Dette omfatter det:

• Innlogging med nasjonal idretts-ID. Brukere kan logge inn i Profixio med Idrettens ID i stedet for et eget Profixio-passord, og da følger også navn, fødselsdato og kontaktinformasjon med.
• Klubber og kretser. Klubb- og kretslister importeres fra det nasjonale registeret, inkludert klubblogoer der de finnes. Norsk rugby har en klubbimport som kjører én gang i døgnet om natten; norsk fotball har en klubb- og konkurransefeed som kjører én gang i døgnet om morgenen.
• Lisenskontroll. Om en person har gyldig lisens, kan sjekkes mot det nasjonale registeret i stedet for å registreres to ganger.
• Reservasjoner mot visning. Personer som har registrert en reservasjon mot å bli vist, blir flagget, og flaggene brukes til å holde dem unna strømming og grafikk. De fjernes igjen utenfor tidsrommet der de trengs.

Siden klubbene kommer fra det nasjonale registeret, krever enkelte klubb- og lagfunksjoner at klubben er koblet til sin oppføring i registeret. «Klubben mangler id i det nasjonale registeret» er et dataproblem i registeret eller i koblingen, ikke et tilgangsproblem i Profixio – kontakt Profixio support og oppgi klubbnavnet.

Tilsvarende løsning for svenske forbund er en annen prosess med andre regler og er beskrevet i Synkronisering av svenske medlemsdata.

Profixio kobler seg ikke direkte til et regnskapsprogram. Det finnes ingen innebygd integrasjon mot et bestemt regnskapssystem, og ingenting å autorisere eller installere. Det som finnes, er to veier ut:

1. Hent det via API-et. En regnskapsintegrasjon leser fakturaer og betalinger via REST-API-et, med en egen rettighet på nøkkelen for hver av dem:

• Turneringsfakturaer, med linjer og faktura-PDF.
• Fullførte betalinger per lag, med beløp, betalingsmåte, om det er en tilbakebetaling, merknad, fakturareferanse, betalingsreferanse og kunde, pluss fakturalinjene bak. Betalinger støtter en markør, slik at en nattlig jobb bare trenger å be om det som er nytt, og et datofilter, slik at en regnskapsperiode kan lukkes ryddig.
• Fakturaer for klubblisenser for et forbund, inkludert statusoppdatering i bulk når de er avstemt på regnskapssiden.

Antall og beløp på fakturaene gjenspeiler det som opprinnelig ble bestilt, slik at kreditnotaer som eksporteres som egne dokumenter, ikke trekker fra det samme antallet to ganger.

2. Send dokumentet på e-post. For dommerregninger kan et forbund registrere en adresse til økonomisystemet sitt, og en økonomigodkjenner kan sende en godkjent dommerfaktura dit som PDF med knappen Send to Economy System. Adressen settes under Integration Settings - External Economy System i innstillingene for dommerregninger, i feltet Economy System Email. Profixio registrerer at fakturaen er sendt.

Bankfiler og avstemming av innbetalinger er et eget tema; se Lese bankfiler og avstemme betalinger.

Profixio kan gjøre én turnering, eller en tilbakevendende cup på tvers av årganger, tilgjengelig for en KI-assistent, slik at besøkende kan stille spørsmål med vanlige ord og få svar fra oppdaterte turneringsdata. Dette er et pilotprosjekt og settes opp sammen med Profixio, ikke slås på fra en innstillingsside.

Dette kan assistenten slå opp:

• Turneringsinformasjon – periode, klasser, avgifter, om påmeldingen er åpen og til når, og hvor mange lag som er påmeldt.
• Lag, inkludert å koble et navn eller en forkortelse til riktig lag og lenke til lagets side.
• Kampprogrammet, resultater, navn på spillrunder og utslagsforløp, med lenker til kampsidene.
• Publiserte nyhetsartikler og sider fra turneringens egen nettside.

Dette når den med vilje ikke: tropper, spillere og personopplysninger. Endepunktene er skrivebeskyttet – assistenten kan ikke endre noe i Profixio.

En tilbakevendende cup får en fast adresse som alltid peker på årets utgave, også etter navnebytter og sponsorendringer, med mulighet for å spørre om et tidligere år. Før kampprogrammet er publisert, kan assistenten likevel svare med de påmeldte lagene i stedet for ingenting.

Der et forbund også bruker et eget dommer- og konkurransesystem, er ikke Profixio det eneste systemet som skriver til den underliggende databasen: det systemet kjører ved siden av, på de samme dataene. Derfor er noen verdier i Profixio merket som eid av det andre systemet og må ikke endres. Det tydeligste eksempelet er den interne nivånummereringen på dommerroller, som har en uttrykkelig advarsel om at den aldri må endres.

Hva dette betyr i praksis:

• En endring gjort i det andre systemet kan dukke opp i Profixio uten at noen har gjort noe i Profixio, og omvendt.
• Hvis en verdi ser feil ut og er merket som tilhørende det andre systemet, ikke rett den i Profixio – ta det opp med Profixio support, som finner ut hvilket system som eier den.

Hvilke forbund som er satt opp slik, er ikke noe du kan gjette ut fra et skjermbilde; spør Profixio support hvis du trenger å vite om det gjelder dere.

Ingenting i denne listen kan endres av en forbunds- eller turneringsadministrator fra en innstillingsside – alt avtales med Profixio.

Gå gjennom denne listen før du melder inn en feil.

Alle kall feiler med 401. Nøkkelen mangler, er feilstavet, sendes i feil header eller er deaktivert. Headeren er X-Api-Secret. Det finnes ikke noe innloggingskall og ingen bearer-token.

Noen kall virker, ett blir avvist. Endepunktet krever en rettighet nøkkelen ikke har – fakturaer, betalinger, alle spillere, fødselsnumre, dommereksport og strømming gis hver for seg. Be Profixio utvide nøkkelen.

En turnering du forventer, mangler eller gir feilmelding. Turneringen tilhører en annen organisasjon, eller nøkkelen har verken et tilgangsnivå som dekker den eller en egen tilgang til den.

Listen er tom, men dataene finnes på nettsiden. Kampene er skjult enkeltvis, eller klassen deres er upublisert eller lukket. Tabeller krever i tillegg at klassens tabell og resultater ikke er skjult, og spillerstatistikk krever at statistikk er slått på for klassen. Se Skjule kamper, kampoppsett og resultater for publikum.

Dommernavn mangler. Divisjonen viser ikke dommere offentlig. En nøkkel kan få rettigheten til dommereksport hvis forbundet vil at egne systemer skal få dem.

Troppene kommer tilbake tomme. Troppene åpnes først kort tid før planlagt kampstart – en time før i de fleste forbund, 45 minutter i svensk håndball. Hver kamp oppgir tidspunktet troppen er tilgjengelig fra.

Bare de 15 første postene kommer. Det er standard sidestørrelse. Bruk limit, opptil 500, og følg pagineringslenkene.

429 Too Many Requests. Du er over 120 forespørsler per minutt for den nøkkelen. Les Retry-After og senk tempoet; hent lister i stedet for å gå gjennom enkeltposter.

Et resultat skrevet via API-et vises ikke. Sjekk svaret i stedet for skjermen – en skriving som ikke består valideringen, blir avvist, ikke stille forkastet. Skriving krever også en nøkkel med skrivetilgang til akkurat den turneringen.