Introdução à API v0
A API disponibilizada inicialmente (v0) permite aceder a rotas para criação e edição de documentos das áreas comercial e de contabilidade. Quando se pretende utilizar rotas de contabilidade é necessário que a sessão esteja associada a um exercício contabilístico. Note-se que a sessão da API está associada a um utilizador do tipo Empresário, pelo que o acesso de leitura e escrita via API dependem das permissões que esse Empresário tenha aos Exercícios fiscais da empresa. A seleção do exercício usado na sessão da API está documentada na autenticação.
Nas páginas seguintes são descritas as rotas em maior detalhe, e apresentados exemplos da sua utilização.
A documentação Swagger (OpenAPI) para da versão inicial está disponível em: https://app.swaggerhub.com/apis/gitbook/APIv0/1.0
Formato da API
A versão v0 da API foi desenvolvida com base na especificação de JSON:API version 1.0. Na altura em que foi implementada a nossa API inicial, a especificação JSON:API 1.0 ainda estava em discussão e incluía a execução de operações através da extensão 'JSON Patch', que foi incluída parcialmente na API v0.
Ordenação
A ordenação de pedidos que devolvem coleções no data, pode ser indicada usando o parâmetro sort=<criteria>, de acordo com o formato de ordenação da JSON:API.
Um exemplo de ordenação pelo campo date por ordem descendente, seguido de ordenação por document_type por ordem ascendente seria:
sort=-date,document_typePaginação
A JSON:API é agnóstica em relação às estratégias de paginação implementadas no servidor.
Pelo que optamos por implementar uma estratégia pelo número da página, ou seja usando os parâmetros page[number] e page[size], por exemplo:
page[number]=1&page[size]=10Filtragem
Em relação a critérios de filtragem, a especificação apenas indica que deve ser usado o parâmetro filter.
Na nossa implementação da API, optamos por usar este parâmetro num formato de texto livre, no formato filter="<texto>", ou como filtro específico de um campos, no formato filter[<field>]=<value>. Sendo possível combinar vários critérios de filtragem, como por exemplo:
filter[document_type]=FT&filter[status]=1&filter="documents.date>'2024-01-01'"Quando se usa critérios pode ser conveniente saber o número de elementos que obedecem ao critério de filtragem (total) e o número total de elementos (grand-total) que seriam devolvidos sem filtragem. Essa informação pode ser obtida com o parâmetro totals=1, este parâmetro também pode ser usado com o valor zero sendo equivalente a não estar definido.
Assim, num pedido com totals=1 o número de elementos filtrados e sem filtragem são devolvidos no meta:
{
"data": [...],
"meta": {
"total": "12",
"grand-total": "83"
}
}Inclusão de recursos relacionados
Quando se faz um pedido, podemos incluir na resposta a informação dos recursos relacionados. Por exemplo quando se consulta um documento de vendas podemos pedir para incluir na resposta as linhas do documento, e o cliente assim como a morada deste:
include=lines,customer.addressesNote-se que não é possível controlar a ordenação dos recursos incluídos, uma vez que não é relevante.
Exemplo de resposta:
{
"data": [
{
"type": "commercial_sales_documents",
"id": "4",
"attributes": {...},
"relationships": {
...
"customer": {
"data": {
"type": "customers",
"id": "47"
}
},
"lines": {
"data": [
{
"type": "commercial_sales_document_lines",
"id": "4"
}
]
},
...
}
}
],
"included": [
{
"type": "addresses",
"id": "53",
"attributes": {
"is_primary": true,
"name": "Sede",
...
},
"relationships": {...}
},
{
"type": "commercial_sales_document_lines",
"id": "4",
"attributes": {...},
"relationships": {...}
},
{
"type": "customers",
"id": "47",
"attributes": {...},
"relationships": {
"addresses": {
"data": [
{
"type": "addresses",
"id": "53"
}
]
},
...
}
}
]
}Campos na resposta
Para optimizar a quantidade de dados enviados na resposta, é possível indicar no pedido quais são os campos que devem ser devolvidos para cada tipo de recurso. Usando o exemplo anterior de consulta de um documento de vendas, com inclusão das linhas do documento, o cliente e a morada deste, podemos definir quais os campos a devolver para cada um destes recursos.
fields[addresses]=city&fields[customers]=business_name&fields[commercial_sales_documents]=document_no,date,gross_total&fields[commercial_sales_document_lines]=description,amountAssim, a resposta completa seria apenas:
{
"data": [
{
"type": "commercial_sales_documents",
"id": "4",
"attributes": {
"document_no": "FT 2024/3",
"date": "2024-01-12",
"gross_total": 363
}
}
],
"included": [
{
"type": "addresses",
"id": "53",
"attributes": {
"city": "Madrid"
}
},
{
"type": "commercial_sales_document_lines",
"id": "4",
"attributes": {
"description": "Serviço de atualização",
"amount": 363
}
},
{
"type": "customers",
"id": "47",
"attributes": {
"business_name": "Hispanic Business, S.L."
}
}
]
}Extensão JSON Patch
Embora a extensão JSON Patch, entretanto tenha sido descontinuada, a documentação desta extensão, imediatamente antes de ser descontinuada, e com base na qual foram implementadas operação na APIv0, encontra-se disponível no histórico da extensão JSON Patch.
Caraterísticas dos pedidos
A utilização de operações foi implementada na API v0 sem que seja necessário definir os headers específicos de extensão. Ou seja, embora a especificação indique que é necessário identificar a extensão:
Content-Type: application/vnd.api+json; ext=jsonpatch
Accept: application/vnd.api+json; ext=jsonpatchOs pedidos devem ser feitos de forma genérica indicando apenas que se está a usar uma API JSON:
Content-Type: application/vnd.api+json
Accept: application/vnd.api+jsonOperações
São suportados os 3 tipos de operação previstos na especificação da extensão: "add", "replace" e "remove". Alguns exemplos de utilização estão na documentação de contabilização.
Last updated