# Clientes, Morada e E-mail

## 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.

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/customers" method="get" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

### 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.

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/customers/{clientId}" method="get" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

### 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.&#x20;

{% hint style="info" %}
Para associar uma morada ao cliente deverá já ter inserido um cliente [#criar-cliente](#criar-cliente "mention")e efectuar o seguinte passo [#associar-morada-a-cliente](#associar-morada-a-cliente "mention")
{% endhint %}

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/customers" method="post" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

## 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.&#x20;

<figure><img src="https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FWK9QGTMZuW5WyvnWzJAf%2FDiagramas%20de%20Documentac%CC%A7a%CC%83o-Associar%20Cliente%20a%20Morada.jpg?alt=media&#x26;token=9af6a197-189a-47c6-8556-226089045c26" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
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.
{% endhint %}

Através do `id` obtido pela response do [#criar-cliente](#criar-cliente "mention") este deverá ser usado para obter o id da morada ao fazer um `GET /customers/{id}` [#obter-cliente-por-id](#obter-cliente-por-id "mention")&#x20;

O `id` da morada obtido anteriormente, será usado para atualizar os dados da morada através de um `PATCH / addresses`.

#### Atualizar Morada

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/addresses" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

O body deste pedido (payload JSON) deverá conter as informações de cliente que se pretende atualizar nos respetivos atributos.

{% tabs %}
{% tab title="Payload" %}
{% code title="Payload " %}

```json
{
  "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"
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code title="Response" %}

```json
{
    "data": {
        "type": "addresses",
        "id": "45",
        "attributes": {
            "is_primary": true,
            "address_detail": "Avenida Principal",
            "city": "Setúbal",
            "postcode": "2910-099",
            "region": "Setúbal",
            "name": "Sede",
            "for_discharge": false,
            "for_charge": false,
            "subtype": null,
            "is_saturday_workday": false,
            "is_sunday_workday": false,
            "is_national_holidays_workday": false,
            "code": null,
            "payroll_enumerations_tax_office_id": null
        },
        "relationships": {
            "company": {
                "data": null
            },
            "country": {
                "data": {
                    "type": "countries",
                    "id": "3"
                }
            },
            "customer": {
                "data": null
            },
            "supplier": {
                "data": null
            },
            "user": {
                "data": null
            }
        }
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

| 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.\\

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/customers/{clientId}" method="delete" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

### 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.

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/customers/{clientId}" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

No exemplo que se segue poderá observar todos os campos dentro dos atributos que são possiveis de editar.

{% tabs %}
{% tab title="Request" %}
{% code title="Request" %}

```json

{
    "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" 
        }
    }
}
```

{% endcode %}

{% endtab %}

{% tab title="Response" %}
{% code title="Response" %}

```json
{
    "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",
            "not_final_customer": false,
            "cashed_vat": false,
            "tax_country_region": "PT",
            "country_iso_alpha_2": "PT",
            "saft_import_id": null,
            "is_tax_exempt": false,
            "tax_exemption_reason_id": null,
            "accounting_number": null,
            "data": {},
            "credit_limit_value": null,
            "credit_limit_days": null,
            "has_credit_limit_override": false
        },
        "relationships": {
            "addresses": {
                "data": []
            },
            "company": {
                "data": {
                    "type": "current_company",
                    "id": "800000046"
                }
            },
            "contacts": {
                "data": []
            },
            "defaults": {
                "data": null
            },
            "email_addresses": {
                "data": []
            },
            "main_address": {
                "data": null
            },
            "main_email_address": {
                "data": null
            },
            "tax_exemption_reason": {
                "data": null
            }
        }
    }
}
```

{% endcode %}

{% endtab %}
{% endtabs %}

***

## 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

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/addresses" method="post" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

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

{% code title="Payload" %}

```json
{
    "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
        }
    }
}
```

{% endcode %}

| 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         |

{% hint style="info" %}
"addressable\_id" - corresponde ao id da morada do cliente obtido da relação entre cliente e morada,  através do [#obter-cliente](#obter-cliente "mention")&#x20;
{% endhint %}

{% hint style="info" %}
Para usar outro país que não seja Portugal, poderá consultar mais informação em: [paises](https://api-docs.toconline.pt/apis/apis-auxiliares/paises "mention")
{% endhint %}

***

## 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`.

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/contacts" method="post" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

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**"

{% tabs %}
{% tab title="Payload" %}
{% code title="Exemplo de Payload" %}

```json
{
    "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"
        }
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code title="Exemplo de Response" %}

```json
{
    "data": {
        "type": "contacts",
        "id": "27",
        "attributes": {
            "is_primary": true,
            "name": "teste_cmo",
            "position": null,
            "phone_number": null,
            "mobile_number": null,
            "email": "61_manuel@email.pt"
        },
        "relationships": {
            "supplier": {
                "data": null
            }
        }
    }
}
```

{% endcode %}

<figure><img src="https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FybzSDSrvzyUUdO4pU7JW%2FDiagramas%20de%20Documentac%CC%A7a%CC%83o%20TOCOnline%20API-Criar%20Email%20de%20Cliente.jpg?alt=media&#x26;token=570f2275-3c1e-44cf-914b-0a3fbf33afa5" alt=""><figcaption><p>Exemplo de Criação de E-mail para Cliente</p></figcaption></figure>
{% endtab %}
{% endtabs %}

<figure><img src="https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FuEfiA3uAe0tQ1cOTh7qO%2FDiagramas%20de%20Documentac%CC%A7a%CC%83o%20TOCOnline%20API-Criar%20Email%20de%20Cliente.jpg?alt=media&#x26;token=14c06c66-14d3-4dae-80ea-d2cbdd515412" alt=""><figcaption><p>Exemplo de Criação de E-mail para Cliente</p></figcaption></figure>

### Atualizar E-mail de Cliente

{% hint style="warning" %}
Já deve ter realizado [#criar-email-de-cliente](#criar-email-de-cliente "mention")
{% endhint %}

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.

<details>

<summary>Exemplo de response de um GET/customer/{id}</summary>

```json
{
    "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
            }
        }
    }
}
```

</details>

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.&#x20;

{% openapi src="<https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7>" path="/api/contacts" method="patch" %}
[TOConline Open API.yaml](https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2FZBJyxFky3EPPL5hA0Lxx%2FTOConline%20Open%20API.yaml?alt=media\&token=a2616c07-07e1-4b6e-b74f-3de4caae92d7)
{% endopenapi %}

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.

{% tabs %}
{% tab title="Payload" %}
{% code title="Exemplo de Payload" %}

```json
{
    "data": {
        "type": "contacts",
        "id": "24",
        "attributes": {
            "email": "novo@email.pt"
        }
    }
}
```

{% endcode %}

{% endtab %}

{% tab title="Response" %}
{% code title="Exemplo de Response" %}

```json
{
    "data": {
        "type": "contacts",
        "id": "24",
        "attributes": {
            "is_primary": true,
            "name": "teste",
            "position": null,
            "phone_number": null,
            "mobile_number": null,
            "email": "novo@email.pt"
        },
        "relationships": {
            "supplier": {
                "data": null
            }
        }
    }
}
```

{% endcode %}

{% endtab %}
{% endtabs %}

<figure><img src="https://1863668386-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk7sif7BY0rPzivMcj1HB%2Fuploads%2Fy8ltXAcAv79CnNEiHaAs%2FDiagramas%20de%20Documentac%CC%A7a%CC%83o%20TOCOnline%20API-Atualizar%20Email%20de%20Cliente.jpg?alt=media&#x26;token=818e93b5-ed7f-4fc4-8d2c-583ba1c6af17" alt=""><figcaption><p>Exemplo de Atualização de E-mail para Cliente</p></figcaption></figure>