API-referanse

Dette er den komplette API-referansen for Billettsalg-backend. Alle endepunkter betjenes av Azure Functions under /api-prefikset, og autentisering skjer via JWT bearer-tokener med mindre annet er angitt.

API-konvensjoner

Disse konvensjonene gjelder på tvers av alle endepunkter. De gjør det enklere å integrere mot API-et.

Responskonvolutt

Alle endepunkter returnerer en konsekvent JSON-konvolutt — sjekk success først, og les deretter data eller error:

{ "success": true, "data": T }
{ "success": false, "error": "string", "message": "string" }

Organisasjonsavgrensing

De fleste autentiserte endepunkter krever en ?organizationId={organizationId}-queryparameter. Middleware bruker denne til å slå opp innringerens medlemskap og rolle i den aktuelle organisasjonen. Manglende parameter er en vanlig årsak til 400-feil.

Paginering

Listeendepunkter som kan returnere store datamengder støtter queryparameteren limit og returnerer en continuationToken for markørbasert paginering. Send tokenet som ?continuationToken={value} for å hente neste side.

Ratebegrensning

Autentiseringsendepunktene magic-link og verify håndhever ratebegrensning per IP for å hindre misbruk. Ratebegrensning er aktivert i alle miljøer og kan ikke omgås av sikkerhetshensyn.

Myk sletting

Arrangementer, registreringer og brukere støtter myk sletting via et deletedAt-tidsstempel. Mykt slettede poster utelates fra vanlige spørringer, men kan gjenopprettes av en admin.

Autentisering

Metode	Endepunkt	Beskrivelse	Autent.
POST	/api/auth/magic-link	Be om innloggings-e-post	Offentlig
POST	/api/auth/verify	Verifiser magic link-token	Offentlig
POST	/api/auth/verify-code	Verifiser 6-sifret kode fra e-post	Offentlig
GET	/api/auth/me	Hent gjeldende bruker	Påkrevd

Arrangementer

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/events	List alle arrangementer	Påkrevd
GET	/api/events-active	Hent aktivt arrangement	Påkrevd
GET	/api/events-overview	Hent arrangementer med statistikk	Påkrevd
GET	/api/events/{id}	Hent arrangementsdetaljer	Påkrevd
POST	/api/management/events	Opprett arrangement	Admin
PUT	/api/management/events/{id}	Oppdater arrangement	Admin
DELETE	/api/management/events/{id}	Mykt slett arrangement	Admin
PATCH	/api/management/events/{id}/restore	Gjenopprett mykt slettet arrangement	Admin
PUT	/api/management/events/{id}/lock	Slå av eller på salgslås	Admin

enableQuotas-felt

Forespørselskroppen for oppretting og oppdatering av arrangement aksepterer et valgfritt enableQuotas-felt (boolean). Når feltet er true, håndheves tildelingsgrenser når bestillinger opprettes for arrangementet. Standard er false.

Delte arrangementer

Endepunktene for delte arrangementer bruker samme JWT- og ?organizationId={organizationId}-konvensjoner som resten av API-et. Azure Functions-utløseren er konfigurert som anonym, men hver handler utfører autentisering og autorisasjon i applikasjonen. Oppretting og endringer krever også SHARED_EVENTS_ENABLED=true. En konfigurert organisasjonstillatelsesliste kan begrense hvem som kan gjøre endringer.

Rollebetegnelsene nedenfor oppsummerer de effektive tilgangskontrollene. Navngitte rettighetstildelinger kan delegere bestemte oppgaver uten å gi en bredere organisasjonsrolle.

Grunnleggende endepunkter og invitasjoner

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/shared-event-capabilities/create	Sjekk om gjeldende organisasjon kan opprette delte arrangementer	Organisasjonsadmin
POST	/api/shared-events	Opprett et delt arrangement som utkast	Organisasjonsadmin eller superadmin
GET	/api/shared-events	List delte arrangementer for gjeldende organisasjon. scope=all er bare for superadmin	Deltakermedlem eller superadmin
GET	/api/shared-events/{sharedEventId}	Hent visningen innringeren har tilgang til	Deltakermedlem, invitert leser eller superadmin
GET	/api/shared-events/{sharedEventId}/capacity	Les autoritativ kapasitet for delt arrangement	Deltakermedlem eller superadmin
GET	/api/shared-event-invitations/pending	List invitasjoner for organisasjoner innringeren administrerer	Autentisert organisasjonsadmin
POST	/api/shared-event-invitations/pending/accept	Godta en invitasjon i appen	Admin i mottakende organisasjon
GET	/api/shared-event-invitations/preview	Forhåndsvis en lenkeinvitasjon uten å røpe detaljer om ugyldige tokener	Autentisert
POST	/api/shared-event-invitations/accept	Godta en lenkeinvitasjon	Admin i mottakende organisasjon
POST	/api/shared-events/{sharedEventId}/invitation-links	Opprett en invitasjonslenke og forsøk eventuelt e-postlevering	manageParticipants og organisasjonsadmin
GET	/api/shared-events/{sharedEventId}/invitation-links	List invitasjonsmetadata. Tokenhash returneres aldri	manageParticipants
DELETE	/api/shared-events/{sharedEventId}/invitation-links/{linkId}	Tilbakekall en invitasjonslenke	manageParticipants og organisasjonsadmin
POST	/api/shared-events/{sharedEventId}/participants/{orgId}/accept	Godta en deltakerinvitasjon	Admin i målorganisasjonen
POST	/api/shared-events/{sharedEventId}/participants/{orgId}/decline	Avslå en deltakerinvitasjon	Admin i målorganisasjonen
POST	/api/shared-events/{sharedEventId}/participants/{orgId}/leave	Forlat et delt arrangement	Admin i målorganisasjonen

Ugyldige, utløpte, brukte, tilbakekalte eller utilgjengelige invitasjoner returnerer generiske ikke-funnet-svar slik at innringere ikke kan undersøke invitasjonsstatus.

Administrasjon for arrangør og deltakere

Metode	Endepunkt	Beskrivelse	Autent.
PATCH	/api/shared-events/{sharedEventId}	Rediger felles detaljer eller priser	Organisasjonsadmin med manageSharedDetails eller managePricing
PATCH	/api/shared-events/{sharedEventId}/capacity	Rediger felleskapasitet	Superadmin
DELETE	/api/shared-events/{sharedEventId}	Avslutt et utkast på en sikker måte	Superadmin
POST	/api/shared-events/{sharedEventId}/participants	Legg en organisasjon direkte til deltakerlisten	Superadmin
DELETE	/api/shared-events/{sharedEventId}/participants/{orgId}	Fjern en deltaker	Organisasjonsadmin med manageParticipants
PATCH	/api/shared-events/{sharedEventId}/lifecycle	Flytt arrangementet mellom tillatte livssyklusstatuser	Organisasjonsadmin med manageSharedDetails
PATCH	/api/shared-events/{sharedEventId}/participants/{orgId}/quota	Oppdater kvoten for én deltaker	manageCapacity
PATCH	/api/shared-events/{sharedEventId}/quotas	Oppdater deltakerkvoter samlet	manageCapacity
POST	/api/shared-events/{sharedEventId}/capacity-policy	Endre kapasitetsmodell gjennom den beskyttede overgangsprosessen	manageCapacity
GET	/api/shared-events/{sharedEventId}/participants/{orgId}/users	List aktuelle brukere for eier- eller rettighetsadministrasjon	Organisasjonsadmin med manageOwners, eller superadmin
PUT	/api/shared-events/{sharedEventId}/grants/{granteeUserId}	Opprett eller oppdater en navngitt rettighetstildeling	Organisasjonsadmin med manageOwners
DELETE	/api/shared-events/{sharedEventId}/grants/{granteeUserId}	Tilbakekall en navngitt rettighetstildeling	Organisasjonsadmin med manageOwners
GET	/api/shared-events/{sharedEventId}/audit	Les den paginerte revisjonsloggen	Autorisert deltaker eller superadmin

Rapportering, salgskanaler og driftsendepunkter

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/shared-events/{sharedEventId}/reports/combined	Hent samlet arrangementsrapport	Eier, viewCombinedReports eller superadmin
GET	/api/shared-events/{sharedEventId}/reports/participant	Hent deltakerrapport. Standard er innringerens organisasjon	Deltaker for egen organisasjon. Eier eller superadmin for tillatt mål
GET	/api/shared-events/{sharedEventId}/external-sales-channels	List eksterne salgskanaler med beskyttede referanser skjult	Deltakermedlem, medlem i invitert organisasjon eller superadmin
GET	/api/shared-events/{sharedEventId}/external-sales-channels/{source}	Hent én ekstern salgskanal med beskyttede referanser skjult	Deltakermedlem, medlem i invitert organisasjon eller superadmin
PUT	/api/shared-events/{sharedEventId}/external-sales-channels/{source}	Tildel eller oppdater ansvarlig deltakerorganisasjon	manageExternalSales og organisasjonsadmin
DELETE	/api/shared-events/{sharedEventId}/external-sales-channels/{source}	Deaktiver en kanal uten å slette historisk tilordning	manageExternalSales og organisasjonsadmin
GET	/api/shared-event-organizations/search	Søk etter aktive organisasjoner for direkte deltakeradministrasjon	Superadmin
POST	/api/shared-events/{sharedEventId}/operation-status	Oppdater gjenopprettingsstatus og utfør projeksjonsarbeid i kø	Autorisert deltaker eller superadmin
POST	/api/shared-events/{sharedEventId}/sync-projections	Be om reparasjon eller synkronisering av organisasjonsprojeksjoner	Organisasjonsadmin med manageSharedDetails

Organisasjonssøk, rettighetstildeling, operasjonsstatus og projeksjonssynkronisering er administrative eller driftsrettede endepunkter for administrasjonsgrensesnittet. De er ikke offentlige søke-API-er og erstatter ikke arbeidsflytene for arrangører og deltakere.

Kanalendepunktene gir også autentiserte medlemmer i en invitert organisasjon en begrenset lesetilgang før invitasjonen er godtatt. De mottar bare kanaloppsettet. Beskyttede connectionRef-verdier fjernes. Aktive deltakere får samme skjerming med mindre kanalen er tildelt deres egen organisasjon. Eiere og superadministratorer kan motta de beskyttede referansene. Innringere utenfor deltakerorganisasjonene og inviterte organisasjoner avvises.

Delegert salg (salgspartnere)

Delegert salg lar en arrangementseier gi en annen organisasjon en avgrenset, selvbetjent mulighet til å selge billetter på sine vegne for et vanlig (ikke delt) arrangement, uten rett til å kansellere en godkjent eller levert bestilling, refundere, overføre, avstemme, fakturere, arkivere eller konfigurere arrangementet. Dette er ikke det samme som medeierskap i et delt arrangement. Se Datamodell → Delegert salg for det fullstendige feltnivå-skjemaet.

Fra og med v1.2.0 er hovedflyten for kjøperen selvbetjening: et godkjent medlem av partnerorganisasjonen bestiller det delegerte arrangementet gjennom den vanlige bestillingsflyten for medlemmer, bestillingen opprettes som pending, og partnerorganisasjonens egen billettansvarlig+ godkjenner og leverer den gjennom en godkjenningskø. Katalogsynlighet og bestillingsoppretting styres hver for seg av sin egen utrullingsbryter — se Miljøvariabler → Konfigurasjon for delegert medlemsbestilling. Et ansatt-opprettet (på vegne av) bestillingsendepunkt beholdes som en sekundær, kompatibel løsning for tilfeller selvbetjening ikke dekker.

Endepunkter for eiersiden

Metode	Endepunkt	Beskrivelse	Autent.
POST	/api/organizations/{organizationId}/events/{eventId}/sales-delegations	Inviter en partnerorganisasjon til å selge billetter for arrangementet	Eierorganisasjonens admin+
GET	/api/organizations/{organizationId}/events/{eventId}/sales-delegations	List delegeringer for arrangementet	Eierorganisasjonens admin+
POST	/api/organizations/{organizationId}/events/{eventId}/sales-delegations/{delegationId}/revoke	Tilbakekall en invitert eller aktiv delegering	Eierorganisasjonens admin+

POST .../sales-delegations — inndata for å finne partneren er rollestyrt og gjensidig utelukkende. Forespørselskroppen aksepterer nøyaktig ett av to felt; målorganisasjonen løses alltid opp på serversiden til slutt, aldri som fritekst fra klienten:

Felt	Type	Hvem kan sende det	Beskrivelse
partnerAdminEmail	string (e-post)	Alle innringere	E-postadressen til en administrator i målorganisasjonen. Serveren løser den opp til nøyaktig én kvalifisert organisasjon via resolvePartnerOrganizationByAdminEmail (api/src/shared/delegation-partner-resolution.ts), som gjenbruker samme omvendte oppslag som invitasjoner til delte arrangementer.
partnerOrganizationId	string	Kun superadmin	En rå organisasjons-ID, kun beregnet på den superadmin-only organisasjonssøkeflyten (GET /shared-event-organizations/search) — aldri en verdi en vanlig admin-klient skal konstruere eller sende.

{ "partnerAdminEmail": "admin@partner-choir.example" }

{ "partnerOrganizationId": "org-id-fra-sokeresultat" }

Å sende begge feltene, eller ingen av dem, feiler skjemavalidering og returnerer HTTP 400 (Provide exactly one of partnerOrganizationId or partnerAdminEmail) — det finnes ingen prioriteringsregel mellom de to.

En vellykket invitasjon (uansett vei) returnerer HTTP 201 med et objekt som inneholder delegation, en invitationLink (engangslenke — bare hashen av tokenet lagres, så lenken kan ikke hentes ut igjen etter dette svaret) og reverseIndexSync-status.

• Å invitere en partnerorganisasjon som allerede har en invited- eller active-delegering for arrangementet, er idempotent: den eksisterende delegeringen (og lenken, hvis fortsatt tilgjengelig) returneres i stedet for å opprette en duplikat.
• Kvalifisering for begge veier: den oppløste målorganisasjonen må være aktiv (ikke slettet) og kan ikke være innringerens egen organisasjon. Det finnes ingen egen partnerskaps-godkjenningsprosess utover dette.

Feilkoder spesifikke for oppslag av partner:

• 400 — Både partnerAdminEmail og partnerOrganizationId er til stede, eller ingen av dem er det (skjemavalideringsfeil).
• 400 — partnerOrganizationId løses opp til innringerens egen organisasjon (Cannot delegate sales to your own organization), eller til en projeksjon av et delt arrangement.
• 403 — partnerOrganizationId sendt av en innringer som ikke er superadmin. Dette er en hard rollesperre, uavhengig av om ID-en ellers ville vært gyldig — en vanlig eieradmin kan aldri bruke dette feltet til å utforske organisasjons-ID-er.
• 404 — partnerAdminEmail kunne ikke løses opp til nøyaktig én kvalifisert partnerorganisasjon. Dette ene generiske utfallet (samme melding som «No partner organization could be invited with that email address», med ekstra tidsvariasjon i responsen) returneres identisk enten adressen er ukjent, tilhører en som ikke er admin, bare tilhører en ikke-kvalifisert/slettet organisasjon, bare tilhører innringerens egen organisasjon, eller er administrator for mer enn én kvalifisert organisasjon (tvetydig mål) — anti-enumereringskontrakten gjør disse bevisst umulige å skille fra hverandre for innringeren. Frontend utdyper eller tolker aldri denne meldingen videre.

POST .../sales-delegations/{delegationId}/revoke aksepterer { "revokedReason": "..." } — revokedReason er påkrevd og kan ikke være tom. Å tilbakekalle en allerede tilbakekalt delegering er idempotent. Tilbakekalling trer i kraft umiddelbart mot eierens autoritative Event.salesDelegations[], uavhengig av hvor raskt partnerens egen omvendte indeks henger med — partneren mister umiddelbart retten til å opprette bestillinger, godkjenne/levere og rapportere, selv før egen liste eller katalogprojeksjon er oppdatert.

Endepunkter for aksept på partnersiden

Metode	Endepunkt	Beskrivelse	Autent.
POST	/api/sales-delegations/accept	Godta en invitasjon med tokenet fra engangsinvitasjonslenken	Partnerorganisasjonens admin+
POST	/api/organizations/{partnerOrganizationId}/sales-delegations/{delegationId}/decline	Avslå en ventende invitasjon	Partnerorganisasjonens admin+

POST .../decline krever ikke noe token — det er en handling i appen, gyldig bare fra status invited, og er idempotent hvis delegeringen allerede er avslått.

Endepunkter for medlemmenes selvbetjening og partnerens rapportering

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/organizations/{partnerOrganizationId}/delegated-events	List arrangementer som for øyeblikket er delegert til denne organisasjonen	Ethvert godkjent medlem av partnerorganisasjonen
GET	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/sales-context	Hent forestillinger, billetttyper og en kapasitetsindikasjon for salg	Billettansvarlig+
POST	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders/self	Selvbetjening: oppretter en pending-bestilling for den autentiserte innringeren	Ethvert godkjent medlem av partnerorganisasjonen
POST	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders/{orderId}/cancel	Kanseller en pending-bestilling — av kjøperen selv, eller av partnerens egen billettansvarlig+ på kjøperens vegne	Kjøper, eller billettansvarlig+
GET	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders/queue	Partnerens godkjenningskø for egne medlemmers selvbetjente bestillinger, filtrerbar på status pending eller approved	Billettansvarlig+
POST	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders/{orderId}/approve	Godkjenn en ventende selvbetjent bestilling	Billettansvarlig+
POST	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders/{orderId}/deliver	Merk en godkjent bestilling som levert	Billettansvarlig+
POST	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders/{orderId}/approve-and-deliver	Godkjenn og lever en ventende bestilling i ett steg	Billettansvarlig+
GET	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders	List denne partnerorganisasjonens egne bestillinger for arrangementet	Billettansvarlig+
POST	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders/{orderId}/report-sold	Rapporter solgt antall på en delegert bestilling	Billettansvarlig+, eller kjøperen for egen bestilling
POST	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders/{orderId}/report-returned	Rapporter returnert antall på en delegert bestilling	Billettansvarlig+, eller kjøperen for egen bestilling
POST	/api/organizations/{partnerOrganizationId}/delegated-events/{eventId}/orders	Utfaset, beholdt som sekundær løsning. Ansatt-opprettet (på vegne av) bestilling for et godkjent medlem av partnerens egen organisasjon, opprettet allerede delivered uten godkjenningssteg	Billettansvarlig+

• GET .../delegated-events returnerer bare referanser med denormalisert status "active" — inviterte, avslåtte og tilbakekalte delegeringer vises aldri i denne listen.
• GET .../sales-context returnerer kapasitetstall per forestilling. Dette er kun en indikasjon, ikke en reservasjon — endelig kapasitet håndheves atomisk ved bestillingsopprettelse/rapportering, ikke her.
• POST .../orders/self krever en active-delegering og de samme levende sjekkene som enhver annen delegert skriveoperasjon. Den vanlige POST /api/orders-ruten er ubetinget stengt for et arrangement med en delegert projeksjon — den avvises der med en feilmelding om feil endepunkt, uavhengig av rolle eller projeksjonstilstand, slik at en delegert bestilling aldri kan bygges mot feil organisasjons kapasitetsregnskap. Når DELEGATED_MEMBER_ORDERING_ENABLED er av, returnerer dette endepunktet HTTP 503 med feilkoden DELEGATED_MEMBER_ORDERING_UNAVAILABLE og oppretter ingenting.
• POST .../orders/{orderId}/cancel kan bare flytte en pending-bestilling til kansellert — samme regel som for en vanlig medlemsbestilling. En partner-billettansvarlig+ får ikke eieradministratorens mulighet til å kansellere en bestilling som allerede er godkjent eller levert.
• GET .../orders/queue og handlingene approve / deliver / approve-and-deliver er avgrenset til bestillinger opprettet under partnerens egen, for øyeblikket aktive delegering for dette arrangementet; de returnerer eller handler aldri på eierens egne bestillinger eller en annen partners bestillinger. Alle tre verifiserer delegeringen på nytt ved hvert kall, slik at en delegering som tilbakekalles midt i en økt, umiddelbart blokkerer videre handling, selv på bestillinger som allerede ligger i køen.
• Det ansatt-opprettede endepunktet POST .../orders krever at kjøperen er et godkjent medlem av partnerens egen organisasjon (aldri eierens medlemmer eller en annen partners medlemmer), og oppretter bestillingen allerede med status delivered, soldQuantity: 0 og returnedQuantity: 0. En kapasitetskonflikt ved innsending avvises med HTTP 409 CAPACITY_EXCEEDED.
• GET .../orders er avgrenset server-side til soldByOrganizationId === partnerOrganizationId; den returnerer aldri eierens egne bestillinger eller en annen partners bestillinger, og utelater denne partnerens bestillinger som siden er overført bort fra den.
• POST .../report-sold og POST .../report-returned verifiserer på nytt, ved hvert kall, at innringerens organisasjon fortsatt har en aktiv delegering for arrangementet og fortsatt har salgsmyndighet over den spesifikke bestillingen — en delegering som tilbakekalles midt i en økt, blokkerer umiddelbart videre rapportering, selv på bestillinger som allerede er opprettet. Rapporter-solgt håndhever samme atomiske kapasitetssperre som eiersidens rapportering. Rapporter-returnert speiler eiersidens returregel nøyaktig: kravet om at arrangementet/forestillingen må være avsluttet, gjelder alltid for et medlem som returnerer sin egen delegerte bestilling, akkurat som ved en vanlig egen-organisasjons-retur. Dette kravet fravikes bare for partnerens egen billettansvarlig+ som registrerer en retur på et medlems vegne.

Hva delegert salg aldri eksponerer

Ingen delegert-salg-endepunkt støtter refusjon, overføring, avstemming, oppgjør, fakturering eller arkivering av en bestilling, endring av arrangements-, pris-, billettype- eller kapasitetskonfigurasjon, eller kansellering av en bestilling som allerede er godkjent eller levert. Dette forblir utelukkende hos eiersidens endepunkter, avgrenset til eierorganisasjonens egne roller. Den delegerte projeksjonen som gjør en konsert synlig i partnerens egen katalog, er kun en visningsindeks — den brukes aldri i en autorisasjonsvurdering; hver skriveoperasjon utleder autoritet på nytt fra eierens levende Event.salesDelegations[].

Bestillinger

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/orders	List bestillinger (med filtre)	Billettansvarlig+
POST	/api/orders	Opprett bestilling	Medlem+
GET	/api/orders/{id}	Hent bestillingsdetaljer	Billettansvarlig+
POST	/api/orders/{id}/approve	Godkjenn bestilling	Billettansvarlig+
POST	/api/orders/{id}/deliver	Marker bestilling som levert	Billettansvarlig+
POST	/api/orders/{id}/cancel	Kanseller bestilling	Billettansvarlig+
DELETE	/api/orders/{id}	Slett bestilling	Billettansvarlig+
PATCH	/api/orders/{id}/archive	Arkiver eller gjenopprett bestilling	Billettansvarlig+
POST	/api/orders/archive/preview	Forhåndsvis kvalifiserte fullførte bestillinger for ett arrangement	Billettansvarlig+
POST	/api/orders/archive	Arkiver én gruppe kvalifiserte fullførte bestillinger for ett arrangement	Billettansvarlig+
PATCH	/api/orders/{id}/admin-note	Oppdater adminnotat på bestilling	Billettansvarlig+
POST	/api/orders/{id}/transfer	Overfør bestilling til et annet medlem	Billettansvarlig+
GET	/api/me/orders	Hent gjeldende brukers bestillinger	Medlem+

Begge de arrangementsspesifikke arkivendepunktene aksepterer { "eventId": "..." }. En kansellert bestilling er kvalifisert. En oppgjort bestilling er bare kvalifisert når den har et gyldig, låst invoiceBasis og invoicedAt. Slettede og allerede arkiverte bestillinger utelates. Forhåndsvisningen returnerer eligibleCount, statusBreakdown, blockedSettledUninvoiced og blockedInvalidInvoiceBasis. Arkivendepunktet bruker samme kandidatregel, overstyrer aldri blokkeringer, behandler maksimalt 100 bestillinger per kall og returnerer de to blokkeringstallene sammen med processed, conflicts, skipped, remaining, hasMore og completed.

Hvis en uventet feil oppstår etter at minst én bestilling er varig arkivert, returnerer endepunktet HTTP 207 med success: true og completed: false i data i stedet for å forkaste fremdriften. Resultatet inneholder de varige tellerne samt avgrensede verdier for failureCode og failureReason. remaining er numerisk når den etterfølgende opptellingen lykkes, eller null når antallet ikke kan fastslås; hasMore forblir true når antallet er ukjent. Klienter må ikke prøve denne mutasjonen automatisk på nytt, fordi hvert vellykkede kall endrer kandidatene for neste kall.

Arkivering beholder livssyklus, salg, returer, avstemming, fakturastatus og økonomiske opplysninger. Det individuelle PATCH-endepunktet aksepterer { "archived": true | false }. Organisasjonsadministratorer kan uttrykkelig overstyre en blokkert oppgjort bestilling med { "archived": true, "override": { "confirmed": true } }. Billettansvarlige og kasserere får 403 ARCHIVE_OVERRIDE_FORBIDDEN; vanlige blokkerte forespørsler får 409 INVOICE_REQUIRED eller INVALID_INVOICE_BASIS. Overstyringsbeviset lagrer aktør, visningsnavn, tidspunkt, arkiveringstidspunkt og nøyaktige blokkeringer. Beviset beholdes etter gjenoppretting. Eldre arkiverte bestillinger forblir arkivert, men de nye kravene gjelder etter gjenoppretting.

Livssyklus for trykte billetter

Metode	Endepunkt	Beskrivelse	Autent.
POST	/api/orders/{id}/report-sold	Registrer det nye, samlede antallet solgt fra en levert bestilling	Bestillingseier eller admin
POST	/api/orders/{id}/return	Registrer en trinnvis retur av usolgte trykte billetter	Bestillingseier eller billettansvarlig+
POST	/api/orders/{id}/approve-reconciliation	Godkjenn en fullstendig avstemt bestilling og lås fakturagrunnlaget	Billettansvarlig+

POST /api/orders/{id}/report-sold aksepterer:

{
  "soldQuantity": 4,
  "soldTypeQuantities": [
    { "ticketTypeId": "adult", "soldQuantity": 2 }
  ]
}

soldQuantity er det nye, absolutte totalantallet solgt for bestillingen. Hvert valgfritt antall per billettype er antallet som ble solgt i denne forespørselen, og summen per type må være lik økningen fra forrige total. Bestillingen må være levert, innringeren må eie den eller være admin, og det nye totalantallet kan ikke overstige bestilt antall minus returer. Den lokale kontrollen av salskapasitet returnerer HTTP 409 med errorCode: "CAPACITY_EXCEEDED", data.availableCapacity og data.requestedDelta. Konflikter fordi et delt arrangement er utsolgt eller kapasiteten er fryst, kan returnere samme HTTP-status og feilkode uten kapasitetsfeltene. Et vellykket svar returnerer den oppdaterte bestillingen i data.

POST /api/orders/{id}/return aksepterer:

{
  "returnQuantity": 2,
  "returnTypeQuantities": [
    { "ticketTypeId": "adult", "returnQuantity": 2 }
  ]
}

Returantallet og valgfrie verdier per billettype er trinnvise. De kan ikke overstige utestående antall. Medlemmer kan bare returnere egne billetter og først etter at den aktuelle forestillingen eller arrangementet er avsluttet. Billettansvarlige, kasserere, administratorer og superadministratorer kan registrere en retur på vegne av et medlem uten datobegrensningen. Bestillingen forblir delivered mens billetter er utestående og går til awaitingReconciliation når solgt pluss returnert er lik bestilt antall.

POST /api/orders/{id}/approve-reconciliation krever ingen forespørselskropp. Endepunktet godtar bare en bestilling med status awaitingReconciliation der solgt pluss returnert er lik utlevert antall. Godkjenning endrer status til settled, registrerer godkjenneren og lagrer et uforanderlig fakturagrunnlag.

Grunnlaget inneholder bare solgt antall multiplisert med enhetsprisene som ble lagret med bestillingen. Hvis alle billetter ble solgt, kan eldre bestillinger utlede antall per type fra de bestilte antallene. Hvis ingen billetter ble solgt, blir grunnlaget tomt med verdi null. Et delvis salg krever fullstendige og konsistente soldTypeQuantities, samt konsistente returdetaljer per type når de finnes. Ufullstendig eller selvmotsigende delhistorikk returnerer 400 og blokkerer oppgjør. totalAmount brukes aldri som reserve for fakturagrunnlaget.

Godkjenningen setter ikke invoicedAt og oppretter eller sender ikke en faktura. Et vellykket svar returnerer den oppgjorte bestillingen i data.

Feil i livssyklusen bruker standard feilkonvolutt. Forvent 400 ved ugyldige antall eller statuser, 403 ved feil eierskap eller rolle, 404 for ukjent bestilling, 409 ved kapasitetskonflikt og 503 når kapasiteten for et delt arrangement er midlertidig utilgjengelig.

Overføring av bestillinger

Overføringsendepunktet lar billettansvarlige flytte billetter mellom medlemmer — enten ved å tildele hele bestillingen på nytt, eller ved å dele den i en kilde- og en mottakerbestilling. En delvis overføring gjennomføres som én atomisk Cosmos-transaksjonsbatch innenfor samme organisasjonspartisjon (erstatt kilde, opprett mottaker), og hver forespørsel er idempotent per klientoppgitt transferRequestId, slik at en gjentatt eller reprodusert forespørsel aldri kan duplisere en overføring eller la den ene siden oppdateres uten den andre.

Metode	Endepunkt	Beskrivelse	Autent.
POST	/api/orders/{id}/transfer	Overfør hele eller deler av en bestilling til et annet medlem	Billettansvarlig+

POST /api/orders/{id}/transfer aksepterer:

{
  "toUserId": "user-id-of-destination",
  "transferRequestId": "550e8400-e29b-41d4-a716-446655440000",
  "tickets": [
    { "ticketTypeId": "adult", "quantity": 2 },
    { "ticketTypeId": "child", "quantity": 1 }
  ],
  "reason": "Member requested swap"
}

Hva som kan overføres (kun utestående):

En overføring kan bare flytte utestående (ikke rapportert) billettantall — enheter som ennå ikke er solgt eller returnert, er de eneste som er kvalifisert. Solgte og returnerte enheter, og tilhørende bevis per billetttype, flyttes eller endres aldri av dette endepunktet. Utestående beregnes som max(0, totalQuantity - effectiveSoldQuantity - returnedQuantity). Hvis forespurt antall overstiger det som er utestående — samlet eller for en enkelt billetttype — avvises forespørselen med TRANSFER_EXCEEDS_OUTSTANDING; hvis ingenting er utestående i det hele tatt, avvises den med TRANSFER_BLOCKED_NO_OUTSTANDING. Dette betyr at en forespørsel om å overføre hele bestillingen naturlig mislykkes så snart noe rapportering har skjedd (utestående er da mindre enn totalQuantity), mens en delvis overføring av den gjenværende utestående saldoen fortsatt lykkes.

Avstemming ved siste utestående overføring:

Hvis en delvis overføring flytter hele den gjenværende utestående saldoen på en delivered-kildebestilling (altså sourceRemainingQuantity blir 0), går kildebestillingens status fra delivered til awaitingReconciliation som en del av samme atomiske batch — akkurat som om de siste billettene var rapportert solgt eller returnert i stedet for overført. En full overføring utløser aldri dette, siden hele bestillingen tildeles på nytt (det er ingen redusert bestilling igjen å avstemme).

Feilkoder:

• 400 TRANSFER_EXCEEDS_OUTSTANDING — Forespurt antall overstiger det som er utestående på kildebestillingen.
• 409 TRANSFER_BLOCKED_NO_OUTSTANDING — Kildebestillingen har null utestående antall igjen — alt er allerede solgt eller returnert.
• 409 TRANSFER_REQUEST_ID_REUSED — Samme transferRequestId er allerede brukt til en overføring med en annen mottaker, modus eller andre antall.

Tildelinger (salgskvoter)

Tildelingsendepunkter administrerer billettkvoter per medlem. De brukes via arrangementets administrasjonspanel, ikke som en frittstående seksjon. Tildelingsgrenser håndheves kun når enableQuotas er true på det overordnede arrangementet.

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/allocations	List tildelinger	Billettansvarlig+
POST	/api/allocations	Opprett eller oppdater tildeling	Billettansvarlig+
DELETE	/api/allocations/{id}	Slett tildeling	Billettansvarlig+
GET	/api/allocations/members	List medlemmer med tildelingsoppsummering	Billettansvarlig+
GET	/api/my-allocations	Hent medlemmets egne tildelinger	Medlem+

Forpliktelser / løfter

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/events/{eventId}/my-pledge	Hent medlemmets eget løfte for arrangement	Medlem+
POST	/api/events/{eventId}/my-pledge	Send inn eller oppdater forpliktelsesløfte	Medlem+
GET	/api/events/{eventId}/pledge-summary	Hent samlet løfteoppsummering	Medlem+
GET	/api/management/events/{eventId}/pledges	List alle løfter for arrangement	Billettansvarlig+
PUT	/api/management/events/{eventId}/commitment	Åpne, lukk eller konverter forpliktelsesrunde	Admin

Eksternt salg

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/management/events/{eventId}/external-sales	List eksternt salg for arrangement	Billettansvarlig+
GET	/api/management/events/{eventId}/showtimes/{showtimeId}/external-sales	List eksternt salg per forestilling	Billettansvarlig+
POST	/api/management/events/{eventId}/showtimes/{showtimeId}/external-sales	Opprett ekstern salgsoppføring	Billettansvarlig+
PUT	/api/management/external-sales/{id}	Oppdater eksternt salg	Billettansvarlig+
DELETE	/api/management/external-sales/{id}	Slett eksternt salg	Billettansvarlig+

Fribilletter

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/events/{eventId}/free-tickets	List fribilletter	Billettansvarlig+
POST	/api/events/{eventId}/free-tickets	Opprett fribillettoppføring	Billettansvarlig+
PUT	/api/events/{eventId}/free-tickets/{id}	Oppdater fribillettoppføring	Billettansvarlig+
DELETE	/api/events/{eventId}/free-tickets/{id}	Slett fribillett	Billettansvarlig+
GET	/api/events/{eventId}/capacity-summary	Hent kapasitetsoppsummering for arrangement	Påkrevd

Oppdateringsendepunktet krever ?organizationId={organizationId} og et ikke-tomt JSON-objekt med ett eller flere av feltene showtimeId, ticketTypeId, quantity, recipient og reason. Antall må være et positivt heltall. Hvis billettype eller forestilling endres, må den tilhøre arrangementet i URL-en. Svaret returnerer det oppdaterte fribillettobjektet i data.

For delte arrangementer reserverer og bekrefter en antallsøkning bare den ekstra kapasiteten. En reduksjon behandles som en administrativ korrigering og frigir ikke tidligere bekreftet felleskapasitet. Trygge feil omfatter ugyldig input eller utilgjengelig kapasitet, en manglende kobling mellom billett og arrangement, utilgjengelig salg for delt arrangement og midlertidig kapasitetsoppsett eller synkronisering.

Registreringer (direktesalg)

Metode	Endepunkt	Beskrivelse	Autent.
POST	/api/registrations	Opprett registrering (1-times frist for redigering)	Medlem+
PUT	/api/registrations/{id}	Oppdater registrering (innen 1 time etter opprettelse)	Billettansvarlig+
DELETE	/api/registrations/{id}	Slett registrering (innen 1 time etter opprettelse)	Billettansvarlig+
GET	/api/me/history	Hent brukerens salgshistorikk	Medlem+
GET	/api/me/stats	Hent brukerens statistikk	Medlem+

Admin / oversikt

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/management/dashboard/{eventId}	Hent oversiktsstatistikk	Billettansvarlig+
GET	/api/management/dashboard/{eventId}/export	Eksporter CSV	Billettansvarlig+
GET	/api/management/dashboard/{eventId}/export-excel	Eksporter Excel	Billettansvarlig+
PUT	/api/management/members/{userId}/invoice/{eventId}	Sett eller fjern fakturastatus for medlem og arrangement	Billettansvarlig+
PUT	/api/management/registrations/{id}/invoice	Marker én registrering som fakturert	Billettansvarlig+

Medlems- og arrangementsendepunktet aksepterer { "invoiced": true } for å registrere at fakturaen er utstedt eller sendt, og { "invoiced": false } for å fjerne denne statusen. Et tomt objekt støttes midlertidig som eldre veksleoppførsel, men førstepartsklienter sender uttrykkelig ønsket status. Den eldre retningen bygger bare på kvalifiserte poster: når alle kvalifiserte poster allerede er fakturert, fjernes statusen selv om uavklarte eller ugyldige trykte bestillinger fortsatt finnes.

Kvalifiserte poster er aktive direkteregistreringer og aktive oppgjorte bestillinger med gyldig, låst fakturagrunnlag. Arkiverte oppgjorte bestillinger kan faktureres, men må gjenopprettes før fakturastatus fjernes. Uavklarte bestillinger og bestillinger med ugyldig grunnlag endres ikke. Fakturabeløpet er summen av registreringenes totalAmount og bestillingenes invoiceBasis.grandTotal; det bruker aldri TicketOrder.totalAmount.

Operasjonen bruker ETag-vilkår for hver post. Resultatet rapporterer samlede og typespesifikke tall for oppdatert, uendret, konflikt, uavklart, ugyldig og mislykket. Markøren completed er bare true når ingen konflikt eller skrivefeil oppstod. En forespørsel med konflikter eller skrivefeil returnerer HTTP 207 med completed: false og beholder vellykkede oppdateringer. Gjentakelse av samme uttrykkelige forespørsel konvergerer uten å veksle poster som allerede har riktig status.

Invitasjoner

Metode	Endepunkt	Beskrivelse	Autent.
POST	/api/organizations/{organizationId}/invitations	Opprett invitasjonskode	Admin
GET	/api/organizations/{organizationId}/invitations	List invitasjoner	Admin
DELETE	/api/organizations/{organizationId}/invitations/{code}	Slett eller tilbakekall invitasjon	Admin
GET	/api/join/{code}	Valider invitasjonskode	Offentlig
POST	/api/join/{code}	Godta invitasjon og bli med i organisasjon	Offentlig

Superadmin

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/organizations	List alle organisasjoner	Superadmin
POST	/api/organizations	Opprett organisasjon	Superadmin
GET	/api/organizations/{id}	Hent organisasjonsdetaljer	Superadmin
PUT	/api/organizations/{id}	Oppdater organisasjon	Superadmin
DELETE	/api/organizations/{id}	Slett organisasjon	Superadmin
POST	/api/organizations/{id}/members/import	Importer medlemmer via CSV	Superadmin
GET	/api/organizations/{id}/members	List organisasjonsmedlemmer	Superadmin
POST	/api/organizations/{id}/members	Legg til medlem i organisasjon	Superadmin
PUT	/api/organizations/{id}/members/{memberId}	Oppdater medlemsrolle	Superadmin
DELETE	/api/organizations/{id}/members/{memberId}	Fjern medlem fra organisasjon	Superadmin
GET	/api/users	List alle brukere	Superadmin
GET	/api/users/{id}	Hent brukerdetaljer	Superadmin
PUT	/api/users/{id}	Oppdater bruker	Superadmin
PUT	/api/users/{id}/super-admin	Slå av eller på superadmin-status	Superadmin
POST	/api/users/import	Importer brukere via CSV	Superadmin
DELETE	/api/users/bulk-delete	Masseslett brukere	Superadmin
POST	/api/users/bulk-assign-organization	Massetildel brukere til organisasjon	Superadmin
POST	/api/impersonation/audit	Logg representasjonshendelse	Superadmin
GET	/api/impersonation/audit	Hent representasjonslogger	Superadmin

Varsler

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/notifications	List gjeldende brukers varsler	Medlem+
POST	/api/notifications/{id}/read	Marker ett varsel som lest	Medlem+
POST	/api/notifications/read-all	Marker alle varsler som lest	Medlem+
DELETE	/api/notifications/{id}	Slett et varsel	Medlem+

Alle varselendepunkter krever ?organizationId={organizationId}. Varsler er avgrenset til innlogget bruker — du kan bare lese og slette dine egne varsler. Endepunktet returnerer de 50 nyeste varslene sortert etter createdAt DESC.

Rapporter

Metode	Endepunkt	Beskrivelse	Autent.
GET	/api/management/reports	Hent rapportdata (alle faner)	Kasserer+
GET	/api/management/reports/export	Eksporter rapport som CSV	Kasserer+

Queryparametere for GET /api/management/reports:

Parameter	Verdier	Beskrivelse
type	members, choirs, events, types, ticketmaster, all	Rapportfane som skal lastes
organizationId	organisasjons-ID	Påkrevd
eventId	arrangements-ID	Valgfritt filter

Finansiell rapportering for trykte bestillinger omfatter bare faktisk salg. Ventende og godkjente bestillinger bidrar med null. Leverte bestillinger og bestillinger som venter på avstemming bruker validerte rapporterte salgslinjer når de finnes; oppgjorte bestillinger bruker det validerte låste fakturagrunnlaget. Returnerte eller utestående billetter bidrar ikke med inntekt eller gebyr, og ugyldige eller ufullstendige detaljer faller aldri tilbake til TicketOrder.totalAmount.

Queryparametere for eksport:

Parameter	Verdier	Beskrivelse
exportType	transactions, members, showtimes, orders	Hva som skal eksporteres
format	csv	Filformat (bare CSV foreløpig)
organizationId	organisasjons-ID	Påkrevd

CSV-eksportene transactions, members og showtimes bruker de samme solgte antallene, prisene fra bestillingstidspunktet og gebyrantallene som rapportresponsen.

Administrasjon

Metode	Endepunkt	Beskrivelse	Autent.
POST	/api/management/cleanup	Slett alle data (bare dev/test)	Superadmin
GET	/api/management/events/{eventId}/external-sales	List eksternt salg for arrangement	Billettansvarlig+
GET	/api/management/events/{eventId}/showtimes/{showtimeId}/external-sales	List eksternt salg per forestilling	Billettansvarlig+
POST	/api/management/events/{eventId}/showtimes/{showtimeId}/external-sales	Opprett ekstern salgsoppføring	Billettansvarlig+
PUT	/api/management/external-sales/{id}	Oppdater eksternt salg	Billettansvarlig+
DELETE	/api/management/external-sales/{id}	Slett eksternt salg	Billettansvarlig+

Administrasjonsopprydding

Endepunktet POST /api/management/cleanup er bare tilgjengelig når E2E_TEST_MODE=true og krever superadmin-autentisering. Send ?confirm=yes for å faktisk slette alle data. Advarsel: Dette sletter ALLE organisasjoner, arrangementer, registreringer, billetttyper og andre applikasjonsdata. Bruk det bare i utviklings- og testmiljøer.

---

Neste: Miljøvariabler · Se også: Arkitektur · Datamodell