# Supporto e completezza dei dati

> Cosa coprono e cosa non coprono i dati attuali, come è versionata l'API e come raggiungere una persona.

Source: https://developers.backresto.com/it/docs/support

## L'avvertenza sulla completezza, detta chiaramente

L'API Partner espone i record acquisiti **dopo che la funzionalità è stata
attivata per quel ristorante**, in ogni [collezione](https://developers.backresto.com/it/docs/collections). Non
pretende di contenere lo storico completo di un ristorante, e non lo recupererà
a posteriori. Le consegne sono l'unica eccezione: le loro due collezioni
riportano lo storico che l'app conservava ancora quando sono state aperte.

Questo conta più di quanto sembri:

- Un risultato vuoto **non** è la prova che non sia successo nulla. Può
  significare che il ristorante non era ancora attivato, oppure che un
  dispositivo non ha ancora caricato i dati.
- Un conteggio ottenuto da questa API non è un dato di conformità. Non lo stampi
  su un report che si legge come un audit.
- Se ha bisogno di conoscere la data di attivazione di un ristorante, lo chieda
  a noi o al cliente. Al momento non è esposta attraverso l'API. Se le serve
  come campo, ce lo dica e lo diventerà.

Le collezioni lo dicono nella loro stessa risposta: `stateKind` vale
`received-shadow-snapshot`, cioè lo stato che questa API ha ricevuto, non lo
stato che l'app del ristorante possiede. I due coincidono nel caso ordinario e
divergono esattamente quando un dispositivo non ha ancora caricato i dati.

Una volta che un ristorante è attivato, i record arrivano in modo affidabile,
compresi quelli acquisiti mentre un dispositivo era offline: vengono caricati
quando si riconnette, ed è per questo che
[il polling incrementale dovrebbe sovrapporsi](https://developers.backresto.com/it/docs/pagination) e per cui
`capturedAt` e `receivedAt` sono entrambi su ogni record.

## Versionamento

Ogni percorso ha il prefisso `/v1`, e **questa API è in beta chiusa.** Le chiavi
vengono rilasciate a mano, a una manciata di integratori, e la forma dell'API
non è ancora stabilita. Lo prenda alla lettera: all'interno di `/v1`, finché
dura la beta, un endpoint può cambiare forma o essere ritirato, e non
promettiamo il contrario.

Cosa significa in pratica:

- **Sia tollerante nel parsing.** Ignori i campi che non conosce anziché fallire
  su di essi; di campi se ne aggiungono spesso.
- **Tenga d'occhio gli endpoint ritirati.** Gli endpoint dedicati alle
  consegne, e lo scope che ne apriva le fotografie, non esistono più: le
  consegne si leggono come [collezioni](https://developers.backresto.com/it/docs/collections), come ogni altro
  tipo di record. Veda più sotto.
- **Ci faccia sapere che esiste.** Sappiamo quali chiavi ci hanno chiamato, e
  quando. Se la sua è in uso la contatteremo prima di spostare qualcosa sotto di
  essa, non perché la beta ci obblighi, ma perché rompere di sorpresa
  un'integrazione che funziona è un brutto modo di portarne avanti una.

Quando la beta finirà, questa sezione diventerà la promessa consueta: modifiche
additive all'interno di una versione, tutto il resto dietro `/v2`. Non è ancora
così, e dirlo le è più utile di una garanzia che dovremmo ritirare.

Il [documento OpenAPI](https://api.backresto.com/openapi.json) è generato dal
servizio in esecuzione, quindi è la descrizione autorevole di ciò che è
distribuito in questo momento. Se questa documentazione e quel documento non
concordano, ha ragione il documento e noi abbiamo una pagina da correggere. Ce
lo dica.

## Controlli di stato

Due endpoint pubblici, senza autenticazione:

| Endpoint | Significato |
| --- | --- |
| `GET /health/live` | Il processo è in esecuzione. |
| `GET /health/ready` | Il processo raggiunge il proprio database e può servire traffico. |

`/health/ready` è quello da interrogare se ci monitora. I controlli riusciti non
vengono registrati nel log di audit, quindi un sistema di monitoraggio non
aggiunge rumore.

## Ottenere aiuto

Scriva a [contact@backresto.com](mailto:contact@backresto.com). Cosa rende
rapida una risposta:

- il `requestId` del documento di problema, oppure l'`X-Request-ID` che ha
  inviato;
- il **prefisso pubblico** della sua chiave (la metà `brp_…` prima del punto,
  mai il secret);
- l'ambiente, l'endpoint e all'incirca quando.

Non ci mandi mai il secret di una chiave: il prefisso pubblico la identifica
senza ambiguità. Se un secret è finito dove non doveva, lo dica nell'oggetto e
ci invii il prefisso: la revoca è immediata, ed è tutto il rimedio. Veda
[Ottenere una chiave](https://developers.backresto.com/it/docs/access) per il resto del ciclo di vita di una
chiave.

## Chiedere di più

Quello che esiste qui esiste perché qualcuno l'ha chiesto. Temperature di
cottura e raffreddamento, piani di pulizia, etichette e un endpoint MCP ospitato
erano tutti su questa lista qualche mese fa; adesso sono
[collezioni](https://developers.backresto.com/it/docs/collections) e [un endpoint](https://developers.backresto.com/it/docs/mcp).

**Le consegne erano l'ultima voce di questa lista.** Sono state la prima cosa
servita da questa API, attraverso endpoint propri, con una forma propria e un
intervallo di tempo al posto di un cursore. Adesso sono due collezioni,
`deliveries` e `delivery-pictures`, lette attraverso lo stesso involucro, la
stessa paginazione e lo stesso `GET .../collections/{collection}/records` di
ogni altro tipo di record, e i vecchi endpoint sono stati ritirati anziché
mantenuti accanto. Un solo modo di leggere un record è il senso del
cambiamento. Se ha costruito sui vecchi endpoint, [Consegne](https://developers.backresto.com/it/docs/deliveries)
mostra la nuova forma, e siamo felici di aiutarla nel passaggio.

Cosa c'è ancora in lista: i webhook al posto del polling, un cursore
incrementale sulle collezioni, una data di attivazione sul ristorante, e
l'accesso OAuth per i client MCP che non accettano una chiave. Quale arriva per
primo lo decide chi lo chiede. Quindi lo chieda.