EDU-14427-new-pick-pack-api #1391
Conversation
|
Thanks for your contribution. The .json file will be checked now with Spectral. |
| "Authentication" | ||
| ], | ||
| "summary": "Create JWT token", | ||
| "description": "Creates a `JWT` (JSON Web Token) necessary to access the Pick and Pack Last Mile Protocol API information.\r\n\r\n>ℹ️ To generate the `JWT` it is necessary to have the `API KEY` previously generated by the Pick and Pack team.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", |
There was a problem hiding this comment.
Please include token expiration time.
| "variables": { | ||
| "environment": { | ||
| "default": "DefaultParameterValue", | ||
| "description": "Server to access the authentication necessary to make a request in the Pick and Pack Provider API." |
There was a problem hiding this comment.
I believe this description is wrong. Please double check it.
| "url": "https://auth.pickingnpacking.com/prod/{environment}", | ||
| "variables": { | ||
| "environment": { | ||
| "default": "DefaultParameterValue", |
There was a problem hiding this comment.
This is too generic. I think even something like "environment" would be better. But maybe the team can provide something more specific/realist, like we have "vtexcommercestable" for core commercer APIs. Did you check it with them?
| "url": "https://api.pick-and-pack.com/prod/v1/{environment}", | ||
| "variables": { | ||
| "environment": { | ||
| "default": "DefaultParameterValue", |
There was a problem hiding this comment.
This is too generic. I think even something like "environment" would be better. But maybe the team can provide something more specific/realist, like we have "vtexcommercestable" for core commercer APIs. Did you check it with them?
| "Orders" | ||
| ], | ||
| "summary": "Get order by ID", | ||
| "description": "Retrieves order details by its ID.\n\n>ℹ️ The response is cached for 30 seconds based on the `orderId` parameter. The endpoint supports up to 30 requests per second, with a maximum of 100 concurrent requests.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **View order** |\r\n| OMS | OMS access | **Only show orders created by the user (via call center)** |\r\n| Catalog | Telesales | **Assisted Sales** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", |
There was a problem hiding this comment.
Yes, there are aplicable predefined roles. Please fix the text, including the apropriate predefined roles.
There was a problem hiding this comment.
This applies to all endpoints except /token
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/CreatetokenRequest" |
There was a problem hiding this comment.
Not blocking the PR over this, but I don't think it is a good practice to use ref for a component that is used only once in the file. It usually makes maintenance more difficult.
| "Orders" | ||
| ], | ||
| "summary": "Set order delivery", | ||
| "description": "This endpoint finalizes the Pick and Pack workflow by marking the order as delivered. Additionally, it allows you to update the OMS with shipping details. All fields are optional. For more information, see [Update order tracking status](https://developers.vtex.com/docs/api-reference/orders-api#put-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-/tracking) endpoint.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| OMS | OMS access | **View order** |\r\n| OMS | OMS access | **Only show orders created by the user (via call center)** |\r\n| Catalog | Telesales | **Assisted Sales** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", |
There was a problem hiding this comment.
Yes, there are aplicable predefined roles. Please fix the text, including the apropriate predefined roles.
In fact, it sounds very strange to me the resources View order and Only show orders created by the user (via call center) would allow the user to edit order information. Do you think it is worth double checking with the team?
| }, | ||
| "events": { | ||
| "type": "array", | ||
| "description": "List of events that occurred during the delivery process.", |
There was a problem hiding this comment.
I am not sure about this description. What kind of events occur during delivery?
There was a problem hiding this comment.
Isn't it just a list of deliveries? Meaning that orders with split packages (different sellers, etc) have multiple delivery events? Would this apply for pnp?
Types of changes
Changelog
Do not forget to update your changes to our Developer Portal's changelog. Did you create a release note?