AF.BackEnd.Integrations 1.0.2

AF.BackEnd.Integrations

Cliente HTTP centralizado para consumir servicios de terceros desde los backends de Apoyo Financiero, con reintentos, circuit breaker y autenticación por request ya resueltos.

Getting Started

1. Proceso de instalación
2. Software dependencies
3. Cómo usarlo?
4. API references

⚙️ Proceso de instalación:

Instale el nuget usando el siguiente comando.

.NET Cli

dotnet add package AF.BackEnd.Integrations --version 1.0.2

Nuget

NuGet\Install-Package AF.BackEnd.Integrations -Version 1.0.2

Package reference

<PackageReference Include="AF.BackEnd.Integrations" Version="1.0.2" />

🛠️Dependencias

net10.0

• Microsoft.Extensions.Http.Resilience [9.4.0]
• Microsoft.Extensions.Options.ConfigurationExtensions [10.0.0]

✈️ Cómo usarlo?

El paquete resuelve un problema concreto: cada backend que consume AF.BackEnd.Notifications (u otro tercero HTTP interno) terminaba con su propia implementación de cliente, divergente en contrato, payload y sin política de reintentos. AF.BackEnd.Integrations centraliza eso.

1️⃣ Consumir AF.BackEnd.Notifications

Program.cs

Registrar con AddAFNotifications, indicando la sección de configuración que la app decide (el paquete no impone ningún nombre fijo).

using AF.BackEnd.Integrations.Http.Notifications;
            ⁝
    builder.Services.AddAFNotifications(builder.Configuration, "AFIntegrations:Notifications");
            ⁝

{
  "AFIntegrations": {
    "Notifications": {
      "BaseUrl": "https://notifications.internal/api/v1.0/",
      "ServiceToken": "...",
      "Retry": { "MaxRetryAttempts": 3, "TimeoutPerAttemptSeconds": 10 },
      "CircuitBreaker": { "FailureRatio": 0.5, "SamplingDurationSeconds": 30 }
    }
  }
}

Retry y CircuitBreaker son opcionales: si se omiten en la configuración, el paquete aplica sus propios valores por defecto para Notifications (nunca queda sin resiliencia).

Consumir

public sealed class ServicioSolicitudes(INotificationsClient notificationsClient)
{
    public Task NotificarAsync(string email, CancellationToken cancellationToken) =>
        notificationsClient.SendMailAsync(
            "AcuerdoGenerado",
            email,
            new Dictionary<string, string> { ["Cliente.Nombre"] = "Juan" },
            cancellationToken);
}

API

Comportamiento que conviene conocer

SendMailAsync nunca lanza. Errores HTTP (4xx/5xx) y de transporte (HttpRequestException, timeout) se loguean con ILogger<NotificationsClient> y el método retorna. Si el caller necesita saber si el envío falló, tiene que instrumentarlo aparte (métricas, logs), no esperando una excepción.

Autenticación de servicio, no de usuario. El ServiceToken identifica al backend (Core, Auth) como cliente de confianza ante Notifications — es independiente de si hay o no un usuario logueado en la request que disparó el envío. Compartir el JWT del usuario final no es una alternativa válida: ese token trae otro Audience y algunos flujos (recuperar contraseña) no tienen sesión iniciada en absoluto.

2️⃣ Agregar un tercero HTTP nuevo

AddAFHttpIntegration<TClient, TImplementation> es el mecanismo genérico que AddAFNotifications envuelve. No conoce Notifications ni ningún tercero en particular.

Definir las Options del tercero

Herede de HttpIntegrationOptions.

using AF.BackEnd.Integrations.Http.Config;

public sealed class PaymentGatewayOptions : HttpIntegrationOptions
{
    public required string ApiKey { get; set; }
}

Definir cómo se autentica (si aplica)

Implemente IRequestAuthenticator. No está atado a Bearer: puede agregar cualquier header o firma sobre el HttpRequestMessage.

using AF.BackEnd.Integrations.Http;

internal sealed class PaymentGatewayAuthenticator(PaymentGatewayOptions options) : IRequestAuthenticator
{
    public void Authenticate(HttpRequestMessage request) =>
        request.Headers.Add("X-Api-Key", options.ApiKey);
}

Registrar

El wrapper propio del tercero lee configuración y llama al genérico con objetos ya construidos.

using AF.BackEnd.Integrations.Http;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

public static class ServiceCollectionPaymentGatewayExtensions
{
    public static IServiceCollection AddAFPaymentGateway(
        this IServiceCollection services, IConfiguration configuration, string sectionName)
    {
        var options = configuration.GetSection(sectionName).Get<PaymentGatewayOptions>()
            ?? throw new InvalidOperationException($"No se encontró la sección '{sectionName}'.");

        return services.AddAFHttpIntegration<IPaymentGatewayClient, PaymentGatewayClient>(
            options,
            authenticator: new PaymentGatewayAuthenticator(options));
    }
}

API

Comportamiento que conviene conocer

La autenticación y la resiliencia son independientes entre sí. Un tercero puede tener solo BaseUrl (sin auth, sin resiliencia), solo Retry sin CircuitBreaker, o cualquier combinación — AddAFHttpIntegration arma el pipeline únicamente con lo que el tercero provee.

TOptions no es un genérico del método. AddAFHttpIntegration<TClient, TImplementation> recibe HttpIntegrationOptions options directo — cualquier subclase entra sin necesitar un tercer parámetro de tipo, porque el método solo usa miembros de la base (BaseUrl, Retry, CircuitBreaker).

Cada reintento se loguea. Si options.Retry está configurado, cada intento fallido dispara un LogWarning en ILogger<TClient> (la misma categoría del cliente tipado) con el número de intento, el MaxRetryAttempts configurado, el delay antes del siguiente intento y el resultado (status code o excepción) que lo disparó. No hace falta configurar nada aparte: sale del mismo ILogger<TClient> que ya resuelve AddHttpClient.

📌 API references

El paquete incluye documentación XML, así que las firmas y observaciones aparecen en IntelliSense.

🎓 Créditos

Nombre del Paquete: AF.BackEnd.Integrations Versión: 1.0.2

Autor

• Nombre: Dayser José Granados Pineda
• Correo Electrónico: djpgranados@gmail.com | daysergranados@hotmail.com

Licencia

Este paquete está bajo la licencia MIT License

Copyright (c) 2026 Dayser José Granados Pineda

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contacto

Si tienes comentarios, problemas o solicitudes, ¡no dudes en ponerte en contacto conmigo!