IWebhookPartitionsApi

Visão Geral

A interface IWebhookPartitionsApi fornece acesso completo ao gerenciamento de partições e mensagens do sistema de webhooks. Esta API permite listar, monitorar, fazer retry e cancelar partições e suas respectivas mensagens.

Endpoints Disponíveis

📋 Listagem e Consulta

• GetPartitionsAsync - Lista partições com filtros
• GetMessagesAsync - Lista mensagens de uma partição
• GetStatusCountAsync - Estatísticas de status das partições

🔄 Operações de Controle

• RetryMessagesAsync - Reprocessa mensagens falhadas
• CancelEventsAsync - Cancela eventos específicos
• CancelPartitionsAsync - Cancela partições inteiras

---

GetPartitionsAsync

Lista partições com opções de filtro e paginação.

Assinatura

IWebhookPartitionsApi.cs

Task<List<PartitionDto>> GetPartitionsAsync(
    [Query] GetPartitionsParams? requestParams = null,
    CancellationToken cancellationToken = default
);

Parâmetros

GetPartitionsParams

public class GetPartitionsParams
{
    public int? Limit { get; set; }     // Limite de resultados (padrão: sem limite)
    public int? Offset { get; set; }    // Offset para paginação (padrão: 0)
    public string? Status { get; set; } // Filtro por status: "active", "cancelled", "completed"
}

Retorno

public class PartitionDto
{
    public int Id { get; set; }                    // ID único da partição
    public string Status { get; set; }             // Status atual
    public int MessageCount { get; set; }          // Quantidade de mensagens
    public DateTime CreatedAt { get; set; }        // Data de criação
    public DateTime? UpdatedAt { get; set; }       // Última atualização
}

Exemplos de Uso

// Listar todas as partições ativas
var activePartitions = await partitionsApi.GetPartitionsAsync(new GetPartitionsParams
{
    Status = "active",
    Limit = 50
});

// Paginação
var nextPage = await partitionsApi.GetPartitionsAsync(new GetPartitionsParams
{
    Limit = 20,
    Offset = 20
});

// Todas as partições (sem filtros)
var allPartitions = await partitionsApi.GetPartitionsAsync();

Status HTTP

• 200 OK: Lista de partições retornada com sucesso
• 400 Bad Request: Parâmetros inválidos
• 401 Unauthorized: API Key inválida
• 500 Internal Server Error: Erro interno do servidor

---

GetMessagesAsync

Recupera mensagens de uma partição específica com opções de filtro.

Assinatura

Task<List<MessageDto>> GetMessagesAsync(
    int partitionId,
    [Query] GetMessagesParams? requestParams = null,
    CancellationToken cancellationToken = default
);

Parâmetros

GetMessagesParams

public class GetMessagesParams
{
    public int? Limit { get; set; }        // Limite de resultados
    public int? Offset { get; set; }       // Offset para paginação
    public string? Status { get; set; }    // Filtro por status: "pending", "processing", "completed", "failed"
    public DateTime? StartDate { get; set; } // Data inicial do filtro
    public DateTime? EndDate { get; set; }   // Data final do filtro
}

Retorno

public class MessageDto
{
    public int Id { get; set; }                    // ID único da mensagem
    public int PartitionId { get; set; }           // ID da partição pai
    public string Status { get; set; }             // Status atual da mensagem
    public string EventType { get; set; }          // Tipo do evento
    public object Data { get; set; }               // Payload da mensagem
    public DateTime CreatedAt { get; set; }        // Data de criação
    public DateTime? ProcessedAt { get; set; }     // Data de processamento
    public string? ErrorMessage { get; set; }      // Mensagem de erro (se houver)
    public int RetryCount { get; set; }            // Número de tentativas
}

Exemplos de Uso

// Buscar mensagens falhadas de uma partição
var failedMessages = await partitionsApi.GetMessagesAsync(123, new GetMessagesParams
{
    Status = "failed",
    Limit = 100
});

// Mensagens de um período específico
var recentMessages = await partitionsApi.GetMessagesAsync(123, new GetMessagesParams
{
    StartDate = DateTime.UtcNow.AddHours(-24),
    EndDate = DateTime.UtcNow,
    Status = "completed"
});

// Todas as mensagens de uma partição
var allMessages = await partitionsApi.GetMessagesAsync(123);

Status HTTP

• 200 OK: Lista de mensagens retornada com sucesso
• 400 Bad Request: Parâmetros inválidos
• 404 Not Found: Partição não encontrada
• 401 Unauthorized: API Key inválida

---

RetryMessagesAsync

Força o reprocessamento de mensagens específicas que falharam.

Assinatura

Task RetryMessagesAsync(
    [Body] RetryMessagesDto retryMessagesDto,
    CancellationToken cancellationToken = default
);

Parâmetros

public class RetryMessagesDto
{
    public List<int> MessageIds { get; set; } = new(); // IDs das mensagens para retry
}

Exemplos de Uso

// Retry de mensagens específicas
await partitionsApi.RetryMessagesAsync(new RetryMessagesDto
{
    MessageIds = new List<int> { 1001, 1002, 1003 }
});

// Retry baseado em busca prévia
var failedMessages = await partitionsApi.GetMessagesAsync(123, new GetMessagesParams
{
    Status = "failed"
});

var messageIds = failedMessages.Where(m => m.RetryCount < 3)
                              .Select(m => m.Id)
                              .ToList();

await partitionsApi.RetryMessagesAsync(new RetryMessagesDto
{
    MessageIds = messageIds
});

Status HTTP

• 200 OK: Mensagens enfileiradas para retry com sucesso
• 400 Bad Request: Lista de IDs inválida
• 404 Not Found: Uma ou mais mensagens não encontradas
• 401 Unauthorized: API Key inválida

---

CancelEventsAsync

Cancela eventos/mensagens específicos, impedindo seu processamento.

Assinatura

Task CancelEventsAsync(
    [Body] CancelEventsDto cancelEventsDto,
    CancellationToken cancellationToken = default
);

Parâmetros

public class CancelEventsDto
{
    public List<int> EventIds { get; set; } = new(); // IDs dos eventos para cancelar
}

Exemplos de Uso

// Cancelar eventos específicos
await partitionsApi.CancelEventsAsync(new CancelEventsDto
{
    EventIds = new List<int> { 2001, 2002, 2003 }
});

// Cancelar mensagens antigas
var oldMessages = await partitionsApi.GetMessagesAsync(123, new GetMessagesParams
{
    EndDate = DateTime.UtcNow.AddDays(-7), // Mais de 7 dias
    Status = "pending"
});

await partitionsApi.CancelEventsAsync(new CancelEventsDto
{
    EventIds = oldMessages.Select(m => m.Id).ToList()
});

Status HTTP

• 200 OK: Eventos cancelados com sucesso
• 400 Bad Request: Lista de IDs inválida
• 404 Not Found: Um ou mais eventos não encontrados
• 401 Unauthorized: API Key inválida

---

CancelPartitionsAsync

Cancela partições inteiras, incluindo todas as suas mensagens pendentes.

Assinatura

Task CancelPartitionsAsync(
    [Body] CancelPartitionsDto cancelPartitionsDto,
    CancellationToken cancellationToken = default
);

Parâmetros

public class CancelPartitionsDto
{
    public List<int> PartitionIds { get; set; } = new(); // IDs das partições para cancelar
}

Exemplos de Uso

// Cancelar partições específicas
await partitionsApi.CancelPartitionsAsync(new CancelPartitionsDto
{
    PartitionIds = new List<int> { 10, 11, 12 }
});

// Cancelar partições ativas antigas
var oldPartitions = await partitionsApi.GetPartitionsAsync(new GetPartitionsParams
{
    Status = "active"
});

var oldPartitionIds = oldPartitions
    .Where(p => p.CreatedAt < DateTime.UtcNow.AddDays(-30))
    .Select(p => p.Id)
    .ToList();

if (oldPartitionIds.Any())
{
    await partitionsApi.CancelPartitionsAsync(new CancelPartitionsDto
    {
        PartitionIds = oldPartitionIds
    });
}

Status HTTP

• 200 OK: Partições canceladas com sucesso
• 400 Bad Request: Lista de IDs inválida
• 404 Not Found: Uma ou mais partições não encontradas
• 401 Unauthorized: API Key inválida

---

GetStatusCountAsync

Obtém estatísticas de contagem por status das partições em um período.

Assinatura

Task<List<StatusCountDto>> GetStatusCountAsync(
    [Query] GetPartitionStatusCount? requestParams = null,
    CancellationToken cancellationToken = default
);

Parâmetros

public class GetPartitionStatusCount
{
    public DateTime? StartDate { get; set; } // Data inicial do período
    public DateTime? EndDate { get; set; }   // Data final do período
}

Retorno

public class StatusCountDto
{
    public string Status { get; set; } = string.Empty; // Status da partição
    public int Count { get; set; }                      // Quantidade de partições
}

Exemplos de Uso

// Estatísticas dos últimos 7 dias
var weekStats = await partitionsApi.GetStatusCountAsync(new GetPartitionStatusCount
{
    StartDate = DateTime.UtcNow.AddDays(-7),
    EndDate = DateTime.UtcNow
});

foreach (var stat in weekStats)
{
    Console.WriteLine($"{stat.Status}: {stat.Count} partições");
}

// Estatísticas de todo o período
var allStats = await partitionsApi.GetStatusCountAsync();

// Estatísticas de um mês específico
var monthStats = await partitionsApi.GetStatusCountAsync(new GetPartitionStatusCount
{
    StartDate = new DateTime(2024, 1, 1),
    EndDate = new DateTime(2024, 1, 31)
});

Status HTTP

• 200 OK: Estatísticas retornadas com sucesso
• 400 Bad Request: Parâmetros de data inválidos
• 401 Unauthorized: API Key inválida

---

Tratamento de Erros

try
{
    var partitions = await partitionsApi.GetPartitionsAsync();
}
catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
{
    Console.WriteLine("Recurso não encontrado");
}
catch (ApiException ex) when (ex.StatusCode == HttpStatusCode.Unauthorized)
{
    Console.WriteLine("Chave de API inválida");
}
catch (ApiException ex)
{
    Console.WriteLine($"Erro da API: {ex.StatusCode} - {ex.Content}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Erro de rede: {ex.Message}");
}

---

Filtros e Status Disponíveis

Status de Partições

• active: Partições ativas processando mensagens
• completed: Partições que finalizaram o processamento
• cancelled: Partições canceladas manualmente

Status de Mensagens

• pending: Mensagens aguardando processamento
• processing: Mensagens sendo processadas no momento
• completed: Mensagens processadas com sucesso
• failed: Mensagens que falharam no processamento