Clientes e Moradas
As rotas definidas no presente capítulo permitem gerir toda a informação relativa aos clientes associados a uma dada empresa: obter informação sobre clientes, editá-la, eliminar, e criar novos
Neste primeiro exemplo, ao realizar um pedido para a rota https://apiv1.toconline.com/customers irá receber uma resposta semelhante à descrita de seguida, com uma lista de elementos 'data', onde cada elemento corresponde a um cliente associado à sua empresa. Esta rota não requer qualquer tipo de parâmetros.
À semelhança do pedido anterior, se este for realizado para a rota
https://apiv1.toconline.com/customers/{id}Irá obter como resposta apenas as informações de um único cliente, em vez de receber uma lista de todos os clientes existentes.
GET /customers/{id} HTTP/1.1
Host:
Accept: */*
OK
No content
A seguinte rota permite a criação de novas instâncias de clientes, associados à sua empresa. De modo a realizar um pedido para esta rota, terá de enviar alguns parâmetros no body do pedido. Tal como está descrito no pedido em baixo, dentro do body terá de criar dois objetos: data, e relationships. Dentro de data, deverá colocar todos os parâmetros obrigatórios (assinalados com um asterisco), e poderá também colocar os restantes parâmetros, se for do seu interesse. O tipo dos parâmetros está também especificado. Dentro de relationships deverá colocar um objeto para cada uma das entradas descritas em baixo, sendo que cada uma deverá conter todos os parâmetros indicados.
POST /customers HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 935
{
"data": {
"type": "customers",
"attributes": {
"id": 1,
"tax_registration_number": "text",
"business_name": "text",
"contact_name": "text",
"website": "text",
"phone_number": "text",
"mobile_number": "text",
"email": "text",
"observations": "text",
"internal_observations": "text",
"not_final_customer": true,
"cashed_vat": true,
"tax_country_region": "text",
"country_iso_alpha_2": "text",
"saft_import_id": 1,
"is_tax_exempt": true,
"data": {}
},
"relationships": {
"company": {
"data": {
"resource": "current_company"
}
},
"main_address": {
"data": {
"table": "addresses",
"resource": "addresses"
}
},
"main_email_address": {
"data": {
"table": "email_addresses",
"resource": "email_addresses"
}
},
"tax_exemption_reason": {
"data": {
"resource": "tax_exemption_reasons"
}
},
"defaults": {
"data": {
"table": "customer_defaults",
"resource": "customers_defaults"
}
},
"addresses": {
"data": {
"table": "addresses",
"resource": "addresses"
}
},
"email_addresses": {
"data": {
"table": "email_addresses",
"resource": "email_addresses"
}
}
}
}
}OK
{
"data": {
"type": "customers",
"id": null,
"attributes": {
"id": 1,
"tax_registration_number": "text",
"business_name": "text",
"contact_name": "text",
"website": "text",
"phone_number": "text",
"mobile_number": "text",
"email": "text",
"observations": "text",
"internal_observations": "text",
"not_final_customer": true,
"cashed_vat": true,
"tax_country_region": "text",
"country_iso_alpha_2": "text",
"saft_import_id": 1,
"is_tax_exempt": true,
"data": {}
},
"relationships": {
"company": {
"data": {
"resource": "current_company"
}
},
"main_address": {
"data": {
"table": "addresses",
"resource": "addresses"
}
},
"main_email_address": {
"data": {
"table": "email_addresses",
"resource": "email_addresses"
}
},
"tax_exemption_reason": {
"data": {
"resource": "tax_exemption_reasons"
}
},
"defaults": {
"data": {
"table": "customer_defaults",
"resource": "customers_defaults"
}
},
"addresses": {
"data": {
"table": "addresses",
"resource": "addresses"
}
},
"email_addresses": {
"data": {
"table": "email_addresses",
"resource": "email_addresses"
}
}
}
}
}A seguinte rota permite a remoção de um dado cliente. Esta rota deve ser utilizada de forma cautelosa dado que é irreversível, e mesmo que este cliente volte a ser criado, o seu id nunca será o mesmo que teria anteriormente. Utilizando o id do cliente que quer eliminar, que poderá fazer utilizando a primeira rota desta página, por exemplo, terá simplesmente de fazer um pedido para https://apiv1.toconline.com/customers/{id}. Este irá retornar OK em caso de sucesso.
DELETE /customers/{id} HTTP/1.1
Host:
Accept: */*
OK
No content
A rota PATCH permite a edição de um cliente existente. O body deste pedido deverá ser igual ao descrito na rota POST, contendo todas as informações obrigatórias do cliente, atualizadas para os valores que tenciona alterar, além do campo "id" no "data" do "body". Álem disto, o pedido deverá ser feito a https://apiv1.toconline.com/customers/{id}, sendo que {id} é o identificador do cliente que tenciona atualizar.
PATCH /customers/{id} HTTP/1.1
Host:
Accept: */*
OK
No content
Morada
De modo a associar uma morada a um cliente, deverá realizar o seguinte pedido
POST /addresses HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 529
{
"data": {
"type": "addresses",
"attributes": {
"id": 1,
"is_primary": true,
"address_detail": "text",
"city": "text",
"postcode": "text",
"region": "text",
"name": "text",
"for_discharge": true,
"for_charge": true
},
"relationships": {
"country": {
"data": {
"resource": "countries"
}
},
"company": {
"data": {
"table": "addresses",
"resource": "current_company"
}
},
"customer": {
"data": {
"table": "addresses",
"resource": "customers"
}
},
"supplier": {
"data": {
"table": "addresses",
"resource": "suppliers"
}
},
"user": {
"data": {
"table": "addresses",
"resource": "current_company_users"
}
}
}
}
}OK
{
"data": {
"type": "addresses",
"id": null,
"attributes": {
"id": 1,
"is_primary": true,
"address_detail": "text",
"city": "text",
"postcode": "text",
"region": "text",
"name": "text",
"for_discharge": true,
"for_charge": true
},
"relationships": {
"country": {
"data": {
"resource": "countries"
}
},
"company": {
"data": {
"table": "addresses",
"resource": "current_company"
}
},
"customer": {
"data": {
"table": "addresses",
"resource": "customers"
}
},
"supplier": {
"data": {
"table": "addresses",
"resource": "suppliers"
}
},
"user": {
"data": {
"table": "addresses",
"resource": "current_company_users"
}
}
}
}
}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'No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato
// Exemplo de payload
{
"data": {
"type": "addresses", // [OBRIGATÓRIO]
"id": "<id da morada principal do cliente>", // [OBRIGATÓRIO]
"attributes": {
"address_detail": "Test address", // [OPCIONAL]
"city": "Test city", // [OPCIONAL]
"postcode": "0000-000", // [OPCIONAL] Se o país for Portugal, deve obedecer ao formato português, DDDD-DDD
"region": "Test region" // [OPCIONAL]
},
"relationships": { // [OPCIONAL] Recursos associados à morada. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
"country": { // [OPCIONAL] Por omissão, a morada fica associada ao país "PT"
"data": {
"type": "countries", // [OBRIGATÓRIO]
"id": "<id do país>" // [OBRIGATÓRIO] Vd. NOTA 1
}
}
}
}
}NOTA 1: O "id" interno do país deve ser obtido por um GET /countries?filter[iso_alpha_2]=PT|<o código do país>... São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira).
E-mail
De modo a associar um email a um cliente, deverá realizar o seguinte pedido
GET /email_addresses HTTP/1.1
Host:
Accept: */*
OK
{
"data": {
"type": "email_addresses",
"id": null,
"attributes": {
"id": 1,
"due_days": "text",
"payment_mechanism": "text",
"payment_reference": "text",
"retention_value": "text",
"sales_price": "text",
"gobal_settlement_percentage_formula": "text",
"line_settlement_percentage_formula": "text",
"retention_type": "text",
"apply_retention_to": "text",
"currency_iso_code": "text",
"bank_account_id": "text",
"cash_account_id": "text",
"direct_debit": "text",
"direct_debit_customer_code": "text",
"direct_debit_customer_date": "text",
"direct_debit_customer_account": "text",
"direct_debit_bank_account_id": "text",
"direct_debit_document_series_id": "text"
},
"relationships": {}
}
}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>/email_addresses'No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato
{
"data": {
"type": "email_addresses", // [OBRIGATÓRIO]
"id": "<id do endereço de email do cliente>", // [OBRIGATÓRIO]
"attributes": {
"email": "test@gmail.com", // [OBRIGATÓRIO]
}
}
}Last updated