Suporte e completude dos dados

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 — tanto as entregas como as coleções. Não pretende ter o histórico completo de um restaurante, e não o vai recuperar.

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 e que capturedAt e receivedAt estão ambos em todos os registos.

Versionamento

Todos os caminhos têm o prefixo /v1. Dentro dessa versão, iremos:

• acrescentar campos a uma resposta, e
• acrescentar endpoints e parâmetros opcionais.

Ambas as coisas são retrocompatíveis, e nenhuma será anunciada como uma alteração incompatível — por isso analise as respostas com tolerância: ignore os campos que não conhece em vez de falhar por causa deles.

Não vamos remover nem mudar o tipo de um campo, mudar o significado de um campo existente, nem tornar obrigatório um parâmetro opcional dentro de /v1. O que precisasse disso chegaria como /v2, a par de /v1, com aviso prévio.

O documento OpenAPI é gerado a partir do serviço em execução, por isso é a descrição autoritativa daquilo 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:

/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. 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 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 e um endpoint.

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.