Integração

Neste documento serão descritos os passos para realizar a integração com a API do SMS.

Configuração do Acesso Cidadão

1. Solicitar via SA o acesso ao Acesso Cidadão Admin;
2. Criar um sistema para a aplicação que irá consumir a Api de SMS;
3. Após criar o sistema, deve ser criado um APP com as configurações:
   • Fluxo: ClientCredentials
   • Scopes de Api: api-sistema-sms-acesso
4. Solicitar ao Prodest a criação de um usuário na Api de SMS;

Atenção

Caso o scope acima não esteja disponível na lista entrar em contato via SA.

Telas do AC Admin para criação de um no APP:

Novo APP

Criação de um APP com o fluxo Client Credentials

Editando um APP para adicionar o scope de SMS

APP novo sem nenhum scope

Scope de SMS adicionado

Testando a integração

Swagger

1. Acesse o endereço da Api de SMS em um nova aba;
2. Volte ao AC Admin e gere um access token no APP criado anteriormente;
3. Clique no botão Authorize e cole o token no campo indicado;
4. Vá até a seção SMS e clique no endpoint /v2/enviar e preencha os dados solicitados;
   • O campo agendamento é opcional e pode ser removido para envio instantâneo;
   • O campo idMensagem pode ser o valor do client_id criado anteriormente;
5. Clique em enviar e se tudo estiver correto você receberá o retorno conforme a imagem abaixo;

Telas para realizar o teste via swagger:

Swagger

Botão para gerar token de teste no AC Admin

Token gerado

Usando o token gerado no swagger

Enviando um SMS

SMS enviado com sucesso

Dotnet

Atenção

Os códigos abaixo são apenas para demonstração, aplique as melhores práticas ao implementar em produção.

appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "SmsApiClient": {
    "Authority": "https://acessocidadao.es.gov.br/is/",
    "ClientId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "ClientSecret": "s3nh@$up3rS3cre74",
    "RequireHttpsMetadata": "true",
    "ResponseType": "code id_token",
    "SaveTokens": "true",
    "Scopes": [
      "api-sistema-sms-acesso"
    ]
  }
}

Program.cs

using Microsoft.AspNetCore.Mvc;
using WebApplication2;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddOptions<ApiClientConfiguration>()
    .BindConfiguration("SmsApiClient");

builder.Services
    .AddHttpClient<SmsApiClient>(options =>
    {
        options.BaseAddress = new Uri("https://api.sms.es.gov.br");
    });

var app = builder.Build();

app.MapPost("/enviaSms", async ([FromBody] SmsDto sms, [FromServices] SmsApiClient apiClient) =>
{
    var resposta = await apiClient.EnviaSmsAsync(sms);

    return resposta;
});

await app.RunAsync();

// ReSharper disable ClassNeverInstantiated.Global
public sealed record ApiClientConfiguration(
    string Authority, string ClientId, string ClientSecret, string[] Scopes
)
{
    public ApiClientConfiguration() : this("", "", "", Array.Empty<string>())
    {
    }
}

internal sealed record SmsDto(string Mensagem, string Numero);

SmsApiClient.cs

using IdentityModel.Client;
using Microsoft.Extensions.Options;

namespace WebApplication2;

public sealed class SmsApiClient
{
    private readonly ApiClientConfiguration _apiClientConfiguration;
    private readonly HttpClient _httpClient;

    public SmsApiClient(
        IOptions<ApiClientConfiguration> apiClientConfiguration,
        HttpClient httpClient
    )
    {
        _apiClientConfiguration = apiClientConfiguration.Value;
        _httpClient = httpClient;
    }

    internal async ValueTask<RespostaSms> EnviaSmsAsync(SmsDto sms)
    {
        var tokenRequest = await _httpClient.RequestClientCredentialsTokenAsync(
            new ClientCredentialsTokenRequest
            {
                Address = $"{_apiClientConfiguration.Authority}connect/token",
                ClientId = _apiClientConfiguration.ClientId,
                ClientSecret = _apiClientConfiguration.ClientSecret,
                ClientCredentialStyle = ClientCredentialStyle.PostBody,
                Scope = string.Join(" ", _apiClientConfiguration.Scopes)
            }
        );

        _httpClient.DefaultRequestHeaders
            .Add("Authorization", $"Bearer {tokenRequest.AccessToken}");

        var response = await _httpClient.PostAsJsonAsync("/v2/enviar", new
        {
            Mensagens = new[]
            {
                new MensagemSms
                {
                    IdMensagem = _apiClientConfiguration.ClientId,
                    Destinatarios = new[]
                    {
                        sms.Numero
                    },
                    Mensagem = sms.Mensagem
                }
            }
        });

        if (response is { IsSuccessStatusCode: false })
        {
            return new RespostaSms
            {
                Sucesso = false,
                Resposta = "Erro ao enviar o SMS"
            };
        }

        var smsResposta = await response.Content
            .ReadFromJsonAsync<RespostaSms>();

        return smsResposta!;
    }
}

internal sealed class MensagemSms
{
    public string? IdMensagem { get; set; }

    public string[]? Destinatarios { get; set; }

    public string? Mensagem { get; set; }
}

internal sealed class RespostaSms
{
    public bool Sucesso { get; set; }

    public string? Resposta { get; set; }

    public int Lote { get; set; }
}

Administração de recursos

Cada orgão é responsável por gerir os créditos alocados para a organização. Para mais informações consulte o manual do atual provedor de SMS.