Moradas

As rotas aqui descritas permitem criar, modificar e remover moradas de clientes e de fornecedores.

Criação de uma morada (em adição à morada da sede)

Ao ser criado um cliente ou um fornecedor, é também criada automaticamente uma morada a ele associada: a morada principal (sede). Esta morada não precisa de ser criada novamente! O processo de criação aqui descrito serve apenas para a criação de outras moradas associadas, além da sede. Para a alteração da morada da sede, proceder como descrito em Alteração de uma morada.

POSThttps://api-cwb.cldware.com/addresses

Body

application/json

data*object

Response

200

OK

Body

application/json

dataobject

Request

JavaScriptCurl

const response = await fetch('https://api-cwb.cldware.com/addresses', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": {
        "type": "addresses",
        "attributes": {
          "addressable_type": "Customer",
          "addressable_id": 1,
          "address_detail": "Rua dos Testes, 1"
        }
      }
    }),
});
const data = await response.json();

Response

{
  "data": {
    "type": "addresses",
    "id": "1",
    "attributes": {
      "name": "Sede",
      "address_detail": "Rua dos Testes, 1",
      "city": "Porto",
      "postcode": "4000-000",
      "is_primary": false,
      "for_discharge": false,
      "for_charge": false
    },
    "relationships": {
      "country": {
        "data": {
          "type": "countries",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "supplier": {
        "data": {
          "type": "suppliers",
          "id": "1"
        }
      }
    }
  }
}

curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/addresses'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth. O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "addresses",                              // [OBRIGATÓRIO]
    "attributes": {                                   // [OBRIGATÓRIO] Os atributos da morada
      "addressable_type": "Customer|Supplier",        // [OBRIGATÓRIO] O tipo de entidade a quem a morada está associada: "Customer" se um cliente, "Supplier" se um fornecedor.
      "addressable_id": 1,                            // [OBRIGATÓRIO] O identificador interno da entidade (do cliente ou do fornecedor, dependendo do atributo "addressable_type") a quem a morada está associada. Ver NOTA 1.
      "name": "Filial",                               // [OPCIONAL] A designação desta morada
      "address_detail": "Rua dos Testes, 1",          // [OPCIONAL]
      "city": "Porto",                                // [OPCIONAL]
      "postcode": "4000-000",                         // [OPCIONAL] Se o país for Portugal, deve obedecer ao formato português, DDDD-DDD
      "for_charge": false,                            // [OPCIONAL] Por omissão, false; true se a morada for para ser usada como morada de carga.
      "for_discharge": false,                         // [OPCIONAL] Por omissão, false; true se a morada for para ser usada como morada de descarga.
    },
    "relationships": {                                // [OPCIONAL] Recursos associados à morada. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      // [OPCIONAL] Por omissão, a morada fica associada ao país "PT". Caso a morada seja de outro país, este deverá ser indicado.
      "country": {
        "data": {
          "type": "countries",                        // [OBRIGATÓRIO]
          "id": "1"                                   // [OBRIGATÓRIO] Identificador interno do país. Ver NOTA 2.
        }
      }
    }
  }
}

• NOTA 1: O cliente ou o fornecedor ao qual a morada vai ficar associada tem já que existir, e o seu "id" interno pode ser obtido, no caso de um cliente, por um

GET /customers?filter[tax_registration_number]=<o NIF do cliente>

ou, no caso de um fornecedor, por um

GET /suppliers?filter[tax_registration_number]=<o NIF do fornecedor>

• NOTA 2: São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira). Os países disponíveis podem ser consultados por um GET /countries, ou um em particular por um

GET /countries?filter[iso_alpha_2]=PT|<o código do país>

Alteração de uma morada

Ao ser criado um cliente ou um fornecedor, é também criada automaticamente uma morada a ele associada: a morada principal (sede). Esta morada, inicialmente sem estar preenchida, pode ser alterada pelo processo descrito de seguida.

PATCHhttps://api-cwb.cldware.com/addresses/{id}

Path parameters

id*string

Body

application/json

data*object

Response

200

OK

Body

application/json

dataobject

Request

JavaScriptCurl

const response = await fetch('https://api-cwb.cldware.com/addresses/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": {
        "type": "addresses",
        "id": "1",
        "attributes": {}
      }
    }),
});
const data = await response.json();

Response

{
  "data": {
    "type": "addresses",
    "id": "1",
    "attributes": {
      "name": "Sede",
      "address_detail": "Rua dos Testes, 1",
      "city": "Porto",
      "postcode": "4000-000",
      "is_primary": false,
      "for_discharge": false,
      "for_charge": false
    },
    "relationships": {
      "country": {
        "data": {
          "type": "countries",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "1"
        }
      },
      "supplier": {
        "data": {
          "type": "suppliers",
          "id": "1"
        }
      }
    }
  }
}

curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/addresses/<id da morada>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth.

No caso da alteração da morada da sede, o id da morada é o "id" interno da sede, que pode ser obtido consultando o campo "id" da relação "main_address" (incluída no objeto "relationships") do respectivo cliente (ver Consulta de um cliente) ou fornecedor (ver Consulta de um fornecedor).

Nos casos em que a alteração seja a de uma morada adicional, o id da morada é o "id" interno da morada, devolvido no campo "id" da resposta ao seu pedido de criação (ver Criação de uma morada (em adição à morada da sede)). Este "id" também pode ser obtido consultando os campos "id" da relação "addresses" (incluída no objeto "relationships") do respectivo cliente (ver Consulta de um cliente) ou fornecedor (ver Consulta de um fornecedor).

O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "addresses",                              // [OBRIGATÓRIO]
    "id": "1",                                        // [OBRIGATÓRIO] O identificador interno da morada. Este "id" é o devolvido na resposta ao pedido de criação da morada, ver acima.
    "attributes": {                                   // [OBRIGATÓRIO] Os atributos da morada
      "name": "Filial",                               // [OPCIONAL] A designação desta morada
      "address_detail": "Rua dos Testes, 1",          // [OPCIONAL]
      "city": "Porto",                                // [OPCIONAL]
      "postcode": "4000-000",                         // [OPCIONAL] Se o país for Portugal, deve obedecer ao formato português, DDDD-DDD
      "for_charge": false,                            // [OPCIONAL] true se a morada for para ser usada como morada de carga.
      "for_discharge": false                          // [OPCIONAL] true se a morada for para ser usada como morada de descarga.
    },
    "relationships": {                                // [OPCIONAL] Recursos associados à morada. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      // [OPCIONAL] Por omissão, a morada fica associada ao país "PT". Caso a morada seja de outro país, este deverá ser indicado.
      "country": {
        "data": {
          "type": "countries",                        // [OBRIGATÓRIO]
          "id": "1"                                   // [OBRIGATÓRIO] Identificador interno do país. Ver NOTA 1.
        }
      }
    }
  }
}

• NOTA 1: São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira). Os países disponíveis podem ser consultados por um GET /countries, ou um em particular por um

GET /countries?filter[iso_alpha_2]=PT|<o código do país>

Eliminação de uma morada

Só podem ser eliminadas moradas adicionais à da sede. A morada da sede não pode ser eliminada.

DELETEhttps://api-cwb.cldware.com/addresses/{id}

Path parameters

id*string

Response

200

OK

Request

JavaScriptCurl

const response = await fetch('https://api-cwb.cldware.com/addresses/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/addresses/<id da morada>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id da morada é o "id" interno da morada, devolvido no campo "id" da resposta ao seu pedido de criação (ver Criação de uma morada (em adição à morada da sede)). Este "id" também pode ser obtido consultando os campos "id" da relação "addresses" (incluída no objeto "relationships") do respectivo cliente (ver Consulta de um cliente) ou fornecedor (ver Consulta de um fornecedor).