Eshop API Documentation

This documentation provides an overview of the available API endpoints for Eshop integration. Each section is organized by functional area—code lists, credit wallet, customer operations, exchange rates, and more—with descriptions, input parameters, and return values.

1. Code Lists

Controller: EshopCodeListController
Description: Provides the code lists used throughout the Eshop.

1.1 Get List of Contact Types

  • Method: GetListContactTypeAsync
  • Description: Returns a list of contact types.
  • Return Value: A list of contact type entries.

1.2 Contact Type Details

  • Method: GetContactTypeAsync
  • Parameters:
    • listContactTypeRequest – request object specifying which contact type to retrieve.
  • Description: Returns detailed information for the specified contact type.

1.3 Get List of Currencies

  • Method: GetListCurrencyAsync
  • Description: Returns a list of supported currencies.
  • Return Value: A list of currency entries.

1.4 Currency Details

  • Method: GetCurrencyAsync
  • Parameters:
    • listCurrencyRequest – request object specifying which currency to retrieve.
  • Description: Returns detailed information for the specified currency.

1.5 Get List of States

  • Method: GetListStateAsync
  • Description: Returns a list of states.
  • Return Value: A list of state entries.

1.6 State Details

  • Method: GetStateAsync
  • Parameters:
    • listStateRequest – request object specifying which state to retrieve.
  • Description: Returns detailed information for the specified state.

2. Credit Wallet

Controller: EshopCreditWalletController
Description: Manages operations related to a customer’s credit balance. All operations require a Customer-authorization header containing the logged-in customer’s token.

2.1 Customer Credit Balance History

  • Method: GetCustomerCreditBalanceHistoryAsync
  • Parameters:
    • customerCreditBalance – GUID (ExternalUserId obtained from LoginUserResponse).
  • Description: Retrieves the history of the customer’s credit balance.
  • Return Value: A list of credit balance history entries.

2.2 Current Credit Balance

  • Method: GetCurrentCreditBalanceAsync
  • Parameters:
    • creditBalanceRequest – GUID (ExternalUserId obtained from LoginUserResponse).
  • Description: Returns the customer’s current credit balance across all currencies.

2.3 Top Up Credit Balance

  • Method: CustomerCreditTopUpAsync
  • Parameters:
    • creditTopUpRequest – request object containing top-up details.
  • Description: Performs a credit balance top-up for the customer.

2.4 Pay by Credit

  • Method: PayByCreditAsync
  • Parameters:
    • creditPaymentRequest – request object containing payment details.
  • Description: Processes an order payment using the customer’s credit balance.

2.5 Check Credit Payment

  • Method: CheckCreditPayment
  • Parameters:
    • creditCheckPaymentRequest – request object to verify credit payment status.
  • Description: Checks the status of a credit-based payment.

3. Customer Operations

Controller: EshopCustomerController
Description: Provides endpoints for customer-related operations. All operations (except login) require a Customer-authorization header containing the logged-in customer’s token.

3.1 Customer Login

  • Method: LoginUser
  • Parameters:
    • loginUserRequest – contains userEmail and Password.
  • Description: Authenticates the customer. Does not require Customer-authorization.
  • Return Value:
    • ExternalUserId – GUID representing the user.
    • IsAuthenticated – boolean indicating success.
    • Message – result message.

3.2 Get Customer Account Details

  • Method: GetCustomerAccount
  • Parameters:
    • customerAccountRequest – GUID (ExternalUserId obtained from LoginUserResponse).
  • Description: Retrieves information about the customer’s account.

3.3 Get Customer Addresses

  • Method: GetCustomerAddress
  • Parameters:
    • customerAddressRequest – GUID (ExternalUserId obtained from LoginUserResponse).
  • Description: Returns the list of addresses associated with the customer.

3.4 Get Customer Contacts

  • Method: GetCustomerContact
  • Parameters:
    • customerContactRequest – GUID (ExternalUserId obtained from LoginUserResponse).
  • Description: Returns the list of contact details for the customer.

3.5 Add Customer Contact

  • Method: CreateCustomerContact
  • Parameters:
    • createCustomerContactRequest
      • ExternalUserId (from LoginUserResponse)
      • ExternalContactTypeId (from EshopCodeList/GetListContactType)
      • Value – the contact value.
  • Description: Adds a new contact detail for the customer.

3.6 Customer Login History

  • Method: GetCustomerLoginHistory
  • Parameters:
    • customerLoginHistory – GUID (ExternalUserId obtained from LoginUserResponse).
  • Description: Retrieves the customer’s login history.

3.7 Customer Order History

  • Method: GetCustomerOrderHistoryAsync
  • Parameters:
    • request – GUID (ExternalUserId obtained from LoginUserResponse).
  • Description: Retrieves the customer’s order history.

3.8 Add Order to Customer

  • Method: AddOrderToCustomerAsync
  • Parameters:
    • request – contains OrderId and ExternalUserId.
  • Description: Associates an existing order with the customer.

3.9 Create New Customer

  • Method: CreateCustomer
  • Parameters:
    • createCustomerRequest – request object for creating a new customer.
  • Description: Creates a new customer account.

3.10 Activate Customer Account

  • Method: ActivateCustomer
  • Parameters:
    • activateCustomerRequest – contains the activation token.
  • Description: Activates the customer’s account.

3.11 Update Customer Details

  • Method: UpdateCustomer
  • Parameters:
    • updateCustomerRequest – request object containing updated customer information.
  • Description: Updates the customer’s profile details.

3.12 Change Customer Password

  • Method: ChangePassword
  • Parameters:
    • changePasswordRequest – contains ExternalUserId, the old password, and the new password.
  • Description: Changes the customer’s password.

3.13 Create Customer Address

  • Method: CreateCustomerAddress
  • Parameters:
    • createCustomerAddressRequest – request object for adding a new address.
  • Description: Adds a new address for the customer.

3.14 Update Customer Address

  • Method: UpdateCustomerAddress
  • Parameters:
    • updateCustomerAddressRequest – request object for modifying an existing address.
  • Description: Updates an existing customer address.

3.15 Delete Customer Address

  • Method: DeleteCustomerAddress
  • Parameters:
    • deleteCustomerAddress – request object for deleting an address.
  • Description: Removes a customer address.

3.16 Check Email Availability for Login

  • Method: CustomerLoginAvailable
  • Parameters:
    • customerLoginAvailableRequest – request object containing the email to check.
  • Description: Checks whether an email address is available for use as a login.

4. Exchange Rates

Controller: EshopExchangeRateController
Description: Provides an endpoint to retrieve exchange rates.

4.1 Get Exchange Rate

  • Method: GetExchangeRateAsync
  • Parameters:
    • exchangeRateRequest – request object specifying the currency for which to retrieve the rate.
  • Description: Returns detailed exchange rate information for the selected currency.

5. Eshop PayU Controller

Controller: EshopPayUController
Description: Provides payment processing via the PayU gateway.

5.1 CreatePayment

  • Method: CreatePayment
  • Parameters:
    • purchaseId – unique identifier for the purchase session (used to track order status).
    • currencyId – identifier of the payment currency (see EshopCodeList/GetListCurrency).
    • description – description displayed on the payment summary page.
    • email – customer’s email address (required by PayU).
    • firstName – (optional) customer’s first name.
    • lastName – (optional) customer’s last name.
    • language – (optional) language code (e.g., cs, en) for the payment interface.
    • additionalPaymentFlag – (optional) flag for special payment requirements.
  • Description:
    Initializes a PayU payment transaction. Validates input, assembles order details, and prepares documentation for the payment process. On success, returns a URL for redirecting the customer to PayU’s payment gateway; on error, returns an appropriate message.
  • Response:
    • status – overall processing status.
    • redirectUri – PayU gateway URL for redirection.
    • orderId – unique PayU transaction identifier (for verification).
    • extOrderId – unique Arriva order identifier (for verification).

5.2 CheckPayment

  • Method: CheckPayment
  • Parameters:
    • payUOrderId – (optional) PayU-generated payment identifier.
    • arrivaOrderId – (optional) Arriva-generated order identifier.
      At least one parameter must be provided for verification.
  • Description:
    Verifies a payment’s status by querying the PayU system. Indicates whether payment is complete or requires further action.
  • Response:
    • orderResult – detailed result of the order processing (including errors or success).
    • isPaid – boolean indicating payment success.
    • paymentStatusCode – status code (e.g., confirmed, pending confirmation).

6. Other Controllers

6.1 Eshop Mail Controller

  • Controller: EshopMailController
  • Description: Manages email communication within the Eshop. (Specific endpoints are not detailed.)

7. Error Handling

7.1 Error Details (Problem)

  • Type: Arriva.Arrtic.Api.Models.Problem
  • Description: Represents error details following RFC 7807.
  • Properties:
    • Type: absolute URI identifying the error type.
    • Title: brief summary of the problem (in English, for technical users).
    • Status: HTTP status code.
    • Detail: description of the specific error.
    • Instance: absolute URI identifying this error occurrence.

7.2 Warnings

  • Type: Arriva.Arrtic.Api.Models.Warning
  • Description: Conveys non-blocking information (e.g., price differences from the original offer).
  • Properties:
    • Code: warning code.
    • Type: warning type.
    • Detail: detailed description of the warning.