openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Seller Invite 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: Seller Invite
paths:
  /seller-register/pvt/seller-leads:
    post:
      tags:
      - Seller Invite
      summary: VTex Invite Seller Lead
      description: "This API is used by marketplace operators to invite sellers to join their marketplace. The request sends an email to the seller, inviting sellers to activate their store. The invitation's link in the email is unique per user, and available for only seven days for the seller to click and begin activating their store. \n\nThe email template is completely customizable. All email templates that VTEX sends to seller leads can be found and edited in the marketplace's VTEX Admin, on the Message Center section.\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| Seller Register | Seller Administration | **Save Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. | Save Seller |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: CreateSellerLead
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      requestBody:
        description: This request requires detailed information about the seller, including their email, name, account name, sales channel, and other related details. Data should be in JSON format and follow the schema specified in 'CreateSellerLeadRequest'. A sample valid payload is provided for reference, including details such as address, contact information, and acceptance of legal terms.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSellerLeadRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseCreateSellerLead'
              example:
                sellerId: '7890123456'
                createdAt: '2023-01-01T12:34:56Z'
                updatedAt: '2023-01-01T12:34:56Z'
      deprecated: false
    get:
      tags:
      - Seller Invite
      summary: VTex List Seller Leads
      operationId: ListSellerLeads
      description: "This call's response includes a list of all sellers invited by the marketplace operator to join them. Retrieved results can be filtered by adding optional query fields to the request. Each seller listed includes the following information: \n\n- `id` \n\n- `createdAt` \n\n- `status` \n\n- `isConnected` \n\n- `sellerEmail` \n\n- `sellerName` \n\n- `salesChannel` \n\n- `email`\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| Seller Register | Seller Administration | **View Seller** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| View all sellers linked to the Marketplace account described on the sellers management page, including recovering seller data, either from the sellers listing, or a specific seller. | View Seller |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/isConnected'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/status'
      - $ref: '#/components/parameters/orderBy'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
  /seller-register/pvt/seller-leads/{sellerLeadId}:
    put:
      tags:
      - Seller Invite
      summary: VTex Accept Seller Lead
      operationId: AcceptSellerLead
      description: "This endpoint is triggered by the seller onboarding wizard, once the seller confirms their invitation. It can be used by marketplace operators to manually accept seller leads, and carry on with their onboarding process. \n\nNote that there's no specific API call that allows status changes. The operations only allow the seller lead to move forward: \n\n From `invite` > to `Accept` > closing on `Create Seller`.  \n\nIf you want to change the status, you can start the process again, by deleting that lead through the *Delete Seller Lead* endpoint, and resending the invite through the *Resend Seller Lead's Invite* endpoint."
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/sellerId'
      - $ref: '#/components/parameters/contentType'
      requestBody:
        description: This request requires information about the seller who is accepting the lead, including their email, name, account name, sales channel, and other relevant details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptSellerLeadRequest'
        required: true
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
    get:
      tags:
      - Seller Invite
      summary: VTex Get Seller Lead's Data by Id
      operationId: RetrieveSellerLead
      description: "Marketplace operators may call this endpoint to retrieve information about a specific seller invited to the Seller Portal, by searching through their `Seller Lead Id`. To know the chosen seller's `sellerLeadId`, marketplace operators can count on the *List Sellers* endpoint's response as well. Each seller listed includes the following information: \n\n- `id` \n\n- `createdAt` \n\n- `status` \n\n- `isConnected` \n\n- `sellerEmail` \n\n- `sellerName` \n\n- `salesChannel` \n\n- `email`"
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/sellerId'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
    delete:
      tags:
      - Seller Invite
      summary: VTex Delete Seller Lead
      description: This endpoint permanently deletes a seller previously invited to the marketplace, if the seller has not already accepted the invitation.
      operationId: RemoveSellerLead
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/sellerLeadId'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
  /seller-register/pvt/seller-leads/{sellerLeadId}/seller:
    put:
      tags:
      - Seller Invite
      summary: VTex Create Seller From Lead
      operationId: CreateSellerFromSellerLead
      description: "This endpoint is used by marketplace operators to create seller accounts. The request will only accept Seller Leads whose status is `accepted`. If they are already `connected` or `invited`, the call will not be fulfilled. \n\nThe creation of the account at VTEX is done by an internal Billing service. There is no seller account and marketplace affiliation if you do not go through this step. \n\nNote that there's no specific API call that allows status changes. The operations only allow the seller lead to move forward: \n\n From `invite` > to `Accept` > closing on `Create Seller`.  \n\nIf you want to change the status, you can start the process again, by deleting that lead through the *Delete Seller Lead* endpoint, and resending the invite through the *Resend Seller Lead's Invite* endpoint."
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/isActive'
      - $ref: '#/components/parameters/sellerId'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
  /seller-register/pvt/seller-leads/{sellerLeadId}/status:
    put:
      tags:
      - Seller Invite
      summary: VTex Resend Seller Lead Invite
      description: This endpoint allows marketplace operators to resend an invitation to a seller lead, previously invited to join their marketplace. The request will only accept Seller Leads whose status is `invited`. If they are already `connected` or `accepted`, the call will not be fulfilled.
      operationId: ResendSellerLeadRequest
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/sellerId'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      requestBody:
        description: This request requires information specifying the action to be taken, such as the status to be resent.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendSellerLeadRequestRequest'
        required: true
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
components:
  parameters:
    offset:
      name: offset
      in: query
      description: This field determines the limit used to retrieve the list of sellers. The response includes objects starting `from` the value inputted here.
      required: true
      style: form
      explode: true
      schema:
        type: integer
        default: 0
    orderBy:
      name: orderBy
      in: query
      description: "Query param determining how data will be ordered in the response, ordering by name or ID in descending our ascending order. Includes the following values: \n\n`namesort` = desc/asc \n\n`idsort` = desc/asc"
      required: true
      style: form
      explode: true
      schema:
        type: string
    sellerLeadId:
      name: sellerLeadId
      in: path
      description: ID of the Seller Lead invited to the marketplace.
      required: true
      style: simple
      schema:
        type: string
    isConnected:
      name: isConnected
      in: query
      description: Query param that enables results to be filter by whether the seller lead is already connected to the marketplace or not.
      required: true
      style: form
      explode: true
      schema:
        type: string
        default: ''
    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
    status:
      name: status
      in: query
      description: Seller Lead's status. Includes `accepted`, `connected` or `invited`.
      required: true
      style: form
      explode: true
      schema:
        type: string
        default: invited
    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
    limit:
      name: limit
      in: query
      description: 'This field determines the limit used to retrieve the list of sellers. The response includes objects until the value inputted here.            '
      required: true
      style: form
      explode: true
      schema:
        type: integer
        default: 15
    isActive:
      name: isActive
      in: query
      description: Enables to filter sellers that are active (`true`) or unactive (`false`) in the marketplace.
      required: false
      schema:
        type: boolean
        default: false
    contentType:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
    search:
      name: search
      in: query
      description: Custom search field, that filters sellers invited by specific marketplace operator's  email.
      required: true
      style: form
      explode: true
      schema:
        type: string
        default: user email
    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
    environment:
      name: environment
      in: path
      required: true
      description: Environment to use. Used as part of the URL.
      schema:
        type: string
        default: vtexcommercestable
  schemas:
    responseCreateSellerLead:
      type: object
      properties:
        sellerId:
          type: string
          description: ID of the created seller.
          example: '7890123456'
        createdAt:
          type: string
          description: Creation date of the seller.
          example: '2022-01-01T12:34:56Z'
        updatedAt:
          type: string
          description: Date of the last update of the seller.
          example: '2023-01-01T12:34:56Z'
    ResendSellerLeadRequestRequest:
      title: ''
      required:
      - status
      type: object
      properties:
        status:
          type: string
          description: Seller Lead's status. Includes `accepted`, `connected` or `invited`.
          default: accepted
      example:
        status: accepted
    AcceptSellerLeadRequest:
      title: ''
      required:
      - sellerEmail
      - sellerName
      - sellerAccountName
      - salesChannel
      - email
      - sellerType
      - accountId
      - document
      - hasAcceptedLegalTerms
      - address
      - accountable
      type: object
      properties:
        sellerEmail:
          type: string
          description: Seller's contact email.
          default: selleremail@email.com
        sellerName:
          type: string
          description: Seller's store's name.
          default: Seller Name
        sellerAccountName:
          type: string
          description: Name of the seller's account, part of the url of their VTEX Admin.
          default: seller123
        salesChannel:
          type: string
          description: Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created.
          default: '1'
        email:
          type: string
          description: email of the admin responsible for the seller.
          default: seller@email.com
        sellerType:
          type: integer
          description: "Type of seller, including: \n\n`1`: regular seller \n\n`2`: whitelabel seller"
          default: 1
        accountId:
          type: string
          description: Marketplace's account ID
          default: 5fb38ace-d95e-45ad-970d-ee97cce9fbcd
        document:
          type: string
          description: Company's legal document code.
          default: '12345671000'
        hasAcceptedLegalTerms:
          type: boolean
          description: Indicates if the seller has accepted the platform's legal terms and conditions.
          default: true
        address:
          $ref: '#/components/schemas/address'
        accountable:
          $ref: '#/components/schemas/accountable'
      example:
        sellerEmail: selleremail@email.com
        sellerName: Seller Name
        affiliateId: MKP
        sellerAccountName: seller123
        salesChannel: '1'
        email: seller@email.com
        sellerType: 1
        accountId: 5fb38ace-d95e-45ad-970d-ee97cce9fbcd
        document: '12345671000'
        hasAcceptedLegalTerms: true
        address:
          postalcode: '12345678'
          complement: Appartment 1234
          street: VTEX street
          number: '25'
          neighborhood: VTEX quarter
          state: RJ
          city: Rio de Janeiro
        accountable:
          name: Jane Smith
          email: email@email.com
          phone: '1234567890'
    address:
      type: object
      title: address
      required:
      - postalcode
      - complement
      - street
      - number
      - neighborhood
      - state
      - city
      properties:
        postalcode:
          type: string
          title: postalCode
          description: Postal code from the seller's address.
          default: '12345678'
        complement:
          type: string
          title: complement
          description: Seller's address complement.
          default: Appartment 1234
        street:
          type: string
          title: street
          description: Street information, from the seller's address.
          default: VTEX street
        number:
          type: string
          title: number
          description: Street's number, from the seller's address.
          default: '25'
        neighborhood:
          type: string
          title: The neighborhood schema
          description: Seller's address neighborhood.
          default: VTEX quarter
        state:
          type: string
          title: state
          description: State, from the seller's address.
          default: RJ
        city:
          type: string
          title: city
          description: City name, from the seller's address.
          default: Rio de Janeiro
    CreateSellerLeadRequest:
      title: ''
      required:
      - sellerEmail
      - sellerName
      - sellerAccountName
      - salesChannel
      - email
      - sellerType
      - accountId
      - accountable
      - hasAcceptedLegalTerms
      - address
      - document
      type: object
      properties:
        sellerEmail:
          type: string
          description: Seller's contact email;
          default: selleremail@email.com
        sellerName:
          type: string
          description: Seller's store's name.
          default: Seller Name
        sellerAccountName:
          type: string
          description: Name of the seller's account, part of the url of their VTEX Admin.
          default: seller123
        salesChannel:
          type: string
          description: Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created.
          default: '1'
        email:
          type: string
          default: email@email.com
        sellerType:
          type: integer
          description: "Type of seller, including: \n\n`1`: regular seller \n\n`2`: whitelabel seller"
          default: 1
        accountId:
          type: string
          description: Marketplace's account ID
          default: 5fb38ace-d95e-45ad-970d-ee97cce9fbcd
        document:
          type: string
          description: Company's legal document code.
          default: '12345671000'
        hasAcceptedLegalTerms:
          type: boolean
          description: Indicates if the seller has accepted the platform's legal terms and conditions.
          default: true
        address:
          $ref: '#/components/schemas/address'
        accountable:
          $ref: '#/components/schemas/accountable'
      example:
        sellerEmail: selleremail@email.com
        sellerName: Seller Name
        sellerAccountName: seller123
        salesChannel: '1'
        email: email@email.com
        sellerType: 1
        accountId: 5fb38ace-d95e-45ad-970d-ee97cce9fbcd
        document: '12345671000'
        hasAcceptedLegalTerms: true
        address:
          postalcode: '12345678'
          complement: Appartment 1234
          street: VTEX street
          number: '25'
          neighborhood: VTEX quarter
          state: RJ
          city: Rio de Janeiro
        accountable:
          name: Jane Smith
          email: email@email.com
          phone: '1234567890'
    accountable:
      type: object
      title: accountable
      required:
      - name
      - email
      - phone
      properties:
        name:
          type: string
          title: name
          description: Name of the person responsible for the seller.
          default: Jane Smith
        email:
          type: string
          title: email
          description: Email address of the person responsible for the seller.
          default: email@email.com
        phone:
          type: string
          title: phone
          description: Phone number of the person responsible for the seller.
          default: '1234567890'
  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.'