openapi: 3.0.0 info: title: VTex Anti-fraud Provider Account Notification API description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)" version: '1.0' servers: - url: https://{providerApiEndpoint} description: Anti-fraud provider endpoint URL. variables: providerApiEndpoint: description: Anti-fraud provider endpoint URL. default: '{providerApiEndpoint}' tags: - name: Notification paths: /notificator/{sellerId}/changenotification/{skuId}/price: post: tags: - Notification summary: VTex Notify marketplace of price update description: "This endpoint is used by *sellers* to notify marketplaces that the price has changed for one of their SKUs. \n\nThere is no request body in this call, indicating the new price value, for instance. It only notifies a specific marketplace (`accountName`) that a seller (`sellerId`) has changed the price of an SKU (`skuId`). \n\n*Marketplaces* will then call the [fulfillment endpoint](https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) provided in the seller registration form to get the updated price information.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ 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." operationId: PriceNotification parameters: - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/accountName' - $ref: '#/components/parameters/contentType' - $ref: '#/components/parameters/environment' - $ref: '#/components/parameters/sellerId' - $ref: '#/components/parameters/skuId' responses: '202': description: Accepted deprecated: false /notificator/{sellerId}/changenotification/{skuId}/inventory: post: tags: - Notification summary: VTex Notify marketplace of inventory update description: "This endpoint is used by *sellers* to notify marketplaces that the inventory level has changed for one of their SKUs. \n\nThere is no request body in this call, indicating the new inventory level, for instance. It only notifies a specific marketplace (`accountName`) that a seller (`sellerId`) has changed the inventory level of an SKU (`skuId`). \n\n*Marketplaces* will then call the [fulfillment endpoint](https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) provided in the seller registration form to get the updated inventory information.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\r\n\r\n>❗ 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." operationId: InventoryNotification parameters: - $ref: '#/components/parameters/accountName' - $ref: '#/components/parameters/environment' - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/contentType' - $ref: '#/components/parameters/sellerId' - $ref: '#/components/parameters/skuId' responses: '202': description: Accepted deprecated: false /{app_name}/v{app_version}/{account}/{workspace}/notify: post: tags: - Notification summary: VTex Notify carrier with app description: "This endpoint notifies the carrier about a dispatch order by calling the `vtex.carrier-notifier app`. When the call is made, the following data is sent: \n\n- Dispatched packages information. \n\n- Fiscal information about the carrier notified. \n\n- Carrier's contact email. \n\nThe call's response includes all tracking data and each package's ID generated by the notification made to the carrier. \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| Logistics | Logistics access | **Transportation read only** |\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>❗ 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." operationId: NotifyCarrierwithApp parameters: - name: app_name in: path description: Name of the app developed by the carrier's integration. required: true style: simple schema: type: string default: '{{app name}}' - name: app_version in: path description: Version of the app developed by the carrier's integration. required: true style: simple schema: type: string default: '{{version}}' - name: account in: path description: VTEX account dispatching the package. required: true style: simple schema: type: string default: VTEX Store example - name: workspace in: path description: 'Workspace used in VTEX IO. ' required: true style: simple schema: type: string default: master requestBody: content: application/json: schema: $ref: '#/components/schemas/NotifyCarrierwithAppRequest' example: account: name: Ltda accountName: '{{account}}' isOperating: true defaultUrl: null district: null country: Brasil complement: null companyName: LTDA cnpj: '00000000000000' city: null address: null number: null postalCode: null state: null telephone: null tradingName: tradingName email: email dispatchOrder: id: 653560c2-7965-4614-a730-8e45c89bf284 packageIds: - 6529cd28-6fd1-4b95-8397-5fad0a79d41c sender: cnpj: '00000000000000' fantasyName: null stateRegistration: null id: null name: LTDA address: postalCode: '03475015' country: code: BRA name: Brasil subregion1: code: SP name: São Paulo subregion2: code: São Paulo name: São Paulo subregion3: code: Vila Antonieta name: Vila Antonieta street: Rua Exemplo number: '01' complement: '' location: null email: null phone: '999999999' carrier: cnpj: '00000000000000' fantasyName: carrier stateRegistration: 096/3624636 id: vtexlog_exemplo name: Carrier LTDA. address: postalCode: '90200001' country: code: BRA name: Brasil subregion1: code: RS name: Rio Grande do Sul subregion2: code: Porto_Alegre name: Porto Alegre subregion3: code: Anchieta name: Anchieta street: Rua Exemplo number: '01' complement: Pavilhão 6 location: null email: email phone: '+5511111111111' required: true responses: '200': description: OK headers: {} deprecated: false components: parameters: sellerId: name: sellerId in: path description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built. required: true style: simple schema: type: string example: seller123 accountName: name: accountName in: path required: true description: Name of the VTEX account that belongs to the marketplace. The notification will be posted into this account. schema: type: string example: apiexamples contentType: name: Content-Type in: header description: Type of the content being sent. required: true style: simple schema: type: string default: application/json skuId: name: skuId in: path description: A string that identifies the seller's SKU that suffered the change. This is the ID that the marketplace will use for all references to this SKU, such as price and inventory notifications. required: true style: simple schema: type: string example: '1234' accept: name: Accept in: header description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand. required: true style: simple schema: type: string default: application/json environment: name: environment in: path required: true description: Environment to use. Used as part of the URL. schema: type: string default: vtexcommercestable schemas: DispatchOrder: title: DispatchOrder description: Information about the dispatched order. required: - id - packageIds - sender - carrier type: object properties: id: type: string description: ID of the dispatched order. example: 653560c2-7965-4614-a730-8e45c89bf284 packageIds: type: array description: Array with package IDs. items: type: string description: Identification codes of the packages. example: 6529cd28-6fd1-4b95-8397-5fad0a79d41c sender: $ref: '#/components/schemas/Sender' carrier: $ref: '#/components/schemas/Carrier' Sender: title: Sender description: User's logged account in the VTEX store. required: - cnpj - fantasyName - stateRegistration - id - name - address - email - phone type: object properties: cnpj: type: string description: CNPJ code of the VTEX account responsible for sending the package. example: 81.316.120/0001-02 fantasyName: type: string description: Fantasy name of the VTEX account responsible for sending the package. example: Carrier 123 nullable: true stateRegistration: type: string description: State Registration code of the VTEX account responsible for sending the package. example: '9843759348' nullable: true id: type: string description: VTEX account's ID. example: accountId nullable: true name: type: string description: Name of the VTEX account responsible for sending the package. example: Store LTDA address: $ref: '#/components/schemas/Address' email: type: string description: Email of the VTEX account responsible for sending the package. example: email@email.com nullable: true phone: type: string description: Sender's contact number. example: '+5511111111111' nullable: true example: cnpj: '00000000000000' fantasyName: null stateRegistration: null id: null name: LTDA address: postalCode: '03475015' country: code: Brasil name: Brasil subregion1: code: SP name: SP subregion2: code: São Paulo name: São Paulo subregion3: code: Vila Antonieta name: Vila Antonieta street: Rua Exemplo number: '01' complement: '' location: null email: null phone: '+5511111111111' Location: title: Location description: Recipient's address geocoordinates. required: - lat - lng type: object nullable: true properties: lat: type: number description: Latitude number of the address' geolocation coordinates. example: -46.48582077026367 lng: type: number description: Longitude number of the address' geolocation coordinates. example: -23.521709442138672 example: lat: -46.48582077026367 lng: -23.521709442138672 Subregion3: title: Neighborhood description: Recipient's address neighborhood's information. required: - code - name type: object properties: code: type: string description: Neighborhood's code, from the recipient's address. example: Neighborhood example name: type: string description: Neighborhood's name, from the recipient's address. example: Neighborhood example example: code: Vila Antonieta name: Vila Antonieta Subregion1: title: State description: Recipient's address state's information. required: - code - name type: object properties: code: type: string description: State's code, from the recipient's address. example: SP name: type: string description: State's name, from the recipient's address. example: Sao Paulo example: code: SP name: SP Address: title: Address description: Address of the VTEX account responsible for sending the package. required: - postalCode - country - subregion1 - subregion2 - subregion3 - street - number - complement - location type: object properties: postalCode: type: string nullable: true description: ZIP code of the package's recipient. example: 12345-678 country: $ref: '#/components/schemas/Country' subregion1: $ref: '#/components/schemas/Subregion1' subregion2: $ref: '#/components/schemas/Subregion2' subregion3: $ref: '#/components/schemas/Subregion3' street: type: string description: Recipient's address. example: Street example number: type: string description: Number of the recipient's address. example: '1' complement: type: string nullable: true description: Complement for the recipient's address. example: A location: $ref: '#/components/schemas/Location' example: postalCode: 00000-000 country: code: BRA name: BRA subregion1: code: SP name: SP subregion2: code: São Paulo name: São Paulo subregion3: code: Burgo Paulista name: Burgo Paulista street: Rua Exempo number: '01' complement: null location: lat: -46.48582077026367 lng: -23.521709442138672 Account: title: Account required: - name - accountName - isOperating - defaultUrl - district - country - complement - companyName - cnpj - city - address - number - postalCode - state - telephone - tradingName type: object properties: name: type: string description: Inserted name. example: Ltda accountName: type: string description: Name of the VTEX Account dispatching the package. example: mystore isOperating: type: boolean description: Whether the store is operating or not. example: true defaultUrl: type: string nullable: true description: Retrieved from VTEX's License Manager. example: https://url.example.com district: type: string nullable: true description: District where the VTEX store dispatching the package is located. example: District name country: type: string description: Country where the VTEX store, dispatching the package, is located. example: Brasil complement: type: string nullable: true description: Complement for the VTEX store's address. example: Second floor companyName: type: string description: Name of the VTEX store responsible for the package. example: VTEX Store 1 cnpj: type: string description: CNPJ code of the VTEX store responsible for the package. example: '00000000000000' city: type: string nullable: true description: City where the VTEX store responsible for the package is located. example: Rio de Janeiro address: type: string nullable: true description: Address where the VTEX store responsible for the package is located. example: VTEX Street number: type: string nullable: true description: Number of the address related to the `address` field. example: '26' postalCode: type: string nullable: true description: ZIP code of the VTEX store responsible for the package. example: 12345-678 state: type: string nullable: true description: State of the address belonging to the VTEX store responsible for the package. example: RJ telephone: type: string nullable: true description: Telephone number of the VTEX store responsible for the package. example: '99999999' tradingName: type: string description: Trading name of the VTEX store responsible for the package. example: Trading name description: Account information. example: name: Ltda accountName: '{{account}}' isOperating: true defaultUrl: null district: null country: Brasil complement: null companyName: LTDA cnpj: '00000000000000' city: null address: null number: null postalCode: null state: null telephone: null tradingName: tradingName NotifyCarrierwithAppRequest: title: NotifyCarrierwithAppRequest description: Object containing email, account, and dispatched order information. required: - email - dispatchOrder - account type: object properties: account: $ref: '#/components/schemas/Account' email: type: string description: Fill in this field if you wish to send the generated file for an email besides the ones already involved in the operation, like the carrier and VTEX account's email. example: email dispatchOrder: $ref: '#/components/schemas/DispatchOrder' Carrier: title: Carrier description: Carrier responsible for delivering the dispatched order. required: - cnpj - fantasyName - stateRegistration - id - name - address - email - phone type: object properties: cnpj: type: string description: Carrier's CNPJ. example: '00000000000000' fantasyName: type: string description: Carrier's fantasy name. example: Carrier A stateRegistration: type: string description: Carrier's state registration number. example: '843904894875' id: type: string description: Carrier's ID. example: vtexShippinNetwork_example name: type: string description: Carrier's company name. example: Carrier LTDA address: $ref: '#/components/schemas/Address' email: type: string description: Carrier's email address. example: email@example.com phone: type: string description: Carrier's contact number. example: '+5511111111111' nullable: true example: cnpj: '00000000000000' fantasyName: carrier stateRegistration: 096/3624636 id: vtexlog_exemplo name: Carrier LTDA. address: postalCode: '90200001' country: code: BRA name: Brasil subregion1: code: RS name: Rio Grande do Sul subregion2: code: Porto_Alegre name: Porto Alegre subregion3: code: Anchieta name: Anchieta street: Rua Exemplo number: '01' complement: Pavilhão 6 location: null email: email phone: '+5511111111111' Subregion2: title: City description: Recipient's address city's information. required: - code - name type: object properties: code: type: string description: City's code, from the recipient's address. example: SP name: type: string description: City's name, from the recipient's address. example: Sao Paulo example: code: SP name: São Paulo Country: title: Country description: Recipient's country. required: - code - name type: object properties: code: type: string description: Country's three-digit identifying code, from the recipient's address. example: BRA name: type: string description: Country's name, from the recipient's address. example: Brasil example: code: BRA name: BRA securitySchemes: VtexIdclientAutCookie: type: apiKey in: header name: VtexIdclientAutCookie description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'