BKS.Integracoes

Biblioteca .NET Standard 2.0 para consumo de API externas utilizando Refit.

Log API

O papel da biblioteca no novo ecossistema esta descrito em docs/log-api-architecture.md. O acompanhamento executável do piloto Solvera está em docs/LOGAPI-11.md.

📦 Instalação

Disponível como pacote NuGet:

dotnet add package BKS.Integracoes

Ou via Package Manager Console:

Install-Package BKS.Integracoes

🚀 Como usar

Configurando o cliente

using BKS.Integracoes.Clients;
using BKS.Integracoes.Models.ApiGrandino;

// Configure a URL base da API e sua chave de API
string baseUrl = "https://api.grandinobank.com.br/";
string apiKey = "sua-chave-de-api-aqui";

// Cria o cliente usando a factory estática
var clienteApi = GrandinoApiClientFactory.Create(baseUrl, apiKey);

// Consulta um CNPJ completo
string cnpj = "12345678000195";
CnpjCompletoResponse resultado = await clienteApi.ConsultarCnpjCompletoAsync(cnpj);

Console.WriteLine($"Razão Social: {resultado.RazaoSocial}");

Tratando erros

A biblioteca não trata exceções de HTTP automaticamente. Recomenda-se envolver as chamadas em try/catch:

try
{
    var resultado = await clienteApi.ConsultarCnpjCompletoAsync(cnpj);
    // Processar resultado
}
catch (Refit.ApiException ex)
{
    // Tratar erros de API (4xx, 5xx)
    Console.WriteLine($"Erro na API: {ex.StatusCode} - {ex.Content}");
}
catch (HttpRequestException ex)
{
    // Tratar erros de rede, timeout, etc.
    Console.WriteLine($"Erro de comunicação: {ex.Message}");
}

🔧 Configuração do .gitlab-ci.yml

O repositório já contém um pipeline de CI/CD configurado para:

• Restauração de dependências
• Build da biblioteca
• Execução de testes
• Geração do pacote NuGet

As variáveis de ambiente importantes são:

• PROJECT_LIB: Nome do projeto da biblioteca (BKS.Integracoes)
• TEST_PROJECT: Caminho para o projeto de testes (./tests/BKS.Integracoes.Tests.csproj)

🏗️ Build e Testes Locais

Para buildar a biblioteca:

dotnet build lib/BKS.Integracoes.csproj

Para rodar os testes:

dotnet test tests/BKS.Integracoes.Tests.csproj

Para gerar o pacote NuGet:

dotnet pack lib/BKS.Integracoes.csproj --configuration Release

📚 Estrutura do Projeto

lib/
├── Clients/
│   ├── IGrandinoApiClient.cs          # Interface Refit com os endpoints
│   ├── GrandinoAuthHeaderHandler.cs   # Handler para injetar API key
│   └── GrandinoApiClientFactory.cs    # Factory estática para criar o cliente
├── Models/
│   └── ApiGrandino/
│       └── CnpjCompletoResponse.cs    # DTO de resposta da API
└── BKS.Integracoes.csproj             # Projeto da biblioteca

tests/
└── BKS.Integracoes.Tests.csproj       # Projeto de testes

specs/
└── Grandino/
    └── openapi.json                   # Especificação OpenAPI da API Grandino

🤝 Contribuindo

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

📄 Licença

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

🙏 Agradecimentos

• Refit pela biblioteca de cliente REST tipo-safe
• .NET pela plataforma

ApiNovaVidaSMS

Integração com a API NovaVida SMS (https://apiopera.novavidati.com.br).

Documentação pública:

• Gerar token: https://apiopera.novavidati.com.br/docs/#tag/v2/get/api/sms/v2/GerarToken
• Envio do SMS (EnvioSmsUnitario): https://apiopera.novavidati.com.br/docs/#tag/v2/post/api/sms/v2/EnvioSmsUnitario

Exemplo mínimo com HttpClient (fluxo: gerar token -> enviar SMS):

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;

public static async Task EnviarSmsAsync(string baseUrl, string usuario, string senha, string cliente, string telefone, string mensagem)
{
    using var http = new HttpClient { BaseAddress = new Uri(baseUrl) };

    // 1) Gerar token conforme a documentação oficial
    var tokenRequest = new StringContent(
        $"{{\"usuario\":\"{usuario}\",\"senha\":\"{senha}\",\"cliente\":\"{cliente}\"}}",
        Encoding.UTF8,
        "application/json");

    var tokenResponse = await http.PostAsync("/api/sms/v2/GerarToken", tokenRequest);
    tokenResponse.EnsureSuccessStatusCode();

    var tokenJson = await tokenResponse.Content.ReadAsStringAsync();
    var token = JObject.Parse(tokenJson)["token"]?.ToString() ?? JObject.Parse(tokenJson)["access_token"]?.ToString();
    if (string.IsNullOrWhiteSpace(token))
        throw new InvalidOperationException("Token não retornado pela API NovaVidaSMS.");

    // 2) Envio do SMS
    http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var payload = new JObject
    {
        ["telefone"] = telefone,
        ["mensagem"] = mensagem,
        ["idCategoria"] = 1
    };

    var content = new StringContent(payload.ToString(), Encoding.UTF8, "application/json");
    var sendResponse = await http.PostAsync("/api/sms/v2/EnvioSmsUnitario", content);
    sendResponse.EnsureSuccessStatusCode();
}

Exemplo com Refit (contrato simplificado):

public interface IApiNovaVidaSms
{
    [Post("/api/sms/v2/GerarToken")]
    Task<ApiResponse<object>> GerarTokenAsync([Body] object payload);

    [Post("/api/sms/v2/EnvioSmsUnitario")]
    Task<ApiResponse<object>> EnviarSmsUnitarioAsync([Header("Authorization")] string authorization, [Body] object payload);
}

// Uso: criar HttpClient com BaseAddress = https://apiopera.novavidati.com.br e chamar os métodos

Tratamento de exceções recomendado

• Refit.ApiException — quando usar Refit, captura respostas HTTP 4xx/5xx com conteúdo da API.
• HttpRequestException — falhas de rede, DNS, timeouts.
• TaskCanceledException — timeouts ou cancelamento de requisições.
• InvalidOperationException / JsonException — quando a resposta não possui o formato esperado.

Boas práticas

• Valide e renove o token antes do envio quando necessário (caching com expiry).
• Faça retry com política exponencial para erros transitórios (5xx, timeouts).
• Logue respostas de erro com cuidado, sem expor dados sensíveis.
• Consulte a documentação oficial nos links acima para parâmetros obrigatórios e esquema de payload.

Se quiser, posso gerar um cliente Refit completo e testes de unidade/simulação usando RichardSzalay.MockHttp para esta API.

ApiNovaVidaWhatsapp

Integração com a API NovaVida WhatsApp (https://whats.novavidati.com.br).

Ponto de entrada de envio:

• POST /api/v1/whatsapp/send
• Header Authorization: SEU_TOKEN_AQUI
• Content-Type: application/json

Payload mínimo:

{
  "numero": "5599999999999",
  "mensagem": "Sua mensagem aqui",
  "idCustom": "ID_UNICO",
  "base64": "<conteudo-base64>",
  "originalname": "imagem.jpg",
  "mimetype": "image/jpeg",
  "centrocusto": "CENTRO_CUSTO"
}

Observações importantes:

• O token é enviado diretamente no header Authorization.
• Atualmente o serviço aceita mimetype igual a image/jpeg para anexos.
• A resposta de sucesso costuma retornar status, codigo e mensagem.

Exemplo de contrato Refit:

public interface IApiNovaVidaWhatsapp
{
    [Post("/api/v1/whatsapp/send")]
    Task<ApiResponse<WhatsappSendResponse>> EnviarWhatsappAsync(
        [Header("Authorization")] string authorization,
        [Body] WhatsappSendRequest payload);
}

Uso com o wrapper da biblioteca:

var client = NovaVidaWhatsappClientFactory.Create(
    "https://whats.novavidati.com.br/",
    "SEU_TOKEN_AQUI");

var resposta = await client.EnviarWhatsappAsync(
    "5599999999999",
    "Olá, mensagem de teste",
    "ID_CUSTOM",
    base64Image,
    "imagem.jpg",
    "image/jpeg",
    "CENTRO_CUSTO");

if (resposta.IsT0)
{
    Console.WriteLine($"WhatsApp enviado: {resposta.AsT0.Mensagem}");
}
else
{
    Console.WriteLine($"Falha no envio: {resposta.AsT1}");
}

Integração da ApiNovaVida SMS

API Nova Vida Envio WhatsApp

Publicação e validação

A CI usa os templates de BankSoft/Pipelines/Comum em dev. Build e testes em Release são bloqueantes em branches de trabalho, MRs, dev, main e tags estáveis. O job validate_no_alpha_packages verifica referências declaradas em MRs para dev/main e nessas branches; ele não substitui a inspeção das dependências transitivas restauradas antes da promoção.

A publicação estável requer homologação em dev, MR revisado dev → main sem squash, confirmação do SHA aprovado e criação manual de uma tag protegida vX.Y.Z nesse SHA. Merge em main não publica pacote. A pipeline da tag executa build, testes, empacotamento e publicação; depois confira o pacote no feed e seu consumo em um projeto piloto. Tags e versões publicadas são imutáveis.

O empacotamento e a publicação usam .package_nuget_lib e .publish_nuget_lib; a versão calculada é transmitida pelo artefato .nuget-package-version.env. Notificações devem receber os webhooks por variáveis do GitLab, sem valores sensíveis versionados. Configure também as credenciais do feed no ambiente de CI.