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.
post
Body
Responses
200
OK
application/json
post
/addresses
200
OK
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:
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
ou, no caso de um fornecedor, por um
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
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.
patch
Path parameters
idstringRequired
Body
Responses
200
OK
application/json
patch
/addresses/{id}
200
OK
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:
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
Eliminação de uma morada
Só podem ser eliminadas moradas adicionais à da sede. A morada da sede não pode ser eliminada.
delete
Path parameters
idstringRequired
Responses
200
OK
No content
delete
/addresses/{id}
200
OK
No content
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).
{
"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.
}
}
}
}
}
GET /customers?filter[tax_registration_number]=<o NIF do cliente>
GET /suppliers?filter[tax_registration_number]=<o NIF do fornecedor>
GET /countries?filter[iso_alpha_2]=PT|<o código do país>
{
"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.
}
}
}
}
}
GET /countries?filter[iso_alpha_2]=PT|<o código do país>