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, em todas as coleções. 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 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, 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 é 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:

/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.

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 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.