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.

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.

Payload 
{
  "data": {
    "type": "addresses", //OBRIGATÓRIO
    "id": [ID ADRESS],      //OBRIGATÓRIO provém do id da address obtido no get anterio
    "attributes": {
      "address_detail": "string",
      "city": "string",
      "postcode": "string",
      "region": "string"
    }
  }
}

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.

Request

{
    "data": {
        "type": "customers",
        "id": "31",
        "attributes": {
            "tax_registration_number": "146081692",
            "business_name": "Isso mesmo",
            "contact_name": "Bruno Cascais",
            "website": "http://issomesmo.pt",
            "phone_number": "21344444",
            "mobile_number": "935678999",
            "email": "aaaaa@issomesmo.pt",
            "observations": "observções do cliente",
            "internal_observations": "observações internas" 
        }
    }
}

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

Payload
{
    "data": {
        "type": "addresses",
        "attributes": {
            "addressable_type": "Customer",  //OBRIGATÓRIO
            "addressable_id": 47,            //OBRIGATÓRIO - ID da morada do Cliente
            "address_detail": "morada teste 2", 
            "city": "Setúbal",                
            "postcode": "2910-099",
            "region": "Setúbal" 
            "country_id" : 1 // 1 = PT (Portugal Continental); //2 = PT_MA (Madeira); //3 = PT_AC (Açores)...Ver Get/countries
        }
    }
}

"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

Criar E-mail de Cliente

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"

Exemplo de Payload
{
    "data": {
        "type": "contacts",
        "attributes": {
            "is_primary": true,
            "name": "teste_cmo",
            "position": null,
            "phone_number": null,
            "mobile_number": null,
            "email": "61_manuel@email.pt",
            "categories": [
                "general"
            ],
            "contactable_id": 61,
            "contactable_type": "Customer"
        }
    }
}

Atualizar E-mail de Cliente

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.

Exemplo de response de um GET/customer/{id}
{
    "data": {
        "type": "customers",
        "id": "61",
        "attributes": {
            "tax_registration_number": "229659179",
            "business_name": "Manuel Ricardo Ribeiro",
            "contact_name": null,
            "website": null,
            "phone_number": null,
            "mobile_number": null,
            "email": null,
            "observations": null,
            "internal_observations": null,
            "not_final_customer": false,
            "cashed_vat": false,
            "tax_country_region": "PT",
            "country_iso_alpha_2": "PT",
            "saft_import_id": null,
            "is_tax_exempt": false,
            "data": {}
        },
        "relationships": {
            "addresses": {
                "data": [
                    {
                        "type": "addresses",
                        "id": "67"
                    }
                ]
            },
            "company": {
                "data": {
                    "type": "current_company",
                    "id": "800000046"
                }
            },
            "defaults": {
                "data": {
                    "type": "customers_defaults",
                    "id": "31"
                }
            },
            "email_addresses": {
                "data": [
                    {
                        "type": "email_addresses",
                        "id": "24"
                    }
                ]
            },
            "main_address": {
                "data": {
                    "type": "addresses",
                    "id": "67"
                }
            },
            "main_email_address": {
                "data": {
                    "type": "email_addresses",
                    "id": "24"
                }
            },
            "tax_exemption_reason": {
                "data": null
            }
        }
    }
}

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.

Exemplo de Payload
{
    "data": {
        "type": "contacts",
        "id": "24",
        "attributes": {
            "email": "novo@email.pt"
        }
    }
}

PreviousEmpresaNextFornecedores, Morada e E-mail

Last updated