Integrationer, det öppna API:et och åtkomst till webbtjänsten

För vissa förbund skickas det som sekretariatet registrerar under en match också live vidare till en extern partner för livegrafik, resultattavla och streaming: matchuppsättningen när liverapporten förbereds, när klockan startas och pausas, och varje mål, kort och timeout i takt med att det registreras.

Detta slås på av Profixio per förbund och per idrott i konfigurationen och körs i bakgrunden utan att något syns i gränssnittet. Det används för svensk basket, svensk handboll inklusive beachhandboll, och norsk fotboll. Streaminglänkar från partnern läses tillbaka och kopplas till matchen, med varje förbunds egen varumärkta spelardomän.

Rätta en match: nya händelser skickas vidare, men att ta bort eller ändra en händelse i efterhand gör det inte. Har ett fel redan gått ut, be Profixio support att få det rättat hos mottagaren.

För en integration du bygger själv har streamingdelen två delar på API-nyckeln:

• En streamingbehörighet, som lägger till fält i match-endpoints som visar om en match får streamas och om en stream pågår just nu, och som lägger till varje spelares publiceringsspärr i truppen, så att namn och bilder på personer som har spärrat sig inte visas i bild.
• En callback-adress, registrerad på nyckeln, som Profixio anropar när streamingläget för en match ändras, så att en partner inte behöver fråga regelbundet.

Båda ställs in av Profixio när nyckeln skapas. Hur streaming slås på för en match, och hur en spelare eller ett lag avböjer, beskrivs i Liveresultat, liveflöden och streaming.

Svensk basket utbyter tävlingsdata med Genius Sports, plattformen bakom förbundets publika statistik och sändningsdata. Det är en integration på förbundsnivå som drivs av Profixio och förbundet, inte något som en förening eller en turneringsadministratör slår på.

Vad som överförs. Profixio skickar tävlingsstrukturen, lag, matcher, grupper och tabeller till Genius, och hämtar tillbaka resultat för matcher som har spelats men ännu saknar resultat. En serie måste kopplas till sin motsvarighet hos Genius innan något utbyts; därefter håller den sig i takt av sig själv.

Vad användarna ser. På ett lags sida visas länkarna Öppna lagstatistik och Öppna spelarstatistik när lagets tävling är synkad och laget har kopplats till sin motsvarighet. De öppnar den detaljerade statistiken hos leverantören. I appen får samma lag extra statistikflikar. Saknas länkarna är laget inte kopplat – fråga förbundets personal som sköter Genius-integrationen.

Vem som driver det. Det finns en operatörspanel för förbundspersonal som har behörigheten Genius-administratör. I panelen kopplas säsongens serier, en synk startas eller tvingas igenom, tabeller och grupper skickas över, och synk stängs av för en serie.

Varför allt inte sker direkt. En ändring du gör nu skickas normalt över inom några minuter, inte omedelbart.

Den inbäddade sidan med livestatistik som visas för enskilda matcher beskrivs i Liveresultat, liveflöden och streaming.

För norska förbund kommunicerar Profixio direkt med Norges idrottsförbunds centrala system. Det körs schemalagt i bakgrunden; det finns ingen knapp att trycka på.

Det här omfattas:

• Inloggning med nationell idrotts-id. Användare kan logga in i Profixio med sitt norska idrotts-id i stället för ett separat Profixio-lösenord, och då följer även namn, födelsedatum och kontaktuppgifter med.
• Föreningar och distrikt. Förenings- och distriktslistor importeras från det nationella registret, inklusive föreningslogotyper där sådana finns. Norsk rugby har en föreningsimport som körs en gång per dygn under natten; norsk fotboll har ett förenings- och tävlingsflöde som körs en gång per dygn på morgonen.
• Licenskontroll. Om en person har giltig licens kan kontrolleras mot det nationella registret i stället för att registreras två gånger.
• Publiceringsspärrar. Personer som har registrerat en spärr mot att visas flaggas, och flaggorna används för att hålla dem borta från streaming och grafik. De tas bort igen utanför det tidsfönster där de behövs.

Eftersom föreningarna kommer från det nationella registret kräver vissa förenings- och lagfunktioner att föreningen är kopplad till sin post i registret. ”Föreningen saknar id i det nationella registret” är ett dataproblem i registret eller i kopplingen, inte ett behörighetsproblem i Profixio – kontakta Profixio support och ange föreningens namn.

Motsvarigheten för svenska förbund är ett annat flöde med andra regler och beskrivs i Synkronisering av svenska medlemsdata.

API-åtkomst är inget du kan slå på själv. Det finns ingen sida i Profixio där du skapar en nyckel – API-dokumentationen säger det rakt ut: ”Contact Profixio to get an API token”.

Så fungerar det i praktiken:

1. Du kontaktar Profixio och beskriver vad integrationen ska läsa eller skriva.
2. Profixio skapar en applikationsnyckel åt dig och ställer in behörighetsnivån.
3. Du skickar nyckeln med varje anrop. Samma nyckel fungerar både för REST-API:et och för den äldre SOAP-webbtjänsten.

Eftersom varje extra behörighet ges uttryckligen är den vanliga orsaken till ”API:et returnerar ingenting / säger att jag inte har behörighet” att nyckeln är rätt men att just den behörigheten aldrig lades till. Be Profixio utöka nyckeln i stället för att prova en annan endpoint.

När du ber om en nyckel sparar du en vända genom att ange: vilken organisation och idrott, vilka turneringar eller säsonger, enbart läsning eller även skrivning av resultat, om du behöver fakturor eller betalningar, om integrationen är för ett testsystem eller produktion, och vem som är teknisk kontaktperson.

Vad en nyckel är kopplad till. En nyckel tillhör en organisation – ett förbund eller ett distrikt inom det. En nyckel som utfärdats till ett förbund kan inte läsa ett annat förbunds data, och ber du om en turnering som hör till någon annan får du ett felmeddelande i stället för en tom lista. Inom organisationen begränsas åtkomsten ytterligare:

• Nycklar på distriktsnivå kan begränsas till ett enda distrikt. Det används för fakturaåtkomst på distriktsnivå.
• Turneringsåtkomst ställs in per nyckel: ingen turneringsåtkomst alls, enbart läsning, läsning och skrivning, eller läsning och skrivning i alla turneringar i organisationen. Enskilda turneringar kan också ges en och en, var och en med läsrätt eller läs- och skrivrätt.
• Extra behörigheter ges separat och är avstängda som standard: fakturor, betalningar, hela spelarlistan för en organisation, personnummer, domarexport för divisioner där domare inte visas offentligt, samt streamingdata.

Den fullständiga, genererade referensen för REST-API:et finns på profixio.com/app/docs. Den är öppen – dina utvecklare behöver ingen Profixio-inloggning för att läsa den, bara en nyckel för att faktiskt anropa API:et.

Sidan innehåller:

• alla endpoints, med parametrar, exempelanrop och exempelsvar,
• en ändringslogg överst som visar vad som har lagts till eller ändrats och när, flera år tillbaka,
• en översikt över vilka REST-endpoints som ersätter de gamla SOAP-operationerna, för integrationer som flyttas över,
• en Postman-samling och en OpenAPI-specifikation att ladda ner, på samma adress med .postman och .openapi på slutet.

Några konventioner som gäller överallt och är lätta att missa:

• Autentisering sker med en header, X-Api-Secret, som innehåller din applikationsnyckel. Det finns inget användarnamn och lösenord och inget inloggningsanrop.
• De flesta listor är paginerade. page och limit är valfria frågeparametrar; standardstorleken per sida är 15 och maxvärdet 500. Svaren har blocken meta och links med pagineringsläget.
• Det finns inget versionsnummer i adressen. API:et byggs bara ut – nya fält tillkommer, befintliga tas inte bort utan förvarning – så skriv klienter som ignorerar fält de inte känner igen.

Knapparna ”Try it out” i dokumentationen körs mot de dokumenterade exempeldata, inte mot organisationens riktiga uppgifter.

REST-API:et är uppbyggt kring tre saker: en organisation (ett förbund eller ett distrikt), en säsong och en turnering (som i Profixio också är hur en serie lagras). Allt annat hänger på någon av dem.

Två saker som är bra att veta innan du bygger mot API:et:

• Trupperna öppnas strax före planerad matchstart, inte tidigare. Hur långt innan bestäms per förbund – en timme är normalinställningen, och svensk handboll använder 45 minuter. Varje match anger från vilken tid dess trupp blir tillgänglig, så läs det i stället för att räkna med ett fast värde.
• Personnummer ingår inte i spelarlistorna om inte just den behörigheten har lagts till på nyckeln för den organisationen. Domarexporten innehåller domarnas personnummer.

Varje applikationsnyckel får göra 120 anrop per minut. Anrop utöver det besvaras med 429 Too Many Requests i stället för data.

Varje svar talar om var du ligger:

• X-RateLimit-Limit – taket för den aktuella minuten,
• X-RateLimit-Remaining – hur mycket som återstår,
• Retry-After – hur många sekunder du ska vänta, skickas med en 429.

Läs de headerna i stället för att hårdkoda 120: gränsen kan justeras.

Praktiska råd för att hålla dig gott och väl inom gränsen:

• Hämta säsongens eller turneringens matchlista med ett rimligt intervall i stället för att fråga efter matcherna en och en. Ett listanrop med högt limit kostar lika mycket som ett anrop efter en enda match.
• Under livespel bör du hämta turneringens matchlista i stället för att loopa över varje match.
• Betalningar och fakturor stöder en ändringsmarkör, så en synkronisering kan be om ”allt efter den senaste jag såg” i stället för att läsa om hela historiken.
• Cacha det som sällan ändras – föreningar, spelplatser, klasser, säsongsträdet.

Om en legitim integration verkligen inte ryms inom gränsen, prata med Profixio innan du bygger omförsök som hamrar på API:et. Ihållande 429-svar från en nyckel syns och följs upp.

Före REST-API:et fanns en SOAP-webbtjänst, och den är fortfarande i drift. Befintliga integrationer fortsätter att fungera; inget datum för nedstängning har aviserats i produkten.

Den är dock utfasad. Tjänstens egen startsida har ett meddelande om att API:et är utfasat och hänvisar till REST-dokumentationen, och REST-dokumentationen har en lista över vilken SOAP-operation varje ny endpoint ersätter.

Det här erbjuder den, ungefär grupperat som tjänsten själv grupperar det:

• Turneringstjänster – sökning efter turneringar, turneringsuppgifter, klasser, lag, anmälningar, föreningar, domare, matchuppgifter, kommande och spelade matcher, tabeller och registrering av matchresultat.
• Förbundstjänster – föreningar, spelare, regioner och domare för ett förbund, säsonger, tävlingar för en förening, lagkontakter för en säsong, licensnycklar för föreningar.
• Gruppaktivitet / gruppträning – aktiviteter, pass, aktivitetstyper och en aktivitetskalender för ett förbund.

Åtkomst. Samma applikationsnyckel som Profixio utfärdar för REST-API:et används här; du behöver ingen nyckel till. Tjänsten beskriver tre nivåer: enbart läsning med bara applikationsnyckeln, läsning och skrivning som dessutom kräver användarnamn och lösenord, och en nivå för turneringsägare som kräver turneringens egen nyckel. Profixio ställer in nivån när nyckeln skapas.

Bygger du något nytt, använd REST-API:et i stället. Det är snabbare, bättre dokumenterat, har en publicerad ändringslogg och är där nya fält läggs till. Förvaltar du en gammal SOAP-integration är migreringslistan i REST-dokumentationen den kortaste vägen över.

Du kan prenumerera på matcher som ett vanligt kalenderflöde, och ofta är det allt en förening eller en domare egentligen behöver – ingen nyckel och inget utvecklingsarbete.

Det finns tre flöden: ett lags matcher, dina egna matcher i alla lag och en domares egna uppdrag. Adressen får du från knappen Lägg till i Google Kalender, Outlook eller iCal på den aktuella sidan, som erbjuder Google, Apple och Microsoft Outlook samt kopiering till urklipp.

Steg-för-steg-instruktionerna för att lägga till ett flöde i en personlig kalender finns i Liveresultat, liveflöden och streaming.

För dig som kopplar ett flöde till ett annat system i stället för till en personlig kalender:

• Det är en vanlig iCalendar-prenumeration, inte en engångsexport. Flyttade matcher och ändrade spelplatser fångas upp när det mottagande systemet själv uppdaterar, och för Google och Outlook sker det oftast med flera timmars mellanrum – det styr inte Profixio över.
• Varje post har de två lagnamnen som rubrik, start- och sluttid, turneringen och planen i beskrivningen, en länk tillbaka till matchsidan och kartkoordinater där planen eller spelplatsen har sådana.
• Ett flöde innehåller matcher från ungefär ett år tillbaka plus allt som är inplanerat framåt, högst 500 poster, och bara matcher som är synliga och har en tid satt.
• Kopiera adressen bara till den kalender eller det system som ska visa matcherna.
• En domaradministratörs version av domarflödet kan begränsas till de organisationer hen administrerar.

Profixio kopplar inte direkt mot ett bokföringsprogram. Det finns ingen inbyggd integration mot något namngivet bokföringssystem och inget att godkänna eller installera. Det som finns är två vägar ut:

1. Hämta via API:et. En bokföringsintegration läser fakturor och betalningar via REST-API:et, med en behörighet på nyckeln för vardera:

• Turneringsfakturor, med rader och faktura-PDF.
• Slutförda betalningar per lag, med belopp, betalsätt, om det är en återbetalning, notering, fakturareferens, betalningsreferens och kund, plus fakturaraderna bakom. Betalningar stöder en markör, så att ett nattligt jobb bara behöver be om det som är nytt, och ett datumfilter, så att en bokföringsperiod kan stängas på ett rent sätt.
• Fakturor för föreningslicenser för ett förbund, inklusive statusuppdatering i bulk när de har stämts av på bokföringssidan.

Antal och belopp på fakturorna speglar det som ursprungligen beställdes, så kreditfakturor som exporteras som separata dokument inte drar av samma antal två gånger.

2. Mejla dokumentet. För domarersättningar kan ett förbund registrera en adress till sitt ekonomisystem, och en ekonomigranskare kan skicka en godkänd domarfaktura dit som PDF med knappen Send to Economy System. Adressen ställs in under Integration Settings - External Economy System i inställningarna för domarersättningar, i fältet Economy System Email. Profixio registrerar att fakturan har skickats.

Bankfiler och avstämning av inbetalningar är ett eget ämne; se Läsa bankfiler och matcha betalningar.

Profixio kan göra en enskild turnering, eller en återkommande cup över flera upplagor, tillgänglig för en AI-assistent, så att besökare kan ställa frågor med vanliga ord och få svar från aktuella turneringsdata. Det är ett pilotprojekt och sätts upp tillsammans med Profixio, inte från en inställningssida.

Det här kan assistenten slå upp:

• Turneringsinformation – period, klasser, avgifter, om anmälan är öppen och till när, och hur många lag som är anmälda.
• Lag, inklusive att koppla ett namn eller en förkortning till rätt lag och länka till lagets sida.
• Spelprogrammet, resultat, namn på spelomgångar och utslagsförlopp, med länkar till matchsidorna.
• Publicerade nyhetsartiklar och sidor från turneringens egen webbplats.

Det här når den medvetet inte: trupper, spelare och personuppgifter. Endpoints är skrivskyddade – assistenten kan inte ändra något i Profixio.

En återkommande cup får en permanent adress som alltid pekar på den aktuella upplagan, även efter namnbyten och sponsorbyten, med möjlighet att fråga om ett tidigare år. Innan spelprogrammet är publicerat kan assistenten ändå svara med de anmälda lagen i stället för ingenting alls.

Där ett förbund också använder ett separat domar- och tävlingssystem är Profixio inte det enda system som skriver till den underliggande databasen: det systemet körs parallellt på samma data. Därför är några värden i Profixio markerade som ägda av det andra systemet och får inte ändras. Tydligast är den interna nivånumreringen på domarroller, som har en uttrycklig varning om att den aldrig får ändras.

Vad det innebär i praktiken:

• En ändring som görs i det andra systemet kan dyka upp i Profixio utan att någon har gjort något i Profixio, och tvärtom.
• Om ett värde ser fel ut och är markerat som tillhörande det andra systemet, rätta det inte i Profixio – ta upp det med Profixio support, som tar reda på vilket system som äger det.

Vilka förbund som är uppsatta så går inte att gissa sig till från en vy; fråga Profixio support om du behöver veta om det gäller er.

Inget i den här listan kan ändras av en förbunds- eller turneringsadministratör från en inställningssida – allt ordnas med Profixio.

Gå igenom den här listan innan du rapporterar ett fel.

Alla anrop misslyckas med 401. Nyckeln saknas, är felstavad, skickas i fel header eller har inaktiverats. Headern är X-Api-Secret. Det finns inget inloggningsanrop och ingen bearer-token.

Vissa anrop fungerar, ett nekas. Endpointen kräver en behörighet som nyckeln inte har – fakturor, betalningar, alla spelare, personnummer, domarexport och streaming ges var för sig. Be Profixio utöka nyckeln.

En turnering du väntar dig saknas eller ger fel. Turneringen tillhör en annan organisation, eller så har nyckeln varken en åtkomstnivå som täcker den eller en enskild åtkomst till den.

Listan är tom men uppgifterna finns på webbplatsen. Matcherna är dolda var för sig, eller så är deras klass opublicerad eller stängd. Tabeller kräver dessutom att klassens tabell och resultat inte är dolda, och spelarstatistik kräver att statistik är påslagen för klassen. Se Dölja matcher, spelprogram och resultat för allmänheten.

Domarnamn saknas. Divisionen visar inte domare offentligt. En nyckel kan få behörigheten för domarexport om förbundet vill att dess egna system ska få dem.

Trupperna kommer tillbaka tomma. Trupperna öppnas först strax före planerad matchstart – en timme innan i de flesta förbund, 45 minuter i svensk handboll. Varje match anger från vilken tid dess trupp är tillgänglig.

Bara de 15 första posterna kommer. Det är standardstorleken per sida. Använd limit, upp till 500, och följ pagineringslänkarna.

429 Too Many Requests. Du ligger över 120 anrop per minut för den nyckeln. Läs Retry-After och sakta ner; hämta listor i stället för att loopa över enskilda poster.

Ett resultat som skrivits via API:et syns inte. Kontrollera svaret i stället för skärmen – en skrivning som inte klarar valideringen nekas, den kastas inte tyst. Skrivning kräver också en nyckel med skrivrätt till just den turneringen.