WIP Freightcom new REST API

[jacobshilitz]

Freightcom announced they're migrating to a new REST API, their current xml api will be retiring in March

I've been working on implementing the new REST API for Freightcom. The changes and enhancements have been made in line with the API provided in the Freightcom developer documentation. Here's the link for your reference: Freightcom API documentation
Please note that this is still a draft and not the final version of the code. Posting so that you can review when you have a moment and share your thoughts.

The challenges I still face are:

1. We need to pass a payment key when transmitting a shipment, so we need to aggregate it from the API and pass with each shipment, i'm not sure how we should go about it, option one is call the endpoint to get payment keys when the config page loads and display a dropdown, this option will not allow for per shipment basis, it will also error out if there has been a change in the profile, option 2 would be to always automatically select "terms".
2. I have not written any tests yet.
3. Freightcom tracking isn't implemented, but perhaps it is redundant by native trackings, if we do go ahead with freightcom tracking we will have to figure out how to do it because they use shipment-id in place of tracking# for tracking so the flow will be different than the rest of the carriers.
4. Need to review the flow for rate requests, they have an API to create the rate and then we need to call a separate api to pull the rates, it loads dynamically and the api responds with ready when done, so i'm not sure how to properly confirm that we have all rates, i've done a basic implementation but perhaps there's something more cool or standard.
5. WIP Pickups API
6. WIP Commercial invoicing

[jacobshilitz]

@danh91 can you review and let me know thought and adjustments?

[danh91]

Hi @jacobshilitz, I will be able to review it today.
Thanks for the detailed explanation

[jacobshilitz]

kind reminder

[jacobshilitz]

1. We need to pass a payment key when transmitting a shipment, so we need to aggregate it from the API and pass with each shipment, i'm not sure how we should go about it, option one is call the endpoint to get payment keys when the config page loads and display a dropdown, this option will not allow for per shipment basis, it will also error out if there has been a change in the profile, option 2 would be to always automatically select "terms".

I setup for now it should require the manual input of payment id in the settings, is there anyway we can populate a dropdown, the problem is that it need to save the api key first only then you can authenticate? i'll look if they have a place in the interface to get the payment ids

[jacobshilitz]

Dear Freightcom API Customer,

Please note that the legacy version of the Freightcom API will no longer be supported as of March 31st, 2025.

We request that you begin the process of switching to the most recent and updated Freightcom API, which has been available for the last 18 months.

With the new Freightcom API you gain access to more functionality, faster response times, superior uptime, all while future proofing your integration for upcoming feature and service releases.

[minchaminder]

@danh91 got a chance to review?

[danh91]

@danh91 got a chance to review?

Hi @minchaminder ,
I will certainly be able to review it tomorrow.

[danh91]

I have added a couple of comments to help with some changes recommendation.
Let me know if you have a question particularly related to passing the payment_method_id around

[danh91]

@jacobshilitz ,
Did you get a chance to update the unit tests as well?
Let me know what else is missing or unresolved.
I will check out your branch to help with testing once you have running unit tests so we can close this.

[jacobshilitz]

@jacobshilitz , Did you get a chance to update the unit tests as well? Let me know what else is missing or unresolved. I will check out your branch to help with testing once you have running unit tests so we can close this.

Yes, I tried my best to implument the unit tests...

[jacobshilitz]

I'm not sure how to set payment_method_type here. now that's it's a connection_config (maybe we should go back and have it as a normal setting)

tracking is not working yet... its comlicated as ferightcom has its own tracking API, only the real tracking of the carrier

[danh91]

I'm not sure how to set payment_method_type here. now that's it's a connection_config (maybe we should go back and have it as a normal setting)

tracking is not working yet... its comlicated as ferightcom has its own tracking API, only the real tracking of the carrier

payment_method_type can be set on the settings config object like https://github.com/jacobshilitz/karrio/blob/4cbd25689ef0c778d01182cfb00296d52dcbfe1d/modules/connectors/asendia_us/tests/asendia_us/fixture.py#L9-L11

Tracking is indeed tricky when dealing with hubs. Here is an example with EasyPost

https://github.com/jacobshilitz/karrio/blob/4cbd25689ef0c778d01182cfb00296d52dcbfe1d/modules/connectors/easypost/karrio/providers/easypost/tracking.py#L82-L117

https://github.com/jacobshilitz/karrio/blob/4cbd25689ef0c778d01182cfb00296d52dcbfe1d/modules/connectors/easypost/karrio/mappers/easypost/proxy.py#L63-L83

The general idea is that if they are already tracking the shipment, you want to retrieve the tracking information they have by using the shipment_id or any tracking ID that they returned when you created the label.
Otherwise, use the tracking_number and the carrier saved in shipment.meta when the label was created to make a request

[jacobshilitz]

The general idea is that if they are already tracking the shipment, you want to retrieve the tracking information they have by using the shipment_id or any tracking ID that they returned when you created the label.
Otherwise, use the tracking_number and the carrier saved in shipment.meta when the label was created to make a request

I'm bracking my head as freightcom is requiring the shipment_id that I store in shipment_identifier, any ideas how to retrive it? in easyship it seems you send the actual tracking ID

[danh91]

The general idea is that if they are already tracking the shipment, you want to retrieve the tracking information they have by using the shipment_id or any tracking ID that they returned when you created the label.

Otherwise, use the tracking_number and the carrier saved in shipment.meta when the label was created to make a request

I'm bracking my head as freightcom is requiring the shipment_id that I store in shipment_identifier, any ideas how to retrive it? in easyship it seems you send the actual tracking ID

You can store it in meta as 'freightcom_shipment_identifier'

When the request for the Tracking is sent, the meta content gets added to tracking_request.options.freightcom_shipment_identifier

So the trick is that you can add anything that you might need later that is specific to your integration inside meta when you are parsing shipment and rates responses

[jacobshilitz]

one more thing how do I trigger a tracking fetch for the api? tests are not a real api call

[danh91]

one more thing how do I trigger a tracking fetch for the api? tests are not a real api call

Using the API you can call the it like this:

POST /v1/proxy/tracking?hub=freightcom

When you create a shipment it will automatically append the hub to the tracking url

[jacobshilitz]

When you create a shipment it will automatically append the hub to the tracking url

I only get the canpar "tracking_url": "/v1/trackers/canpar/D999999990000322579001"

I added "freightcom_shipment_identifier" to meta, and when i call the post api with your data, I get empty options()

this is the body i post in the api:

{
	"tracking_number": "trk_0603e74fe19144daad0fc4bf48256c14",
	"carrier_name": "canpar",
	"metadata": {
		"freightcom_shipment_identifier": "4RMI0rQg9dt8xuJX00p4LnuHavkGIUL4"
	}
}

[jacobshilitz]

for now lets put it to work with no tracking

[minchaminder]

@danh91 freightcom legacy API has officially shutdown as of 03/31/2025