Clientes, Morada e Email
As rotas definidas no presente capítulo permitem gerir toda a informação relativa aos clientes associados a uma dada empresa e as suas respetivas moradas e emails.
Cliente
O TOC Online disponibiliza as seguintes rotas que permitem operações sobre clientes (customers) da empresa:
GET – obter informação de cliente
POST – criar novos clientes
PATCH – Alterar um cliente
DELETE – Apagar um cliente (atenção, o uso desta operação não permite a recuperação do identificador inicial)
Obter Todos os Clientes
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.
Obter Cliente por Id
À semelhança do pedido anterior, se este for realizado para a rota irá obter como resposta apenas as informações de um único cliente, em vez de receber uma lista de todos os clientes existentes.
Criar Cliente
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.
Para associar uma morada ao cliente deverá já ter inserido um cliente Criar Clientee efectuar o seguinte passo Associar morada a Cliente
Associar morada a Cliente
A sequência de passos delineada no diagrama proporciona uma compreensão do processo, desde a criação do cliente até a sua associação com uma morada.
Quando um cliente é criado, uma morada principal fica associada ao cliente. Esta morada por default vem vazia e é necessário atualizar com os dados da nova morada do cliente.
Através do id obtido pela response do Criar Cliente este deverá ser usado para obter o id da morada ao fazer um GET /customers/{id} Obter Cliente por Id
O id da morada obtido anteriormente, será usado para atualizar os dados da morada através de um PATCH / addresses.
Atualizar Morada
O body deste pedido (payload JSON) deverá conter as informações de cliente que se pretende atualizar nos respetivos atributos.
| Atributo | Descrição | Obrigatório |
|---|---|---|
type | Tipo de entidade associada ao endereço (ex: Customer). | Sim |
id | ID da entidade associada ao endereço. | Sim |
address_detail | Detalhes do endereço (ex: rua, número). | Não |
city | Cidade. | Não |
postcode | Código postal. | Não |
region | Região ou província. | Não |
Remover Cliente
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.\
Atualizar Cliente
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.
No exemplo que se segue poderá observar todos os campos dentro dos atributos que são possiveis de editar.
Morada
Criar Morada
Quando um Cliente é criado este já tem uma morada vazia associada, mas é possível adicionar mais do que uma morada ao Cliente.
De modo a associar uma morada a um cliente, deverá realizar o seguinte pedido
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
| Atributo | Descrição | Obrigatório |
|---|---|---|
type | Tipo de entidade associada ao endereço (ex: Customer). | Sim |
addressable_type | Tipo de entidade associada ao endereço (ex: Customer). | Sim |
addressable_id | ID da entidade associada ao endereço (ex: ID do Cliente). | Sim |
address_detail | Detalhes do endereço (ex: rua, número). | Não |
city | Cidade. | Não |
postcode | Código postal. | Não |
region | Região ou província. | Não |
country_id | ID do país. | Não |
"addressable_id" - corresponde ao id da morada do cliente obtido da relação entre cliente e morada, através do #obter-cliente
Para usar outro país que não seja Portugal, poderá consultar mais informação em: Países
E-mail
Atualizar Email de Cliente
Para proceder à actualização do E-mail de um cliente deverá utilizar a PATCH / customers.
Será devolvido o elemento 'data' correspondente ao cliente actualizado (Schema).
O body deste pedido (<payload JSON>) deverá conter as informações de cliente que se pretende atualizar, sendo obrigatório campo "id" identificador do cliente que tenciona atualizar.
Last updated
