TourService API

Overview

The TourService provides comprehensive methods for managing tours in the AndanDo marketplace. It handles tour creation, updates, deletion, marketplace listings, reservations, and all related entities like tickets, extras, itineraries, and FAQs.

Interface

public interface ITourService

Location: ~/workspace/source/AndanDo/Services/Tour/TourService.cs

Tour Management

CreateTourAsync

Creates a new tour in the system and returns the generated tour ID.

Task<int> CreateTourAsync(
    TourRegistrationRequest request,
    CancellationToken cancellationToken = default)

request

TourRegistrationRequest

required

Tour registration data including owner, title, location, description, and images

Show TourRegistrationRequest properties

OwnerUserId (string) - User ID of the tour owner
Title (string) - Tour title
LocationLabel (string) - Location display text
ShortDescription (string) - Brief tour description
DescriptionHtml (string) - Full HTML description
ImageList (string) - Comma-separated image URLs
IsActive (bool) - Active status flag
MuestraInstantanea (bool) - Show as featured/instant booking
IsQuote (bool) - Whether this is a quote-based service
IsNoPayment (bool) - Whether payment is disabled
QuoteDepositPercent (decimal?) - Deposit percentage for quotes
QuoteDueDays (int?) - Days until payment is due

cancellationToken

CancellationToken

default:"default"

Optional cancellation token

tourId

int

The newly created tour’s unique identifier

var request = new TourRegistrationRequest(
    OwnerUserId: "123",
    Title: "Beach Adventure Tour",
    LocationLabel: "Punta Cana, Dominican Republic",
    ShortDescription: "Experience pristine beaches",
    DescriptionHtml: "<p>Full description...</p>",
    ImageList: "image1.jpg,image2.jpg",
    IsActive: true,
    MuestraInstantanea: true,
    IsQuote: false,
    IsNoPayment: false,
    QuoteDepositPercent: null,
    QuoteDueDays: null,
    CreatedAt: DateTime.UtcNow,
    UpdatedAt: null
);

int tourId = await tourService.CreateTourAsync(request);

UpdateTourAsync

Updates an existing tour with new information.

Task UpdateTourAsync(
    int tourId,
    TourRegistrationRequest request,
    bool isActive,
    CancellationToken cancellationToken = default)

tourId

int

required

The ID of the tour to update

request

TourRegistrationRequest

required

Updated tour data

isActive

bool

required

Whether the tour should be active

This method automatically updates the UpdatedAt timestamp to the current UTC time.

UpdateTourStatusAsync

Updates only the status field of a tour.

Task<bool> UpdateTourStatusAsync(
    int tourId,
    string status,
    CancellationToken cancellationToken = default)

tourId

int

required

The tour ID

status

string

required

New status value (e.g., “draft”, “published”, “archived”)

success

bool

Returns true if the status was updated, false otherwise

DeleteTourAsync

Permanently deletes a tour and all related data.

Task DeleteTourAsync(
    int tourId,
    CancellationToken cancellationToken = default)

tourId

int

required

The tour ID to delete

This operation cannot be undone. The method will throw an exception if the tour has any reservations.

Automatically cascades deletion to:

Ticket types
Extras and pricing
FAQs
Inclusions
Info items
Itinerary steps
Service locations
Tour dates
Reviews and likes

DeleteTourDetailsAsync

Deletes all child entities of a tour without deleting the tour itself.

Task DeleteTourDetailsAsync(
    int tourId,
    CancellationToken cancellationToken = default)

Tour Queries

GetTourFullByIdAsync

Retrieves complete tour details including all related entities.

Task<TourFullDetailDto?> GetTourFullByIdAsync(
    int tourId,
    CancellationToken cancellationToken = default)

tourId

int

required

The tour ID to retrieve

tour

TourFullDetailDto?

Complete tour data or null if not found

Show TourFullDetailDto structure

TourId (int) - Tour identifier
OwnerUserId (int) - Owner user ID
Title (string) - Tour title
LocationLabel (string) - Location
ImageList (string?) - Comma-separated images
DescriptionHtml (string?) - HTML description
ShortDescription (string?) - Short description
IsActive (bool) - Active status
MuestraInstantanea (bool) - Featured flag
IsQuote (bool) - Quote mode
IsNoPayment (bool) - No payment flag
QuoteDepositPercent (decimal?) - Deposit percentage
QuoteDueDays (int?) - Payment due days
CreatedAt (DateTime) - Creation timestamp
UpdatedAt (DateTime?) - Last update timestamp
TicketTypes (IReadOnlyList<TourTicketTypeDetailDto>) - Ticket types
Extras (IReadOnlyList<TourExtraDetailDto>) - Tour extras
Faqs (IReadOnlyList<TourFaqDetailDto>) - FAQ items
Inclusions (IReadOnlyList<TourInclusionDetailDto>) - Inclusions/exclusions
InfoItems (IReadOnlyList<TourInfoItemDetailDto>) - Hero info items
Itinerary (IReadOnlyList<TourItineraryItemDetailDto>) - Day-by-day itinerary
ServiceLocations (IReadOnlyList<ServicioUbicacionDetailDto>) - Location URLs

GetToursForMarketplaceAsync

Retrieves all active tours for the marketplace display.

Task<IReadOnlyList<TourMarketplaceItemDto>> GetToursForMarketplaceAsync(
    CancellationToken cancellationToken = default)

tours

IReadOnlyList<TourMarketplaceItemDto>

List of tours with marketplace display data including ratings and pricing

var tours = await tourService.GetToursForMarketplaceAsync();

foreach (var tour in tours)
{
    Console.WriteLine($"{tour.Title} - From ${tour.FromPrice}");
    Console.WriteLine($"Rating: {tour.AvgRating:F1} ({tour.RatingCount} reviews)");
}

GetLatestPublishedToursForSliderAsync

Retrieves the most recent published tours for homepage slider.

Task<List<SlideDTO>> GetLatestPublishedToursForSliderAsync(
    int top = 4,
    CancellationToken cancellationToken = default)

top

int

default:"4"

Number of tours to retrieve

GetCountToursAsync

Retrieves a limited number of tours.

Task<IReadOnlyList<TourMarketplaceItemDto>> GetCountToursAsync(
    int topRows,
    CancellationToken cancellationToken = default)

GetOwnerToursAsync

Retrieves tours belonging to a specific owner.

Task<IReadOnlyList<TourMarketplaceItemDto>> GetOwnerToursAsync(
    int ownerUserId,
    int topRows,
    CancellationToken cancellationToken = default)

ownerUserId

int

required

The owner’s user ID

topRows

int

required

Maximum number of tours to return

GetAllToursForAdminAsync

Retrieves all tours for administrative purposes.

Task<IReadOnlyList<TourAdminSummaryDto>> GetAllToursForAdminAsync(
    CancellationToken cancellationToken = default)

GetTourVisibilityAsync

Retrieves visibility settings for a tour.

Task<(DateTime? StartDate, DateTime? EndDate, bool MuestraInstantanea, string? Status)> 
    GetTourVisibilityAsync(
        int tourId,
        CancellationToken cancellationToken = default)

GetTourDateRangeAsync

Retrieves the date range for a tour.

Task<(DateTime? StartDate, DateTime? EndDate)> GetTourDateRangeAsync(
    int tourId,
    CancellationToken cancellationToken = default)

Tour Details Management

UpsertHeroInfoAsync

Inserts or updates hero information items (duration, group size, etc.).

Task UpsertHeroInfoAsync(
    int tourId,
    IEnumerable<TourInfoItemRequest> infoItems,
    CancellationToken cancellationToken = default)

tourId

int

required

The tour ID

infoItems

IEnumerable<TourInfoItemRequest>

required

Collection of info items to add

Show TourInfoItemRequest properties

Label (string) - Display label (e.g., “Duration”, “Group Size”)
Value (string) - Value to display (e.g., “3 hours”, “Max 15 people”)
Icon (string) - Icon key or CSS class
SortOrder (int) - Display order

var infoItems = new[]
{
    new TourInfoItemRequest("Duration", "3 hours", "clock-icon", 1),
    new TourInfoItemRequest("Group Size", "Max 15", "users-icon", 2),
    new TourInfoItemRequest("Age", "18+", "age-icon", 3)
};

await tourService.UpsertHeroInfoAsync(tourId, infoItems);

UpsertInclusionsAsync

Manages tour inclusions and exclusions.

Task UpsertInclusionsAsync(
    int tourId,
    IEnumerable<TourInclusionRequest> inclusions,
    CancellationToken cancellationToken = default)

inclusions

IEnumerable<TourInclusionRequest>

required

Collection of inclusion/exclusion items

Show Properties

Text (string) - Inclusion/exclusion text
IsIncluded (bool) - True for inclusion, false for exclusion
SortOrder (int) - Display order

UpsertItineraryAsync

Manages day-by-day itinerary.

Task UpsertItineraryAsync(
    int tourId,
    IEnumerable<TourItineraryStepRequest> itinerary,
    CancellationToken cancellationToken = default)

itinerary

IEnumerable<TourItineraryStepRequest>

required

Collection of itinerary steps

Show TourItineraryStepRequest properties

DayNumber (string) - Day identifier (e.g., “Day 1”, “1”)
Title (string) - Step title
DescriptionHtml (string) - HTML description of the day’s activities
SortOrder (int) - Display order

UpsertFaqAsync

Manages frequently asked questions.

Task UpsertFaqAsync(
    int tourId,
    IEnumerable<TourFaqRequest> faqs,
    CancellationToken cancellationToken = default)

faqs

IEnumerable<TourFaqRequest>

required

Collection of FAQ items

Show Properties

Question (string) - The question
AnswerHtml (string) - HTML answer
SortOrder (int) - Display order

UpsertServiceLocationsAsync

Manages service location URLs (maps, meeting points).

Task UpsertServiceLocationsAsync(
    int tourId,
    IEnumerable<ServicioUbicacionRequest> locations,
    CancellationToken cancellationToken = default)

locations

IEnumerable<ServicioUbicacionRequest>

required

Collection of location URLs

Show Properties

Url (string) - Location URL (Google Maps, etc.)

UpsertTourDatesAsync

Sets the tour’s availability date range.

Task UpsertTourDatesAsync(
    int tourId,
    DateTime startDate,
    DateTime? endDate,
    CancellationToken cancellationToken = default)

startDate

DateTime

required

Tour start date

endDate

DateTime?

Optional tour end date (null for ongoing)

Ticket Management

UpsertTicketTypesAsync

Replaces all ticket types for a tour.

Task UpsertTicketTypesAsync(
    int tourId,
    IEnumerable<TourTicketTypeRequest> tickets,
    CancellationToken cancellationToken = default)

tickets

IEnumerable<TourTicketTypeRequest>

required

Collection of ticket types

Show TourTicketTypeRequest properties

Name (string) - Ticket name (e.g., “Adult”, “Child”)
MinAge (int?) - Minimum age
MaxAge (int?) - Maximum age
Price (decimal?) - Ticket price
CurrencyCode (string) - Currency code (USD, DOP, etc.)
SortOrder (int) - Display order
CapacidadPorTipo (int?) - Capacity for this ticket type
VentaInicioUtc (DateTime?) - Sale start date
VentaFinUtc (DateTime?) - Sale end date
MaxPorOrden (int?) - Max per order
MaxPorUsuario (int?) - Max per user

This method deletes all existing ticket types before inserting new ones.

GetTicketTypeReservedCountAsync

Gets the number of reserved tickets per ticket type.

Task<Dictionary<int, int>> GetTicketTypeReservedCountAsync(
    int tourId,
    CancellationToken cancellationToken = default)

reservedCounts

Dictionary<int, int>

Dictionary mapping ticket type ID to reserved count

GetTicketTypeCapacityAsync

Gets the capacity for each ticket type.

Task<Dictionary<int, int?>> GetTicketTypeCapacityAsync(
    int tourId,
    CancellationToken cancellationToken = default)

capacities

Dictionary<int, int?>

Dictionary mapping ticket type ID to capacity (null = unlimited)

Extras Management

UpsertExtrasAsync

Manages tour extras (add-ons).

Task UpsertExtrasAsync(
    int tourId,
    IEnumerable<TourExtraRequest> extras,
    CancellationToken cancellationToken = default)

extras

IEnumerable<TourExtraRequest>

required

Collection of extras

Show TourExtraRequest properties

Name (string) - Extra name
Description (string) - Description
ChargeMode (int) - Charging mode:
- 1 = Fixed price per order
- 2 = Per person (price varies by ticket type)
BasePrice (decimal?) - Base price
CurrencyCode (string) - Currency code
TicketPrices (IEnumerable<TourExtraTicketPriceRequest>) - Per-ticket-type pricing
SortOrder (int) - Display order

Reservations

CreateReservationAsync

Creates a new tour reservation.

Task<int> CreateReservationAsync(
    TourReservationRequest request,
    IEnumerable<TourReservationTicketRequest> tickets,
    CancellationToken cancellationToken = default)

request

TourReservationRequest

required

Reservation details including user, tour, dates, and payment info

tickets

IEnumerable<TourReservationTicketRequest>

required

Collection of tickets being reserved

reservationId

int

The newly created reservation ID

UpdateReservationPaymentStatusAsync

Updates the payment status of a reservation.

Task UpdateReservationPaymentStatusAsync(
    int reservationId,
    byte paymentStatus,
    string? paymentProvider,
    string? paymentReference,
    CancellationToken cancellationToken = default)

reservationId

int

required

The reservation ID

paymentStatus

byte

required

Payment status code (0 = pending, 1 = paid, etc.)

paymentProvider

string?

Payment provider name (e.g., “PayPal”)

paymentReference

string?

Payment reference/transaction ID

GetReservationsByTourAsync

Retrieves all reservations for a specific tour.

Task<IReadOnlyList<TourReservationReportDto>> GetReservationsByTourAsync(
    int tourId,
    CancellationToken cancellationToken = default)

GetReservationsByUserAsync

Retrieves all reservations for a specific user.

Task<IReadOnlyList<TourUserReservationDto>> GetReservationsByUserAsync(
    int userId,
    int topRows = 50,
    CancellationToken cancellationToken = default)

userId

int

required

The user ID

topRows

int

default:"50"

Maximum number of reservations to return

GetTourReservationStatsAsync

Retrieves reservation statistics for a tour.

Task<TourReservationStatsDto> GetTourReservationStatsAsync(
    int tourId,
    int recentDays = 30,
    CancellationToken cancellationToken = default)

recentDays

int

default:"30"

Number of days to include in statistics

stats

TourReservationStatsDto

Statistics including total reservations, amounts, and daily breakdown

Owner Analytics

GetOwnerEarningsAsync

Calculates total earnings for a tour owner.

Task<decimal> GetOwnerEarningsAsync(
    int ownerUserId,
    CancellationToken cancellationToken = default)

earnings

decimal

Total earnings amount

GetOwnerTourStatsAsync

Retrieves tour statistics for an owner.

Task<(int TotalServices, int RecentServices)> GetOwnerTourStatsAsync(
    int ownerUserId,
    int recentDays = 7,
    CancellationToken cancellationToken = default)

recentDays

int

default:"7"

Number of days to consider as “recent”

totalServices

int

Total number of tours owned

recentServices

int

Number of tours created in the recent period

Best Practices

Transaction Handling: Many operations (especially deletes and upserts) use database transactions. Ensure proper error handling to avoid partial updates.

Cancellation Tokens: All async methods support cancellation tokens for graceful shutdown and request cancellation.

Data Integrity: When updating ticket types or extras, be aware that existing reservations reference these entities. Consider the impact before making changes.

Architecture

API Reference

Configuration

Deployment

​Overview

​Interface

​Tour Management

​CreateTourAsync

​UpdateTourAsync

​UpdateTourStatusAsync

​DeleteTourAsync

​DeleteTourDetailsAsync

​Tour Queries

​GetTourFullByIdAsync

​GetToursForMarketplaceAsync

​GetLatestPublishedToursForSliderAsync

​GetCountToursAsync

​GetOwnerToursAsync

​GetAllToursForAdminAsync

​GetTourVisibilityAsync

​GetTourDateRangeAsync

​Tour Details Management

​UpsertHeroInfoAsync

​UpsertInclusionsAsync

​UpsertItineraryAsync

​UpsertFaqAsync

​UpsertServiceLocationsAsync

​UpsertTourDatesAsync

​Ticket Management

​UpsertTicketTypesAsync

​GetTicketTypeReservedCountAsync

​GetTicketTypeCapacityAsync

​Extras Management

​UpsertExtrasAsync

​Reservations

​CreateReservationAsync

​UpdateReservationPaymentStatusAsync

​GetReservationsByTourAsync

​GetReservationsByUserAsync

​GetTourReservationStatsAsync

​Owner Analytics

​GetOwnerEarningsAsync

​GetOwnerTourStatsAsync

​Best Practices

Build docs developers (and LLMs) love

Overview

Interface

Tour Management

CreateTourAsync

UpdateTourAsync

UpdateTourStatusAsync

DeleteTourAsync

DeleteTourDetailsAsync

Tour Queries

GetTourFullByIdAsync

GetToursForMarketplaceAsync

GetLatestPublishedToursForSliderAsync

GetCountToursAsync

GetOwnerToursAsync

GetAllToursForAdminAsync

GetTourVisibilityAsync

GetTourDateRangeAsync

Tour Details Management

UpsertHeroInfoAsync

UpsertInclusionsAsync

UpsertItineraryAsync

UpsertFaqAsync

UpsertServiceLocationsAsync

UpsertTourDatesAsync

Ticket Management

UpsertTicketTypesAsync

GetTicketTypeReservedCountAsync

GetTicketTypeCapacityAsync

Extras Management

UpsertExtrasAsync

Reservations

CreateReservationAsync

UpdateReservationPaymentStatusAsync

GetReservationsByTourAsync

GetReservationsByUserAsync

GetTourReservationStatsAsync

Owner Analytics

GetOwnerEarningsAsync

GetOwnerTourStatsAsync

Best Practices