# Obter uma chave

> Como pedir uma chave da API de Parceiros, o que incluir no pedido e o que recebe de volta.

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

As chaves de parceiro são emitidas manualmente. Preencha o formulário abaixo
(ou escreva-nos por email, que chega às mesmas pessoas) e nós criamos a
credencial e enviamo-la ao contacto que indicar.

Há uma pessoa a ler cada pedido, porque uma chave dá acesso aos registos de
conformidade de um restaurante e o restaurante tem de ter concordado. O que
isso lhe custa é uma resposta em vez de um redirecionamento; o que ganha com
isso é que ninguém consegue emitir para si próprio acesso aos dados de outra
pessoa. O formulário pede tudo aquilo de que precisamos para agir de uma só
vez.

## Quem pode pedir

Qualquer um dos lados, mas o restaurante tem sempre de concordar.

- **Você, o integrador.** Diga de que restaurantes precisa e indique o seu
  contacto nesses restaurantes; confirmamos com eles antes de emitir seja o que
  for.
- **O restaurante.** Pedem em seu nome e indicam-no. Este é o caminho mais
  rápido, porque a confirmação já aconteceu.

Não emitimos uma chave para um restaurante que não tenha concordado, e não
alargamos uma chave existente sem lhes voltar a perguntar.

## Pedir uma chave

To request a key, write to contact@backresto.com or fill in the form at https://developers.backresto.com/pt/docs/access. Name the company, the product that will call the API, a technical contact, the restaurants and the scopes you need.

Se está a integrar para vários restaurantes que pertencem a clientes
diferentes, envie um pedido por cliente. Uma chave por cliente evita que uma
revogação deite abaixo todas as outras integrações que mantém.

Dois dos campos merecem uma nota. O **ambiente** conta porque as chaves e os
dados são por ambiente: uma chave de produção não significa nada em
pré-produção, por isso diga se quer começar por desenvolver em pré-produção. E
os **scopes** devem ser aquilo que usa, em vez de tudo: são vinte e seis, um
por [coleção](https://developers.backresto.com/pt/docs/collections), incluindo as entregas e as suas fotografias, e
o restaurante lê a lista antes de concordar com ela. Indicar os quatro de que
precisa consegue um sim mais rápido do que pedi-los todos; veja
[Autenticação](https://developers.backresto.com/pt/docs/authentication) para saber o que cada um abre.

Já tem uma chave e quer uma coleção que ela não alcança? É o mesmo email, e é
um alargamento e não uma chave nova: o seu segredo não muda e não é preciso
reimplantar nada.

Prefere escrever você mesmo? [contact@backresto.com](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)
com os mesmos dados chega à mesma caixa de correio.

## O que recebe de volta

Um único valor, com o formato `brp_<prefix>.<secret>`, enviado ao contacto
técnico que indicou.

**Guarde-o assim que chegar e apague o email.** Guardamos apenas o prefixo
público e um resumo criptográfico do segredo, por isso não o podemos reenviar.
Se se perder, revogamos essa chave e emitimos uma nova, o que significa mais
uma ida e volta.

As chaves não expiram por si próprias. Mantêm-se válidas até serem revogadas, e
é por isso que a resposta a «saiu alguém da equipa» é uma rotação, não um
encolher de ombros.

## Alterar uma chave mais tarde

Tudo isto se resolve por email, e tudo isto precisa do acordo do restaurante
sempre que alargue o acesso:

| Pedido | O que acontece |
| --- | --- |
| **Acrescentar um restaurante ou um scope** | Alargamos a chave existente. O seu segredo não muda e não é preciso reimplantar nada. |
| **Rodar** | Emitimos primeiro uma segunda chave, você implanta-a, e só depois revogamos a antiga. Não há qualquer janela em que nenhuma funcione. |
| **Revogar** | Imediato. O pedido seguinte com essa chave responde `401`. |
| **Uma chave temporária** | Diga-o no pedido. Para uma auditoria pontual ou uma prova de conceito, uma chave que morre sozinha é mais segura do que uma que se tem de lembrar de matar. |

Para o que for urgente (sobretudo um segredo exposto), escreva para
[contact@backresto.com](mailto:contact@backresto.com?subject=Urgent%3A%20revoke%20Partner%20API%20key)
com o **prefixo público** da chave (a metade `brp_…` antes do ponto) e diga que
é urgente. Nunca nos envie o próprio segredo, nem sequer para provar de que
chave está a falar.

## Enquanto espera

Nada [na documentação](https://developers.backresto.com/pt/docs) precisa de uma chave para ser lido, e os formatos
estão todos nestas páginas: [o registo de entrega e as suas
fotografias](https://developers.backresto.com/pt/docs/deliveries),
[as coleções e os registos](https://developers.backresto.com/pt/docs/collections), [o modelo de erros](https://developers.backresto.com/pt/docs/errors)
e [a paginação](https://developers.backresto.com/pt/docs/pagination). O
[documento OpenAPI](https://api.backresto.com/openapi.json) também é público,
por isso pode gerar um cliente e começar a escrever código antes de a chave
chegar.