Request your API KEY
API ROOT
https://api.smartports.app/
You can request your API KEY from the your profile page. Log into your account and click on the top right corner on your profile to retrieve your secret API KEY.
To use this API, you need an API key. Please contact us at [email protected] if you run into any trouble with your KEY.
Demurrage Insurance
# Here is a curl example
curl \
-X POST https://api.smartports.app/insurance/sea-demurrages \
-H "Content-Type: application/json" \
-d '{
"apiKey": "your_api_key",
"items": [
{
"houseBL": "string",
"masterBL": "string",
"certificateId": 1,
"insurerCode": "123456",
"insurerName": "SEA CARGO LOGISTICS SA",
"rfcId": "RFC SCL090414QE0",
"arrivalEta": "2025-02-10T19:36:49Z",
"departureEtd": "2024-12-29T19:36:49Z",
"consigneeCode": "123456",
"consigneeName": "SEA CARGO LOGISTICS SA",
"freeDays": 21,
"remarks": "IMGDL18587,IMGDL18588",
"vesselVoyage": "ERAMUS CHIEF / ZRM C0452N",
"createdAt": "2025-02-28T17:27:36Z",
"status": "REC",
"originPort": "VIETNAM",
"destinationPort": "MEXICO"
},
{
"houseBL": "string",
"masterBL": "string",
"certificateId": 3,
"insurerCode": "123456",
"insurerName": "SEA CARGO LOGISTICS SA",
"rfcId": "RFC SCL090414QE0",
"arrivalEta": "2025-02-10T19:36:49Z",
"departureEtd": "2024-12-29T19:36:49Z",
"consigneeCode": "123456",
"consigneeName": "SEA CARGO LOGISTICS SA",
"freeDays": 21,
"remarks": "IMGDL18587,IMGDL18588",
"vesselVoyage": "ERAMUS CHIEF / ZRM C0452N",
"createdAt": "2025-03-18T18:28:44Z",
"status": "REC",
"originPort": "VIETNAM",
"destinationPort": "MEXICO"
}
]
}'
Request your demurrage insurance for each of your BL's by making a POST call to the following URL and sending the parameters in the BODY as raw JSON (Content-Type: application/json):
https://api.smartports.app/insurance/sea-demurrages
Create Invoice
# Here is a curl example
curl \
-X POST https://api.smartports.app/invoices \
-H "Content-Type: application/json" \
-d '{
"api_key": "your_api_key",
"invoice": [
{
"customer": {
"legal_name": "Acme Inc.",
"email": "[email protected]",
"tax_id": "ABC101010111",
"tax_system": "601",
"address": {
"zip": "85900"
}
},
"items": [{
"quantity": 2,
"product": {
"description": "Freight",
"product_key": "60131324",
"price": 2200.00
}
}],
"payment_form": "06",
"folio_number": 914,
"series": "F"
}
]
}'
Submit your manifest data by making a POST call to the following URL and sending the parameters in the BODY as raw JSON (Content-Type: application/json):
https://api.smartports.app/invoices
QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| type | string | Required. Value: "E" |
| customer | object or string | Required. The recipient of the invoice. Either a customer object or customer_id string. |
| payment_form | string (2 characters) | Required. Code representing the payment method, according to the SAT catalog. |
| items | Array of objects (LineItem), max 5000 | Required. Line items to include in the credit note. Max 5000. Split into multiple documents if needed. |
| use | string | Optional. Default: "G01". Usage code according to the SAT CFDI catalog. |
| currency | string | Optional. Default: "MXN". Currency code as per ISO 4217 standard. |
| exchange | number | Optional. Default: 1. Exchange rate, i.e., MXN per one unit of the specified currency. |
| status | string | Optional. Default: "pending". Initial invoice status. Use "draft" to save without sending to SAT. |
| date | string (ISO8601 date-time) | Optional. Default: "now". Invoice issue date. Must be within the past 72 hours or up to the current time. |
| address | object | Optional. Issuing address of the invoice. Defaults to organization’s address if not provided. |
| external_id | string | Optional. Custom identifier for your records. Not validated for uniqueness. |
| idempotency_key | string | Optional. Unique key to prevent duplicate requests. If blank, it’s ignored. |
| folio_number | integer | Optional. Default: autoincremental. Internal control number. Auto-assigned if not provided. |
| series | string (max 25 characters) | Optional. Series identifier for internal control. Not fiscally valid. |
Transmissions - Sea (Data)
# Here is a curl example
curl \
-X POST https://api.smartports.app/transmissions/sea \
-H "Content-Type: application/json" \
-d '{
"api_key": "your_api_key",
"transmission": [
{
"customSection": "string",
"carrierKey": "string",
"vesselName": "string",
"tripNumber": "string",
"operationType": 0,
"blCount": "string",
"loadingPort": {
"name": "string",
"country": "string",
"portType": 0,
"portKey": "string",
"portCountry": "string"
},
"bl": {
"type": "H",
"referenceNumber": "string"
},
"figures": [
{
"type": 0,
"name": "string",
"fiscalId": "string",
"residence": "string"
},
{
"type": 0,
"name": "string",
"fiscalId": "string",
"residence": "string"
},
{
"type": 0,
"name": "string",
"fiscalId": "string",
"residence": "string"
}
],
"reference": "string",
"goods": [
{
"sequence": 0,
"pieceCount": 0,
"grossWeightVolume": 0,
"unit": "41",
"description": "string",
"goodsType": 0,
"packingType": 0,
"dangerousGoods": {
"classDivision": "string",
"unNumber": "string",
"contact": "string",
"name": "string"
},
"containers": [
{
"number": "string",
"type": "1",
"serviceType": "FCL",
"grossWeight": "string",
"pieceCount": 0
}
]
}
]
}
]
}'
Submit your manifest data by making a POST call to the following URL and sending the parameters in the BODY as raw JSON (Content-Type: application/json):
https://api.smartports.app/transmissions/sea
QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| customSection | string | Custom section information |
| carrierKey | string | SCAC for the carrier |
| vesselName | string | Name of the vessel |
| tripNumber | string | Trip identifier or number |
| operationType | integer | Type of operation (numeric code) |
| blCount | string | Number of Bills of Lading |
| loadingPort.name | string | Name of the loading port |
| loadingPort.country | string | Country of the loading port |
| loadingPort.portType | integer | Port type (numeric code) |
| loadingPort.portKey | string | Unique key for the port |
| loadingPort.portCountry | string | Country code for the port |
| bl.type | string | Type of Bill of Lading (e.g., H for House BL) |
| bl.referenceNumber | string | Reference number of the BL |
| figures[].type | integer | Type of figure (numeric code) |
| figures[].name | string | Name of the figure |
| figures[].fiscalId | string | Fiscal ID of the figure |
| figures[].residence | string | Residence country of the figure |
| reference | string | General reference string |
| goods[].sequence | integer | Sequence number for goods |
| goods[].pieceCount | integer | Total number of pieces |
| goods[].grossWeightVolume | float | Gross weight or volume |
| goods[].unit | string | Measurement unit (e.g., 41 for kg) |
| goods[].description | string | Description of the goods |
| goods[].goodsType | integer | Type of goods (numeric code) |
| goods[].packingType | integer | Packing type (numeric code) |
| goods[].dangerousGoods.classDivision | string | Class or division of dangerous goods |
| goods[].dangerousGoods.unNumber | string | UN number for dangerous goods |
| goods[].dangerousGoods.contact | string | Emergency contact for dangerous goods |
| goods[].dangerousGoods.name | string | Name of dangerous goods |
| goods[].containers[].number | string | Container number |
| goods[].containers[].type | string | Container type (e.g., 1) |
| goods[].containers[].serviceType | string | Service type (e.g., FCL) |
| goods[].containers[].grossWeight | string | Gross weight of the container |
| goods[].containers[].pieceCount | integer | Piece count within the container |
Transmissions - Sea (File)
# Here is a curl example
curl \
-X POST https://api.smartports.app/transmissions/sea-file \
-F 'api_key=your_api_key' \
-F 'file=@path_to_file.pdf;type=application/pdf'
Submit your transmission sea data by making a POST call to the following URL and sending the parameters in the BODY as raw JSON (Content-Type: application/json):
https://api.smartports.app/transmissions/sea-file
Transmissions - Air (Data)
# Here is a curl example
curl \
-X POST https://api.smartports.app/transmissions/air \
-H "Content-Type: application/json" \
-d '{
"api_key": "your_api_key",
"transmission_air": {
"masterGuide": "string",
"houseGuide": "string",
"caat": "string",
"carrier": "string",
"grossWeight": 0,
"pieces": 0,
"productDescription": "string",
"hazardous": "ED",
"supplementaryDescription": "string",
"originAirport": "NHI",
"destinationAirport": "BBG",
"originCurrency": "BRI",
"subjectCode": "IMP",
"shipper": {
"name": "string",
"street": "string",
"city": "string",
"country": "string"
},
"consignee": {
"name": "string",
"street": "string",
"city": "string",
"country": "string"
}
}
}'
Submit your transmission air data by making a POST call to the following URL and sending the parameters in the BODY as raw JSON (Content-Type: application/json):
https://api.smartports.app/transmissions/air
QUERY PARAMETERS
| Field | Type | Description |
|---|---|---|
| masterGuide | string | Master guide number |
| houseGuide | string | House guide number |
| caat | string | Carrier authorization or CAAT code |
| carrier | string | Carrier name or identifier |
| grossWeight | integer | Gross weight of the shipment |
| pieces | integer | Number of pieces in the shipment |
| productDescription | string | Description of the product |
| hazardous | string | Hazardous material code (e.g., ED) |
| supplementaryDescription | string | Additional description for the shipment |
| originAirport | string | Origin airport code |
| destinationAirport | string | Destination airport code |
| originCurrency | string | Currency code of the origin |
| subjectCode | string | Subject code (e.g., IMP) |
| shipper.name | string | Shipper's name |
| shipper.street | string | Shipper's street address |
| shipper.city | string | Shipper's city |
| shipper.country | string | Shipper's country |
| consignee.name | string | Consignee's name |
| consignee.street | string | Consignee's street address |
| consignee.city | string | Consignee's city |
| consignee.country | string | Consignee's country |
Transmissions - Air (File)
# Here is a curl example
curl \
-X POST https://api.smartports.app/transmissions/air-file \
-F 'api_key=your_api_key' \
-F 'file=@path_to_file.pdf;type=application/pdf'
Submit your transmission air data by making a POST call to the following URL and sending the parameters in the BODY as raw JSON (Content-Type: application/json):
https://api.smartports.app/transmissions/air-file
Errors
The Smartports API uses the following error codes:
| Error Code | Meaning |
|---|---|
| X000 | Some parameters are missing. This error appears when you don't pass every mandatory parameters. |
| X001 |
Unknown or unvalid api_key. This error appears if you use an unknow API key or if your API key expired.
|
| X002 |
Unvalid api_key for this domain. This error appears if you use an API key non specified for your domain. Developper or Universal API keys doesn't have domain checker.
|