API do Libax Business

Aqui poderá encontrar toda a documentação relacionada com a API do Libax Business para o ajudar a ligar a sua aplicação com o seu software de faturação. Com esta integração poderá facilmente:

• Criar clientes
• Emitir faturas ou outro tipo de documentos
• Realizar impressão de documentos
• e muito mais...

É uma excelente solução para adicionar as funcionalidade de faturação à sua loja on-line ou a outra aplicação que necessite de ter um suporte de faturação associado.

Obter o ClientID

Para utilizar a API é preciso criar um clientID para utilizar na fase de autenticação.

Esta funcionalidade está disponível Business -> Configurações (roda dentada em cima à direita) -> Cliente API

Após entrar nesta opção, pressione o botão Criar conforme imagem seguinte:

Após criação do ID de cliente, será mostrado o ID e o seacret conforme imagem seguinte:

O secret não será mostrado novamente. Assim, guarde esta informação num local seguro e partilhe apenas com que vai utilizar a API. Caso perca informação terá de gerar novo secret.

A qualquer momento poderá voltar a esta configuração se pretender remover esta funcionalidade.

Utilizar a API

A API está disponível no endereço https://api.libax.com/business/v1/

Neste endereço está também disponível a documentação Swagger onde pode também autenticar-se e invocar os métodos de forma a facilitar o desenvolvimento.

Para a autenticação ser completa é necessário escolher o scope business_public_api conforme imagem seguinte:

Restrições de utilização

Se o client_id foi configurado com uma restrição de parceiros ou escritórios, não irá ter autorização para utilizar os métodos seguintes: ATM transactions, BankAccounts, Banks, Mandates, Offices, PaymentProviders, Products, Schedules, TextMessages

Exemplos em C# de como utilizar a API

Para utilizar os exemplos seguintes é preciso referênciar as libraries seguintes:

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

Exemplo para obter o token de autenticação

Utilize o código seguinte como exemplo para obter o token de autenticação

using HttpClient client = new HttpClient();
string url = "https://id.libax.com/api/connect/token";
string clientId = "YOUR-CLIENTID";
string clientSecret = "YOUR-SECRET";

string encodedCredentials = Convert.ToBase64String(Encoding.ASCII.GetBytes(clientId + ":" + clientSecret));
client.DefaultRequestHeaders.Add("Authorization", "Basic " + encodedCredentials);

var content = new StringContent("grant_type=client_credentials&scope=business_public_api", Encoding.UTF8, "application/x-www-form-urlencoded");

using HttpResponseMessage response = await client.PostAsync(url, content);

if (response.IsSuccessStatusCode)
{
    string responseData = await response.Content.ReadAsStringAsync();
    dynamic t = Newtonsoft.Json.JsonConvert.DeserializeObject(responseData);

    string accessToken = t.access_token;
    int expiresIn = t.expires_in;
    string tokenType = t.token_type;
    string scope = t.scope;

    Console.WriteLine($"Access Token: {accessToken}, Expires in {expiresIn}, type {tokenType}, scope {scope}");
}
else
{
    Console.WriteLine($"Error: {response.StatusCode}");
}

using HttpClient client = new HttpClient();
string url = "https://api.libax.com/business/v1/products";

client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR-ACCESS-TOKEN");

var queryParams = new System.Collections.Generic.Dictionary<string, string> { { "take", "10" } };

using FormUrlEncodedContent formContent = new FormUrlEncodedContent(queryParams);
string queryString = await formContent.ReadAsStringAsync();

using HttpResponseMessage response = await client.GetAsync($"{url}?{queryString}");

if (response.IsSuccessStatusCode)
{
    string data = await response.Content.ReadAsStringAsync();
    Console.WriteLine(data);
}
else
{
    Console.WriteLine($"Error: {response.StatusCode}");
}

using HttpClient client = new HttpClient();
string url = "https://api.libax.com/business/v1/entities";

client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR-ACCESS-TOKEN");

var data = new
{
    name = "Ana Ferreira",
    city = "Lisboa"
};
using StringContent content = new StringContent(JsonSerializer.Serialize(data), Encoding.UTF8, "application/json");

using HttpResponseMessage response = await client.PostAsync(url, content);

if (response.IsSuccessStatusCode)
{
    string newEntityId = await response.Content.ReadAsStringAsync();
    Console.WriteLine(newEntityId);
}
else
{
    Console.WriteLine($"Error: {response.StatusCode}");
}

using HttpClient client = new HttpClient();
string url = "https://api.libax.com/business/v1/Entities/search";

client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR-ACCESS-TOKEN");

var data = new
{
    take = 5,
    filters = new[]
    {
        new { propertyName = "creationdate", @operator = "GTE", value = "2022-01-01" },
        new { propertyName = "creationdate", @operator = "LT", value = "2023-01-01" }
    }
};

using StringContent content = new StringContent(JsonSerializer.Serialize(data), Encoding.UTF8, "application/json");

using HttpResponseMessage response = await client.PostAsync(url, content);

if (response.IsSuccessStatusCode)
{
    string newEntityId = await response.Content.ReadAsStringAsync();
    Console.WriteLine(newEntityId);
}
else
{
    Console.WriteLine($"Error: {response.StatusCode}");
}

Filtros

É possível aplicar filtros nos pedidos da API no sentido de obter apenas a informação que pretende.

Considere os seguintes operators disponíveis:

Nota 1: em Booleans o operator é ignorado e é sempre feita uma igualdade e diferente.

Nota 2: filtros para saber se um objeto está preenchido, a comparação é feita com o "null". Assim, pode enviar o operador "EQ" com o valor "true" em que irá retornar "true" o objeto em causa for "null". Ex: para filtrar entidades que não tenham registo de consentimento RGPD, pode pesquisa pelo campo "entityConsent", operador "EQ", valor "true".

Campos possível para filtrar

Nota: São todos case insensitive

Exemplos de utilização de filtros

Dica: quando pretende considerar uma condição "ou", coloque os filters dentro de uma lista de filterGroups.

Procura por entidades com "ana" no nome e ordena por data de criação 

{
  "take": 50,
  "skip": 0,
  "filters": [
    {
      "propertyName": "name",
      "operator": "CONTAINS_TOKEN",
      "value": "Ana"
    }
  ],
  "sort": {
    "propertyName": "creationDate",
    "direction": 1
  }
}

{
  "take": 50,
  "skip": 0,
  "filters": [
    {
      "propertyName": "creationdate",
      "operator": "GTE",
      "value": "2022-01-01"
    },
    {
      "propertyName": "creationdate",
      "operator": "LT",
      "value": "2023-01-01"
    }
  ]
}

{
  "take": 50,
  "skip": 0,
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "city",
          "operator": "EQ",
          "value": "Lisboa"
        }
      ]
    },
    {
      "filters": [
        {
          "propertyName": "city",
          "operator": "EQ",
          "value": "Porto"
        }
      ]
    }
  ]
}

{
  "take": 50,
  "skip": 0,
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "city",
          "operator": "EQ",
          "value": "Lisboa"
        }
      ]
    },
    {
      "filters": [
        {
          "propertyName": "city",
          "operator": "EQ",
          "value": "Porto"
        }
      ]
    }
  ],
  "filters": [
    {
      "propertyName": "creationdate",
      "operator": "GTE",
      "value": "2023-01-01"
    }
  ]
}