Need a help to setup custom carrier

[ndmallai]

I have followed the instructions however the newly added carrier is not showing the dropdown carrier list. Also, the step# 2 is not very clear to complete "i.e. Generate Python data types from the carrier API schemas". is anyone configured successfully?

[danh91]

Hi @ndmallai ,
We have an overdue task to update the full integration process.
It will be updated with more guidance next week.

In the meantime, our recommendation is to take inspiration from existing carrier integrations:
For JSON APIs, good inspirations are

• Amazon Shipping https://github.com/karrioapi/karrio/tree/main/modules/connectors/amazon_shipping
• Sendle https://github.com/karrioapi/karrio/tree/main/modules/connectors/sendle
• UPS https://github.com/karrioapi/karrio/tree/main/modules/connectors/ups

For XML APIs

• Canada Post https://github.com/karrioapi/karrio/tree/main/modules/connectors/canadapost
• Purolator https://github.com/karrioapi/karrio/tree/main/modules/connectors/purolator

The general approach is

1. Generate the plugin structure
2. Identify the API calls and collect or produce schema files like .xsd or .json files
   Once the files are ready, you can generate the Python files by running ./bin/run-generate-on modules/connectors/[extension]
3. Define the required API credentials and account settings

• First in the providers/utils.py file
• Then summarize the connection fields int mappers/settings.py

4. Next define the API calls for the services that you are integrating int mappers/proxy.py
5. Write the data mapping from Karrio models to the API requests you are trying to integrate like this rating request from Amazon Shipping https://github.com/karrioapi/karrio/blob/main/modules/connectors/amazon_shipping/karrio/providers/amazon_shipping/rate.py
6. The final stages are generally to centralize error parsing in the providers/error.py
7. Define the Django model to make the Extension accessible through the API here:
   https://github.com/karrioapi/karrio/tree/main/modules/core/karrio/server/providers/extension/models
   Here is an example https://github.com/karrioapi/karrio/blob/main/modules/core/karrio/server/providers/extension/models/canadapost.py
   You will see that the fields here are the same as the settings.py ones that you prepared at the beginning
8. To make the API configurable from the Karrio dashboard, you need:

• Add the new API GraphQL query to the others here
  This will require regenerating the Typescript types for the app using ./bin/generate-graphql-types at the root of the project
• Add the fields you need to be configured here
• And make sure that if the React components fields are missing for a field name that has never been used before, you can add them here

We try to standardize and automate the process but I understand that there is a long way to go. You will need to familiarize yourself with the existing codebase and how other carriers are integrated.
Hopefully, you can help improve the process

lastly, I always recommend creating a PR and joining the Discord channel so that we can help along the way.
The first integration will have a learning curve but the second ones will begin to look straightforward.

Let me know if you have any other questions

[ndmallai]

Thanks for your quick response. Btw, May I know the ETA of this "It will be updated with more guidance next week."

[danh91]

Hi @ndmallai ,
I added further documentation on the integration docs here https://docs.karrio.io/carriers/sdk/extension/
There is more to do and I will be updating it progressively. Please feel free to provide feedback and ask further questions.

[ndmallai]

Unable to complete the "2. Generate Python data types" step successfully. I have placed on JSON file in the schema folder.

Step 1: Run "./bin/build-tool-image" command
Step 2: Run "./bin/run-generate-on modules/connectors/delhivery"

But it is not generating the .py file in the ".\connectors[carrier_name]\karrio\schemas\delhivery" folder...

[danh91]

Hi @ndmallai,
Are there any error logs you can share?
also can you share the modules/connectors/dlhivery/generate file

Where you able to build the docker image using ./bin/build-tool-image?

[ndmallai]

your help is appriciated.

[ndmallai]

Yes. I ran the "./bin/build-tool-image" command. But not sure, how to verify whether it is successfully executed or not.

[danh91]

Can you check the docker images with

docker image ls

it should have a Karrio/tools image

[ndmallai]

No. It is not

PS C:\workspace\temp\karrio_main> docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
karrio_main-karriodev latest bd990bb02a05 2 weeks ago 418MB
karrio.docker.scarf.sh/karrio/server 2024.2.rc10 1a5549b62d9b 2 weeks ago 970MB
karrio.docker.scarf.sh/karrio/dashboard 2024.2.rc10 d78e3c628b45 2 weeks ago 1.2GB
karrio-main-karriodev latest c22bab21350e 2 months ago 418MB
karrio.docker.scarf.sh/karrio/dashboard 2024.2.rc2 59f2406bc4d4 2 months ago 2.19GB
karrio.docker.scarf.sh/karrio/server 2024.2.rc2 7c8b04a20ed5 2 months ago 968MB
karrio.docker.scarf.sh/karrio/server 2023.9.12 5246f5ebf489 3 months ago 964MB
karrio.docker.scarf.sh/karrio/dashboard 2023.9.12 5c5814ef9a6d 3 months ago 1.83GB
karrio.docker.scarf.sh/karrio/server 2023.9.4 cd5508bf9302 3 months ago 963MB
karrio.docker.scarf.sh/karrio/dashboard 2023.9.4 f81826d80781 3 months ago 1.55GB
postgres latest 391a00ec7cac 3 months ago 425MB
redis latest 76506809a39f 3 months ago 138MB
docker/welcome-to-docker latest c1f619b6477e 4 months ago 18.6MB
maildev/maildev latest 8a920dba53d6 8 months ago 199MB

---

[danh91]

Seems that’s the first issue to investigate.
Are there any logs at all when you run./bin/build-tool-image?

[ndmallai]

Ok. May I know the log file location? (i mean folder or directory name)

[danh91]

I don't think this log goes to any file.
I guess what I am curious about is what happens when you run the script in your terminal. Are there any output? errors…?

[ndmallai]

there is no error.

[danh91]

Hi @ndmallai,
It looks like you are using Windows Powershell. 🤔 correct?
If so, unfortunately, most of the scripts for the development only work on Linux, WSL or MacOS.

It won't work on Windows Powershell nor CMD 😓