Clientes, Morada e E-mail
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.
Last updated
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.
Last updated
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)
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 irá obter como resposta apenas as informações de um único cliente, em vez de receber uma lista de todos os clientes existentes.
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
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.
O body deste pedido (payload JSON) deverá conter as informações de cliente que se pretende atualizar nos respetivos atributos.
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
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.\
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.
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
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
Para proceder à criação do E-mail de um cliente pela primeira vez deverá utilizar a POST / contacts.
O body deste pedido (<payload JSON>) deverá conter as informações de cliente que se pretende atualizar, sendo obrigatório campo "contactable_id" identificador do cliente que tenciona atualizar e o "contactable_type" sendo este do tipo "Customer"
Já deve ter realizado #criar-email-de-cliente
Usando o GET / customer{id} deverá obter o id correspondente ao contacto do cliente, que se encontra localizado na área de relationships-> main_contact, como pode observar no exemplo de response abaixo.
Para proceder à atualização do E-mail de um cliente deverá utilizar a PATCH / contacts usando o id obtido do main_contact obtido do cliente pretendido.
O body deste pedido (<payload JSON>) deverá conter as informações de cliente que se pretende atualizar, sendo obrigatório campo "id" id do contacto correspondente ao utilizador que tenciona atualizar e o "email" novo a ser alterado.
