SaveRates

Sends rates into the draft of a rate card, from your pricing system or a vendor’s rate sheet, without opening the page. It is one of the card’s rate feeds, with email and SFTP. Send the rates either as a file, an Excel or CSV file read as Upload a file reads it, or as lines in JSON.

TrakIT checks every line first, and writes them into the draft only when all of them are right; if one has a problem, nothing is written. The rates are not in use until someone publishes the draft on the card’s page: SaveRates never publishes.

How to sign in and read the response: Authentication, Responses.

POST /api/v1/SaveRates
Token: your-token
Content-Type: application/json

With lines:

{
  "Card": "VR-0012",
  "ReplaceAll": false,
  "Lines": [
    {
      "Leg": "Freight",
      "FromCode": "CNSHA",
      "ToCode": "KEMBA",
      "Charge": "Ocean Freight",
      "Basis": "Container",
      "Curr": "USD",
      "Values": { "20DV": 1200, "40HC": 2100 },
      "Transit": 28
    },
    {
      "Leg": "Destination",
      "FromCode": "KEMBA",
      "Charge": "Terminal Handling",
      "Values": { "20DV": 150, "40HC": 220 }
    }
  ]
}

With a file:

{
  "Card": "VR-0012",
  "ReplaceAll": true,
  "FileName": "VR-0012 November.xlsx",
  "File": "UEsDBBQABgAIAAAAIQBi7p1oXgEAAJAEAAATAAgCW0NvbnRlbnRfVHlwZXNd..."
}

Field	Required	Meaning
Card	Yes	The card’s Code, for example VR-0012.
Lines	One of the two	The rates as lines: see Lines.
File	One of the two	The rates as a file, an .xlsx or .csv, encoded in base64: see File. If you send Lines too, File is not used.
FileName	No	The file’s name, for example VR-0012 November.xlsx. It is shown on the card’s Feeds tab.
ReplaceAll	No	true to delete the draft’s lines that none of the lines or rows sent match. The default, false, keeps them.

Field names are not case-sensitive.

Lines

Each line is a whole rate line, with the fields of Line details:

Field	Meaning
Leg	Pre-carriage, Origin, Freight, Destination or On-carriage. Left out, Freight.
FromCode	Where the line starts, or for origin and destination charges, the place they are at. A place’s code, a UN/LOCODE such as CNSHA, or an exact name that only one place has. Left out, anywhere.
ToCode	Where the line ends, in the same way. Leave it out for origin and destination charges.
ViaCode	The routing or transhipment port, for information. Not for origin and destination charges.
Charge	Required. The charge’s name, or a code that only that charge has. On a company’s card, an active charge of that company: an income or disbursement charge on a selling card, an expense or disbursement charge on a buying card. On a card for all companies, a charge name that some company has.
Detail	Shown with the charge, up to 300 characters.
Basis	Shipment, Container, TEU, Kg, Chg kg, Ton, CBM, W/M, Trip, % or Unit. Usual other names, such as Per container, work too. Left out, the mode’s usual basis.
PctOf	For the % basis only: the charge this line is a percentage of.
Curr	The currency of the line’s prices. Left out, the card’s currency.
Values	The prices: see Prices. At least one.
Min, Max	The minimum and maximum charge. The minimum cannot be negative.
CargoTypes, Services, JobTypes	The cargo types, services and job types the line applies to, by name, separated by commas. Left out, any.
WtFrom, WtTo	The weights in kg the line applies to: from the first, up to but not including the second.
Ratio	The volume ratio in kg per CBM, for this line instead of the card’s: from 1 to 10,000.
VFrom, VTo	The dates the line is valid, when it is valid for less than its version, as yyyy-MM-dd.
Transit, FreeDays	Transit days and free days, whole numbers up to 999.
Notes	Up to 300 characters.
RLID	The ID of a line of the draft, from the ID column of a file downloaded from the draft. The line replaces that one.

Numbers can be JSON numbers or text with a point or a comma for decimals. Dates can also be written as dd/MM/yyyy or dd MMM yyyy, but yyyy-MM-dd is the safest.

How lines are matched

• A line with the RLID of a line of the draft replaces that line.
• Otherwise, a line replaces the draft’s line with the same leg, places, charge, detail, cargo types, services, job types, weights and dates. A line that matches none is added.
• A line is whole: a field you leave out is blank in the draft, or takes its default, even if the draft’s line had a value. To change one price, send the whole line again.
• With ReplaceAll set to true, the draft’s lines that no line matches are deleted.
• Two lines cannot price the same leg, places, charge, detail and conditions for weights or dates that overlap, whether both are in the request or one is a line of the draft that stays.

Prices

Values holds one price per price column of the draft, keyed by the column. The draft’s columns are its equipment types or weight breaks (see Dates & columns), or a single price:

The card is priced	Key each price by	For example
By equipment type, for example sea FCL or road	The equipment code of the column. Spaces and capitals do not matter. If the draft has only one column, Rate works too.	{ "20DV": 1200, "40HC": 2100 }
By weight break, for example air	The weight the band starts at, with or without + and kg. The first band can also be keyed by its heading, - and the next break.	{ "-45": 4.10, "+45": 3.20, "+100": 2.90 }
With one price, for example sea LCL	Rate, Price, Amount, Value, Tariff, Cost, Sell or Buy.	{ "Rate": 38 }

A price under a key that is not a column of the draft is a problem: '...' is not a price column of this version. An empty price is skipped.

File

A file is read as Upload a file reads it on the card’s page:

• an Excel workbook (.xlsx) or a CSV file, up to 10 MB and 20,000 rows; save an .xls file as .xlsx or .csv first;
• in a workbook, the sheet named Rates, or else the first visible sheet; the heading row can be anywhere in the first 20 rows; a CSV file can be separated by commas, semicolons or tabs;
• columns are matched by their heading, as on the page, or as remembered for the card or its customer or vendor. A layout that TrakIT cannot match must be uploaded once on the card’s page, with Remember this ticked; files of that layout are then read the same way;
• a row updates the draft’s line with its ID, else the line with the same leg, places, charge, detail, conditions, weights and dates. Fields the file has no column for keep their values. Other rows are added.

Send the file’s content in base64, without a data: prefix. TrakIT recognizes an Excel file by its content, so FileName is optional; a name that ends in .xls is refused.

Rules

The checks below come in this order. Up to the File check, a failed check returns RetInfo null; from the Card check on, RetInfo is the outcome, with Status 3 when a check fails.

Rule	Info when it fails
The request has a Token header.	Token missing in header
The body is JSON.	Incorrect Json syntax or rates missing
The token is valid.	Token invalid or expired, or another answer listed in Login token
The user is a system administrator with API access.	API User must be SysAdmin with API Access
Rate feeds are set up on your TrakIT.	Rate feeds are not set up on this system
The body has Lines or a File.	Send the rates as File (an .xlsx or .csv, base64) or as Lines
File is base64.	File is not base64
Card is given.	Name the rate card by its code, e.g. VR-0012
A rate card has that code.	No rate card has the code ..., or ... cannot see it
The card is active.	The card is inactive - reactivate it to take new rates
Lines has from 1 to 20,000 lines.	There are no lines to upload, Send up to 20,000 lines at a time
The file is not empty and is at most 10 MB.	The file is empty, The file is larger than 10 MB - split it
The card’s draft can be opened, if it has none.	Unable to open a draft
The file can be read.	Save the file as .xlsx (Excel Workbook) or .csv and upload it again, The file could not be read as an Excel workbook, The workbook has no data, The file could not be read at line ... - check for an unclosed quote, The file has more than 20,000 rows - split it
The file has a heading row, and rows below it.	No heading row was found - the file needs a row of column headings such as From, To, Charge and the prices, The file has headings but no rows
TrakIT can match the file’s columns: a charge column, at least one price column, and no field from two columns.	Choose the column that holds the charge, Choose the columns that hold the prices or Two columns are matched to ... - choose one, followed by how to fix it
Every line or row is right: see Problems.	... of ... row(s) have problems, so nothing was written. Fix them and send the rates again., with Code 1 and Status 2
The draft did not change meanwhile in a way the rates no longer fit.	The draft this file was uploaded into was published or discarded meanwhile - upload the file again, The draft changed since the file was uploaded and some rows no longer fit - upload the file again

Problems

Each line or row is checked as on the page. A row can have several problems, separated by ; . Rows in the response lists the first 200 rows with problems. The problems are, by field:

Field	Problems
Leg	Leg '...' is not one of Pre-carriage, Origin, Freight, Destination, On-carriage
FromCode, ToCode, ViaCode	No place has the code or name '...', '...' matches ... places by ... - use the place's code, Origin and destination charges are for one place - put it in From and leave To empty, Origin and destination charges have no routing
Charge, PctOf	Enter the charge, '...' is not an active ... charge of ..., No company has an active ... charge named '...', ... charges are named '...' in this company - rename them in the charge master, Code '...' is shared by ... charges (...) - use the charge name, Say which charge the percentage is of (% of), A charge cannot be a percentage of itself, '% of' is only for a percentage basis
Basis	Basis '...' is not one of Shipment, Container, TEU, Kg, Chg kg, Ton, CBM, W/M, Trip, %, Unit
Curr	Currency '...' is not set up
Values	'...' is not a price column of this version, This card prices by column - put the price under its column, Rate '...' is not a number (or the column’s name), A percentage must be between -100 and 1000, A price is too large, Enter at least one price
Min, Max	Min '...' is not a number, The minimum charge cannot be negative, The maximum charge is below the minimum
CargoTypes, Services, JobTypes	'...' is not a cargo type, '...' is not a service, '...' is not a job type, Too many ...s on one line
WtFrom, WtTo, Ratio	Weight from cannot be negative, Weight to must be above weight from, Weight to is too large, The volume ratio is the kg charged per CBM - between 1 and 10,000
VFrom, VTo	Valid from '...' is not a date - use yyyy-mm-dd, Valid from is out of range, The line cannot end before it starts
Transit, FreeDays	Transit days must be a whole number of days up to 999, Free days must be a whole number of days up to 999
Detail, Notes	Detail can have up to 300 characters, Notes can have up to 300 characters
The whole line	Prices the same line as row ..., Prices the same charge, places and conditions as row ... for overlapping weights or dates (or as a line of the draft the file does not change instead of the row)

A file can also have Could be any of ... lines of the draft for this lane and charge (they differ by conditions, weights or dates) - add those columns to the file.

Response

Code is 1 when the rates were read: either written into the draft (Status 1) or refused because some lines have problems (Status 2, nothing written). Check Status, not only Code. Code is 0 when the rates could not be read at all. Info repeats the outcome’s Message.

{
  "Code": 1,
  "Info": "Written into draft v4: 1 added, 1 changed, 0 deleted, 38 unchanged. The draft is not in use until it is published.",
  "RetInfo": {
    "Status": 1,
    "StatusText": "Written into the draft",
    "CardCode": "VR-0012",
    "CardName": "Example Shipping Co FCL rates",
    "FileName": "API lines",
    "VerNo": 4,
    "Total": 40,
    "Added": 1,
    "Changed": 1,
    "Deleted": 0,
    "Unchanged": 38,
    "Problems": 0,
    "Message": "Written into draft v4: 1 added, 1 changed, 0 deleted, 38 unchanged. The draft is not in use until it is published.",
    "Rows": null
  },
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 0
}

With problems:

{
  "Code": 1,
  "Info": "1 of 40 row(s) have problems, so nothing was written. Fix them and send the rates again.",
  "RetInfo": {
    "Status": 2,
    "StatusText": "Has problems - nothing written",
    "CardCode": "VR-0012",
    "CardName": "Example Shipping Co FCL rates",
    "FileName": "API lines",
    "VerNo": 4,
    "Total": 40,
    "Added": 1,
    "Changed": 0,
    "Deleted": 0,
    "Unchanged": 38,
    "Problems": 1,
    "Message": "1 of 40 row(s) have problems, so nothing was written. Fix them and send the rates again.",
    "Rows": [
      { "Row": 2, "Problem": "No place has the code or name 'KEMBX'" }
    ]
  },
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 0
}

Field	Meaning
Status	1 written into the draft, 2 has problems and nothing was written, 3 not read.
StatusText	Written into the draft, Has problems - nothing written or Not read.
CardCode, CardName	The card’s code and name. CardName is null when no card has the code.
FileName	FileName as sent, or API lines or API file when you sent none.
VerNo	The number of the draft version the rates went into, as vn on the card.
Total	The number of lines or rows read.
Added, Changed, Deleted, Unchanged	How many lines were added, changed and left unchanged, and how many draft lines ReplaceAll deleted. With Status 2, what the rows without problems would have done.
Problems	The number of lines or rows with problems.
Message	The outcome in words, as in Info.
Rows	With Status 2, the first 200 lines or rows with problems: Row, the line’s position in Lines (from 1) or the row’s number in the file, and Problem. Otherwise null.

When every line matches the draft already, nothing changes and the message is Nothing changed: the ... row(s) match draft v... already.

Example

To send a file with curl from a shell that has base64:

curl -H "Token: your-token" -H "Content-Type: application/json" \
  -d "{\"Card\":\"VR-0012\",\"FileName\":\"rates.xlsx\",\"File\":\"$(base64 -w0 rates.xlsx)\"}" \
  https://trakit.example.com/api/v1/SaveRates

Replace https://trakit.example.com with your TrakIT address. For a large file, write the JSON to a file first and send it with -d @body.json.

Notes

• If the card has no draft, SaveRates opens one first, with a copy of the lines of the latest published version if there is one, as Edit does on the page (see Change the rates). The draft stays open even if nothing is written.
• Each call for a card that exists is listed on the card’s Feeds tab, from API, with its result, and the card’s History records the rates received and written. Feed records are kept for a year.
• When rates are written and something changed, TrakIT emails the card’s notify group, with a workbook that lists every row and what came of it.
• Sending the same rates again is safe: lines that already match the draft are counted as unchanged.