Visão geral

A API de exibição básica do Instagram é uma API baseada em HTTP que os apps usam para obter o perfil, as imagens, os vídeos e os álbuns de um usuário do Instagram.

Componentes

URLs de base

• api.instagram.com – para obter tokens de acesso do usuário do Instagram
• graph.instagram.com – para obter perfis e mídias do usuário do Instagram

Versões

A API é compatível com o mesmo protocolo de versões e ciclo de lançamentos da Graph API do Facebook. Lançamos novas versões a cada 3 meses, aproximadamente. Cada versão fica disponível por cerca de 2 anos até se tornar obsoleta.

Para consultar uma versão específica da API, inclua o número correspondente no caminho da consulta após a URL de base. Por exemplo:

https://graph.instagram.com/v11.0/10218560180051171/media

Se você não incluir o número da versão, a solicitação considerará a versão especificada na seção Painel de Apps > Configurações > Avançado > Atualizar a versão da API.

Janela de autorização

Com a janela de autorização, o app pode obter códigos de autorização e permissões dos usuários. É possível trocar os códigos de autorização por tokens de acesso do usuário do Instagram, que precisam ser incluídos ao consultar a mídia ou o perfil de um usuário do app.

Para implementar a janela de autorização, consulte o guia Obter tokens de acesso e permissões.

Códigos de autorização

É possível trocar códigos de autorização por tokens de acesso do usuário do Instagram de curta duração. Para obter um código, implemente a janela de autorização no app. Depois que o usuário fizer a autenticação de identidade por meio da janela e conceder as permissões necessárias, o redirecionaremos ao app e incluiremos um código de autorização. Depois, você poderá usar a API para trocar o código pelo token de acesso do usuário do Instagram de curta duração.

Os códigos de autorização têm duração curta e permanecem válidos por somente 1 hora.

Tokens de acesso do usuário do Instagram

A autenticação de API é feita pelos tokens de acesso do usuário do Instagram, que seguem o protocolo OAuth 2.0. Os tokens de acesso estão no escopo do app (único para o par de app e usuário) e podem ser de curta ou de longa duração. As solicitações de API que consultam os usuários do Instagram ou as mídias deles devem incluir um token de acesso do usuário do Instagram.

Tokens de acesso de curta duração

Os tokens de acesso de curta duração são válidos por 1 hora, mas podem ser trocados por tokens de longa duração. Para obter um token de acesso de curta duração, implemente a janela de autorização no app. Depois que o usuário fizer a autenticação de identidade pela janela, ele será redirecionado ao app, e incluiremos um código de autorização que poderá ser trocado por um token de acesso de curta duração.

Tokens de acesso de longa duração

É possível trocar tokens de curta duração não expirados por tokens de acesso de longa duração, que ficam válidos por 60 dias. Os tokens de acesso de longa duração podem ser atualizados antes de expirarem por meio de uma consulta ao ponto de extremidade GET /refresh_access_token.

Permissões

A autorização do acesso aos dados é controlada pelos usuários do app e feita por meio do uso das permissões listadas abaixo. Os usuários devem conceder essas permissões via janela de autorização para que o app possa acessar os dados.

• instagram_graph_user_profile – permite que o app leia o nó do usuário, que representa o usuário do Instagram e as bordas dos nós.
• instagram_graph_user_media – permite que o app leia o nó de mídia, que representa uma imagem, um vídeo ou um álbum, assim como as bordas do nó.

Os testadores do Instagram podem conceder essas permissões ao seu app a qualquer momento. Para que usuários sem função no app em modo publicado possam conceder essas permissões a ele, cada permissão precisa ser aprovada para acesso avançado no processo de análise do app.

As concessões de permissões feitas por usuários do app com contas públicas são válidas por 90 dias. Atualizar o token de acesso de longa duração de um usuário do app prorrogará a concessão por mais 90 dias, caso o usuário que concedeu a permissão tenha uma conta pública. No entanto, se a conta do usuário do app for privada, a concessão não poderá ser estendida, e o usuário precisará conceder a permissão ao seu app novamente.

Testadores do Instagram

Para testar o app com um usuário do Instagram, primeiro é necessário enviar um convite à conta desse usuário para que ele possa confirmar o aceite. Os convites podem ser enviados a partir da seção Testadores do Instagram na aba Painel de Apps > Funções > Funções.

Depois de acessar a própria conta, o usuário do Instagram pode aceitar os convites na seção (ícone do perfil) > Editar perfil > Aplicativos e sites > Convites do testador do site ou do app para celular do Instagram.

Recursos

Os dados na API consistem em usuários do Instagram e as respectivas mídias (imagens, vídeos e álbuns). Todos os dados são protegidos por permissões. Para que o app possa acessar os dados de um usuário, a permissão correspondente deve ser concedida via janela de autorização.

Usuários

Os usuários do Instagram e os respectivos perfis são representados por nós de usuário. Observe que os números de identificação do usuário da API antiga do Instagram são incompatíveis com a API de exibição básica do Instagram.

Mídia

As fotos, os vídeos e os álbuns são representados por nós de mídia e criados em usuários individuais.

Limites de volume

Todas as solicitações de pontos de extremidade estão sujeitas à limitação de volume da plataforma da Graph API.

É possível consultar o consumo total de chamadas na aba Painel de Apps > Instagram > Limitação de volume de exibição básica depois de adicionar o produto Instagram ao app.

Tipos de app

Os apps de negócios não são compatíveis. Caso seu app seja de negócios, use a Graph API do Instagram ou crie um de outro tipo.

Análise do app

Os testadores do Instagram podem conceder permissões do Instagram ao seu app a qualquer momento. Para que usuários sem função no app em modo publicado possam conceder permissões do Instagram a ele, cada permissão precisa ser aprovada para acesso avançado no processo de análise do app.

Quando seu app estiver concluído e pronto para entrar no modo publicado, revise as documentações sobre o processo de análise, exemplos de envio e motivos comuns para rejeição. Depois de se familiarizar com o processo, você pode solicitar a aprovação para as permissões da API de exibição básica do Instagram pela aba Painel de Apps > Produtos > Instagram > Exibição básica.

Se o único objetivo for gerar tokens de acesso via Gerador de Tokens do Usuário, não será necessário enviar o app à análise. O Gerador de Tokens do Usuário não requer nenhuma permissão e pode ser usado enquanto o app estiver no modo de desenvolvimento.

Verificação da empresa

Enquanto o app estiver no modo de desenvolvimento, ele só terá acesso aos dados das contas de testadores do Instagram. Para que seja possível colocar o app no modo publicado e acessar os dados de contas que não sejam de testadores, conclua primeiro a verificação da empresa.

Como funciona

Para usar a API, obtenha e mostre a janela de autorização a um usuário do app. O usuário autenticará a identidade com a janela e autorizará o acesso do app aos próprios dados por meio da concessão de permissões específicas. Depois da autenticação, a janela redirecionará o usuário de volta ao app e incluirá um código de autorização. Capture o código e troque-o por um token de acesso do usuário do Instagram de curta duração. Você pode usar o token de curta duração para consultar os pontos de extremidade de usuário e de mídia para obter os dados de acesso permitido pelo usuário. Como alternativa, é possível trocar esse token por outro de longa duração.

Ferramentas

Gerador de Tokens do Usuário

O Gerador de Tokens do Usuário do Instagram pode ser usado para gerar rapidamente tokens de acesso do usuário do Instagram de longa duração para qualquer conta pública da plataforma. Isso será útil caso você esteja testando um app e não queira implementar a janela de autorização, ou ainda, se estiver usando um código do tipo "copia e cola" fornecido por um serviço de terceiros (por exemplo, para exibir seus dados do Instagram no site).

A ferramenta funciona ao disparar a janela de autorização, que pode ser vinculada a uma conta pública do Instagram designada por você como uma conta de teste. Após fazer login, a ferramenta gerará um token de acesso de longa duração que pode ser copiado e colado. Observe que os tokens só podem ser gerados para contas públicas do Instagram.

Você pode acessar o gerador de tokens na aba Painel de Apps > Produtos > Instagram > Exibição básica.

Se o único objetivo for gerar tokens de acesso via Gerador de Tokens do Usuário, não será necessário enviar o app à análise. O Gerador de Tokens do Usuário não requer nenhuma permissão e pode ser usado enquanto o app estiver no modo de desenvolvimento.

Próximas etapas

Consulte nosso Guia de introdução para saber como configurar um app e fazer uma solicitação básica de API.