karrioapi / karrio Goto Github PK
View Code? Open in Web Editor NEWProgrammable Shipping API (self-hosted)
Home Page: https://karrio.io
License: Apache License 2.0
Programmable Shipping API (self-hosted)
Home Page: https://karrio.io
License: Apache License 2.0
The https://next.purplship.com/docs/carriers will need to have a link to where someone can go and get the appropriate credentials to get their carrier accounts set up on the dashboard. This is most likely a frequently asked question as well and it would be very helpful to have them in there.
Is your feature request related to a problem? Please describe.
As a privacy-first business, the Google Geocoding API may cause privacy concerns to my customers.
Describe the solution you'd like
I propose the integration possibility to use alternative solutions that are more privacy-friendly
Describe alternatives you've considered
OpenCage is mature and very accurate to handle address validations. Could be an ideal alternative to the Google Geocoding API usage
Additional context
OpenCage website https://opencagedata.com/
Pricing compared to Google Geocoding https://opencagedata.com/reducing-your-google-geocoding-costs
Is your feature request related to a problem? Please describe.
Two factor authentication is best practice and a must these days.
Describe the solution you'd like
Add 2FA support for the current user login
Is your feature request related to a problem? Please describe.
There are know convenient ways of adding or inviting a user to join an organization
Describe the solution you'd like
A set of GraphQL queries and mutations to retrieve users and invitations from an organization, send and cancel invitations.
This will allow the integration of user management from the dashboard.
Describe alternatives you've considered
Currently, the only way to add users to an organization is by adding them manually from the admin console.
Is your feature request related to a problem? Please describe.
It is currently possible to track shipments serviced by DHL Universal
. I did like to be able to the purplship SDK
fetch live rates for shipments everywhere DHL eCommerce is available and buy labels.
Is your feature request related to a problem? Please describe.
Currently, some carriers such as FedEx support multi-piece shipment whereas others (Canada post...) do not.
Describe the solution you'd like
Integrate Multi-piece support for all carriers and define a unified abstraction for future carrier integrations
Describe alternatives you've considered
Currently, I can get rates and buy labels for multi-piece shipments carriers that have built-in support and manually create multiple single parcel shipments for the rest.
Describe the bug
DHL tracking works with delivered packages without issues by raises an exception when used with undelivered packages
Ensure returned rates and other monetary values respect the following format
25
20.15
7.10
Is your feature request related to a problem? Please describe.
It is confusing as a dev getting started with the karrio API to understand how to send API requests in test mode and play with carrier sandbox/test servers.
Describe the solution you'd like
Instead of using test
flags in requests query strings to make calls in test mode, use test API keys like Stripe.
It is more explicit and more familiar.
Is your feature request related to a problem? Please describe.
Support for DHL Parcel Pologna
Documentation reference
Is your feature request related to a problem? Please describe.
Right now, there is no option to bill third-party accounts for UPS or FedEx. (Note: When billing third-party accounts, the rates of shipping cannot be pulled from carrier API so if this is implemented, the buying of shipping labels might have to be rethought.)
Describe the solution you'd like
Add feature to allow third-party billing.
Additional context
Third-party billing implementation on a similar app.
Is your feature request related to a problem? Please describe.
Missing UPS ground services for shipment
Describe the solution you'd like
Add a purplship-sdk
extension for UPS Ground or augment the current purplship.ups
integration to support UPS Ground services
Is your feature request related to a problem? Please describe.
purplship currently returns a list for tracking events from carriers with different event codes and different meanings.
Describe the solution you'd like
Define a unified tracking status across carriers that will sum up the meaning of the latest tracking event code.
Describe alternatives you've considered
Currently need to check the meaning of the tracking event code per carrier to determine when there is an issue.
Additional context
e.g. of status
delivered
in-transit
blocked
out-for-delivery
Purplship is a multi-carrier API integration SDK that brings carrier API under a unified interface.
To achieve that goal, Purplship relies on a set of components assembled to simplify the integration process.
Find any docs provided by the shipping carrier that outlines the APIs specifications.
Note that some carrier may require that you subscribe to a dev platform
The goal of this step is to come up with a set of schemas that describes what the carrier expects in terms of input and output.
The shipping carriers APIs come in these variant formats:
XML
based APIWhen you are dealing with WSDL files, extract the all <xs:schema>...<xs:schema>
blocks located under the <wsdl:types>...</wsdl:types>
block into .xsd
files.
Note that you will need to copy the namespaces definitions from <wsdl:definitions ...>
header to <xs:schema ...>
We will also help you validate your schemas when you submit a PR below
Example:
The resulting
.xsd
schema file looks like this:
If the carrier provides .xsd
files, you have literally nothing to do. That's good news, download them and move to the next step.
Collect all XML samples for each request and response you want to integrate and use a platform like the freeformatter xsd-generator to generate .xsd
schema files from the various samples.
Generating schemas from XML sample
JSON
based APIOnce you have the set of APIs schemas you want to support, it's time to transform them into Python classes.
.json
schema files into Python classesGenerating Python code with
quicktype.io
.xsd
schema files input Python classesGenerating Python code with
generateDs
Then
carrier
by the name of the actual carrier you are integratingAfter those things are ready, the integration process is fairly straight forward expressing service request
in Python code.
Is your feature request related to a problem? Please describe.
Sometimes, I know exactly the carrier service I am interested in and since we know the costs in advance,
we want to be able to buy labels with a single API request
Describe the solution you'd like
It would be nice and simple to make a call to POST /v1/shipments
with a carrier service_code
to buy a label
in a single request.
Describe alternatives you've considered
Currently, I need to make a request to create an empty shipment then send a second call to buy it.
Is your feature request related to a problem? Please describe.
karrio currently doesn't support Stamps services. Some users uses Stamps to purchase USPS label because of negotiated rates with stamps.
Describe the solution you'd like
Integrate karrio with Stamps API
Additional context
Stamps API Documentation
Obtain API Keys
Is your feature request related to a problem? Please describe.
It is currently possible to track shipments serviced by Deutsche Post using the DHL Universal integration. I did like to be able to the purplship SDK fetch live rates for shipments within Germany and internationally and buy labels.
Is your feature request related to a problem? Please describe.
karrio currently doesn't support AmazonMws services
Describe the solution you'd like
Integrate karrio with the AmazonMws API
Additional context
AmazonMws API documentation links:
Is your feature request related to a problem? Please describe.
There are no ways to personalize Karrio with preferences such as default dimension units and such.
Describe the solution you'd like
Allow the user to configure preferences and improve their experience,
Is your feature request related to a problem? Please describe.
International carriers return monetary values in the currency of the shipment origin or default to USD and that can lead to inconsistencies
Describe the solution you'd like
It would be great to have a way of configuring preferred currency per system or per organization. So that returned monetary values are consistent for a user.
Is your feature request related to a problem? Please describe.
There is currently no endpoint available to collect the health status of the Purplship API.
That can be a limitation for deployment on certain cloud platforms that require a health check endpoint to ensure the successful deployment of a purplship server instance.
Describe the solution you'd like
An API endpoint displaying the server status:
Describe alternatives you've considered
As a workaround, /login/
page could be used for health check until then
Is your feature request related to a problem? Please describe.
It is currently possible to track shipment serviced by Australia Post
. I did like to be able to the purplship SDK
fetch live rates for shipments within Australia and buy labels.
Is your feature request related to a problem? Please describe.
Karrio current FedEx support is integrated with the Web Service (https://www.fedex.com/en-us/developer.html).
This issue is to plan an upgrade to the new FedEx JSON API (https://developer.fedex.com/api/en-us/home.html)
Is your feature request related to a problem? Please describe.
It is currently possible to track shipment serviced by Aramex
. I did like to be able to the purplship SDK
fetch live rates for shipments and buy labels.
Describe the bug
Some requirements such as Charfield max size or formating are not validated upfront on the API.
The consequence is that one might pass the validation to create a shipment with let's say an organization name of more than 50 characters get rates and only fail to persist the data due to a failed model validation.
This can put the server in an invalid state
Expected behaviour
Get API serializer requirement validations that reflect the related model's requirements.
Is your feature request related to a problem? Please describe.
I am currently unable to specify an insurance coverage value for a single specific package when I use Multi-piece shipment.
The current insurance value is applied at the shipment level instead of package. That works for single package shipments only.
Describe the solution you'd like
In fact, it seems that insurance should be completely moved from the shipment to the package instead.
Is your feature request related to a problem? Please describe.
Integrate a way to import multiple orders at once into purplship-server for fulfillment.
This will allow batch processing (meaning a large volume of shipment processed at once)
Describe the solution you'd like
I did like to be able to export orders from my platform (ERP, marketplace, eCommerce...) in a CSV file and import them in purplship for fulfilment.
Describe the bug
Bug where package.weight.map(MeasurementOptions).KG would round down to 0 when making a conversion to kg failing Canada post rate request
To Reproduce
Steps to reproduce the behavior:
Make a Canada post rate request with a smaller weight than 0.1 kg.
fix
Change providers.canadapost.units:
MeasurementOptions = MeasurementOptionsType(quant=0.01, min_kg=0.01)
I have a fix on a branch but I'm not allowed to make de pull request.
Describe the bug
I followed the installation steps from here: https://docs.karrio.io/installation, but the server throws the following exception ImportError: Could not import 'karrio.server.core.authentication.TokenBasicAuthentication' for API setting 'DEFAULT_AUTHENTICATION_CLASSES'. ModuleNotFoundError: No module named 'yaml'.
To Reproduce
Steps to reproduce the behavior:
.env
file with these valuesDEBUG_MODE=True
ALLOWED_HOSTS=*
DATABASE_HOST=db
DATABASE_PORT=5432
DATABASE_NAME=db
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=postgres
DETACHED_WORKER=False
docker-compose.yml
fileversion: '3'
services:
karrio:
container_name: karrio
image: karrio/server:2022.6
restart: unless-stopped
ports:
- "5002:5002"
env_file: .env
depends_on:
- db
networks:
- db_network
- web_network
volumes:
- karriostatics:/karrio/static
dashboard:
container_name: dashboard
image: karrio/dashboard:2022.6
ports:
- "3000:3000"
environment:
- 'NEXT_PUBLIC_KARRIO_API_URL=http://host.docker.internal:5002'
- 'NEXTAUTH_URL=http://host.docker.internal:3000'
- JWT_SECRET="n*s-ex6@ex_r1i%bk=3jd)p+lsick5bi*90!mbk7rc3iy_op1r"
networks:
- web_network
db:
container_name: db
image: postgres
restart: unless-stopped
environment:
POSTGRES_DB: "db"
POSTGRES_USER: "postgres"
POSTGRES_PASSWORD: "postgres"
PGDATA: /var/lib/postgresql/data/sandbox
networks:
- db_network
volumes:
karriostatics:
karrio-db:
networks:
db_network:
web_network:
docker-compose up
Entire log
karrio | Traceback (most recent call last):
karrio | File "/karrio/venv/lib/python3.8/site-packages/rest_framework/settings.py", line 177, in import_from_string
karrio | return import_string(val)
karrio | File "/karrio/venv/lib/python3.8/site-packages/django/utils/module_loading.py", line 17, in import_string
karrio | module = import_module(module_path)
karrio | File "/usr/local/lib/python3.8/importlib/__init__.py", line 127, in import_module
karrio | return _bootstrap._gcd_import(name[level:], package, level)
karrio | File "<frozen importlib._bootstrap>", line 1014, in _gcd_import
karrio | File "<frozen importlib._bootstrap>", line 991, in _find_and_load
karrio | File "<frozen importlib._bootstrap>", line 975, in _find_and_load_unlocked
karrio | File "<frozen importlib._bootstrap>", line 671, in _load_unlocked
karrio | File "<frozen importlib._bootstrap_external>", line 843, in exec_module
karrio | File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
karrio | File "/karrio/venv/lib/python3.8/site-packages/karrio/server/core/authentication.py", line 1, in <module>
karrio | import yaml
karrio | ModuleNotFoundError: No module named 'yaml'
karrio |
karrio | During handling of the above exception, another exception occurred:
karrio |
karrio | Traceback (most recent call last):
karrio | File "/karrio/venv/bin/karrio", line 8, in <module>
karrio | sys.exit(main())
karrio | File "/karrio/venv/lib/python3.8/site-packages/karrio/server/__main__.py", line 17, in main
karrio | execute_from_command_line(sys.argv)
karrio | File "/karrio/venv/lib/python3.8/site-packages/django/core/management/__init__.py", line 419, in execute_from_command_line
karrio | utility.execute()
karrio | File "/karrio/venv/lib/python3.8/site-packages/django/core/management/__init__.py", line 395, in execute
karrio | django.setup()
karrio | File "/karrio/venv/lib/python3.8/site-packages/django/__init__.py", line 24, in setup
karrio | apps.populate(settings.INSTALLED_APPS)
karrio | File "/karrio/venv/lib/python3.8/site-packages/django/apps/registry.py", line 114, in populate
karrio | app_config.import_models()
karrio | File "/karrio/venv/lib/python3.8/site-packages/django/apps/config.py", line 301, in import_models
karrio | self.models_module = import_module(models_module_name)
karrio | File "/usr/local/lib/python3.8/importlib/__init__.py", line 127, in import_module
karrio | return _bootstrap._gcd_import(name[level:], package, level)
karrio | File "<frozen importlib._bootstrap>", line 1014, in _gcd_import
karrio | File "<frozen importlib._bootstrap>", line 991, in _find_and_load
karrio | File "<frozen importlib._bootstrap>", line 975, in _find_and_load_unlocked
karrio | File "<frozen importlib._bootstrap>", line 671, in _load_unlocked
karrio | File "<frozen importlib._bootstrap_external>", line 843, in exec_module
karrio | File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
karrio | File "/karrio/venv/lib/python3.8/site-packages/karrio/server/graph/models.py", line 5, in <module>
karrio | from karrio.server.manager.models import Customs, Parcel, Address
karrio | File "/karrio/venv/lib/python3.8/site-packages/karrio/server/manager/models.py", line 8, in <module>
karrio | from karrio.server.core.utils import identity
karrio | File "/karrio/venv/lib/python3.8/site-packages/karrio/server/core/utils.py", line 14, in <module>
karrio | from karrio.server.core import datatypes, serializers
karrio | File "/karrio/venv/lib/python3.8/site-packages/karrio/server/core/serializers.py", line 2, in <module>
karrio | from drf_yasg import openapi
karrio | File "/karrio/venv/lib/python3.8/site-packages/drf_yasg/openapi.py", line 11, in <module>
karrio | from .utils import dict_has_ordered_keys, filter_none, force_real_str
karrio | File "/karrio/venv/lib/python3.8/site-packages/drf_yasg/utils.py", line 17, in <module>
karrio | from rest_framework.views import APIView
karrio | File "/karrio/venv/lib/python3.8/site-packages/rest_framework/views.py", line 17, in <module>
karrio | from rest_framework.schemas import DefaultSchema
karrio | File "/karrio/venv/lib/python3.8/site-packages/rest_framework/schemas/__init__.py", line 33, in <module>
karrio | authentication_classes=api_settings.DEFAULT_AUTHENTICATION_CLASSES,
karrio | File "/karrio/venv/lib/python3.8/site-packages/rest_framework/settings.py", line 225, in __getattr__
karrio | val = perform_import(val, attr)
karrio | File "/karrio/venv/lib/python3.8/site-packages/rest_framework/settings.py", line 168, in perform_import
karrio | return [import_from_string(item, setting_name) for item in val]
karrio | File "/karrio/venv/lib/python3.8/site-packages/rest_framework/settings.py", line 168, in <listcomp>
karrio | return [import_from_string(item, setting_name) for item in val]
karrio | File "/karrio/venv/lib/python3.8/site-packages/rest_framework/settings.py", line 180, in import_from_string
karrio | raise ImportError(msg)
karrio | ImportError: Could not import 'karrio.server.core.authentication.TokenBasicAuthentication' for API setting 'DEFAULT_AUTHENTICATION_CLASSES'. ModuleNotFoundError: No module named 'yaml'.
karrio exited with code 1
Currently, the tracking event contains a single key for the location information on each event.
{
... tracking details
"events": [
{
"date": "string",
"description": "string",
"location": "string",
"code": "string",
"time": "string"
}
],
... deliver details
}
]
}
This will need to be a separate object to have more information about the location of the event.
{
... tracking details
"events": [
{
"date": "string",
"description": "string",
"location": {
"city": "string",
"state": "string",
"zipcode": "string",
"country": "string",
"geocoding": {
"latitude": "string",
"longitude": "string",
}
},
"code": "string",
"time": "string"
}
],
... deliver details
}
]
}
The geocoding object can be done through either open-source integrations with geonames.org or through proprietary integrations like Google Geocoding or Maxmind databases. Based on how it is hosted.
Is your feature request related to a problem? Please describe.
It is currently possible to track shipment serviced by Sendle
. I did like to be able to the purplship SDK
fetch live rates for shipments within Australia and buy labels.
Hello,
I apologize if this is answered elsewhere, I did made a search but I may have overlooked it. I am new to purplship
and also still trying to understand the concepts behind shipping API's.
Is your feature request related to a problem? Please describe.
I wonder if the upload of trade documents is supported by the purplship
package. I could find no reference in the documentation.
Describe the solution you'd like
I am looking for a implementation of what it is described here:
https://developertest.fedex.com/api/en-nl/catalog/upload-documents/v1/docs.html
Thank you for all the efforts put in this package!!! I do know how much time it takes...
Update by @danh91: You can now get your carrier integrations prioritized and added by sponsoring (you or your company) the development and maintenance of the extensions.
Is your feature request related to a problem? Please describe.
Karrio current DHL Express support is integrated with the XML-Pi (https://xmlportal.dhl.com/news).
This issue is to plan an upgrade to the new DHL REST API (https://developer.dhl.com/api-reference/dhl-express-mydhl-api#get-started-section/)
Is your feature request related to a problem? Please describe.
Currently, the webhook sends a request that can be impersonated without any distinctive authentication or signature.
That is not a good practice.
Describe the solution you'd like
We should have a header that ensures the authenticity of the event origin similar to Stripe secret header
Describe alternatives you've considered
It is currently possible to use a query string to do something like that is not the most secure.
Additional context
https://stripe.com/docs/webhooks/signatures
Is your feature request related to a problem? Please describe.
Though Karrio offers the possibility to forward any options offered by shipping carrier APIs,
some common options are nice to interact with when they are added to the standardized common Karrio shipping options.
Currently, "hold at location" is not standardized
Describe the solution you'd like
Add support for "hold at location" to the unified Karrio shipping option.
Is your feature request related to a problem? Please describe.
karrio currently doesn't support Asendia US services
Describe the solution you'd like
Integrate karrio with the Asendia US API
Additional context
Asendia US API documentation links:
Describe the bug
Creating order in test mode prevents the use of the same order_id
in live
To Reproduce
Steps to reproduce the behavior:
Expected behavior
I would expect the validation to apply on a specific mode only.
Meaning one should be allowed to create an order in test_mode and reuse the same order_number in live mode.
The times reported in a TrackingEvent from Purolator seem to be incorrectly parsed as seconds instead of the HHMMSS format Purolator weirdly uses.
This is the debug output to console for the tracking number I am testing with (note the <ScanTime>100625</ScanTime>
):
<Scan i:type="DeliveryScan">
<ScanType>Delivery</ScanType>
<PIN>
<Value>607460066279</Value>
</PIN>
<Depot>
<Name>130 IBER RD, STITTSVILLE, ON, K2S1E9</Name>
</Depot>
<ScanDate>2021-01-25</ScanDate>
<ScanTime>100625</ScanTime>
<Description>Shipment delivered</Description>
<Comment/>
<SummaryScanIndicator>false</SummaryScanIndicator>
<ScanDetails>
<DeliverySignature>LYY</DeliverySignature>
<SignatureImage/>
<SignatureImageSize>0</SignatureImageSize>
<SignatureImageFormat>GIF</SignatureImageFormat>
<DeliveryAddress>STITTSVILLE, ON</DeliveryAddress>
<DeliveryCompanyName/>
<PremiumServiceText>Not known or specified</PremiumServiceText>
<ProductTypeText>Regular</ProductTypeText>
<SpecialHandlingText/>
<PaymentTypeText>Sender</PaymentTypeText>
</ScanDetails>
</Scan>
And here is the TrackingEvent
object that is returned (note the time='03:57'
:
TrackingEvent(date='2021-01-25', description='Shipment delivered', location='130 IBER RD, STITTSVILLE, ON, K2S1E9', code='Delivery', time='03:57')
And here is what the Purolator website shows:
I poked around in the code, and it seems like it may be treating 100625
as seconds instead of HHMMSS?
Hi,
Can i integrate purplship for custom Local Courier service additional to standard built in ones in purplship ?
Is your feature request related to a problem? Please describe.
I believe the ability to generate shipping manifests for large volume processing is very important
Describe the solution you'd like
Add support for shipping manifest generation for supported carriers and a multi-carrier option from Karrio would be very valuable.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.