# PEFTrust Public API ## Main informations | Environment | Version | Base url | |---------------|-----------|-----------------------------------| | Demo (test) | 5.8.0 | https://api-demo.peftrust.com | | Production | 5.8.0 | https://api.peftrust.com | ## Postman collection The PEFTrust Public API Postman collection is a perfect way to understand how the api works and try it with specific example. [Download the collection](https://apidoc.peftrust.com/public-api.postman-collection.json?v=5.6.0) Note that the collection has variables (user, password etc) set at the collection level with a login script to avoid repeated logins. ## Authentication First of all, the API is protected with a JWT Bearer that must be set in Authorization header. | Method | Entity | Endpoint | Description | |----------- |----------- |---------- |-------------| | GET | Authentication | /auth/login | Will return a temporary JWT token to handle authentication ## Entities endpoints As an API Consumer you can perform CRUD operation on some entities related to your organization account. | Method | Entity | Endpoint | Description | |----------- |----------- |---------- |-------------| | GET | Evaluation category | /evaluations/categories | Fetch all evaluation categories (as a tree) | GET | Evaluation category | /evaluations/categories/:id | Fetch one specific evaluation category | GET | Evaluation | /evaluations | Fetch all evaluations | POST | Evaluation | /evaluations | Create an evaluation | GET | Evaluation | /evaluations/:id | Fetch one specific evaluation | PATCH | Evaluation | /evaluations/publish/:id | Publish a specific evaluation reference (create a version) | GET | Evaluation | /evaluations/schema/:id | Fetch the current payload schema of a given evaluation | PUT | Evaluation | /evaluations/:id | Update a specific evaluation | PATCH | Evaluation | /evaluations/:id | Update a specific evaluation with atomic operation | DELETE | Evaluation | /evaluations/:id | Delete a specific evaluation | GET | Material | /materials | Fetch all materials | GET | Material | /materials/:id | Fetch one material | GET | Teams | /teams | Fetch all teams | GET | Tag | /tags | Fetch all tags | GET | Accessory | /accessories | Fetch all accessories | GET | Accessory | /accessories/:id | Fetch one accessory | GET | Mask | /masks | Fetch all masks | GET | Mask | /masks/:id | Fetch one mask | POST | Mask | /masks | Create a mask | PUT | Mask | /masks/:id | Update a mask | DELETE | Mask | /masks/:id | Delete a mask | GET | Product | /products | Fetch all products | GET | Product | /products/:id | Fetch one product | POST | Product | /products | Create a product | PUT | Product | /products/:id | Update a product | DELETE | Product | /products/:id | Delete a product | GET | Product packaging | /products/packagings | Fetch all product packagings | GET | Product packaging | /products/packagings/:id | Fetch one product packaging | POST | Product packaging | /products/packagings | Create a product packaging | PUT | Product packaging | /products/packagings/:id | Update a product packaging | DELETE | Product packaging | /products/packagings/:id | Delete a product packaging ## Schema endpoints Schema endpoints provide a readable and complete JSON schema that describes all of the related fields for a given entity (underlying parameters, lifecycles, processes etc.). These endpoints are absolutely necessary when it comes to build a payload in order to create an evaluation. Every categories and materials have their own information groups, processes and last but not least their own parameters. Those parameters could have the same label, functional effect etc. but their ids are different because they are not related to the same entity and they could diverge over time. Note that the returning schema contains some properties that are not necessary for the evaluation create or update payload but they try to provide the most understandable schema with de aim of create it. | Method | Entity | Endpoint | Description | |----------- |----------- |---------- |-------------| | GET | Evaluation category schema | /evaluations/categories/schema/:id | Fetch schema for a specific evaluation category | GET | Material schema | /materials/schema/:id | Fetch schema for a specific material | GET | Mask schema | /masks/schema | Fetch schema for a mask (they all have the same schema) | GET | Product packaging schema | /products/packagings/schema | Fetch schema for a product packaging (they all have the same schema) ## Results endpoint for Product and Evaluation An evaluation is not evaluated once it is created, therefore there are some endpoints to perform this operation and fetch related results. For products, the results are available once the product is created as it is a coumpound entity that contains all of the related precalculated evaluations. | Method | Entity | Endpoint | Description | |----------- |----------- |---------- |-------------| | GET | Evaluation evaluate | /evaluation/evaluate/:id | Evaluate the evaluation | GET | Evaluation evaluate full | /evaluation/evaluate/:id/full | Evaluate the evaluation (standard + exobalyse) | GET | Evaluation evaluate ecobalyse | /evaluation/evaluate/:id/ecobalyse | Evaluate the evaluation with Ecobalyse API | GET | Evaluation check Ecobalyse availability| /evaluation/check/:id/ecobalyse | Check whether the evaluation can be evaluated with Ecobalyse API or not | GET | Evaluation results | /results/evaluation/:id | Get evaluation results | GET | Evaluation results IPC | /results/evaluation/:id/ipc | Get IPC results | GET | Evaluation results full | /results/evaluation/:id/full | Get enhanced evaluation results | GET | Evaluation results ecobalyse | /results/evaluation/:id/ecobalyse | Get evaluation ecobalyse results | GET | Product results IPC | /results/evaluation/:id/ipc | Get IPC results | GET | Product results full | /results/evaluation/:id/full | Get enhanced product results | GET | Product results ecobalyse | /results/evaluation/:id/ecobalyse | Get evaluation ecobalyse results ## Asynchronous results using webhooks While using evaluate endpoints you can specify 3 optional parameters : - async: will not await for the result and confirm processing - webhook: specify an url where we will send the result when it's ready (the results will be sent using `POST` method) - webhook_token: specify a token to secure the webhook call, the token will be pass in `X-Auth-Token` header (you've to implement the logic to secure your application) Notice that async and webhook_token are required why specifying webhook url. ### Webhook payload __evaluate endpoints : /evaluation/evaluate/:id__ ```json { "full": { // Same content as /results/evaluation/:id/full }, "ipc": { // Same content as /results/evaluation/:id } } ``` __evaluate endpoints : /evaluation/evaluate/:id/full__ ```json { "full": { // Same content as /results/evaluation/:id/full }, "ipc": { // Same content as /results/evaluation/:id }, "ecobalyse": { // Same content as /results/evaluation/:id/ecobalyse } } ``` __evaluate endpoints : /evaluation/evaluate/:id/ecobalyse__ ```json { // Same content as /results/evaluation/:id/ecobalyse } ``` ## Evaluation & Product creation process #### Sequence diagram ```mermaid sequenceDiagram local->>API: GET /evaluations/categories API-->>local: Categories list Note over local,API: Select the category of your choice local->>API: GET /evaluations/categories/schema/:id API-->>local: Category schema (with lifecycles, information group, parameters) Note over local,API: Fill your evaluation payload lifecycles related information local->>API: GET /materials API-->>local: Materials list Note over local,API: Select one or several materials that you want to add to your evaluation loop local->>API: GET /materials/schema/:id API-->>local: Material schema Note over local,API: Fill your evaluation payload material parts end opt local->>API: GET /accessories API-->>local: Accessories list Note over local,API: Fill your evaluation payload accessories related information end local->>API: POST /evaluations API-->>local: Created evaluation (not evaluated) Note over local,API: Your evaluation has been created successfully opt local->>API: GET /evaluations/evaluate/:id API-->>local: Quality, pefcore Note over local,API: Your evaluation has been evaluated and the results are now available local->>API: GET /results/evaluations/:id/full API-->>local: Evaluation results local->>API: GET /results/evaluations/:id/ipc API-->>local: IPC results Note over local,API: Once checked, you can publish your evaluation and version its results local->>API: PATCH /evaluations/publish/:id API-->>local: Created version local->>API: GET /evaluations/:created_version_id API-->>local: The created version with results in compositionSchema property end opt Note over local,API: Once published, you can create a product using the evaluation local->>API: POST /products API-->>local: Created product Note over local,API: Your product has been created successfully, you can now fetch its results local->>API: GET /results/products/:id/full API-->>local: Product results local->>API: GET /results/products/:id/ipc API-->>local: IPC results end ``` #### Parameters Parameters have different kind of type that come with their own implicit formating rules and constraints. They are formatted as following in the payload: ```json { "id": "{{id}}", "value": "{{value}}", } ``` __Types__ | Type | Expected format | |------------- |--------------------------------- | | text | Must be a string | | number | Must be a number | | email | Must be an email | | date | Must be a date | | checkbox | Must be a boolean | | select | Must be one of the allowed values | | select-quantity | Must be one of the allowed values separated by a dash "/" and a quantity as a string number | | select-multiple | Must be one or several allowed values eparated by a coma "," | __Select parameters__ Since v5.7.9, slug as been added to the schema allowed values and you can use another property than the id as value. It works with select, select-quantity and select-multiple types. For example, here is a schema for a given select: ```json { "id": "7990de5c-7a29-476e-b801-9517b0cab0e4", "name": "Size", "identifier": "size", "fieldType": "select", "qualityCategoryId": "d6fee280-0610-4cb1-95e4-ed2bcdfa6938", "defaultValue": "0", "allowedValues": [ { "name": " 50 - Men", "value": "50 - Men", "slug": "50_men" } // ... ], "constraints": {}, "customizable": false } ``` Instead of sending the raw value you can send the slug or even the name specifying useProperty: ```json { "id": "7990de5c-7a29-476e-b801-9517b0cab0e4", "useProperty": "slug", "value": "50_men" } ``` Another example with a location select parameter: ```json { "id": "100cee5c-59fb-4bb2-bd4c-0e5927e72c23", "name": "Location", "identifier": "location", "fieldType": "select", "qualityCategoryId": "905adc86-a0fb-4e9c-aea5-af72eef9c62a", "defaultValue": "5a5446dc-b05f-47d4-8604-02040bd31e9f", "allowedValues": [ { "name": "Africa", "value": "e25469ee-e4db-4215-adbb-d6e12658fd22", "slug": "africa", "code": "002", "code_alpha_2": null, "code_alpha_3": null }, // ... ], "constraints": {}, "customizable": false } ``` You can use any of the allowedValue object property such as `code` for example: ```json { "id": "100cee5c-59fb-4bb2-bd4c-0e5927e72c23", "useProperty": "code", "value": "002" } ``` __Constraints__ | Type | Expected format | |------------- |--------------------------------- | | required | This parameter is required (must be filled if it has no default value) | | min | Minimum value (for number type) | | max | Maximum value (for number type) | | pattern | RegEx that must match with the filled value | | minDate | Minimum date | | maxDate | Maximum date | | integer | Must be an integer (!= float) | __Custom parameters__ Parameters flagged as `custumizable` come with nested parameters in their property `customParameters`. In that case you could either: - Fill its value as usual and just ignore this information - Fill its value with the keyword "custom" and complete all of its `customParameters` These parameters allow user to be more specific and complete its own values that make the API able to calculate these parameters impacts much more accurately than pre-completed values. #### Payload format The payload should be an application/json object which contains the following keys at root : | Name | Type | Mandatory | Description | |------------------------- |---------------------|-----------|---------------------------------------------------------------------------------| | category.id | string | YES | The evaluation category id | | mask.id | string | NO | The optional mask to apply on the evaluation | | packaging.id | string | NO | The optional packaging apply to the evaluation | | teams.id | string | YES | The evaluation teams list (with their ids) | | tags.id | string | NO | The evaluation tags (with their ids) | | lifecycles | array | YES | Array of lifecycles that contains their parameters | | composition.parts | array | YES | Array of evaluation parts that contains their materials per percentage | | composition.accessories | object | NO | Object that contains accessories related informations | Every parameters that are not specified in the payload will be filled with their default value. #### Using weight as base unit Since version 1.9.8 it's possible to use weight instead of percentage if you want to. To do so, you just have to change composition baseUnit to "weight" instead of percentage and specify weight everywhere you put percentage before. Then, the API will ignore percentage key and calculate it by itself also the API will take care that the calculated percentage of your evaluation match the requirements otherwise you'll get related error messages. #### Update entity If you want to update an entity, you have to use the PUT method and provide the entity id in the URL. This method will replace the entity with the new one, you need to provide all the fields even if they are not modified. Since version 5.6.0 you can update an entity with atomic operation, you have to use the PATCH method and provide the entity id in the URL. This currently only works for evaluation entity and will update only the fields that are provided in the payload. The documentation about the payload format and operations is available in the documentation below : - Operations: [https://www.npmjs.com/package/json-merger]() - Queries (for $match): [https://www.npmjs.com/package/jsonpath]() Allowed operations are : - $merge - $remove - $replace - $concat - $combine - $append - $prepend - $insert - $match - $move - $select - $repeat Notice that any FS operation are disallowed ($import, $include etc) and the top operation is always $merge but you don't have to specify the source. Show the Postman collection for more details about the payload format an example with multiple atomic operations is available in the collection.