Fornecedores, Morada e E-mail
As rotas definidas no presente capítulo permitem gerir toda a informação relativa a fornecedores: criação, edição, remoção, etc
Last updated
As rotas definidas no presente capítulo permitem gerir toda a informação relativa a fornecedores: criação, edição, remoção, etc
Last updated
Esta primeira rota permite obter a informação de todos os fornecedores disponíveis. Para tal, deve apenas realizar o seguinte pedido:
ttps://api/v1.toconline.com/api/suppliers
Se pretender obter a informação de um fornecedor específico, deverá realizar o mesmo pedido, especificando o id do fornecedor que deseja consultar
Permite a criação de novas instâncias de fornecedores. 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. Dentro de data, deverá colocar todos os parâmetros obrigatórios e poderá também colocar os restantes parâmetros, se for do seu interesse. O tipo dos parâmetros está também especificado.
{
"data": {
"type": "suppliers",
"attributes": {
"tax_registration_number": 533186331, //OBRIGATÓRIO
"business_name": "A Empresa", //OBRIGATÓRIO
"website": null,
"is_taxable": null,
"is_tax_exempt": null,
"self_billing": null,
"document_series_id": null,
"internal_observations": null,
"tax_country_region": null,
"is_independent_worker": null
}
}
}
type
Tipo de entidade (neste caso, fornecedor).
Sim
tax_registration_number
Número de identificação fiscal do fornecedor.
Sim
business_name
Nome comercial ou razão social do fornecedor.
Sim
website
Website do fornecedor (opcional).
Não
is_taxable
Indica se o fornecedor é tributável (opcional).
Não
is_tax_exempt
Indica se o fornecedor está isento de impostos (opcional).
Não
self_billing
Indica se o fornecedor permite a autogestão de faturas (opcional).
Não
document_series_id
ID da série de documentos associada ao fornecedor (opcional).
Não
internal_observations
Observações internas sobre o fornecedor (opcional).
Não
tax_country_region
Região fiscal do fornecedor (opcional).
Não
is_independent_worker
Indica se o fornecedor é um trabalhador independente (opcional).
Não
A sequência de passos delineada no diagrama proporciona uma compreensão do processo, desde a criação do forncedor até a sua associação com uma morada.
Quando um forncedor é criado, uma morada principal fica associada ao fornecedor. Esta morada por default vem vazia e é necessário atualizar com os dados da nova morada do fornecedor.
Através do id
obtido pela response do Criar Fornecedor este deverá ser usado para obter o id da morada ao fazer um GET /suppliers/{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.
{
"data": {
"type": "addresses",
"id": "45",
"attributes": {
"address_detail": "Avenida Principal",
"city": "Setúbal",
"postcode": "2910-099",
"region": "Setúbal",
"country_id": "3"
}
}
}
A seguinte rota permite a remoção de um dado fornecedor. 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 forncedor que quer eliminar, que poderá fazer utilizando a primeira rota desta página, por exemplo, terá simplesmente de fazer o pedido:
A rota PATCH permite a edição de um fornecedor existente. O body deste pedido deverá ser igual ao descrito na rota POST, contendo todas as informações obrigatórias do fornecedor, atualizadas para os valores que tenciona alterar, além do "id" do fornecedor. Álem disto, o pedido deverá ser feito a https://apiv1.toconline.com/suppliers/{id}
, sendo que {id} é o identificador do fornecedor que tenciona atualizar.
Quando um Fornecedor é criado este já tem uma morada vazia associada, mas é possível adicionar mais do que uma morada ao Fornecedor.
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
{
"data": {
"type": "addresses",
"attributes": {
"addressable_type": "Supplier", //OBRIGATÓRIO
"addressable_id": 7, //OBRIGATÓRIO - ID da morada do Fornecedor
"address_detail": "teste 3",
"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
}
}
}
type
Tipo de entidade (neste caso, endereço).
Sim
addressable_type
Tipo de entidade à qual o endereço está associado (neste caso, fornecedor).
Sim
addressable_id
ID do fornecedor associado ao endereço.
Sim
address_detail
Detalhes específicos do endereço, como rua e número.
Não
city
Cidade do endereço.
Não
postcode
Código postal do endereço.
Não
region
Região do endereço (por exemplo, província, estado).
Não
country_id
ID do país do endereço (1 = Portugal Continental, 2 = Madeira, 3 = Açores).
Não
Para proceder à criação do E-mail de um fornecedor pela primeira vez deverá utilizar a POST / contacts
.
O body deste pedido (<payload JSON>) deverá conter as informações de fornecedor que se pretende atualizar, sendo obrigatório campo "contactable_id" identificador do fornecedor que tenciona atualizar e o "contactable_type" sendo este do tipo "Supplier"
{
"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"
}
}
}
Já deve ter realizado Criar E-mail de Fornecedor
Usando o GET / supplier{id}
deverá obter o id correspondente ao contacto do fornecedor, 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 fornecedor deverá utilizar a PATCH / contacts
usando o id obtido do main_contact obtido do fornecedor 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.
{
"data": {
"type": "contacts",
"id": "24",
"attributes": {
"email": "novo@email.pt"
}
}
}
Obter Morada por Id
id da morada
45
GET /api/addresses/{id} HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
Obter Todas as Moradas Copy / Obter Todas as Moradas Copy
{
"data": {
"attributes": {
"address_detail": "",
"city": "",
"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": "Main Address",
"payroll_enumerations_tax_office_id": null,
"postcode": "",
"region": null,
"subtype": null
},
"id": "3",
"relationships": {
"company": {
"data": null
},
"country": {
"data": {
"id": "1",
"type": "countries"
}
},
"customer": {
"data": null
},
"supplier": {
"data": null
},
"user": {
"data": {
"id": "800000863",
"type": "current_company_users"
}
}
},
"type": "addresses"
}
}
Criar Fornecedor
POST /api/suppliers HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 448
{
"data": {
"attributes": {
"accounting_number": null,
"business_name": "A Empresa 3",
"country_iso_alpha_2": "PT",
"document_series_id": null,
"internal_observations": null,
"is_independent_worker": false,
"is_tax_exempt": false,
"is_taxable": false,
"saft_import_id": null,
"self_billing": null,
"tax_country_region": "PT",
"tax_exemption_reason_id": null,
"tax_registration_number": "533186331",
"trusted_email_source": false,
"website": "www.a_empresa3.pt"
},
"type": "suppliers"
}
}
Criar Fornecedor
{
"data": {
"attributes": {
"business_name": "A Empresa 3",
"country_iso_alpha_2": "PT",
"document_series_id": null,
"internal_observations": null,
"is_independent_worker": false,
"is_tax_exempt": false,
"is_taxable": false,
"saft_import_id": null,
"self_billing": null,
"tax_country_region": "PT",
"tax_registration_number": "533186331",
"website": "www.a_empresa3.pt"
},
"id": "29",
"relationships": {
"addresses": {
"data": []
},
"bank_accounts": {
"data": []
},
"company": {
"data": {
"id": "800000046",
"type": "current_company"
}
},
"contacts": {
"data": []
},
"defaults": {
"data": null
},
"main_address": {
"data": null
},
"main_contact": {
"data": null
},
"tax_exemption_reason": {
"data": null
}
},
"type": "suppliers"
}
}
Atualizar Morada
PATCH /api/addresses HTTP/1.1
Host: {{base_url}}
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"
}
}
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"
}
}
Atualizar Fornecedor
PATCH /api/suppliers HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 454
{
"data": {
"attributes": {
"accounting_number": null,
"business_name": "A Empresa",
"country_iso_alpha_2": "PT",
"document_series_id": null,
"internal_observations": null,
"is_independent_worker": false,
"is_tax_exempt": false,
"is_taxable": false,
"saft_import_id": null,
"self_billing": null,
"tax_country_region": "PT",
"tax_exemption_reason_id": null,
"tax_registration_number": "533186331",
"trusted_email_source": false,
"website": "www.a_empresa.pt"
},
"id": "7",
"type": "suppliers"
}
}
Sucesso
{
"data": {
"attributes": {
"business_name": "A Empresa",
"country_iso_alpha_2": "PT",
"document_series_id": null,
"internal_observations": null,
"is_independent_worker": false,
"is_tax_exempt": false,
"is_taxable": false,
"saft_import_id": null,
"self_billing": null,
"tax_country_region": "PT",
"tax_registration_number": "533186331",
"website": "www.a_empresa.pt"
},
"id": "7",
"relationships": {
"addresses": {
"data": []
},
"bank_accounts": {
"data": []
},
"company": {
"data": {
"id": "800000046",
"type": "current_company"
}
},
"contacts": {
"data": []
},
"defaults": {
"data": null
},
"main_address": {
"data": null
},
"main_contact": {
"data": null
},
"tax_exemption_reason": {
"data": null
}
},
"type": "suppliers"
}
}
Criar Morada
POST /api/addresses HTTP/1.1
Host: {{base_url}}
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"
}
}
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 /api/contacts HTTP/1.1
Host: {{base_url}}
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"
}
}
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 /api/contacts HTTP/1.1
Host: {{base_url}}
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81
{
"data": {
"attributes": {
"email": "novo_sup@email.pt"
},
"id": "24",
"type": "contacts"
}
}
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"
}
}