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 Todos os Clientes

get

Obter Todos os Clientes

Required scopes

This endpoint requires the following scopes:

: commercial

Authorizations

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Responses

200Success

No content

400

Autorização em falta

application/json

401

Sessão inválida

application/json

get/api/customers

GET /api/customers HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

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.

Obter Cliente por ID

get

Obter Cliente por ID

Required scopes

This endpoint requires the following scopes:

: commercial

Authorizations

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Path parameters

clientIdstringRequired

Id do cliente

Example: 60

Responses

200

Sucesso

application/json

404

Recurso não encontrado

application/json

get/api/customers/{clientId}

GET /api/customers/{clientId} HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": {
    "attributes": {
      "business_name": "Empresa de Testes",
      "cashed_vat": false,
      "contact_name": "Testes",
      "country_iso_alpha_2": "PT",
      "data": {},
      "email": "testes@testes.pt",
      "internal_observations": "Empresa de teste",
      "is_tax_exempt": false,
      "mobile_number": "939038342",
      "not_final_customer": false,
      "observations": "Empresa de teste",
      "phone_number": "309867004",
      "saft_import_id": null,
      "tax_country_region": "PT",
      "tax_registration_number": "221976302",
      "website": "http://testes.pt"
    },
    "id": "62",
    "relationships": {
      "addresses": {
        "data": [
          {
            "id": "68",
            "type": "addresses"
          }
        ]
      },
      "company": {
        "data": {
          "id": "800000046",
          "type": "current_company"
        }
      },
      "defaults": {
        "data": {
          "id": "32",
          "type": "customers_defaults"
        }
      },
      "email_addresses": {
        "data": [
          {
            "id": "19",
            "type": "email_addresses"
          }
        ]
      },
      "main_address": {
        "data": {
          "id": "68",
          "type": "addresses"
        }
      },
      "main_email_address": {
        "data": {
          "id": "19",
          "type": "email_addresses"
        }
      },
      "tax_exemption_reason": {
        "data": null
      }
    },
    "type": "customers"
  }
}

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

Criar Clientes

post

Criar Clientes

Required scopes

This endpoint requires the following scopes:

: commercial

Authorizations

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

Responses

200

Sucesso

application/json

400

NIF Inválido

application/json

403

Recurso já existe

application/json

post/api/customers

POST /api/customers HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 338

{
  "data": {
    "attributes": {
      "business_name": "Empresa de Contabilidade",
      "contact_name": "Utilizador",
      "email": "user@email.pt",
      "internal_observations": "Empresa de teste",
      "mobile_number": 939038342,
      "observations": "Empresa de teste",
      "phone_number": 309867004,
      "tax_registration_number": "221976302",
      "website": "https://toconline.pt"
    },
    "type": "customers"
  }
}

{
  "data": {
    "attributes": {
      "business_name": "Empresa de Contabilidade",
      "cashed_vat": false,
      "contact_name": "Utilizador",
      "country_iso_alpha_2": "PT",
      "data": {},
      "email": "testes@testes.pt",
      "internal_observations": "Empresa de teste",
      "is_tax_exempt": false,
      "mobile_number": "939038342",
      "not_final_customer": false,
      "observations": "Empresa de teste",
      "phone_number": "309867004",
      "saft_import_id": null,
      "tax_country_region": "PT",
      "tax_registration_number": "221976302",
      "website": "http://testes.pt"
    },
    "id": "62",
    "relationships": {
      "addresses": {
        "data": []
      },
      "company": {
        "data": {
          "id": "800000046",
          "type": "current_company"
        }
      },
      "defaults": {
        "data": null
      },
      "email_addresses": {
        "data": []
      },
      "main_address": {
        "data": null
      },
      "main_email_address": {
        "data": null
      },
      "tax_exemption_reason": {
        "data": null
      }
    },
    "type": "customers"
  }
}

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

patch

Atualizar Morada

Required scopes

This endpoint requires the following scopes:

: commercial

Authorizations

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

Responses

200

Atualizar Morada / Atualizar Morada

application/json

patch/api/addresses

PATCH /api/addresses HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 168

{
  "data": {
    "attributes": {
      "address_detail": "Avenida Principal",
      "city": "Setúbal",
      "country_id": "3",
      "postcode": "2910-099",
      "region": "Setúbal"
    },
    "id": "45",
    "type": "addresses"
  }
}

200

Atualizar Morada / Atualizar Morada

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

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

Response

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

Atributo

Descrição

Obrigatório

type

Tipo de entidade associada ao endereço (ex: Customer).

Sim

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

Remover Cliente

delete

Remover Cliente

Required scopes

This endpoint requires the following scopes:

: commercial

Authorizations

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Path parameters

clientIdstringRequired

Id do cliente

Example: 60

Responses

200

Sucesso

application/json

400

Pedido Inválido

application/json

404

Recurso não existente

application/json

delete/api/customers/{clientId}

DELETE /api/customers/{clientId} HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "meta": {}
}

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

Response

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

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

Criar Morada

post

Criar Morada

Required scopes

This endpoint requires the following scopes:

: commercial

Authorizations

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

Responses

200

Criar Morada / Criar Morada

application/json

post/api/addresses

POST /api/addresses HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 180

{
  "data": {
    "attributes": {
      "address_detail": "teste 3",
      "addressable_id": 7,
      "addressable_type": "Supplier",
      "city": "Setúbal",
      "postcode": "2910-099",
      "region": "Setúbal"
    },
    "type": "addresses"
  }
}

200

Criar Morada / Criar Morada

{
  "data": {
    "attributes": {
      "address_detail": "teste 3",
      "city": "Setúbal",
      "code": null,
      "for_charge": false,
      "for_discharge": false,
      "is_national_holidays_workday": false,
      "is_primary": false,
      "is_saturday_workday": false,
      "is_sunday_workday": false,
      "name": null,
      "payroll_enumerations_tax_office_id": null,
      "postcode": "2910-099",
      "region": "Setúbal",
      "subtype": null
    },
    "id": "74",
    "relationships": {
      "company": {
        "data": null
      },
      "country": {
        "data": null
      },
      "customer": {
        "data": null
      },
      "supplier": {
        "data": null
      },
      "user": {
        "data": null
      }
    },
    "type": "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

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

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 Clientes, Morada e E-mail

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.

Criar email de Cliente

post

Criar email de Cliente

Required scopes

This endpoint requires the following scopes:

: commercial

Authorizations

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

Responses

200

Sucesso / Suceso / Criar Novo Contacto

application/json

post/api/contacts

POST /api/contacts HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 204

{
  "data": {
    "attributes": {
      "contactable_id": 29,
      "contactable_type": "Supplier",
      "email": "user@email.pt",
      "is_primary": true,
      "mobile_number": null,
      "name": null,
      "phone_number": null,
      "position": null
    },
    "type": "contacts"
  }
}

200

Sucesso / Suceso / Criar Novo Contacto

{
  "data": {
    "attributes": {
      "email": "user@email.pt",
      "is_primary": true,
      "mobile_number": null,
      "name": null,
      "phone_number": null,
      "position": null
    },
    "id": "22",
    "relationships": {
      "supplier": {
        "data": null
      }
    },
    "type": "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"
        }
    }
}

Exemplo de Response

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

Atualizar E-mail de Cliente

Já deve ter realizado Clientes, Morada e E-mail

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.

Atualizar email de Cliente

patch

Atualizar email de Cliente

Required scopes

This endpoint requires the following scopes:

: commercial

Authorizations

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

Responses

200

Sucesso / Sucesso

application/json

patch/api/contacts

PATCH /api/contacts HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "data": {
    "attributes": {
      "email": "novo_sup@email.pt"
    },
    "id": "24",
    "type": "contacts"
  }
}

200

Sucesso / Sucesso

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

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

Exemplo de Response

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

PreviousEmpresa NextFornecedores, Morada e E-mail

Last updated 2 years ago