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