Uma encomenda representa um compromisso de compra de um bem ou serviço por parte de um cliente. Neste artigo vamos ver como criar uma encomenda usando a API. O exemplo apresentado foi desenvolvido em C# para uma aplicação de consola e está disponível no repositório de exemplos Jasmin ou Rose.

Conceitos

AccountKey e SubscriptionKey

Em primeiro lugar, é necessário definir estes dois parâmetros, que são requeridos pela Web API e que identificam de forma inequívoca a subscrição (Base Dados) do cliente. No seguinte exemplo, que consta no ficheiro Constants.cs.

internal class RoseConstants
{
    internal const string AccountKey = "HXDID1P";
    internal const string SubscriptionKey = "HXDID7M-HXDIDGJ";
}

Access token

Para aceder à Web API também é necessário o token de autenticação associado ao utilizador e à subscrição. No ficheiro Constants.cs, estão as constantes definidas como clientId e clientSecret (neste caso estamos a usar o fluxo de autenticação Client Credentias) é exemplificado um pedido para obtenção do token através da chamada ao método GetAccessTokenAsync disponivél na classe AuthenticationProvider.cs.

// Get the authorization access token
string accessToken = await GetAccessTokenAsync();
Console.WriteLine(accessToken != null ? "Authorization token found." : "Authorization token not found.");

HttpClient

Para fazer chamadas a uma Web API REST em C# pode utilizar-se a seguinte classe:

System.Net.Http.HttpClient

Como no exemplo:

using (HttpClient client = new HttpClient())
{
    (…)
}

Configuração do access token

Os pedidos à Web API requerem sempre o access token anterior. Deve ser incluído nos headers do pedido.

client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", AccessToken);

Construção da encomenda a criar

Para criar a encomenda, é necessário definir 3 classes que representam os contractos da WebAPI:

• Order: Cabeçalho da encomenda
• OrderLine: Linhas associadas a encomenda.
• Price/Amount: Preço do artigo.

Pode consultar os contratos na documentação técnica da API Jasmin ou Rose de acordo com o produto que está a integrar.

Para invocar o método de criação da encomenda, criamos o objeto que a representa:

No exemplo apresentado é importante destacar o atributo "Company" e que representa a empresa à qual a encomenda ficara associada, visto que dentro de uma base dados podem existir várias empresas.

public static async Task CreateOrderAsync()
{
    // Build the order that should be created
    Order order = new Order();
    try
    {
        order.Company = "Bocasuja";
        order.DocumentType = "ECL";
        order.DocumentDate = DateTime.UtcNow;
        order.CustomerId = "0002";
        order.Currency = "EUR";
        order.Lines = new List
            {
                new OrderLine
                {
                    ItemId = "0002",
                    Quantity = 1,
                    Type = 1,
                    Price = new Price()
                    {
                        Value = 50,
                        Currency = "€"
                    }
                    (...)
                }
              };
    }
}

Construção e execução do pedido

Neste momento a chamada à Web API pode ser executada a partir de um HTTP Client. Note-se que na construção do pedido deve constar sempre o URL base do produto seguido da palavra "api", da AccountKey e SubscriptionKey terminando com o modulo e a entidade sobre a qual a operação será realizada.

// Build the request

string request = "sales/orders";
string resourceLocation = string.Format("{0}/api/{1}/{2}/{3}/", Constants.baseAppUrl, AccountKey, SubscriptionKey, request);

client.DefaultRequestHeaders.Accept.Clear();

client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Token);

HttpRequestMessage postOrderMessage = new HttpRequestMessage(HttpMethod.Post, resourceLocation);

string invoiceRequest = JsonConvert.SerializeObject(order);

postOrderMessage.Content = new StringContent(invoiceRequest, Encoding.UTF8, "application/json");

// Send

using (HttpResponseMessage responseContent = await client.SendAsync(postOrderMessage))
{
    (…)
}

Tratamento da resposta

O endpoint pode devolver dois tipos de respostas: sucesso ou erro. No caso de sucesso, é devolvida uma mensagem de êxito e a informação da encomenda criada. Em caso de erro, o resultado incluirá uma mensagem de erro, dependendo do erro.

// Build the request
// Get the response

if (responseContent.IsSuccessStatusCode)
{
    string result = await ((StreamContent)responseContent.Content).ReadAsStringAsync();
    Console.ForegroundColor = ConsoleColor.Green;
    Console.WriteLine(string.Concat("Order created: ", result));
}
else
{
    Console.WriteLine(string.Concat("Failed. ", responseContent.ToString()));
    string result = await ((StreamContent)responseContent.Content).ReadAsStringAsync();
    Console.WriteLine(string.Concat("Content: ", result));

    throw new Exception("Unable to create the order.");

}

É assim tão simples criar uma encomenda de vendas.