Características dos recursos da Web API
Os recursos da Web API correspondem às entidades geridas pelo sistema, os clientes, os fornecedores, encomendas, faturas, etc. Estas entidades têm um conjunto de características transversais que implementam comportamentos uniformes. Essas características e comportamentos têm influência na forma como os recursos são tratados na Web API. De seguida descrevem-se as características principais das entidades. Nome do recurso Os recursos são identificados pelo seu nome em inglês, sempre no plural. Eis alguns exemplos: Identificador único Todas as entidades do sistema têm um identificador único que é gerado automaticamente pelo sistema. Trata-se de um GUID (global unique identifier). Todas as entidades têm, portanto, um atributo com o nome “id” que corresponde a este identificador único. Eis um exemplo (atributo “id”): É este identificador que deve ser utilizado nos endpoints que suportam a seleção do registo pelo seu id. Como no exemplo seguinte: Chave natural da entidade A chave natural corresponde a identificador único da entidade, tipicamente uma string, sendo que, em alguns casos, essa chave pode ser composta por vários atributos, que é reconhecida e definida pelo utilizador. É essa chave que o utilizador introduz (ou é gerada automaticamente) na própria aplicação. Na prática trata-se de uma forma de obter um registo sem ter que conhecer o identificador interno. Normalmente, o nome do atributo que corresponde à chave natural com o sufixo “Key” no nome da própria entidade. Exemplos: CustomerKey, SupplierKey, CompanyKey. Veja-se a chave natural no exemplo anterior (atributo “typeKey”): Note-se que, no caso da entidade Order Types, a chave natural é composta pela chave da empresa (Company) e pelo valor do atributo TypeKey. A chave natural pode ser utilizada nos endpoints que suportam seleção do registo pela chave. O exemplo seguinte ilustra a seleção pela chave no caso de uma entidade com uma chave simples: Quando a chave é composta por um ou mais atributos, os seus valores devem ser colocados no pedido separados por /, como no seguinte exemplo: Chaves estrangeiras Uma chave estrangeira define uma relação entre duas entidades. Por exemplo, uma fatura pertence a um cliente, o que significa que a entidade Invoices tem uma chave estrangeira para a entidade CustomerParties. As chaves estrangeiras no Jasmin são definidas pela inclusão do identificador único da entidade referenciada (CustomerParties) no registo da entidade que tem a referência (Invoices). Em termos de recursos da Web API podemos ver isso no exemplo seguinte (atributo “buyerCustomerPartyId”): É comum que os recursos da “entidade origem” incluam ainda uma série de atributos da “entidade referenciada” como a sua chave natural (“buyerCustomerParty”), a sua descrição (“buyerCustomerPartyName”). Estes atributos adicionais permitem, por exemplo, apresentar esses dados comuns ao utilizador sem ser necessário fazer uma consulta adicional à Web API. Praticamente todas as entidades do sistema incluem um atributo que descreve cada registo. Por exemplo, um cliente tem um código (a chave natural) e um nome (a descrição). O nome do atributo pode ter várias formas, sendo que as mais comuns são as seguintes: Todas as entidades incluem sempre os seguintes atributos para auditing: Estes atributos não podem ser manipulados pelo utilizador e, por isso, também não podem ser modificados pela Web API. São apenas de consulta.Identificação
{
"typeKey": "ECL2",
"description": "Encomenda",
"deliveryOnInvoice": false,
"isInternal": false,
"company": "PRI",
"companyId": "b74e4e50-0c84-45b0-b20a-836cc45b2409",
"companyDescription": "PRIMAVERA BSS",
"documentTypeSeries": [
(...)
],
"fiscalDocumentType": "NE",
"fiscalDocumentTypeId": "b5eaa842-24e8-442a-b423-62eb43669fce",
"fiscalDocumentTypeDescription": "Nota de encomenda",
"defaultInvoiceType": "FA",
"defaultInvoiceTypeId": "86285923-ef02-4e6f-bc34-972578ae8ae3",
"defaultInvoiceTypeDescription": "Fatura",
"orderNature": 1,
"defaultMemoType": null,
"defaultMemoTypeId": null,
"defaultMemoTypeDescription": null,
"defaultDeliveryType": "GR",
"defaultDeliveryTypeId": "e76764aa-d606-4e4e-a7d8-7525dd36c5ae",
"defaultDeliveryTypeDescription": "Guia de Remessa",
"defaultGoodsReceiptNoteType": null,
"defaultGoodsReceiptNoteTypeId": null,
"defaultGoodsReceiptNoteTypeDescription": null,
"contactType": "01",
"contactTypeId": "ffff2a64-152b-4908-9c2c-82d461f176c2",
"contactTypeDescription": "Principal",
"notification": "DEFAULT",
"notificationId": "353df62d-c525-4b69-ad85-4de6c202c9d8",
"notificationDescription": "Notificação Jasmin",
"naturalKey": "ECL2",
"isDraft": false,
"id": "6b2d37d9-4d92-e711-9401-0003ff41c4eb",
"isActive": true,
"isDeleted": false,
"isSystem": false,
"createdBy": "[email protected]",
"createdOn": "2017-09-05T15:21:42.939088",
"modifiedBy": "[email protected]",
"modifiedOn": "2017-09-05T15:21:42.939088",
"subscriptionId": null,
"draftId": "00000000-0000-0000-0000-000000000000"
}
https://baseurl/api/{Account}/{Subscription}/salesCore/orderTypes/6b2d37d9-4d92-e711-9401-0003ff41c4eb
Chaves
{
"typeKey": "ECL2",
"description": "Encomenda",
"deliveryOnInvoice": false,
"isInternal": false,
"company": "PRI",
"companyId": "b74e4e50-0c84-45b0-b20a-836cc45b2409",
"companyDescription": "PRIMAVERA BSS",
"documentTypeSeries": [
(...)
],
"fiscalDocumentType": "NE",
"fiscalDocumentTypeId": "b5eaa842-24e8-442a-b423-62eb43669fce",
"fiscalDocumentTypeDescription": "Nota de encomenda",
"defaultInvoiceType": "FA",
"defaultInvoiceTypeId": "86285923-ef02-4e6f-bc34-972578ae8ae3",
"defaultInvoiceTypeDescription": "Fatura",
"orderNature": 1,
"defaultMemoType": null,
"defaultMemoTypeId": null,
"defaultMemoTypeDescription": null,
"defaultDeliveryType": "GR",
"defaultDeliveryTypeId": "e76764aa-d606-4e4e-a7d8-7525dd36c5ae",
"defaultDeliveryTypeDescription": "Guia de Remessa",
"defaultGoodsReceiptNoteType": null,
"defaultGoodsReceiptNoteTypeId": null,
"defaultGoodsReceiptNoteTypeDescription": null,
"contactType": "01",
"contactTypeId": "ffff2a64-152b-4908-9c2c-82d461f176c2",
"contactTypeDescription": "Principal",
"notification": "DEFAULT",
"notificationId": "353df62d-c525-4b69-ad85-4de6c202c9d8",
"notificationDescription": "Notificação Jasmin",
"naturalKey": "ECL2",
"isDraft": false,
"id": "6b2d37d9-4d92-e711-9401-0003ff41c4eb",
"isActive": true,
"isDeleted": false,
"isSystem": false,
"createdBy": "[email protected]",
"createdOn": "2017-09-05T15:21:42.939088",
"modifiedBy": "[email protected]",
"modifiedOn": "2017-09-05T15:21:42.939088",
"subscriptionId": null,
"draftId": "00000000-0000-0000-0000-000000000000"
}
https://baseurl/api/{Account}/{Subscription}/corePatterns/companies/company
https://baseurlapi/{Account}/{Subscription}/salesCore/orderTypes/COMPANY/EI
{
"version": [
(…)
],
(…)
"buyerCustomerPartyName": "SOFRIO",
"buyerCustomerPartyTaxId": "123456789",
"buyerCustomerPartyAddress": "SOFRIOrnAvenida do Gelo 11rn4719-006 Braga",
"buyerCustomerParty": "0019",
"buyerCustomerPartyId": "2dd17e54-0369-4264-8c43-dcdda7507f9d",
"buyerCustomerPartyBaseEntityId": "c805b2c2-8f7c-47ca-931e-5fae28b7aa35",
"buyerCustomerPartyDescription": "SOFRIO",
(…)
"id": "682df3eb-fc6d-e711-9401-0003ff41c6db",
(…)
}
Descrições
Atributos Auditing
login para deixar a sua opinião.