Documentation
Feedback
Guides
API Reference

Guides
Integration Guides
Offer Management Integration Guide
Offer Management SDK

To evolve your experience in synchronizing and updating offers, the VTEX team is developing a new functionality that will replace the current module Offer Management. As a result, the module will not receive new updates or maintenance. For connectors and marketplaces already integrated into the module, please contact the development team by email taissa.araujo@vtex.com.br. For connectors interested in starting the integration, we ask you to wait for the release of the new module, as soon as it is available we will announce it to all customers through the dev portal and help VTEX.

For the guide based on APIs, see Offer Management Integration Guide.

The Offer Management allows sellers to track the sending and syncing of their offers in marketplaces integrated with their store. The feature helps sellers identify updates and solve errors in their offers during the sending process, guaranteeing they were sent to the marketplace and synced correctly. In VTEX, an offer is an SKU from a seller that has been sent to a marketplace and whose price and inventory information have been configured.

The current document is a Software Development Kit (SDK) created to facilitate the integration between a connector and Offer Management. The SDK includes the implementation of Offer Management’s main features and a .NET library via MyGet.

The integration using this SDK follows the same concepts presented in the Offer Management Integration Guide:

ConceptDescription
FeedThe feedId attribute created by the connector will identify sellers’ feeds with a channel.
InteractionFor every action that happens to an offer, whether it is a status notification or a price update, the connector creates an interaction about it.
LogsLogs are the granular details of actions that happen within an interaction, and they are organized in a timeline. Logs registers last for ten days.

Offer Management works with the creation of a feed, followed by the creation of interactions and logs. After the log is created, it is necessary to close the interaction, and that process is what makes an offer update visible for sellers in Offer Management’s UI.

These SDK is organized in the following sections:

  1. Installing dependencies
  2. Offer Management APIs
  3. Unified contract
  4. Integration flows

Installing dependencies

Step 1 - Open the terminal and add the package to the project dependencies:


_10
<PackageReference Include=\"SentOffers.SDK\" Version=\"0.0.4\" />

Step 2 - Inject dependencies in the project:


_10
services.AddSingleton<ISentOffersClient, SentOffersClient>();

Offer Management APIs

All of the APIs responses are contained in the object SentOffersResponse, which can be used to check if a transaction was successful or presented an error. All errors are listed in the errors attribute.

This section is organized as below:

This SDK does not reference all the APIs related to Offer Management, however, they can be found in VTEX API Reference under Marketplace APIs > Offer Management.

Authentication

Authentication in Offer Management works as in VTEX REST APIs, as it can be seen in Authentication. Through the SentOffersCredentials class, the connector can send information about AppKey, AppToken and VTEX IO token.

Create feed

The creation of a feed establishes the connection between the seller's affiliate ID and the marketplace’s ID, which corresponds to the attribute Id (also referred to as feedId).


_12
SentOffersResponse <FeedCreateResponseDto> response;
_12
_12
response = await soClient.CreateFeedAsync(
_12
"account",
_12
new FeedCreateDTO
_12
{
_12
Id = "vtex.marketplace",
_12
SalesChannel = "1",
_12
AffiliatedId = "AFL"
_12
},
_12
credentials
_12
)

Deactivate feed

When a feed is deactivated, all data related to the marketplace is removed from Offer Management’s UI, including channels, offers, interactions, and errors. Deactivating a feed does not mean deleting information, and the seller can restore the data through the endpoint Activate Feed.

In order to delete a feed, implement the code below:


_10
var response = await soClient.DeleteFeedAsync(
_10
"account",
_10
“vtex.marketplace”,
_10
“credentials”
_10
)

Create interaction

An interaction should be created before the connector’s integration flow. The reason is that for any flow it will be necessary to inform the interaction context, whether it is a setup or a synchronization.

To create an interaction, do the following:


_11
var response = await soClient.CreateInteractionAsync(
_11
"account",
_11
"vtex.makertplace",
_11
new InteractionCreateDTO
_11
{
_11
StartDate = Datetime.UtcNow.ToString(),
_11
Source = InteractionSourceType.seller,
_11
Origin = OriginType.inventory,
_11
Context = InteractionContextType.sync
_11
},
_11
credentials

Create log

Logs can be created as the following:


_19
CreateLogDTO log = new()
_19
{
_19
Description = "sdk test",
_19
Type = "Info",
_19
Agent = "channel",
_19
Date = DateTime.Now.ToString(),
_19
Data = new CreateLogDataRequest() { Status = "Sending" }
_19
};
_19
_19
string skuId = "1";
_19
string interactionId = "3DB3542A2C93412298AC95964A66A995";
_19
_19
var result = await _soClient.CreateLogAsync(
_19
"account",
_19
"vtex.marketplace",
_19
skuId,
_19
interactionId,
_19
log, credentials
_19
)

Unified contract

In order to facilitate the integration with Offer Management, all the contracts presented in the previous sections were grouped in a single contract, that does the following:

  1. Creates an interaction.
  2. Receives a log.
  3. Closes an interaction.

We highly recommend using this route when integrating with Offer Management. Other specific routes should be used only when the unified contract does not meet the connector's needs.


_20
UnifiedInteractionCreateDTO unifiedContract = new()
_20
{
_20
Date = "2021-10-15T16:20:19.561754Z",
_20
Source = "channel",
_20
Origin = "catalog",
_20
Context = "ongoing",
_20
Description = "Info example",
_20
Type = "Info",
_20
Agent = "My-Conector"
_20
};
_20
_20
string skuId = "1";
_20
_20
var result = await _soClient.CreateUnifiedInteractionAsync(
_20
"account",
_20
"vtex.marketplace",
_20
skuId,
_20
unifiedContract,
_20
credentials
_20
)

Integration flows

If the unified contract was not a solution for the connector, then this section’s specific flows must be implemented.

In order to integrate a VTEX seller’s SKU with a marketplace, the connector has to implement the flows as in the list below:

After the creation of the feed, each interaction in Offer Management must start with the same OriginType attribute used in the integration flow that is operating, whether it is about inventory, price or catalog.

Catalog integration

In order to create catalog integration, do as the following example:


_22
CreateLogDTO log = new()
_22
{
_22
Description = "SKU enviado ao marketplace",
_22
Type = "Failure",
_22
Agent = "channel",
_22
Date = DateTime.Now.ToString(),
_22
Errors = new CreateLogErrorRequest[] {
_22
new CreateLogErrorRequest{
_22
Code = “
_22
}
_22
}
_22
};
_22
_22
string skuId = "1";
_22
string interactionId = "3DB3542A2C93412298AC95964A66A995";
_22
var result = await _soClient.CreateLogAsync(
_22
"account",
_22
"vtex.marketplace",
_22
skuId,
_22
interactionId,
_22
log, credentials
_22
)

Price update

In order to update price in the integration, do as the following example:


_22
CreateLogDTO log = new()
_22
{
_22
Description = "SKU enviado ao marketplace",
_22
Type = "Info",
_22
Agent = "channel",
_22
Date = DateTime.Now.ToString(),
_22
Data = new CreateLogDataRequest
_22
Status = "Synchronized",
_22
Price = 124,
_22
Currency = "BRL"
_22
};
_22
_22
string skuId = "1";
_22
string interactionId = "3DB3542A2C93412298AC95964A66A995";
_22
_22
var result = await _soClient.CreateLogAsync(
_22
"account",
_22
"vtex.marketplace",
_22
skuId,
_22
interactionId,
_22
log, credentials
_22
)

Inventory update

In order to update inventory in the integration, do as the following example:


_21
CreateLogDTO log = new()
_21
{
_21
Description = "SKU enviado ao marketplace",
_21
Type = "Info",
_21
Agent = "channel",
_21
Date = DateTime.Now.ToString(),
_21
Data = new CreateLogDataRequest
_21
Status = "Synchronized",
_21
Inventory= 8
_21
};
_21
_21
string skuId = "1";
_21
string interactionId = "3DB3542A2C93412298AC95964A66A995";
_21
_21
var result = await _soClient.CreateLogAsync(
_21
"account",
_21
"vtex.marketplace",
_21
skuId,
_21
interactionId,
_21
log, credentials
_21
)

Integration errors

To integrate errors cases, do as the following example:


_10
string skuId = "1";
_10
string interactionId = "3DB3542A2C93412298AC95964A66A995";
_10
_10
var result = await _soClient.CreateLogAsync(
_10
"account",
_10
"vtex.marketplace",
_10
skuId,
_10
interactionId,
_10
log, credentials
_10
)

Contributors
3
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 3 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
3
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 3 contributors
On this page