Menu della documentazione
Specifico per il partner Ultimo aggiornamento: 27 luglio 2026

Scambio di dati

Usa le attuali risorse partner in sola lettura e definisci un contratto sicuro per lo scambio dei grafici dei percorsi specifico per il partner.

Parkour Design gestisce attualmente un servizio di risorse coordinato, in sola lettura, con i riepiloghi di eventi e grafici dei percorsi. Geometria completa del progetto, file, scrittura e sincronizzazione richiedono un contratto partner separato.

Stato del contratto: gli endpoint qui sotto descrivono il comportamento attuale in produzione per i client approvati. Non sono ancora un’API pubblica con versionamento. Non sviluppare contro di essi finché Parkour Design non ha confermato accesso, scope, limiti e contratto di lancio.

URL di base e autenticazione

Usa come URL di base dell’API l’emittente scelto per l’ambiente OAuth:

AmbienteURL di base
Produzionehttps://app.parkour.design
Testhttps://parkour-test.web.app

Invia il token di accesso di Parkour Design da un servizio backend:

Authorization: Bearer <access_token>
Accept: application/json

Il token di accesso deve essere valido per l’emittente configurato e l’audience parkour-api, avere token_use uguale a access_token e, attualmente, contenere openid.

L’API attualmente non consente l’accesso da browser di altra origine. Non esporre token di accesso o refresh token al JavaScript del frontend.

Elenco degli eventi

GET /api/events

Esempio di richiesta:

curl "${ISSUER}/api/events" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

Esempio di risposta:

{
  "items": [
    {
      "id": "abcdefghijklmnopqrstuv",
      "name": "Example Event",
      "startDate": "2026-07-24T00:00:00Z",
      "endDate": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T18:42:10Z",
      "designCount": 4
    }
  ]
}

Tipo di risposta attuale:

type EventSummary = {
  id: string;
  name: string;
  startDate: string | null;
  endDate: string | null;
  updatedAt: string | null;
  designCount: number;
};

type EventsResponse = {
  items: EventSummary[];
};

Gli eventi vengono ricavati dai progetti non eliminati dell’utente autenticato. I progetti senza identificatore di evento vengono omessi.

Tratta id come opaco. Copialo invariato nella richiesta dei riepiloghi dei progetti. Non trarre conclusioni dal suo formato e non generarlo nel sistema del partner.

Elenco dei riepiloghi dei progetti di un evento

GET /api/events/{eventId}/designs

Esempio di richiesta:

curl "${ISSUER}/api/events/${EVENT_ID}/designs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

Esempio di risposta:

{
  "event": {
    "id": "abcdefghijklmnopqrstuv",
    "name": "Example Event",
    "startDate": "2026-07-24T00:00:00Z",
    "endDate": "2026-07-26T00:00:00Z",
    "updatedAt": "2026-07-26T18:42:10Z",
    "designCount": 4
  },
  "items": [
    {
      "id": "design-record-id",
      "localId": "design-local-id",
      "eventId": "abcdefghijklmnopqrstuv",
      "title": "Grand Prix",
      "eventName": "Example Event",
      "eventDate": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T18:42:10Z",
      "authorName": "Course Designer",
      "shortDescr": "Competition description"
    }
  ]
}

Tipo di risposta attuale:

type DesignSummary = {
  id: string;
  localId: string | null;
  eventId: string;
  title: string;
  eventName: string;
  eventDate: string | null;
  updatedAt: string | null;
  authorName: string | null;
  shortDescr: string;
};

type EventDesignsResponse = {
  event: EventSummary;
  items: DesignSummary[];
};

Le date sono stringhe ISO 8601 in UTC, quando presenti. I client devono gestire null per le date facoltative e per localId.

Proprietà e visibilità

Il sub del bearer token identifica il proprietario della risorsa in Parkour Design. Le risposte contengono solo i progetti non eliminati di proprietà di quell’utente.

Il servizio attuale non fornisce:

  • accesso per intere organizzazioni o team;
  • accesso ai progetti condivisi o pubblici di un altro utente;
  • filtraggio delle risorse specifico per client;
  • progetti eliminati;
  • dati di abbonamento, profilo o pagamento.

Un evento inesistente e un evento di proprietà di un altro utente restituiscono entrambi 404. Non usare la risposta per dedurre se esiste una risorsa di un altro utente.

Limiti attuali e ordinamento

Gli endpoint attuali non accettano parametri di filtro, ordinamento, paginazione, cursori o sincronizzazione incrementale.

  • /api/events restituisce l’elenco ricavato degli eventi in una sola risposta.
  • /api/events/{eventId}/designs restituisce al massimo 500 riepiloghi.
  • La risposta attualmente non indica se l’elenco è stato troncato e non fornisce un cursore di continuazione.
  • L’ordinamento è il comportamento dell’implementazione attuale e non ancora una garanzia con versionamento.

Prima di approvare un’integrazione per la produzione, Parkour Design e il partner devono confermare che il volume di dati previsto rientri nei limiti. Un partner che ha bisogno di paginazione completa o aggiornamenti incrementali non deve compensare con scraping o indovinando gli identificatori; serve un contratto rivisto.

Risposte di errore

Gli errori usano un corpo JSON compatto:

{"error": "not_found"}
StatoErroreSignificato
401invalid_tokenBearer token mancante, malformato, scaduto, non valido o con ambito attualmente insufficiente
404not_foundPercorso non valido o evento non accessibile per l’utente
405method_not_allowedMetodo diverso da GET

Gli errori imprevisti del servizio non hanno ancora uno schema di errore separato con versionamento. I client devono considerare ripetibili le altre risposte 5xx solo per le operazioni GET idempotenti, con un backoff esponenziale limitato e jitter.

Dati non esposti dall’API

Il riepilogo di un progetto non è un grafico del percorso completo. L’attuale API delle risorse non espone:

  • geometria del percorso o tracciato;
  • ostacoli, gruppi, disposizione del campo o oggetti di disegno;
  • PDF generati, anteprime, immagini o URL di download;
  • operazioni di creazione, aggiornamento, eliminazione o caricamento;
  • ricerca di un singolo progetto tramite il suo ID;
  • webhook o un flusso delle modifiche;
  • token di accesso, sessioni, categorie, attività o destinazioni salvate di Eqify.

Non presentare una risposta con i riepiloghi come un grafico del percorso da stampare o modificare.