Riferimento API

L’API v1 di FixNoty è un’interfaccia HTTP versionata, in sola lettura, per esportare tutte le segnalazioni di un singolo progetto. È pensata per script, CI, tool interni e automazioni successive — anche un agent AI che ha bisogno dello stesso contesto di risoluzione che vede una persona in dashboard.

L’API non cambia stato, non scrive commenti, non elimina oggetti e non restituisce path di storage grezzi né materiale segreto. I media arrivano come URL firmati a tempo. Il session replay arriva come chunk rrweb oppure come link firmato di 24 ore allo stesso player interattivo della tab Replay in dashboard — non come un nuovo MP4.

• Protocollo: HTTPS JSON. Non si usano body di richiesta (tutti i metodi sono GET).
• Prefisso: /api/v1. I prefissi di lingua come /it o /en valgono solo per il sito; non fanno parte del path API.
• Scope: un progetto per chiave. Un id di un altro progetto risponde 404 con code not_found.
• Compatibilità: gli enum di stato, priorità e categoria sono le stringhe italiane del database (es. aperto). Nei client non vanno tradotti.

Host di produzione: https://www.fixnoty.com. In sviluppo usa l’origine del tuo deploy. Concatena il prefisso senza slash finale:

https://www.fixnoty.com/api/v1/feedback

I breaking change escono sotto un nuovo prefisso (/api/v2). In v1 possono comparire campi JSON aggiuntivi senza cambio di versione; i client devono ignorare le chiavi sconosciute. In v1 non c’è un documento OpenAPI.

Autenticati con una chiave API di progetto. La chiave vale per un solo progetto e dà accesso in sola lettura. Autentica il progetto, non un utente: chiunque abbia il secret (script, collaboratore, integrazione) può leggere tutte le segnalazioni di quel progetto.

Invia il secret con esattamente uno di questi header:

Authorization: Bearer fn_live_…
X-Api-Key: fn_live_…

Se sono presenti entrambi, vince Authorization: Bearer. Chiavi in query string, cookie e body vengono ignorate.

Le risposte di errore usano un JSON stabile. code è sempre in inglese ed è il campo su cui fare lo switch. error è un messaggio leggibile e può essere localizzato da Accept-Language (it, oppure fallback en).

{
  "error": "Invalid or revoked API key.",
  "code": "invalid_api_key"
}

Un token del player malformato, scaduto o legato a una chiave revocata non è un errore v1: la pagina watch e lo stream eventi rispondono 404 o 410 e non fanno parte del contratto versionato.

Finestre scorrevoli di 60 secondi, contate in memoria per istanza del server (MVP; non è una quota Redis globale). Valgono entrambi i limiti:

• 60 richieste / minuto / IP client, valutate prima di parsare la chiave. Anche chi non è autenticato consuma questo budget.
• 120 richieste / minuto / chiave autenticata, valutate dopo il lookup riuscito della chiave.

Superato uno dei due limiti si ottiene 429 con code rate_limited e header Retry-After (secondi, minimo 1). L’accesso API è incluso in Agency, non è un piano a parte.

Ogni risposta JSON v1 include:

Cache-Control: private, no-store

Gli URL dei media firmati e i link del player non devono finire in cache CDN o cache HTTP condivise. Il client può tenere la risposta in memoria locale fino a expires_at, poi deve richiamare GET /feedback/:id/assets (o /replay) per un URL nuovo.

I secret non vengono mai scritti nei log applicativi. Non loggare Authorization, X-Api-Key, token del player o le query string degli URL firmati.

GET /feedback usa keyset pagination su (updated_at DESC, id DESC). Non usa SQL OFFSET.

• Dimensione pagina di default 50; massimo 100. I valori sopra il massimo vengono tagliati, non rifiutati.
• Se esiste un’altra pagina, has_more è true e next_cursor è un blob opaco in base64url. Rimandalo come cursor.
• Un cursore malformato dà 400 invalid_request. Non inventare i cursori: non sono un linguaggio di query pubblico.

I binari non sono mai inline nel JSON e l’API non restituisce uno zip del progetto. Ogni file è un oggetto:

{
  "url": "https://…/object/sign/…?token=…",
  "expires_in": 1800,
  "expires_at": "2026-10-02T10:30:00.000Z"
}

Fai GET direttamente sull’url. Dopo la scadenza lo storage rifiuta il token; richiama assets o replay. Le righe allegato includono anche id, file_name, mime_type, file_size e created_at.

La cattura nativa è eventi DOM rrweb, non una registrazione schermo. La v1 espone due formati di prima classe più un video legacy opzionale:

1. formats.player — pagina HTML firmata che monta lo stesso player rrweb della tab Replay in dashboard. Valida 24 ore. Zero storage extra.
2. formats.rrweb — manifest JSON firmato + file chunk in ordine (24 ore). Concatena gli array di eventi dei chunk e passali a un player rrweb.
3. formats.video — presente solo se sulla riga esiste già un MP4 storico. La v1 non transcodifica rrweb in MP4. Stato tipico: not_generated.

formats.still è lo screenshot della segnalazione (TTL 30 minuti). timeline è il log azioni del widget (click, navigazione, input mascherati, errori JS) — un array JSON più piccolo, distinto da rrweb.

Le segnalazioni senza registrazione rispondono comunque HTTP 200 con has_replay: false. HTTP 404 significa che la segnalazione non appartiene al progetto della chiave.

• Emesso solo da GET /api/v1/feedback/:id e …/replay autenticati, per una segnalazione dello stesso progetto della chiave.
• HMAC-SHA256 su un payload con scadenza. I token sono opachi: i client non devono parsarli.
• Le claim includono id progetto, id segnalazione, id chiave API e scadenza Unix. Revocare la chiave invalida tutti i link player già emessi, anche prima delle 24 ore.
• Token scaduti, falsi o revocati → 404/410. La pagina watch non richiede login in dashboard (così un browser o un agent con browser può aprirla). Avere l’URL è la credenziale, fino a scadenza o revoca.
• Header di risposta: Cache-Control: private, no-store, Referrer-Policy: no-referrer, X-Frame-Options: DENY, Content-Security-Policy: frame-ancestors 'none', X-Robots-Tag: noindex, nofollow, X-Content-Type-Options: nosniff. Il player non si può mettere in iframe su un altro sito e non è offerto ai motori di ricerca.

Il player HTML carica gli eventi da uno stream interno GET /api/replay-watch/:token (limitato per IP, stessi header di sicurezza). Quella rotta non fa parte del contratto v1; integra su formats.player.watch.url o formats.rrweb.

Conferma la chiave e restituisce il progetto a cui è legata. Usala come verifica di connettività prima di elencare le segnalazioni.

{
  "project": {
    "id": "11111111-2222-4333-8444-555555555555",
    "name": "Client site",
    "site_url": "https://staging.example.com"
  }
}

Indice leggero delle segnalazioni del progetto. Non include mai recording_events, console_logs, conversation, activity né URL firmati dei file. Per quelli usa dettaglio / assets / replay.

{
  "data": [
    {
      "id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
      "pin_number": 4,
      "status": "aperto",
      "priority": "bloccante",
      "category": "bug",
      "feedback_type": "debug_replay",
      "title": "Il checkout non invia l’ordine",
      "comment": "Clicco Paga e non succede nulla.",
      "client_title": null,
      "page_url": "https://staging.example.com/checkout",
      "page_path": "/checkout",
      "created_at": "2026-10-01T14:12:00.000Z",
      "updated_at": "2026-10-01T15:40:00.000Z",
      "last_activity_at": "2026-10-01T15:40:00.000Z",
      "author_name": "Anna",
      "assigned_to": null,
      "has_screenshot": true,
      "has_replay": true,
      "has_attachments": true,
      "has_console_errors": true,
      "attachment_count": 1
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Contesto completo per capire (e un giorno risolvere) una segnalazione del progetto della chiave. La query opzionale include=recording_events aggiunge la timeline del widget. Gli eventi rrweb non sono mai inline: usa gli URL firmati in replay.

GET /api/v1/feedback/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee?include=recording_events
Authorization: Bearer $FIXNOTY_API_KEY

Riemette gli URL firmati senza riscaricare commenti, conversazione o attività. Il expires_in in cima è il TTL di screenshot/allegati (1800s). replay_expires_in è il TTL di player/rrweb (86400s).

{
  "data": {
    "screenshot": {
      "url": "https://….supabase.co/storage/v1/object/sign/feedback-screenshots/…?token=redacted",
      "expires_in": 1800,
      "expires_at": "2026-10-02T10:30:00.000Z"
    },
    "attachments": [],
    "debug_attachments": [],
    "replay": null
  },
  "expires_in": 1800,
  "replay_expires_in": 86400
}

Busta dedicata al replay. La timeline del widget è inclusa di default. Apri formats.player.watch.url nel browser per vedere la sessione come in dashboard.

{
  "data": {
    "feedback_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "has_replay": true,
    "duration_seconds": 42,
    "recording_session_id": null,
    "debug_session_id": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
    "expires_in": 86400,
    "formats": {
      "rrweb": {
        "available": true,
        "playback": "rrweb",
        "expires_in": 86400,
        "manifest": {
          "url": "https://….supabase.co/storage/v1/object/sign/debug-replays/…?token=redacted",
          "expires_in": 86400,
          "expires_at": "2026-10-03T10:00:00.000Z"
        },
        "chunks": [
          {
            "url": "https://…/chunk-000.json?token=redacted",
            "expires_in": 86400,
            "expires_at": "2026-10-03T10:00:00.000Z"
          }
        ]
      },
      "player": {
        "available": true,
        "playback": "player",
        "expires_in": 86400,
        "watch": {
          "url": "https://www.fixnoty.com/it/replay/<signed-token>",
          "expires_in": 86400,
          "expires_at": "2026-10-03T10:00:00.000Z"
        }
      },
      "video": {
        "available": false,
        "playback": "mp4",
        "status": "not_generated",
        "mime_type": "video/mp4",
        "expires_in": 86400,
        "file": null
      },
      "still": {
        "url": "https://….supabase.co/storage/v1/object/sign/feedback-screenshots/…?token=redacted",
        "expires_in": 1800,
        "expires_at": "2026-10-02T10:30:00.000Z"
      }
    },
    "timeline": [
      {
        "t": 1200,
        "at": "2026-10-01T14:12:01.200Z",
        "type": "click",
        "page_url": "https://staging.example.com/checkout"
      }
    ],
    "warnings": []
  },
  "expires_in": 86400
}

Questa API è un canale dati. Non chiama un modello e non sistema le segnalazioni da sola.

• LLM solo testo. Legge lista + dettaglio JSON, console, timeline e conversazione. Ottiene azioni, errori, copy e un fotogramma. Non ottiene il movimento.
• Agent con browser. Apre formats.player.watch.url, preme play e guarda o screenshotta il DOM ricostruito. Un GET HTTP nudo su quell’URL restituisce l’HTML/JS del player, non i fotogrammi.
• Player proprio. Scarica i chunk formats.rrweb. Sono gli stessi eventi della dashboard.

Non generiamo MP4 da rrweb: duplicerebbe storage già tenuto come chunk di eventi. Il player 24 ore riusa quei chunk.

• Questo URL di documentazione è pubblico di proposito. Le docs pubbliche descrivono il contratto. Non danno accesso.
• Il controllo accessi è la chiave API di progetto (hashata a riposo) più i filtri server-side su project_id. Indovinare l’UUID di una segnalazione di un altro progetto non la fa trapelare.
• RLS in dashboard: solo il proprietario può leggere/inserire/aggiornare le righe di project_api_keys.
• I link del player sono unlisted, non indicizzati, non embeddabili, a tempo e revocabili con la chiave. Non inoltrarli.
• Non mettere le chiavi API nei bundle frontend né in pagine che leakano il Referer. Preferisci caller server-side.

Versione attuale: v1. Possono comparire campi aggiuntivi. Restano esplicitamente fuori dalla v1:

• POST / PATCH / DELETE (stato, commenti, assegnazione)
• Zip sincrono di tutto il progetto
• Billing, piani a pagamento, webhook
• SDK ufficiali e OpenAPI
• Inferenza di modelli, auto-fix o webhook AI in uscita
• Transcodifica MP4 da rrweb

Riferimento pubblico canonico: questa pagina. Una nota tecnica allineata sta nel repository in docs/api-v1.md. Stampa dal browser («Stampa → Salva come PDF») è supportata; non spediamo un PDF versionato a parte che può divergere dall’implementazione.