Supporto e completezza dei dati

L'avvertenza sulla completezza, detta chiaramente

L'API Partner espone i record acquisiti dopo che la funzionalità è stata attivata per quel ristorante — tanto le consegne quanto le collezioni. Non pretende di contenere lo storico completo di un ristorante, e non lo recupererà a posteriori.

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 l'interrogazione incrementale dovrebbe sovrapporsi e per cui capturedAt e receivedAt sono entrambi su ogni record.

Versionamento

Ogni percorso ha il prefisso /v1. All'interno di quella versione:

• aggiungeremo campi a una risposta, e
• aggiungeremo endpoint e parametri facoltativi.

Entrambe le cose sono retrocompatibili, e nessuna delle due verrà annunciata come modifica che rompe la compatibilità — quindi analizzi con indulgenza: ignori i campi che non conosce anziché fallire su di essi.

Non rimuoveremo né cambieremo il tipo di un campo, non cambieremo il significato di uno esistente e non renderemo obbligatorio un parametro facoltativo all'interno di /v1. Tutto ciò che dovesse richiederlo arriverebbe come /v2, accanto a /v1, con preavviso.

Il documento OpenAPI è 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:

/health/ready è quello da interrogare se ci monitora. Le sonde riuscite non vengono registrate nel log di audit, quindi un sistema di monitoraggio non aggiunge rumore.

Ottenere aiuto

Scriva a 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 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 e un endpoint.

Cosa c'è ancora in lista: i webhook al posto dell'interrogazione, 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.