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.'