Add-ons - Add-on Development (Technical Documentation)

Roadmap:

• Creating and Managing Add-ons
  • Add-on Development (Technical Documentation)
    • Add-on Activation
    • Add-on Deactivation
    • Add-on Opening
    • Add-on Testing
    • Add-on Versioning (Functionality Changes)
  • API Documentation (How to Connect Products, Categories, Orders, etc.)
  • Best Practices
    • General Rules
    • Add-on Activation
    • Add-on Opening
    • Add-on Functionality
    • Types of Add-ons
  • Webhooks
  • Discord Developer Forum (Want to Know What's Coming or Need Advice?)

Add-on Development

The development part of the add-on (Add-on Development tab) is used to connect the add-on to the Upgates administration and is divided into two sections.

API Documentation

In the Documentation section, you will find links to the most important parts of add-on development. This includes a link to the complete Developer section, a graphical overview of all used elements, and the Discord developer forum.

API Settings

In the API Settings section, you will find the endpoints that you need to create on your side. Requests related to the add-on's functionality will be sent to these endpoints from our side.

• Endpoints must be publicly accessible.
• We require an SSL certificate on all API endpoints.

(Screen from Marketplace / My Add-ons - Your Add-on - Add-on Development)

Installation Endpoint: Used during the activation of the add-on by the client.

Opening Endpoint: Used to open the Iframe part of the add-on. We send information from our side that Client X, with token Y, wants to open your add-on. You return the address of the iframe in the body of the request.

Uninstallation Endpoint: Used during the deactivation of the add-on. We send information from our side that the client has deactivated the add-on and the API accesses are deleted. No response is required from your side.

Versioning Endpoint: Used when the customer transitions to a new version of the add-on. Information about the version they are transitioning to is sent to this address so you can return the correct information, such as to the iframe or to set up a conversion code, etc.

Signature Token: A unique identifier for your add-on, used to create a signature (see Activation, Opening, Version Change, and Deactivation).

API Accesses

The API Settings section includes the API Accesses section. These API accesses need to be configured according to how your add-on works. For example, if you need to download orders, you will set up the Access Type as Orders, the part as GET Orders, and set the frequency at which you will call GET.

Description of API Access Usage: This serves as information for us about why you need the API access and what function it performs for you.

Call Frequency: This is used for the automatic control of your add-on. The automatic control evaluates whether your add-on stays within the set limits. This control is important to ensure that the API is not regularly overloaded and does not function differently than discussed during the consultation or our testing.

Note! Please ensure a correct and detailed description of the call frequency and the purpose of why you are setting up the API access.

Signing

We sign data with a private key, and you can verify it using the public key method OPENSSL_ALGO_SHA256. The signature can be found in each request body under the key signature. The relevant data is signed according to the requirements.

• The current_admin_language is excluded from the signed data.
• The individual signed data can be found for each endpoint.
• We recommend always loading the current public key when verifying the signature and not storing it for later use due to the possibility of key changes.

Example of Signature Verification in PHP

$data = implode(";",[...]);
$signature = 'a0e0a3e7689bd4c80e4d6ffcccb05235b864e1d0';
$signaturePublicKey = file_get_contents("https://files.upgates.com/addons/signature/api.signature.pub.key");
$verify = openssl_verify($data, base64_decode($signature), $signaturePublicKey, OPENSSL_ALGO_SHA256);
        

Best practices

• Best practices for basic API usage.

Best practices for add-on functionality:

General

• When designing the add-on, consider that multiple activation requests for an already activated add-on or deactivation requests for a currently inactive add-on may come from our side, even if not directly targeted.
• If working with APIs for multiple e-shops on one server, distribute the load throughout the day and avoid downloading data only at night or at 00:00, etc.
  • For example, divide the pool of e-shops and add offsets by hours or other larger time intervals:
    • 2 e-shops at 00:00
    • 2 e-shops at 01:00
    • etc.
• Ensure the server is not overloaded during implementation (use webhooks) - violations may result in blocking API accesses for the add-on across all e-shops.

• Add-on Testing:

  • The main attribute when testing add-ons on your side should be user-friendliness. Before submitting the add-on for our testing, please ensure you can operate your add-on as a regular customer (correctly create a user account, log out and log back into your environment, etc.). This will ease the overall add-on approval process.

  • Our main goal when checking your add-on will be to ensure the best possible use of the API.

  • Do not use the "Synchronize" button. If it is essential for functionality, set up protection against repeated clicks and ensure the button cannot be pressed again if the original synchronization process is still running.

  • Link planned tasks with webhooks. It is unnecessary to download all orders daily, especially if no new orders have been created or no changes have occurred.

Add-on Activation

Account Creation:

• For creating or pairing an account, you can use /owner.
• Finalize account creation in the iframe window in the administration with buttons like "Existing Customer," "New Customer with email /owner," "New Customer."
• (This is because the user may have multiple owners based on languages, and you can manage mutations/domains in one account without knowing which account to create.)
• Once you obtain information from the owner, create the customer's account so they can directly access your environment. Do not require the customer to copy verification codes from emails, etc.
• If your environment requires indicating that the account is linked to the Upgates platform, this must happen during account creation. Do not require the customer to activate the link on their side additionally.
• The user must not have access to the API access credentials sent to you through the add-on. These communication details are for you only, and the client should not be able to discover and use them.

Add-on Opening

• Data Processing / Additional Activation Finalization: If the add-on activation involves processing, include a detailed step-by-step process in the add-on iframe, updating the current status so the customer always knows the activation status. Also, provide your company's phone number and email so the customer can contact you.

Add-on Functionality

• Orders

  • Orders GET: If you need a button in your add-on to download current orders, consider webhooks first. If the button is necessary, set it up to prevent repeated use within a few seconds. Usage should be conditioned to activate only after the previous download is complete + an interval.

• Webhooks:

• • Webhooks must not be bypassed by users in your environment!
  • If you offer customers the option to set synchronization repeatedly, e.g., in minutes, these triggers must be executed on your side and check if a webhook notification has arrived during this interval. It is not allowed to call individual sections every minute and bypass webhooks.

Types of Add-ons

In this section, we will try to describe the basic expected use of the API and the functionality of different types of add-ons. If you do not find a description of your add-on here, do not hesitate to inform us, and we can discuss the ideal functionality of the add-on in an online meeting.