SaveRates

Envoie des tarifs dans le brouillon d’une grille tarifaire, depuis votre système de tarification ou la fiche tarifaire d’un fournisseur, sans ouvrir la page. C’est l’un des flux de tarifs de la grille, avec l’e-mail et le SFTP. Envoyez les tarifs soit sous forme de fichier, un fichier Excel ou CSV lu comme le lit Charger un fichier, soit sous forme de lignes en JSON.

TrakIT vérifie d’abord chaque ligne, et ne les écrit dans le brouillon que si elles sont toutes correctes ; si l’une d’elles pose problème, rien n’est écrit. Les tarifs ne sont pas utilisés tant que quelqu’un n’a pas publié le brouillon sur la page de la grille : SaveRates ne publie jamais.

Comment se connecter et lire la réponse : Authentification, Réponses.

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

Avec des lignes :

{
  "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 }
    }
  ]
}

Avec un fichier :

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

Champ	Obligatoire	Signification
Card	Oui	Le Code de la grille, par exemple VR-0012.
Lines	L’un des deux	Les tarifs sous forme de lignes : voir Lignes.
File	L’un des deux	Les tarifs sous forme de fichier, un .xlsx ou un .csv, encodé en base64 : voir Fichier. Si vous envoyez aussi Lines, File n’est pas utilisé.
FileName	Non	Le nom du fichier, par exemple VR-0012 November.xlsx. Il est affiché dans l’onglet Feeds de la grille.
ReplaceAll	Non	true pour supprimer les lignes du brouillon auxquelles aucune des lignes envoyées ne correspond. La valeur par défaut, false, les conserve.

Les noms de champs ne tiennent pas compte de la casse.

Lignes

Chaque ligne est une ligne tarifaire complète, avec les champs de Détails d’une ligne :

Champ	Signification
Leg	Pre-carriage, Origin, Freight, Destination ou On-carriage. S’il est omis, Freight.
FromCode	L’endroit où commence la ligne ou, pour les frais d’origine et de destination, le lieu où ils s’appliquent. Le code d’un lieu, un UN/LOCODE comme CNSHA, ou un nom exact qu’un seul lieu porte. S’il est omis, n’importe où.
ToCode	L’endroit où se termine la ligne, de la même façon. Omettez-le pour les frais d’origine et de destination.
ViaCode	Le port de routage ou de transbordement, pour information. Pas pour les frais d’origine et de destination.
Charge	Obligatoire. Le nom de la rubrique, ou un code que seule cette rubrique porte. Sur la grille d’une société, une rubrique active de cette société : une rubrique de produits ou de débours sur une grille de vente, une rubrique de charges ou de débours sur une grille d’achat. Sur une grille pour toutes les sociétés, un nom de rubrique qu’au moins une société possède.
Detail	Affiché avec la rubrique, jusqu’à 300 caractères.
Basis	Shipment, Container, TEU, Kg, Chg kg, Ton, CBM, W/M, Trip, % ou Unit. Les autres noms usuels, comme Per container, fonctionnent aussi. S’il est omis, la base de calcul habituelle du mode.
PctOf	Pour la base % uniquement : la rubrique dont cette ligne est un pourcentage.
Curr	La devise des prix de la ligne. S’il est omis, la devise de la grille.
Values	Les prix : voir Prix. Au moins un.
Min, Max	Le montant minimum et le montant maximum. Le minimum ne peut pas être négatif.
CargoTypes, Services, JobTypes	Les types de marchandise, les services et les types de dossier auxquels la ligne s’applique, par leur nom, séparés par des virgules. S’ils sont omis, n’importe lesquels.
WtFrom, WtTo	Les poids en kg auxquels la ligne s’applique : à partir du premier, jusqu’au second non compris.
Ratio	Le rapport poids/volume en kg par CBM, pour cette ligne au lieu de celui de la grille : de 1 à 10 000.
VFrom, VTo	Les dates de validité de la ligne, lorsqu’elle est valable moins longtemps que sa version, au format yyyy-MM-dd.
Transit, FreeDays	Les jours de transit et les jours de franchise, en nombres entiers jusqu’à 999.
Notes	Jusqu’à 300 caractères.
RLID	L’identifiant d’une ligne du brouillon, tiré de la colonne ID d’un fichier téléchargé à partir du brouillon. La ligne remplace celle-ci.

Les nombres peuvent être des nombres JSON ou du texte avec un point ou une virgule comme séparateur décimal. Les dates peuvent aussi s’écrire dd/MM/yyyy ou dd MMM yyyy, mais yyyy-MM-dd est le format le plus sûr.

Mise en correspondance des lignes

• Une ligne qui porte le RLID d’une ligne du brouillon remplace cette ligne.
• Sinon, une ligne remplace la ligne du brouillon qui a le même tronçon, les mêmes lieux, la même rubrique, le même détail, les mêmes types de marchandise, services, types de dossier, poids et dates. Une ligne qui ne correspond à aucune est ajoutée.
• Une ligne est complète : un champ que vous omettez est vide dans le brouillon, ou prend sa valeur par défaut, même si la ligne du brouillon avait une valeur. Pour modifier un prix, renvoyez toute la ligne.
• Avec ReplaceAll à true, les lignes du brouillon auxquelles aucune ligne ne correspond sont supprimées.
• Deux lignes ne peuvent pas tarifer le même tronçon, les mêmes lieux, la même rubrique, le même détail et les mêmes conditions pour des poids ou des dates qui se chevauchent, que les deux soient dans la requête ou que l’une soit une ligne du brouillon qui est conservée.

Prix

Values contient un prix par colonne de prix du brouillon, chaque prix ayant pour clé sa colonne. Les colonnes du brouillon sont ses types d’équipement ou ses tranches de poids (voir Dates & columns), ou un prix unique :

La grille est tarifée	Clé de chaque prix	Par exemple
Par type d’équipement, par exemple en FCL maritime ou par route	Le code d’équipement de la colonne. Les espaces et les majuscules n’ont pas d’importance. Si le brouillon n’a qu’une colonne, Rate fonctionne aussi.	{ "20DV": 1200, "40HC": 2100 }
Par tranche de poids, par exemple en aérien	Le poids auquel commence la tranche, avec ou sans + et kg. La première tranche peut aussi avoir pour clé son intitulé, - et la tranche suivante.	{ "-45": 4.10, "+45": 3.20, "+100": 2.90 }
Avec un prix unique, par exemple en LCL maritime	Rate, Price, Amount, Value, Tariff, Cost, Sell ou Buy.	{ "Rate": 38 }

Un prix sous une clé qui n’est pas une colonne du brouillon est un problème : '...' is not a price column of this version. Un prix vide est ignoré.

Fichier

Un fichier est lu comme Charger un fichier le lit sur la page de la grille :

• un classeur Excel (.xlsx) ou un fichier CSV, jusqu’à 10 Mo et 20 000 lignes ; enregistrez d’abord un fichier .xls au format .xlsx ou .csv ;
• dans un classeur, la feuille nommée Rates, ou à défaut la première feuille visible ; la ligne d’intitulés peut se trouver n’importe où dans les 20 premières lignes ; un fichier CSV peut être séparé par des virgules, des points-virgules ou des tabulations ;
• les colonnes sont reconnues par leur intitulé, comme sur la page, ou comme mémorisé pour la grille ou pour son client ou son fournisseur. Une présentation que TrakIT ne sait pas reconnaître doit être chargée une fois sur la page de la grille, avec Remember this coché ; les fichiers de cette présentation sont ensuite lus de la même façon ;
• une ligne met à jour la ligne du brouillon qui a son ID, sinon la ligne qui a le même tronçon, les mêmes lieux, la même rubrique, le même détail, les mêmes conditions, les mêmes poids et les mêmes dates. Les champs pour lesquels le fichier n’a pas de colonne gardent leurs valeurs. Les autres lignes sont ajoutées.

Envoyez le contenu du fichier en base64, sans préfixe data:. TrakIT reconnaît un fichier Excel à son contenu : FileName est donc facultatif ; un nom qui se termine par .xls est refusé.

Règles

Les contrôles ci-dessous sont effectués dans cet ordre. Jusqu’au contrôle de File, un contrôle qui échoue renvoie RetInfo à null ; à partir du contrôle de Card, RetInfo est le résultat, avec Status 3 quand un contrôle échoue.

Règle	Info en cas d’échec
La requête a un en-tête Token.	Token missing in header
Le corps est du JSON.	Incorrect Json syntax or rates missing
Le jeton est valide.	Token invalid or expired, ou une autre réponse listée dans Jeton de connexion
L’utilisateur est un administrateur système avec l’accès à l’API.	API User must be SysAdmin with API Access
Les flux de tarifs sont configurés sur votre TrakIT.	Rate feeds are not set up on this system
Le corps contient Lines ou un File.	Send the rates as File (an .xlsx or .csv, base64) or as Lines
File est en base64.	File is not base64
Card est indiqué.	Name the rate card by its code, e.g. VR-0012
Une grille tarifaire a ce code.	No rate card has the code ..., or ... cannot see it
La grille est active.	The card is inactive - reactivate it to take new rates
Lines contient de 1 à 20 000 lignes.	There are no lines to upload, Send up to 20,000 lines at a time
Le fichier n’est pas vide et fait au plus 10 Mo.	The file is empty, The file is larger than 10 MB - split it
Le brouillon de la grille peut être ouvert, si elle n’en a pas.	Unable to open a draft
Le fichier peut être lu.	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
Le fichier a une ligne d’intitulés, et des lignes en dessous.	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 sait faire correspondre les colonnes du fichier : une colonne de rubrique, au moins une colonne de prix, et aucun champ issu de deux colonnes.	Choose the column that holds the charge, Choose the columns that hold the prices ou Two columns are matched to ... - choose one, suivi de la façon de corriger
Chaque ligne est correcte : voir Problèmes.	... of ... row(s) have problems, so nothing was written. Fix them and send the rates again., avec Code 1 et Status 2
Le brouillon n’a pas changé entre-temps de telle sorte que les tarifs n’y correspondent plus.	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

Problèmes

Chaque ligne est vérifiée comme sur la page. Une ligne peut avoir plusieurs problèmes, séparés par ; . Rows dans la réponse liste les 200 premières lignes qui ont des problèmes. Les problèmes sont, par champ :

Champ	Problèmes
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 (ou le nom de la colonne), 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
La ligne entière	Prices the same line as row ..., Prices the same charge, places and conditions as row ... for overlapping weights or dates (ou as a line of the draft the file does not change au lieu de la ligne)

Un fichier peut aussi avoir 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.

Réponse

Code vaut 1 quand les tarifs ont été lus : soit écrits dans le brouillon (Status 1), soit refusés parce que certaines lignes ont des problèmes (Status 2, rien n’est écrit). Vérifiez Status, pas seulement Code. Code vaut 0 quand les tarifs n’ont pas pu être lus du tout. Info reprend le Message du résultat.

{
  "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
}

Avec des problèmes :

{
  "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
}

Champ	Signification
Status	1 écrits dans le brouillon, 2 des problèmes et rien n’a été écrit, 3 non lus.
StatusText	Written into the draft, Has problems - nothing written ou Not read.
CardCode, CardName	Le code et le nom de la grille. CardName vaut null quand aucune grille n’a ce code.
FileName	FileName tel qu’il a été envoyé, ou API lines ou API file si vous n’en avez pas envoyé.
VerNo	Le numéro de la version brouillon à laquelle les tarifs ont été envoyés, comme vn sur la grille.
Total	Le nombre de lignes lues.
Added, Changed, Deleted, Unchanged	Le nombre de lignes ajoutées, modifiées et inchangées, et le nombre de lignes du brouillon supprimées par ReplaceAll. Avec Status 2, ce qu’auraient fait les lignes sans problème.
Problems	Le nombre de lignes qui ont des problèmes.
Message	Le résultat en toutes lettres, comme dans Info.
Rows	Avec Status 2, les 200 premières lignes qui ont des problèmes : Row, la position de la ligne dans Lines (à partir de 1) ou son numéro dans le fichier, et Problem. Sinon null.

Quand chaque ligne correspond déjà au brouillon, rien ne change et le message est Nothing changed: the ... row(s) match draft v... already.

Exemple

Pour envoyer un fichier avec curl depuis un shell qui dispose de 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

Remplacez https://trakit.example.com par l’adresse de votre TrakIT. Pour un fichier volumineux, écrivez d’abord le JSON dans un fichier et envoyez-le avec -d @body.json.

Notes

• Si la grille n’a pas de brouillon, SaveRates en ouvre d’abord un, avec une copie des lignes de la dernière version publiée s’il y en a une, comme le fait Edit sur la page (voir Modifier les tarifs). Le brouillon reste ouvert même si rien n’est écrit.
• Chaque appel pour une grille existante est listé dans l’onglet Feeds de la grille, avec la provenance API et son résultat, et l’onglet History de la grille enregistre les tarifs reçus et écrits. Les enregistrements des flux sont conservés un an.
• Quand des tarifs sont écrits et que quelque chose a changé, TrakIT envoie un e-mail au groupe de notification de la grille, avec un classeur qui liste chaque ligne et ce qu’il en est advenu.
• Envoyer à nouveau les mêmes tarifs est sans risque : les lignes qui correspondent déjà au brouillon sont comptées comme inchangées.