Setup Test Environment

The goal

Integrator gets access to a sandbox to develop test and break things freely.
It also allows crating fully functional shops that sell products imported via the integration. These shops then create orders are sent to the integration at various stages.
Most importantly it provides tools to inspect every message between Katalys and the integration and also a way to retry these messages thus providing a real time feedback loop when developing the integration.

Setup a Katalys sandbox account

1. Create an account on Katalys sandbox environment

   1. https://auth.dev.katalys.com

   2. Click on Sign-Up

   3. Complete the signup (Note: Signup with Google is reserved for Katalys mails)

2. Navigate to Katalys Shops

   1. Click on the Open button in the Katalys Shop banner

3. Create an organization

   1. After the organization is created we suggest bookmarking the current page

4. Navigate to: Settings → Apps and Integrations → Stores

   1. Click add Store

   2. Click Custom integration

      1. Side note

         1. Here you can inspect how the user experience flow for existing integrations, part of rolling out a new integration is also about writing instructions for merchants to set it up

   3. Fill in the form

      1. Notice: endpoint for accepting Katalys directives

         1. This has to point to a server running your code

         2. It’s OK to put in something temporary, can be changed later

         3. In case your plugin will run on your local development machine, we suggest using a service like https://ngrok.com/ that can make your local server accessible from the outside world

   4. Click create integration.

      1. You might see an error message. This is expected if the endpoint is not running.

5. Inspect integration’s tabs

   1. API keys

      1. crucial information to talk to our GraphQL API

   2. Logs

      1. every message sent to your endpoint and received from your code will log here. So you can easily debug request and response payloads.

   3. Settings

      1. Here you change the URL location of your plugin and other basic info

6. Click on Logs tab

   1. There you’ll see a Health check button, by clicking it a request with authentication headers will be sent to the url you specified while setting up the Integration

   2. If the url is reachable and responding, you’ll see a request and response appear in the log

   3. Notice: This way you trigger a request any time you need it and inspect the result. This tool is intended to help you develop and debug the connection.

7. Done. You now have an environment in which you can manually fire a request to a URL of your choosing. Next step is to setup a server that will receive the request, authenticate it and reply properly.

Integration’s source code

1. Work with Katalys to setup a Git repository

2. Setup a project that will start a server and expose a URL endpoint

   1. Example: http://some-development.server.net/katalys/directives_endpoint

   2. In case you want to run the development server from localhost, you can use a tool like https://ngrok.com/ to make it publicly accessible

3. Put that URL into your sandbox (see above)

4. That URL endpoint will receive post messages

   1. containing authentication headers

   2. containing JSON payload in body

5. Ensure authentication headers are properly verified - Authentication

6. Parse the JSON payload which contains an array of objects called directives

7. Process each directive individually and store it’s result and return a JSON object.

Next steps: Authentication

Authentication