# Suporte e completude dos dados

> O que os dados atuais cobrem e não cobrem, como a API é versionada, e como falar com uma pessoa.

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

## A ressalva sobre a completude, dita sem rodeios

A API de Parceiros expõe os registos capturados **depois de a funcionalidade ter
sido ativada para esse restaurante**, em todas as
[coleções](https://developers.backresto.com/pt/docs/collections). Não pretende ter o histórico completo de um
restaurante, e não o vai recuperar. As entregas são a única exceção: as suas
duas coleções trazem o histórico que a aplicação ainda tinha quando foram
abertas.

Isto importa mais do que parece:

- Um resultado vazio **não** é prova de que nada aconteceu. Pode significar que
  o restaurante ainda não estava ativado, ou que um dispositivo ainda não
  carregou os dados.
- Uma contagem obtida nesta API não é um número de conformidade. Não a imprima
  num relatório que se leia como uma auditoria.
- Se precisar de saber a data de ativação de um restaurante, pergunte-nos ou
  pergunte ao cliente. De momento não está exposta na API. Se precisar dela
  como campo, diga-nos e passa a existir.

As coleções dizem-no na própria resposta: o `stateKind` é
`received-shadow-snapshot`, ou seja, o estado que esta API recebeu, não o estado
que a aplicação do restaurante tem. Os dois coincidem no caso normal e divergem
exatamente quando um dispositivo ainda não carregou os dados.

Depois de um restaurante estar ativado, os registos chegam de forma fiável,
incluindo os que foram capturados enquanto um dispositivo estava offline: esses
são carregados quando ele volta a ligar-se, e é por isso que
[as consultas incrementais devem sobrepor-se](https://developers.backresto.com/pt/docs/pagination) e que
`capturedAt` e `receivedAt` estão ambos em todos os registos.

## Versionamento

Todos os caminhos têm o prefixo `/v1`, e **esta API está em beta fechada.** As
chaves são emitidas à mão, a um punhado de integradores, e a forma da API ainda
está a ser decidida. Leia isto à letra: dentro de `/v1`, enquanto durar a beta,
um endpoint pode mudar de forma ou ser retirado, e não prometemos o contrário.

O que isso quer dizer na prática:

- **Analise as respostas com tolerância.** Ignore os campos que não conhece em
  vez de falhar por causa deles; acrescentam-se campos com frequência.
- **Esteja atento aos endpoints retirados.** Os endpoints dedicados às
  entregas, e o scope que abria as suas fotografias, desapareceram: as entregas
  leem-se como [coleções](https://developers.backresto.com/pt/docs/collections), tal como qualquer outro tipo de
  registo. Veja mais abaixo.
- **Diga-nos que existe.** Sabemos que chaves nos chamaram, e quando. Se a sua
  estiver a ser usada, falamos consigo antes de mexer no que quer que seja por
  baixo dela, não porque a beta nos obrigue, mas porque partir de surpresa uma
  integração que funciona é uma má maneira de a conduzir.

Quando a beta terminar, esta secção passa a ser a promessa do costume:
alterações aditivas dentro de uma versão, tudo o resto atrás de `/v2`. Ainda não
é isso, e dizê-lo é-lhe mais útil do que uma garantia que teríamos de retirar.

O [documento OpenAPI](https://api.backresto.com/openapi.json) é gerado a partir
do serviço em execução, por isso é a descrição que faz fé sobre aquilo que está
implantado neste momento. Se esta documentação e esse documento estiverem em
desacordo, o documento é que está certo e nós temos uma página para corrigir.
Diga-nos, por favor.

## Verificações de estado

Dois endpoints públicos, sem autenticação:

| Endpoint | Significado |
| --- | --- |
| `GET /health/live` | O processo está a correr. |
| `GET /health/ready` | O processo consegue chegar à base de dados e servir tráfego. |

`/health/ready` é o que deve consultar se nos monitorizar. As sondagens
bem-sucedidas não são registadas na auditoria, por isso um monitor não
acrescenta ruído.

## Obter ajuda

Escreva para [contact@backresto.com](mailto:contact@backresto.com). O que torna
uma resposta rápida:

- o `requestId` do documento de problema, ou o `X-Request-ID` que enviou;
- o **prefixo público** da sua chave (a metade `brp_…` antes do ponto, nunca o
  segredo);
- o ambiente, o endpoint e mais ou menos quando foi.

Nunca nos envie o segredo de uma chave: o prefixo público identifica-a sem
ambiguidade. Se um segredo foi parar a um sítio onde não devia, diga-o na linha
de assunto e envie o prefixo: a revogação é imediata, e é essa a solução por
inteiro. Veja [Obter uma chave](https://developers.backresto.com/pt/docs/access) para o resto do ciclo de vida de
uma chave.

## Pedir mais

O que existe aqui existe porque alguém o pediu. As temperaturas de confeção e de
arrefecimento, os planos de limpeza, as etiquetas e um endpoint MCP alojado
estavam todos nesta lista há uns meses; são agora
[coleções](https://developers.backresto.com/pt/docs/collections) e [um endpoint](https://developers.backresto.com/pt/docs/mcp).

**As entregas foram o último ponto desta lista.** Foram a primeira coisa que
esta API serviu, através dos seus próprios endpoints, com a sua própria forma e
um intervalo de tempo em vez de um cursor. São agora duas coleções,
`deliveries` e `delivery-pictures`, lidas através do mesmo envelope, da mesma
paginação e do mesmo `GET .../collections/{collection}/records` que qualquer
outro tipo de registo, e os antigos endpoints foram retirados em vez de
mantidos ao lado: o objetivo da mudança é haver uma só maneira de ler um
registo. Se construiu sobre os antigos endpoints, a página
[Entregas](https://developers.backresto.com/pt/docs/deliveries) mostra a nova forma, e teremos todo o gosto em
ajudá-lo a migrar.

O que continua nela: webhooks em vez de consultas, um cursor incremental nas
coleções, uma data de ativação no restaurante, e o início de sessão OAuth para
os clientes MCP que não aceitam uma chave. Qual delas vem a seguir é decidido
por quem pede. Por isso peça.