Insta.Package 1.1.0

Codie Insta Tools

Insta.Package

Pacote C# para integração com a Instagram Graph API. Simplifique a obtenção de postagens, gerenciamento de tokens e muito mais em suas aplicações .NET.

🚀 Recursos

• Obtenção de Postagens: Recupere as últimas postagens do Instagram com suporte a paginação
• Gerenciamento de Tokens: Troque tokens de curta duração por tokens de longa duração (60 dias)
• Formatação Frontend: Respostas já formatadas para consumo em aplicações web
• Tratamento de Erros: Validação robusta e mensagens de erro claras
• Compatibilidade: .NET 8.0 e superior

📦 Instalação

dotnet add package Insta.Package

Ou via NuGet Package Manager:

Install-Package Insta.Package

🔧 Configuração

1. Registrar os serviços

// Program.cs (Minimal APIs)
builder.Services.AddHttpClient();
builder.Services.AddScoped<IInstagramService, InstagramService>();
builder.Services.AddControllers(); // Se usar os controllers

// Ou Startup.cs (ConfigureServices)
services.AddHttpClient();
services.AddScoped<IInstagramService, InstagramService>();
services.AddControllers();

2. Configurar o Controller (Opcional)

// Se desejar usar os endpoints pré-configurados
var app = builder.Build();
app.MapControllers();

📚 API Reference

Endpoints Disponíveis

GET /api/instagram/latest-posts

Obtém as últimas postagens do Instagram.

Parâmetros:

• accessToken (string, obrigatório): Token de acesso do Instagram
• limit (int, opcional): Número de postagens (padrão: 4)
• shortLivedToken (string, opcional): Token de curta duração para troca automática

Exemplo de requisição:

GET /api/instagram/latest-posts?accessToken=YOUR_ACCESS_TOKEN&limit=10

Resposta de sucesso:

{
  "success": true,
  "count": 4,
  "posts": [
    {
      "id": "17893443543998041",
      "type": "image",
      "imageUrl": "https://scontent.cdninstagram.com/v/t51.2885-15/123456789_0.jpg",
      "mediaUrl": null,
      "caption": "Linda paisagem 🌅",
      "fullCaption": "Linda paisagem 🌅 #natureza #paisagem",
      "permalink": "https://www.instagram.com/p/C123ABC/",
      "timestamp": "2024-01-15T14:30:00Z",
      "formattedDate": "15/01/2024"
    }
  ]
}

GET /api/instagram/test-connection

Testa a conexão com a API do Instagram.

Parâmetros:

• accessToken (string, obrigatório): Token de acesso para teste

Exemplo de requisição:

GET /api/instagram/test-connection?accessToken=YOUR_ACCESS_TOKEN

Resposta de sucesso:

{
  "success": true,
  "message": "Conexão com Instagram estabelecida com sucesso",
  "userId": "17841405793187218"
}

POST /api/instagram/exchange-token

Troca um token de curta duração por um de longa duração.

Parâmetros:

• shortLivedToken (string, obrigatório): Token de curta duração (1 hora)

Exemplo de requisição:

POST /api/instagram/exchange-token?shortLivedToken=YOUR_SHORT_LIVED_TOKEN

Resposta de sucesso:

{
  "success": true,
  "token": {
    "access_token": "IGLW123456789...",
    "token_type": "bearer",
    "expires_in": 5184000
  }
}

POST /api/instagram/refresh-token

Renova um token de longa duração.

Parâmetros:

• longLivedToken (string, obrigatório): Token de longa duração existente

Exemplo de requisição:

POST /api/instagram/refresh-token?longLivedToken=YOUR_LONG_LIVED_TOKEN

Resposta de sucesso:

{
  "success": true,
  "token": {
    "access_token": "IGLW987654321...",
    "token_type": "bearer",
    "expires_in": 5184000
  }
}

💻 Exemplos de Uso

Usando o serviço diretamente

using Instagram.Interfaces;
using Instagram.Dtos.Instagram;

public class InstagramService
{
    private readonly IInstagramService _instagramService;

    public InstagramService(IInstagramService instagramService)
    {
        _instagramService = instagramService;
    }

    public async Task<InstagramResponseDto> GetLatestPostsAsync(string accessToken)
    {
        try
        {
            var posts = await _instagramService.GetLatestPostsJsonAsync(
                accessToken: accessToken,
                limit: 10
            );

            return posts;
        }
        catch (Exception ex)
        {
            // Tratar erro
            throw new InvalidOperationException("Erro ao obter postagens", ex);
        }
    }

    public async Task<string> GetUserIdAsync(string accessToken)
    {
        return await _instagramService.GetUserIdAsync(accessToken);
    }

    public async Task<InstagramLongLivedTokenResponse> ExchangeTokenAsync(string shortLivedToken)
    {
        return await _instagramService.ExchangeForLongLivedTokenAsync(shortLivedToken);
    }

    public async Task<InstagramLongLivedTokenResponse> RefreshTokenAsync(string longLivedToken)
    {
        return await _instagramService.RefreshLongLivedTokenAsync(longLivedToken);
    }
}

Exemplo com Controller personalizado

[ApiController]
[Route("api/[controller]")]
public class MyInstagramController : ControllerBase
{
    private readonly IInstagramService _instagramService;

    public MyInstagramController(IInstagramService instagramService)
    {
        _instagramService = instagramService;
    }

    [HttpGet("posts")]
    public async Task<IActionResult> GetPosts([FromQuery] string accessToken)
    {
        try
        {
            var result = await _instagramService.GetLatestPostsJsonAsync(
                accessToken: accessToken,
                limit: 5
            );

            return Ok(result);
        }
        catch (ArgumentException ex)
        {
            return BadRequest(new { success = false, message = ex.Message });
        }
        catch (Exception ex)
        {
            return StatusCode(500, new { 
                success = false, 
                message = "Erro ao processar requisição",
                details = ex.Message 
            });
        }
    }
}

🔐 Segurança e Boas Práticas

1. Armazenamento de Tokens

• Nunca exponha tokens em código-fonte
• Use variáveis de ambiente ou serviços de segredos
• Considere usar Azure Key Vault, AWS Secrets Manager, etc.

2. Validação de Tokens

• Sempre valide tokens antes de usar
• Implemente tratamento de expiração
• Use o endpoint test-connection para verificar validade

3. Rate Limiting

• Respeite os limites da API do Instagram
• Implemente cache para reduzir chamadas
• Monitore erros de rate limiting

📝 Modelos de Dados

InstagramPostDto

public class InstagramPostDto
{
    public string Id { get; set; }           // ID único da postagem
    public string Type { get; set; }         // "image", "video", "carousel"
    public string ImageUrl { get; set; }     // URL da imagem principal
    public string MediaUrl { get; set; }     // URL do vídeo (se aplicável)
    public string Caption { get; set; }      // Legenda truncada
    public string FullCaption { get; set; }  // Legenda completa
    public string Permalink { get; set; }    // URL do post no Instagram
    public DateTime? Timestamp { get; set; } // Data de publicação
    public string FormattedDate { get; set; } // Data formatada (dd/MM/yyyy)
}

InstagramLongLivedTokenResponse

public class InstagramLongLivedTokenResponse
{
    public string AccessToken { get; set; }   // Token de acesso
    public string TokenType { get; set; }    // "bearer"
    public int ExpiresIn { get; set; }       // Tempo até expiração (segundos)
}

🚨 Tratamento de Erros

Códigos de Status HTTP

• 200 OK: Requisição bem-sucedida
• 400 Bad Request: Parâmetros inválidos ou token ausente
• 500 Internal Server Error: Erro interno ou falha na API do Instagram

Respostas de Erro

{
  "success": false,
  "message": "Token de acesso do Instagram não foi fornecido."
}

{
  "success": false,
  "message": "Erro ao obter postagens",
  "details": "OAuthAccessTokenException: Invalid OAuth access token"
}

🔄 Fluxo de Autenticação

1. Obtenha um Short-Lived Token (1 hora de validade)

   • Use o OAuth 2.0 do Instagram
   • Redirecione o usuário para autenticação

2. Troque por Long-Lived Token (60 dias de validade)

   var longLivedToken = await _instagramService.ExchangeForLongLivedTokenAsync(shortLivedToken);
   

3. Use o Long-Lived Token nas chamadas da API

   var posts = await _instagramService.GetLatestPostsJsonAsync(longLivedToken, 10);
   

4. Renove antes de expirar (opcional)

   var renewedToken = await _instagramService.RefreshLongLivedTokenAsync(longLivedToken);
   

📋 Requisitos

• .NET 8.0 ou superior
• HttpClient configurado
• Token de acesso válido da Instagram Graph API

🤝 Contribuição

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🆘 Suporte

• 📧 Email: codiebackend@gmail.com
• 🐛 Issues: GitHub Issues

Desenvolvido com ❤️ por CodieDigital