Quais são os endpoints da Web API?
A Web API disponibiliza endpoints para aceder a todas as entidades do sistema e para realizar as seguintes operações: Nota: Não existem endpoints para atualizar um registo numa única operação. Estas são as operações standard disponíveis para todas as entidades. Podem estar disponíveis outras operações para entidades particulares, de acordo com a respetiva lógica de negócio. A lista exaustiva de todos os endpoints, operações e parâmetros de entrada está disponível na documentação de referência. Por questões de organização, as entidades e os endpoints estão agrupados em módulos. Um módulo define uma categoria de entidades que estão logicamente relacionadas porque fazem parte da mesma área funcional do produto. O identificador do módulo é utilizado no URL do endpoint antes do identificador da entidade (sales nos exemplos anteriores). Seguem alguns exemplos dos módulos existentes e respetivas entidades: As entidades são identificadas por um nome que normalmente corresponde ao seu nome em Inglês, em camel case. Por exemplo, a encomenda de compra e a encomenda de venda são ambas identificadas pelo termo order mas não existe conflito porque estão em módulos diferentes (purchases e sales). Outros exemplos de nomes de entidades podem ser a condição de entrega (deliveryTerm), caixa (pettyCash) ou instituição financeira (financialInstitution). A forma mais fácil de determinar o nome exato de cada entidade na Web API é consultar a documentação de referência da API. Listagem de uma entidade É possível obter a lista de todos os registos de uma entidade, como por exemplo, todos os clientes existentes, através do endpoint principal com o verb GET. O resultado é devolvido no corpo da mensagem em JSON: Este resultado é uma lista de resources CustomerPartyResource. Quando se pretende criar uma nova entidade, como por exemplo, um método de pagamento, deve utilizar-se o endpoint principal da entidade e o verb POST. Os dados da entidade nova devem ser fornecidos no corpo da mensagem. Se o registo for devidamente criado, será devolvido o status code 201 (Created) e o identificador do novo registo será devolvido no corpo da mensagem. Os registos existentes no sistema podem ser atualizados atributo a atributo, usando o endpoint respetivo. Usando o exemplo anterior, podemos atualizar o atributo “useInAccountsPayable” da condição de pagamento usando o seguinte URL: Note-se que este URL inclui a chave do registo (PT001) antes da parte que define o atributo a atualizar. O novo valor do atributo deve ser passado no corpo da mensagem em JSON. Pode obter-se um determinado registo de uma entidade de duas formas: usando o identificador único do registo (o resultado da operação de criação) ou a chave única do registo (um dos atributos do registo). Os parâmetros dos endpoints serão diferentes, mas ambos usam o verb GET. Os registos podem ser eliminados (ou anulados, dependendo da entidade em causa) usando o verbo DELETE no endpoint principal. Neste caso, também se pode usar o identificador do registo ou a chave natural para identificar o registo a eliminar. Se o registo for eliminado com sucesso o status code devolvido será o 204 (No Content).Operação Verb Exemplo Obter uma lista de todos os registos GET GET /sales/orders Obter uma página da lista de todos os registos GET GET /sales/orders?page={page}&pageSize={size} Obter um registo a partir do seu id GET GET /sales/orders/{id} Obter um registo a partir da sua chave GET GET /sales/orders/{key} Criação de um novo registo POST POST /sales/orders Atualizar o valor de um atributo do registo PUT PUT /sales/orders/{key}/{field} Anular um registo a partir do seu id DELETE DELETE /sales/orders/{id} Anular um registo a partir da sua chave DELETE DELETE /sales/orders/{key} Organização dos endpoints
Módulo Descrição Entidades Financials Tratamento financeiro das transações financialInstitutions, paymentMethods, pettyCashes Logistics Tratamento logístico das transações deliveryTerms, deliveryTypes, shippingMethods Purchases Transações de compras a fornecedores invoice, orders, supplierParties Sales Transações de vendas a clientes invoices, orders, customerParties Entidades (Resources)
https://baseurl/api/{account}/{subscription}/salesCore/customerParties
[
{
"settlementDiscountPercent": 10,
"locked": false,
"oneTimeCustomer": false,
"endCustomer": true,
"partyKey": "0001",
"partyKeySegments": null,
"partyKeySequenceId": null,
"searchTerm": null,
"name": "Fornecedor",
"companyTaxID": "123456789",
"electronicMail": null,
"telephone": null,
"mobile": null,
"websiteUrl": null,
"notes": null,
"picture": null,
"pictureThumbnail": null,
"streetName": "Rua",
"buildingNumber": "100",
"postalZone": "4700-100",
"cityName": "Braga",
"contactName": "Fornecedor",
"contactTitle": null,
"username": null,
"externalId": null,
"externalVersion": null,
"isExternallyManaged": false,
"customerGroup": "01",
"customerGroupId": "59548ad9-8647-400b-9a6d-4ad9042179d0",
"customerGroupDescription": "Clientes Finais",
"priceList": "PVP1",
"priceListId": "d74c0465-edfb-4855-a988-5e8ee40e555f",
"priceListDescription": "Preço de venda ao público 1",
"paymentMethod": "NUM",
"paymentMethodId": "6fcdea7e-274c-40bd-aeee-848d73ccd4d3",
"paymentMethodDescription": "Numerário",
"paymentTerm": "00",
"paymentTermId": "34a8eeac-9dfe-4ada-b46d-8776566dc5f4",
"paymentTermDescription": "Pronto Pagamento",
"salesperson": null,
"salespersonId": null,
"salespersonBaseEntityId": null,
"salespersonDescription": null,
"partyTaxSchema": "IVA-RN-MN2",
"partyTaxSchemaId": "7bdc2748-fa41-e711-9401-0003ff41e200",
"partyTaxSchemaDescription": "IVA - Regime Normal - Mercado Nacional",
"partyWithholdingTaxSchema": null,
"partyWithholdingTaxSchemaId": null,
"partyWithholdingTaxSchemaDescription": null,
"deliveryTerm": "EM-MAO",
"deliveryTermId": "d50e4e63-e95f-406a-91f6-b7a0c1b45674",
"deliveryTermDescription": "Entregue em mão",
"accountingSchema": 1,
"accountingParty": null,
"accountingPartyId": null,
"accountingPartyDescription": null,
"currency": "EUR",
"currencyId": "b28426d4-f1c0-4210-baa3-a080cf06ff4f",
"currencyDescription": "Euro",
"country": "PT",
"countryId": "02c605d0-24ca-11df-85ae-005056c00001",
"countryDescription": "Portugal",
"address": "3",
"addressId": "85c719da-56b9-4004-88b2-9b47b4e376cf",
"contact": "2",
"contactId": "85c719da-56b9-4004-88b2-9b47b4e376cf",
"culture": "PT-PT",
"cultureId": "fcd41e40-248e-11df-9deb-005056c00001",
"cultureDescription": "Portuguese-Portugal",
"baseEntityId": "85c719da-56b9-4004-88b2-9b47b4e376cf",
"isDraft": false,
"id": "fb70fb36-2240-4e09-8b74-6cfc8ba771a7",
"isActive": true,
"isDeleted": false,
"isSystem": false,
"createdBy": "[email protected]",
"createdOn": "2017-05-18T09:29:53.1202287",
"modifiedBy": "[email protected]",
"modifiedOn": "2017-07-19T16:27:45.2775966",
"subscriptionId": null,
"draftId": "00000000-0000-0000-0000-000000000000"
},
(…)
]
Criar registo
https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms
{
"paymentTermKey": "PT001",
"description": "My payment term 001",
"useInAccountsReceivable": true,
"useInAccountsPayable": true
}
Atualizar atributo do registo
https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{key}/useInAccountsPayable
Consultar registo
https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{id}
https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{key}
{
"version": [
0,
0,
0,
0,
0,
2,
89,
31
],
"paymentTermKey": "PT001",
"description": "My payment term 001",
"validFrom": "2017-01-01T00:00:00",
"validTo": "2099-12-31T00:00:00",
"useInAccountsReceivable": true,
"useInAccountsPayable": false,
"daysFromReferenceDate": 1,
"naturalKey": "PT001",
"isDraft": false,
"id": "7b0595fd-bdd6-4f96-8f5c-0dd3ba6c685f",
"isActive": true,
"isDeleted": false,
"isSystem": false,
"createdBy": "[email protected]",
"createdOn": "2017-09-12T14:57:05.5452566",
"modifiedBy": "[email protected]",
"modifiedOn": "2017-09-12T15:05:09.1178198",
"subscriptionId": null,
"draftId": "00000000-0000-0000-0000-000000000000"
}
Anular registo
https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{id}
https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{key}
login para deixar a sua opinião.