Shopee.Affiliate 1.1.2

Shopee.Affiliate

A lightweight, strongly typed .NET SDK for Shopee Affiliate Open Platform APIs.

Small .NET SDK for Shopee Affiliate Open API workflows.

Maintained by Greco Labs.

Shopee.Affiliate helps affiliate bots, deal monitors, content automations, and back-office tools turn Shopee product URLs into affiliate-ready links while optionally enriching the response with product offer data.

What It Does

Installation

After the package is published to NuGet:

dotnet add package Shopee.Affiliate

To build from source:

git clone https://github.com/gregojoao/shopee-affiliate.git
cd shopee-affiliate
dotnet restore
dotnet test
dotnet pack -c Release

The package is generated at:

src/Shopee.Affiliate/bin/Release/Shopee.Affiliate.<version>.nupkg

Quick Start

using Shopee.Affiliate.Application;

var options = new ShopeeAffiliateOptions
{
    AppId = Environment.GetEnvironmentVariable("SHOPEE_AFFILIATE_APP_ID")!,
    Secret = Environment.GetEnvironmentVariable("SHOPEE_AFFILIATE_SECRET")!,
    SubIds = new[] { "telegram", "bot" }
};

using var httpClient = new HttpClient();
var client = new ShopeeAffiliateClient(httpClient, options);

var result = await client.GenerateAffiliateLinkAsync(new ShopeeAffiliateLinkRequest
{
    OriginUrl = new Uri("https://shopee.com.br/product/627750190/23798776965")
});

Console.WriteLine(result.AffiliateUrl);
Console.WriteLine(result.Source);
Console.WriteLine(result.Product?.ProductTitle);
Console.WriteLine(result.Product?.ProductPrice);
Console.WriteLine(result.Product?.ProductOriginalPrice);
Console.WriteLine(result.Product?.ProductImageUrl);

Configuration

You can pass credentials manually:

using System.Globalization;
using Shopee.Affiliate.Application;

var options = new ShopeeAffiliateOptions
{
    AppId = "your-app-id",
    Secret = "your-secret",
    Endpoint = ShopeeAffiliateOptions.DefaultEndpoint,
    SubIds = new[] { "campaign", "channel" },
    Timeout = TimeSpan.FromSeconds(90),
    PriceCulture = CultureInfo.GetCultureInfo("pt-BR")
};

For ASP.NET Core, Worker Services, or any app using Microsoft.Extensions.DependencyInjection, register the SDK once:

using Shopee.Affiliate.Infrastructure;

builder.Services.AddShopeeAffiliate(builder.Configuration);

Then configure secrets through environment variables, user secrets, Key Vault, or any other configuration provider:

{
  "Shopee": {
    "Affiliate": {
      "AppId": "your-app-id",
      "Secret": "your-secret",
      "SubIds": [ "campaign", "channel" ],
      "Timeout": "00:01:30",
      "PriceCulture": "pt-BR"
    }
  }
}

In production, prefer environment variables or a secret manager instead of committing secrets to appsettings.json.

After registration, inject the client:

using Shopee.Affiliate.Application;

public sealed class DealPublisher(IShopeeAffiliateClient shopee)
{
    public async Task PublishAsync(string productUrl)
    {
        var result = await shopee.GenerateAffiliateLinkAsync(new ShopeeAffiliateLinkRequest
        {
            OriginUrl = new Uri(productUrl)
        });

        Console.WriteLine(result.AffiliateUrl);
    }
}

You can also configure options directly in code:

using Shopee.Affiliate.Infrastructure;

builder.Services.AddShopeeAffiliate(options =>
{
    options.AppId = builder.Configuration["SHOPEE_AFFILIATE_APP_ID"]!;
    options.Secret = builder.Configuration["SHOPEE_AFFILIATE_SECRET"]!;
    options.SubIds = new[] { "telegram", "bot" };
});

Per-call behavior lives on request objects:

Main APIs

Use IShopeeAffiliateClient when credentials are registered through DI. Use ShopeeAffiliateClient directly when you want to provide ShopeeAffiliateOptions in code.

GenerateAffiliateLinkAsync

High-level helper for the usual bot workflow. It tries to extract product identifiers, query the affiliate product offer, and return the best affiliate URL available.

ShopeeAffiliateLinkResult result = await client.GenerateAffiliateLinkAsync(new ShopeeAffiliateLinkRequest
{
    OriginUrl = new Uri(url),
    Strategy = ShopeeAffiliateLinkStrategy.PreferProductOffer
});

Available strategies:

GenerateShortLinkAsync

Calls generateShortLink directly.

ShopeeShortLinkResult result = await client.GenerateShortLinkAsync(new ShopeeShortLinkRequest
{
    OriginUrl = new Uri(url)
});

Console.WriteLine(result.ShortLink);

GetProductOfferAsync

Calls productOfferV2 directly for a known product identity.

using Shopee.Affiliate.Domain;

var identity = new ShopeeAffiliateProductIdentity(
    ShopId: "627750190",
    ItemId: "23798776965");

ShopeeProductOffer? offer = await client.GetProductOfferAsync(new ShopeeProductOfferRequest
{
    ProductIdentity = identity
});

Console.WriteLine(offer?.ProductTitle);

ResolveShopeeUrlAsync

Follows redirects for Shopee short URLs and returns the final URL when possible.

Uri resolvedUrl = await client.ResolveShopeeUrlAsync(new Uri(shortUrl));

Credential errors

The link client throws ShopeeAffiliateCredentialException when Shopee rejects Affiliate/Open API credentials. It derives from ShopeeAffiliateApiException, so existing catch blocks keep working, while callers that need to distinguish credential failures can catch the more specific type.

try
{
    ShopeeShortLinkResult result = await client.GenerateShortLinkAsync(new ShopeeShortLinkRequest
    {
        OriginUrl = new Uri(url)
    });
}
catch (ShopeeAffiliateCredentialException ex) when (!ex.IsRetryable)
{
    // Disable the credential, alert the operator, or route to reconfiguration.
    Console.WriteLine($"{ex.Platform}: {ex.Kind} ({ex.ProviderErrorCode})");
}
catch (ShopeeAffiliateApiException)
{
    // Generic GraphQL, HTTP 5xx, timeout, rate-limit, or other API failure.
    throw;
}

Affiliate reports

Shopee.Affiliate.Reports.ShopeeAffiliateReportsClient exposes the reporting surface of the Shopee Affiliate Open API. It signs every call with the same SHA256 scheme as the link client, posts to the GraphQL endpoint, and returns strongly-typed DTOs.

Register it the same way you register the link client:

using Shopee.Affiliate.Infrastructure;

builder.Services.AddShopeeAffiliateReports(builder.Configuration);
// or:
builder.Services.AddShopeeAffiliateReports(options =>
{
    options.AppId = builder.Configuration["SHOPEE_AFFILIATE_APP_ID"]!;
    options.Secret = builder.Configuration["SHOPEE_AFFILIATE_SECRET"]!;
});

Configuration section (defaults Shopee:Affiliate:Reports):

{
  "Shopee": {
    "Affiliate": {
      "Reports": {
        "AppId": "your-app-id",
        "Secret": "your-secret",
        "Endpoint": "https://open-api.affiliate.shopee.com.br/graphql",
        "Timeout": "00:00:30"
      }
    }
  }
}

Then inject IShopeeAffiliateReportsClient:

using Shopee.Affiliate.Reports;

public sealed class DashboardService(IShopeeAffiliateReportsClient reports)
{
    public async Task<ShopeeSalesSummary> LoadSummaryAsync(DateTimeOffset from, DateTimeOffset to, CancellationToken ct)
    {
        var conversions = await reports.ListConversionsAsync(new ListShopeeConversionsRequest(
            From: from,
            To: to,
            Status: ShopeeConversionStatusFilter.All,
            PageSize: 200), ct);

        return await reports.GetSalesSummaryAsync(new ShopeeSalesSummaryRequest(from, to), ct);
    }
}

Methods

Exceptions

All reporting exceptions derive from Shopee.Affiliate.Infrastructure.ShopeeAffiliateException:

Limits and conventions

• Time zone. Shopee operates in GMT+7. The SDK accepts DateTimeOffset so the caller's offset is preserved; the wire format is Unix-seconds.
• Maximum window. conversionReport accepts at most ~90 days between From and To. Wider windows are rejected by Shopee with error code 11001 ("Params Error : can only query data for the last 3 months"), surfaced as ShopeeAffiliateApiException. Split larger ranges into chunks of ≤ 90 days.
• Page size. Capped at 500 (Shopee server limit).
• Cursor TTL. scrollId values expire ~30 seconds after issue; resume on fresh windows or restart from page 1 if the cursor is rejected.
• Retries. A single automatic retry on HTTP 5xx and request timeouts. HTTP 4xx surfaces immediately.
• Currency. Money.Currency is preserved verbatim from Shopee — no conversion happens inside the SDK.

The GraphQL surface used by 1.1.0 is documented at https://www.affiliateshopee.com.br/documentacao.

Architecture

The SDK is organized with a small DDD-inspired structure:

Public namespaces follow the physical project structure: use Shopee.Affiliate.Application for clients/options/results, Shopee.Affiliate.Domain for value objects, and Shopee.Affiliate.Infrastructure for DI registration and infrastructure exceptions.

Returned Data

ShopeeAffiliateLinkResult contains:

ShopeeProductOffer contains:

Supported URL Formats

The SDK can extract shopId and itemId from these common formats:

https://shopee.com.br/product/{shopId}/{itemId}
https://shopee.com.br/{slug}-i.{shopId}.{itemId}
https://shopee.com.br/opaanlp/{shopId}/{itemId}
https://shopee.com.br/...?...shopid={shopId}&itemid={itemId}

When ShopeeAffiliateLinkRequest.ResolveShortUrls is enabled, short URLs are resolved before product identity extraction.

Authentication

Requests are signed with SHA-256:

Authorization: SHA256 Credential={AppId}, Timestamp={Timestamp}, Signature={Signature}
Signature = SHA256(AppId + Timestamp + Payload + Secret)

Timestamp is Unix time in seconds. Payload must be the exact JSON body sent to the GraphQL endpoint.

API Notes

Shopee's official Help Center says the Affiliate API can retrieve Shopee, brand, and product offer lists, generate short links, and retrieve conversion reports:

https://help.shopee.sg/portal/10/article/191702-API-Access

For Brazil, the affiliate Open API is exposed as GraphQL. Publicly available documentation and existing integrations use:

• productOfferV2
• generateShortLink

Important: the public affiliate schema used by this SDK does not expose a dedicated "old price" field. ProductOriginalPrice is calculated with:

original = current / (1 - discountRate / 100)

This is useful for promotion messages, but it can differ slightly from Shopee's displayed price because priceDiscountRate may be rounded.

Development

dotnet restore
dotnet test
dotnet pack -c Release

Publishing

Before publishing a new NuGet version:

1. Update <Version> and <PackageReleaseNotes> in src/Shopee.Affiliate/Shopee.Affiliate.csproj.
2. Run the validation:

dotnet test
dotnet pack -c Release

3. Push the package:

dotnet nuget push src/Shopee.Affiliate/bin/Release/Shopee.Affiliate.*.nupkg --api-key "$NUGET_API_KEY" --source https://api.nuget.org/v3/index.json

See PUBLISHING.md for the full release checklist.

License

This project is licensed under the MIT License. See LICENSE for details.