O iFood fornece dois fluxos de autorização para que o seu aplicativo seja capaz de acessar recursos das lojas: o fluxo de credencial de aplicativo e o fluxo de código de autorização. Através desses fluxos, seu aplicativo será capaz de adquirir um token de acesso e assim ser capaz de consumir as nossas APIs.

Fluxo de credencial de aplicativo

O fluxo de credencial de aplicativo é destinado a aplicativos internos/privados, que não são acessíveis diretamente pela internet. Tais aplicativos também devem ser capazes de armazenar a chave secreta no seu servidor com segurança. Um exemplo de aplicativo apropriado para esse fluxo são aplicativos que rodam dentro de uma VPC sem acesso externo, como um servidor que expõem APIs com base nas APIs do iFood.

No fluxo de credencial de aplicativo, para autenticar seu aplicativo e ser capaz de usar nossas APIs, você precisará de uma credencial de aplicativo. A credencial de aplicativo pode ser obtida via Portal do Desenvolvedor (no menu Meus Apps, aba Credenciais do aplicativo selecionado).

• O clientId representa a identificação única do cliente (nesse caso o aplicativo);
• O clientSecret é a chave secreta utilizada para obter um novo token de acesso. Essa chave não pode ser exposta e deve ser armazenada de forma segura.

As etapas do fluxo de credencial de aplicativo são apresentadas no diagrama abaixo. Detalhes de cada etapa são encontrados nas subseções posteriores.

Passo a passo

1. Solicita o token de acesso enviando as credenciais do aplicativo

Após a criação do aplicativo no Portal do Desenvolvedor, o aplicativo deve usar seu clientId e clientSecret para solicitação de um token de acesso via a nossa API de token.

2. Aplicativo recebe token de acesso

A resposta da API de token conterá o token de acesso para consumo de nossas APIs. Não geramos refresh tokens para aplicativos centralizados. Mais informações podem ser encontradas em nossa FAQ.

3. Aplicativo usa token para acessar recursos das lojas via as APIs do iFood

Uma vez que o token de acesso é obtido, você poderá utilizá-lo via autenticação HTTP do tipo Bearer.

Na prática

O fluxo de credencial de aplicativo é utilizado para aplicativos centralizados. O passo a passo prático da autenticação via fluxo de credenciais de aplicativo também se encontra no nosso canal para a pessoa desenvolvedora, apresentado abaixo.

Fluxo de código de autorização

O fluxo de código de autorização é destinado a aplicativos públicos que são acessíveis via internet. Esse fluxo não depende apenas de uma credencial de aplicativo. Em outras palavras, esse fluxo exige que a pessoa que tenha acesso aos recursos da loja seja capaz de se autenticar via Portal do Parceiro e delegar a autorização solicitada pelo aplicativo. O fluxo de código de autorização é apresentado no diagrama abaixo. Detalhes de cada etapa são encontrados nas subseções posteriores.

Passo a passo

1. Solicita código de vínculo

O primeiro passo é solicitar um código de vínculo. Esse código de vínculo é obtido via nossa API de geração de código de vínculo e deve ser a primeira requisição que o aplicativo realiza. Esse código de vínculo representa um alias para seu aplicativo. Posteriormente, esse código é utilizado no Portal do Parceiro pela pessoa dona da loja para que assim ela seja capaz de autorizar seu aplicativo a acessar os recursos da loja da mesma.

2. Recebe código de vínculo de código verificador

Além do código de vínculo, apresentado anteriormente, a mesma API de código de vínculo também retorna o código verificador. Esse código serve para aumentar a segurança na requisição do token de acesso. Logo, o aplicativo precisa manter esse código de forma segura até chegar ao passo de obtenção do token, que depende do código verificador para ser gerado.

3. Usa código de vínculo no Portal do Parceiro

Seu aplicativo deve ser capaz de mostrar o código de vínculo e a URL de verificação para as pessoas usuárias para que assim elas sejam capazes de digitar esse código no portal do parceiro. Ao digitar o código de vínculo, a pessoa poderá autorizar (ou não) o acesso de seu aplicativo aos recursos da loja.

4. Após autorizar o aplicativo, o código de autorização é digitado no aplicativo

Uma vez que seu aplicativo é autorizado pela pessoa dona da loja, a pessoa receberá um código de autorização no próprio Portal do Parceiro. Esse código deverá ser digitado no seu aplicativo para que assim, posteriormente, o aplicativo seja capaz de solicitar um token de acesso.

5. Solicita token de acesso com código de autorização e código verificador

Uma vez que seu aplicativo obtém o código de autorização, que é digitado pela pessoa dona da loja, seu aplicativo deve enviar não somente o código de autorização, mas também o código de verificação, obtido anteriormente junto do código de vínculo, para a nossa API de token

6. Aplicativo recebe token de acesso e refresh token

Uma vez que o código de autorização e o código de verificação são válidos, seu aplicativo obterá não somente o token de acesso, mas também, o refresh token. Para que a pessoa usuária não precise passar pelos passos anteriores quando o token de acesso expirar, é necessário que o aplicativo seja capaz de usar o refresh token posteriormente e assim obter um novo token de acesso.

7. Aplicativo usa token para acessar recursos das lojas via as APIs do iFood

Uma vez que o token de acesso é obtido, você poderá utilizá-lo via autenticação HTTP do tipo Bearer.

8. Aplicativo atualiza o token de acesso com o refresh token

Antes do token de acesso expirar, você deve atualizá-lo chamando a API de token com o grantType refresh_token, as credenciais clientId e clientSecret e o refresh token obtido no passo 6.

Na prática

O fluxo de código de autorização é utilizado para aplicativos distribuídos. O passo a passo prático da autenticação via fluxo de código de autorização também se encontra no nosso canal para a pessoa desenvolvedora, apresentado abaixo.

Validar permissões

Sempre que o seu aplicativo recebe uma nova permissão de algum merchant, é necessário solicitar um novo token para que o seu novo access_token tenha permissão nesse merchant recém adicionado.

Depois de gerar esse novo access_token, caso seu aplicativo tenha permissão no módulo merchant você pode fazer uma consulta no endpoint de listagem de merchants para validar se o seu novo access_token possui permissão no novo merchant.

Expiração de códigos e tokens

Ao solicitar um código (de vínculo ou de autorização) ou token (de acesso ou refresh) com sucesso, o retorno conterá não somente o código ou token, mas também um atributo expiresIn, que representa o período de validade do retorno. A tabela abaixo apresenta os tempos de expiração padrões de cada token e código.

É importante ressaltar que os tokens e códigos são válidos apenas durante esse período de tempo. No caso dos códigos, deverão ser gerados novamente após esse período. Já no caso dos tokens, se o token de acesso expirar e o meio de autorização fornecer o refresh token, basta usá-lo para renovar o token de acesso. Já caso o refresh token expire, será necessário a criação de um novo token via endpoint de token.

Assim que o token de acesso expirar, todas as chamadas que o utilizam retornarão o status 401, o que indica que o mesmo deve ser renovado.