Introdução à API v1

De modo a simplificar a utilização da API disponibilizada, foram criadas novas rotas.

As diferenças entre a nova versão da API e a anterior são essencialmente duas:

Em primeiro lugar, a estrutura do payload a enviar foi alterada, de modo a ser mais simples de ler e de construir, sendo assim também menos predisposta a erros.

Em segundo lugar, a criação e alteração de documentos de vendas e compras, de recibos e de pagamentos passa a ser feita com um único pedido. As linhas destas entidades, que anteriormente eram criadas e alteradas em pedidos independentes, passam agora a estar incluídas no mesmo, e único, payload.

Relativamente à estrutura do payload, as alterações são:

• Todos os atributos enviados foram movidos do componente 'data'.'attributes', para o componente principal;

• O atributo 'type' foi removido;

• Todos os atributos antes enviados no componente 'relationships', são agora enviados no corpo principal, como os restantes atributos.

De resto, tal como referido, os atributos referentes às linhas, antes enviados num segundo pedido, são agora enviados dentro de um vector 'lines' no pedido original.

De seguida, vemos um exemplo fictício, no formato da API legacy, e no novo formato

Legacy (v0)

Primeiro pedido

{
    "data": {
      "type": "document_type_name",
      "attributes": {
        "attributeA": 1,
        "attributeB": 2,
        "attributeC": 3,
      },
      "relationships": {
        "relationshipA": {
          "data": {
            "type": "type",
            "id": "1"
          }
        },
        "relationshipB": {
          "data": {
            "type": "type",
            "id": "2"
          }
        }
      }
    }
  }

Segundo pedido

{
    "data": {
      "type": "document_type_name_lines",
      "attributes": {
        "attributeD": 4,
        "attributeE": 5,
        "attributeF": 6
      },
      "relationships": {
        "relationshipD": {
          "data": {
            "type": "type",
            "id": "1"
          }
        },
        "relationshipE": {
          "data": {
            "type": "type",
            "id": "2"
          }
        }
      }
    }
  }

Novo formato (v1)

{
    "attributeA": 1,
    "attributeB": 2,
    "attributeC": 3,
    "relationshipA_id": 1,
    "relationshipB_id": 2,
    "lines": [
        {
            "attributeD": 4,
            "attributeE": 5,
            "attributeF": 6,
            "relationshipD_id": 1,
            "relationshipE_id": 2,
        }
    ]
}

Os pedidos tornam-se assim muito mais simples de escrever e de ler, minimizando os erros e simplificando a sua construção.

Nas páginas seguintes são descritas as novas rotas em maior detalhe, e apresentados exemplos da sua utilização.

A documentação Swagger (OpenAPI) para a nova versão está disponível em: https://app.swaggerhub.com/apis/cloudware-deploy/APIv1/1.0