TOConline - Documentação API
  • Introdução
  • Setup do Postman
  • Autenticação Simplificada
  • Autenticação Detalhada
  • Características dos pedidos
  • APIs
    • Empresa
      • Clientes, Morada e E-mail
      • Fornecedores, Morada e E-mail
      • Produtos e Serviços
    • Vendas
      • Documentos de Venda
      • Documentos Retificativos
      • Recibos de Venda
      • Descarregar PDF de Documentos de Venda
      • Descarregar PDF de Recibo
      • Comunicação de documentos à AT
      • Envio de Documentos por email
      • Envio de Recibos por email
    • Compras
      • Documentos de Compra
      • Pagamentos
      • Descarregar PDF de Documentos de Compra
      • Descarregar PDF de Pagamentos
      • Comunicação de documentos à AT
    • Versões Anteriores
      • Vendas
        • Documentos de Venda
        • Recibos de Venda
      • Compras
        • Documentos de Compra
        • Pagamentos
    • APIs Auxiliares
      • Descritores de Taxa
      • Família de Itens
      • Países
      • Unidades de Medida
      • Contas Bancárias
      • Caixa Associada
      • Unidade Monetária
      • Taxas
      • Categorias de Despesa
      • Documentos de Série
Powered by GitBook
On this page
  1. APIs
  2. Empresa

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.

PreviousEmpresaNextFornecedores, Morada e E-mail

Last updated 10 months ago

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

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.

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

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

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

Exemplo de Criação de E-mail para Cliente
Exemplo de Criação de E-mail para Cliente
Exemplo de Atualização de E-mail para Cliente

Obter Todos os Clientes

get

Obter Todos os Clientes

Authorizations
Responses
200Success
400
Autorização em falta
application/json
401
Sessão inválida
application/json
get
GET /api/customers HTTP/1.1
Host: {{base_url}}
Accept: */*

No content

Obter Cliente por ID

get

Obter Cliente por ID

Authorizations
Path parameters
clientIdstringRequired

Id do cliente

Example: 60
Responses
200
Sucesso
application/json
404
Recurso não encontrado
application/json
get
GET /api/customers/{clientId} HTTP/1.1
Host: {{base_url}}
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"
  }
}

Remover Cliente

delete

Remover Cliente

Authorizations
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
DELETE /api/customers/{clientId} HTTP/1.1
Host: {{base_url}}
Accept: */*
{
  "meta": {}
}
  • Cliente
  • Obter Todos os Clientes
  • GETObter Todos os Clientes
  • Obter Cliente por Id
  • GETObter Cliente por ID
  • Criar Cliente
  • POSTCriar Clientes
  • Associar morada a Cliente
  • PATCHAtualizar Morada
  • Remover Cliente
  • DELETERemover Cliente
  • Atualizar Cliente
  • Morada
  • Criar Morada
  • POSTCriar Morada
  • E-mail
  • Criar E-mail de Cliente
  • POSTCriar email de Cliente
  • Atualizar E-mail de Cliente
  • PATCHAtualizar email de Cliente

Criar Clientes

post

Criar Clientes

Authorizations
Body
Responses
200
Sucesso
application/json
400
NIF Inválido
application/json
403
Recurso já existe
application/json
post
POST /api/customers HTTP/1.1
Host: {{base_url}}
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"
  }
}

Atualizar Morada

patch

Atualizar Morada

Authorizations
Body
Responses
200
Atualizar Morada / Atualizar Morada
application/json
patch
PATCH /api/addresses HTTP/1.1
Host: {{base_url}}
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"
  }
}

Criar Morada

post

Criar Morada

Authorizations
Body
Responses
200
Criar Morada / Criar Morada
application/json
post
POST /api/addresses HTTP/1.1
Host: {{base_url}}
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"
  }
}

Criar email de Cliente

post

Criar email de Cliente

Authorizations
Body
Responses
200
Sucesso / Suceso / Criar Novo Contacto
application/json
post
POST /api/contacts HTTP/1.1
Host: {{base_url}}
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"
  }
}

Atualizar email de Cliente

patch

Atualizar email de Cliente

Authorizations
Body
Responses
200
Sucesso / Sucesso
application/json
patch
PATCH /api/contacts HTTP/1.1
Host: {{base_url}}
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"
  }
}