# 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

```json

{
    "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

```json
{
    "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)

```json
{
    "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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cloudware.gitbook.io/documentacao-api/api-v1/introducao-a-api-v1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.