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

Roadmap:

• Creating and Managing Add-ons
  • Add-on Development
    • Verification of add-ons
    • Add-on Activation
    • Add-on Opening
      • Add-on iframe
    • Add-on Deactivation
    • Add-on Testing
    • Add-on Versioning (Functionality Changes)
  • API Documentation (How to Connect Products, Categories, Orders, etc.)
    • Automatic Check and Add-on API Restrictions
  • Rules and Best Practices
    • General Rules
    • Add-on Activation
    • Add-on Opening
    • Add-on Functionality
    • Basic expected add-on features
  • 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.

TIP! Before you start creating an add-on, even if you have gone through an initial online consultation, do not hesitate to create a ticket right from the start via your development project (or write on Discord) and discuss step by step how the add-on should behave, from activation, through normal operation to special cases such as what to do with the add-on if the client stops paying for your service. We would rather always help during the development of the add-on itself than encounter obstacles in approving the add-on during testing itself.

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.

Rules and Best practices

The basic goal of the verified add-on is to bring clients as much automation as possible in the connection without unnecessary clicking and filling out forms.

Always use the current Upgates logos.

General

• The add-on works thanks to communication via API. Basic BestPractices in using API can be found here.
• In case of working with the API of multiple e-shops on one server, it is necessary to distribute the workload over the whole day, and not download data, for example, only during the night or at 00:00, etc.
  • For example, divide the pool of e-shops and add offsets by hours or other larger time periods:
    • 2 e-shops at 00:00
    • 2 e-shops at 01:00
      etc.
• Upgates allows multilingualism and multi-domain.
  • What does this mean for you?
    You need to prepare for the fact that products, categories, articles, and other sections are in multiple languages ​​under multiple domains, but only under one administration.
    For example, the product "T-shirt" can be in CZ, SK, EN, it can have its own domain for each mutation, but it will still be in one administration under one unique ID.
    There can also be a product "Jacket", which will be in SK only, but will still fall under the same administration as the product "T-shirt".
  • If you are solving multilingualism for products, categories, etc., download them as a whole (without URL restrictions for languages).
    Solve the division into languages ​​​​only on your side. You should use downloading specific languages, for example, when you are solving a matter related to a specific language mutation. For example, responding to the webhook languages.create - when a new language mutation is created.
• Use webhooks - Violation can cause the add-on to be disapproved, or later blocked if it is detected by automatic control.
• Add-on testing:
  • The main attribute when testing add-ons on your side should be user-friendliness. Before you submit your add-on for testing, please make sure that you can operate your add-on as a regular customer (a user account is created correctly, logging out and logging back into your environment works, etc.). This will make the overall add-on approval process easier.
  • The main goal of our review of your add-on will be to ensure the best possible use of the API.
  • Do not use the "Synchronize" button. If you really need it to work, set it to prevent repeated clicking, and also make it impossible to press the button again while the original synchronization process is still running.
    Connect scheduled tasks with webhooks. It is not necessary to download all orders every day, especially if there are no new orders / no changes.

Activating the add-on

• When designing the add-on, you should take into account that we may, although not directly targeted, receive more requests to activate an already activated add-on or requests to deactivate a currently inactive add-on.
• Activation (or subsequent registration) can be considered as already verified (authorized). It is always performed by a user in Upgates.

Account creation

• You can use /owner to create or pair an account.
• Fully automate account creation. Do not require the client to fill out a special form on your website. The client is verified by us, so registration can be carried out directly with you, without unnecessary delays.
  • If you do not obtain all the necessary data for registration from /owner and other endpoints, solve this using an iframe.
  • Once you obtain information from the owner, create an account for the customer so that they can get directly into your environment without unnecessary delays. Do not require the customer to additionally copy verification codes from emails, copy connection tokens, etc.
• If your environment requires you to indicate that the account is linked to a given Upgates platform, this must be done during account creation. Do not require the customer to additionally activate the connection on your side.
• The user must not have access to the API access data that is sent to you via the add-on. This communication data is only for you and the client should not be able to find out and use it further.

Opening the add-on

• It is governed by the rules for using the iframe add-on.
• If everything within the pairing of an existing customer and the registration of a new one is done automatically, it is not necessary to use an iframe.
• (We recommend) You can provide your application settings to the client via an iframe so that they do not have to leave the Upgates administration at all, making everything more comfortable and faster for them.

How the add-on works

• Synchronize / Update button
  If you need to have a button in your add-on to download current data (for example, orders), first think about the webhook requirement. If the button really has to be included, we recommend setting it so that it cannot be used repeatedly within a few seconds. Its use must be conditioned at least so that it can only be activated after the previous download is complete +, for example, some interval.
  If changes were downloaded X seconds ago, the update button should not call the API again.
• Webhooks (documentation here)
  • Webhooks must not be bypassed by the user in your environment!
  • If you offer the customer the option of setting synchronization repeatedly, for example, in units of minutes. These time triggers must be executed on your side and check whether a notification from the webhook has arrived during this interval. It is not possible to call individual sections, for example, every minute, and bypass webhooks in this way.

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.