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_type

Paginaçã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]=10

Filtragem

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.addresses

Note-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,amount

Assim, 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=jsonpatch

Os 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+json

Operaçõ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.