Skip to content

docs: refresh non-mcp guides #167

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dodeja wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: refresh non-mcp guides #167

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 45 additions & 73 deletions docs/api-docs/getting-started/tracking-shipments-and-containers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,11 @@ og:description: Track shipments and containers with ease via Terminal49's API. O
---

## What is a Tracking Request?

Your tracking request includes two pieces of data:

- Your Bill of Lading, Booking number, or container number from the carrier.
- The SCAC code for that carrier.

<Tip>
**Don't know the SCAC?** Use the [Auto-Detect
Carrier](/api-docs/in-depth-guides/auto-detect-carrier) endpoint to
automatically identify the shipping line from your tracking number.
</Tip>

You can see a complete list of supported SCACs in row 2 of the Carrier Data Matrix.

## What sort of numbers can I track?
Expand All @@ -28,7 +21,7 @@ You can see a complete list of supported SCACs in row 2 of the Carrier Data Matr
2. Booking number from the carrier
3. Container number

- Container number tracking support across ocean carriers is sometimes more limited. Please refer to the Carrier Data Matrix to see which SCACs are compatible with Container number tracking.
* Container number tracking support across ocean carriers is sometimes more limited. Please refer to the Carrier Data Matrix to see which SCACs are compatible with Container number tracking.

**Unsupported numbers**

Expand All @@ -38,7 +31,6 @@ You can see a complete list of supported SCACs in row 2 of the Carrier Data Matr
- Internally generated numbers, for example PO numbers or customer reference numbers.

## How do I use Tracking Requests?

Terminal49 is an event-based API, which means that the API can be used asynchronously. In general the data flow is:

1. You send a tracking request to the API with your Bill of Lading number and SCAC.
Expand All @@ -48,7 +40,6 @@ Terminal49 is an event-based API, which means that the API can be used asynchron
5. At any time, you can directly request a list of shipments and containers from Terminal49, and the API will return current statuses and information. This is covered in a different guide.

## How do you send me the data relating to the tracking request?

You have two options. First, you can poll for updates. This is the way we'll show you first.

You can poll the `GET /tracking_request/{id}` endpoint to see the status of your request. You just need to track the ID of your tracking request, which is returned to you by the API.
Expand All @@ -61,28 +52,25 @@ When we successfully lookup the Bill of Lading with the Carrier's SCAC, we will

If we encounter a problem we'll send the event `tracking_request.failed`.

<Frame caption="Tracking Request Diagram">
![](/images/create-shipment-flow.png)
</Frame>
<Frame caption="Tracking Request Diagram">![Tracking request flow diagram](/images/create-shipment-flow.png)</Frame>

## Authentication

## Authentication
The API uses Bearer Token style authentication. This means you send your API Key as your token in every request.

To get your API token to Terminal49 and go to your [account API settings](https://app.terminal49.com/settings/api)

The token should be sent with each API request in the Authentication header:

Support [dev@terminal49.com](dev@terminal49.com)
Support: dev@terminal49.com

```
Authorization: Token YOUR_API_KEY
```

## How to Create a Tracking Request

Here is javascript code that demonstates sending a tracking request

Here is javascript code that demonstrates sending a tracking request
```json
fetch("https://api.terminal49.com/v2/tracking_requests", {
"method": "POST",
Expand All @@ -108,94 +96,83 @@ fetch("https://api.terminal49.com/v2/tracking_requests", {
console.error(err);
});
```

## Anatomy of a Tracking Request Response

Here's what you'll see in a Response to a tracking request.

```json
{
"data": {
"id": "478cd7c4-a603-4bdf-84d5-3341c37c43a3",
"type": "tracking_request",
"attributes": {
"request_number": "xxxxxx",
"request_type": "bill_of_lading",
"scac": "MAEU",
"ref_numbers": [],
"created_at": "2020-09-17T16:13:30Z",
"updated_at": "2020-09-17T17:13:30Z",
"status": "pending",
"failed_reason": null,
"is_retrying": false,
"retry_count": null
},
"relationships": {
"tracked_object": {
"data": null
}
},
"links": {
"self": "/v2/tracking_requests/478cd7c4-a603-4bdf-84d5-3341c37c43a3"
"data": {
"id": "478cd7c4-a603-4bdf-84d5-3341c37c43a3",
"type": "tracking_request",
"attributes": {
"request_number": "xxxxxx",
"request_type": "bill_of_lading",
"scac": "MAEU",
"ref_numbers": [],
"created_at": "2020-09-17T16:13:30Z",
"updated_at": "2020-09-17T17:13:30Z",
"status": "pending",
"failed_reason": null,
"is_retrying": false,
"retry_count": null
},
"relationships": {
"tracked_object": {
"data": null
}
},
"links": {
"self": "/v2/tracking_requests/478cd7c4-a603-4bdf-84d5-3341c37c43a3"
}
}
}
}
```

Note that if you try to track the same shipment, you will receive an error like this:

```json
{
"errors": [
{
"status": "422",
"source": {
"pointer": "/data/attributes/request_number"
},
"title": "Unprocessable Entity",
"detail": "Request number 'xxxxxxx' with scac 'MAEU' already exists in a tracking_request with a pending or created status",
"code": "duplicate"
}
]
"errors": [
{
"status": "422",
"source": {
"pointer": "/data/attributes/request_number"
},
"title": "Unprocessable Entity",
"detail": "Request number 'xxxxxxx' with scac 'MAEU' already exists in a tracking_request with a pending or created status",
"code": "duplicate"
}
]
}
```

<Info>
**Why so much JSON? (A note on JSON API)**

The Terminal49 API is JSON API compliant, which means that there are nifty libraries which can translate JSON into a fully fledged object model that can be used with an ORM. This is very powerful, but it also requires a larger, more structured payload to power the framework. The tradeoff, therefore, is that it's less convenient if you're parsing the JSON directly. Ultimately we strongly recommend you set yourself up with a good library to use JSON API to its fullest extent. But for the purposes of understanding the API's fundamentals and getting your feet wet, we'll work with the data directly.

The Terminal49 API is JSON API compliant, which means that there are nifty libraries which can translate JSON into a fully fledged object model that can be used with an ORM. This is very powerful, but it also requires a larger, more structured payload to power the framework. The tradeoff, therefore, is that it's less convenient if you're parsing the JSON directly. Ultimately we strongly recommend you set yourself up with a good library to use JSON API to its fullest extent. But for the purposes of understanding the APIs fundamentals and getting your feet wet, we'll work with the data directly.
</Info>

## Try It: Make a Tracking Request

Try it using the request maker below!

1. Enter your API token in the autorization header value.
2. Enter a value for the `request_number` and `scac`. The request number has to be a shipping line booking or master bill of lading number. The SCAC has to be a shipping line scac (see data sources to get a list of valid SCACs)

Note that you can also access sample code in multiple languages by clicking the "Code Generation" below.

<Warning>
**Tracking Request Troubleshooting**

The most common issue people encounter is that they are entering the wrong number.

Please check that you are entering the Bill of Lading number, booking number, or container number and not internal reference at your company or by your frieght forwarder. You can the number you are supplying by going to a carrier's website and using their tools to track your shipment using the request number. If this works, and if the SCAC is supported by T49, you should able to track it with us.

If you're unsure of the correct SCAC, try the [Auto-Detect Carrier](/api-docs/api-reference/tracking-requests/auto-detect-carrier) endpoint first.
Please check that you are entering the Bill of Lading number, booking number, or container number and not internal reference at your company or by your freight forwarder. You can the number you are supplying by going to a carrier's website and using their tools to track your shipment using the request number. If this works, and if the SCAC is supported by T49, you should able to track it with us.

It is entirely possible that's neither us nor you but the shipping line is giving us a headache. Temporary network problems, not populated manifest and other things happen! You can read on how are we handling them in the [Tracking Request Retrying](/api-docs/useful-info/tracking-request-retrying) section.

</Warning>

<Info>
Rate limiting: You can create up to 100 tracking requests per minute.
Rate limiting: You can create up to 100 tracking requests per minute.
</Info>

<Info>
You can always email us at support@terminal49.com if you have persistent
issues.
You can always email us at support@terminal49.com if you have persistent issues.
</Info>

```json
Expand All @@ -211,8 +188,7 @@ It is entirely possible that's neither us nor you but the shipping line is givin
```

## Try It: List Your Active Tracking Requests

We have not yet set up a webook to receive status updates from the Terminal49 API, so we will need to manually poll to check if the Tracking Request has succeeded or failed.
We have not yet set up a webhook to receive status updates from the Terminal49 API, so we will need to manually poll to check if the Tracking Request has succeeded or failed.

**Try it below. Click "Headers" and replace `<YOUR_API_KEY>` with your API key.**

Expand All @@ -226,13 +202,9 @@ We have not yet set up a webook to receive status updates from the Terminal49 AP
}
}
```

## Next Up: Get your Shipments

Now that you've made a tracking request, let's see how you can list your shipments and retrieve the relevant data.

<Info>
Go to this
[page](https://help.terminal49.com/en/articles/8074102-how-to-initiate-shipment-tracking-on-terminal49)
to see different ways of initiating shipment tracking on Terminal49.
Go to this [page](https://help.terminal49.com/en/articles/8074102-how-to-initiate-shipment-tracking-on-terminal49) to see different ways of initiating shipment tracking on Terminal49.
</Info>
3 changes: 1 addition & 2 deletions docs/api-docs/in-depth-guides/including-resources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Including Resources
---
Throughout the documentation you will notice that many of the endpoints include a `relationships` object inside of the `data` attribute.

For example, if you are [requesting a container](/api/4c6091811c4e0-get-a-container) the relationships will include `shipment`, and possibly `pod_terminal` and `transport_events`
For example, if you are requesting a container (see containers API reference in this site) the relationships will include `shipment`, and possibly `pod_terminal` and `transport_events`

If you want to load the `shipment` and `pod_terminal` without making any additional requests you can add the query parameter `include` and provide a comma delimited list of the related resources:
```
Expand All @@ -14,4 +14,3 @@ You can even traverse the relationships up or down. For example if you wanted to
```
containers/{id}?include=shipment,shipment.port_of_lading
```

19 changes: 8 additions & 11 deletions docs/api-docs/in-depth-guides/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,6 @@ You'll need a four things to get started.
3. **A Terminal49 Account.** If you don't have one yet, [sign up here.](https://app.terminal49.com/register)
4. **An API key.** Sign in to your Terminal49 account and go to your [developer portal page](https://app.terminal49.com/developers) to get your API key.

<Tip>
Not sure which SCAC to use? The [Auto-Detect
Carrier](/api-docs/in-depth-guides/auto-detect-carrier) API can identify it
from your tracking number.
</Tip>

## Track a Shipment

You can try this using the embedded request maker below, or using Postman.
Expand All @@ -42,18 +36,20 @@ Note that you can also access sample code, include a cURL template, by clicking

## Check Your Tracking Request Succeeded

We have not yet set up a webook to receive status updates from the Terminal49 API, so we will need to manually poll to check if the Tracking Request has succeeded or failed.
We have not yet set up a webhook to receive status updates from the Terminal49 API, so we will need to manually poll to check if the Tracking Request has succeeded or failed.



> ### Tracking Request Troubleshooting
> The most common issue people encounter is that they are entering the wrong number.
>
> The most common issue people encounter is that they are entering the wrong number.
>
> Please check that you are entering the Bill of Lading number, booking number, or container number and not internal reference at your company or by your frieght forwarder. You can the number you are supplying by going to a carrier's website and using their tools to track your shipment using the request number. If this works, and if the SCAC is supported by T49, you should able to track it with us.
> Please check that you are entering the Bill of Lading number, booking number, or container number and not internal reference at your company or by your freight forwarder. You can the number you are supplying by going to a carrier's website and using their tools to track your shipment using the request number. If this works, and if the SCAC is supported by T49, you should able to track it with us.
>
> You can always email us at support@terminal49.com if you have persistent issues.

** Try it below. Click "Headers" and replace `<YOUR_API_KEY>` with your API key.**


```json http
{
"method": "get",
Expand Down Expand Up @@ -103,6 +99,7 @@ Try it after replacing `<YOUR_API_KEY>` with your API key.
}
```


## Listening for Updates with Webhooks

The true power of Terminal49's API is that it is asynchronous. You can register a Webhook, which is essentially a callback URL that our systems HTTP Post to when there are updates.
Expand All @@ -125,4 +122,4 @@ View the "Code Generation" button to see sample code.
},
"body": "{\r\n \"data\": {\r\n \"type\": \"webhook\",\r\n \"attributes\": {\r\n \"url\": \"https:\/\/webhook.site\/\",\r\n \"active\": true,\r\n \"events\": [\r\n \"*\"\r\n ]\r\n }\r\n }\r\n}"
}
```
```
4 changes: 2 additions & 2 deletions docs/api-docs/in-depth-guides/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ You may subscribe to events through webhooks to be alerted when events are trigg

Visit https://app.terminal49.com/developers/webhooks and click the 'Create Webhook Endpoint' button to create your webhook through the UI.

If you prefer to create webhooks programatically then see the [webhooks post endpoint documentation](/api-docs/api-reference/webhooks/create-a-webhook).
If you prefer to create webhooks programmatically then see the [webhooks post endpoint documentation](/api-docs/api-reference/webhooks/create-a-webhook).


## Available Webook Events
## Available Webhook Events

Each `WebhookNotification` event represents some change to a model which you may be notified of.

Expand Down
Loading