CreateJob

Crée un dossier avec ses ordres de travail, un par conteneur ou par chargement, en une seule requête : ce que fait Créer un dossier dans TrakIT. Utilisez-le lorsque les dossiers naissent dans un autre système, comme un système de réservation ou de dédouanement. Lisez ensuite le dossier avec GetJob, enregistrez ses événements avec SaveSeqData, et modifiez l’en-tête d’un ordre de travail avec UpdateWOHeader.

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

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

{
  "WFID": 12,
  "TD": "EXBL2610045",
  "CusID": 3021,
  "ShipperID": 3022,
  "ReceiverID": 3021,
  "JobType": [2],
  "CargoType": 0,
  "IncoTerms": "CIF",
  "Remarks": "Booking received from the customer portal",
  "WOList": [
    {
      "ContNum": "ABCU1234560",
      "TypeCode": "22G1",
      "SealNum": "SL778812",
      "Commodity": "Ceramic tiles",
      "Weight": 21450.5,
      "OpID": 1187,
      "TransID": 2210,
      "ClAgentID": 2304,
      "Resp": "JSMITH",
      "Priority": 3,
      "Remarks": "Check the seal at the gate",
      "CustRemarks": "Delivery before noon",
      "Services": [4, 6]
    },
    {
      "ContNum": "ABCU2345677",
      "TypeCode": "45G1",
      "SealNum": "SL778813",
      "Commodity": "Ceramic tiles",
      "Weight": 24310,
      "OpID": 1187,
      "Resp": "JSMITH",
      "Services": [4]
    }
  ]
}

TrakIT lit le corps champ par champ, par nom, et les noms sont sensibles à la casse : envoyez WFID, pas wfid. Un champ qu’il ne connaît pas est ignoré. De même pour une valeur qu’il ne peut pas lire dans le type du champ, par exemple du texte dans un champ numérique : TrakIT considère alors le champ comme non envoyé. Envoyez les nombres comme des nombres JSON et les listes comme des listes JSON. Un champ que vous omettez reste vide, sauf si sa ligne ci-dessous indique une valeur par défaut.

Les champs renseignent les champs d’en-tête du dossier et des ordres de travail. L’API les nomme comme ci-dessous.

Champs du dossier

Champ	Obligatoire	Signification
WFID	Oui	Le workflow du dossier : son identifiant, un nombre entier, tel qu’il figure dans la colonne ID de Définitions de workflows.
TD	Non	La référence du dossier, par exemple le numéro du connaissement. TrakIT supprime les espaces, l’enregistre en majuscules et en garde les 30 premiers caractères. Seuls les lettres de A à Z, les chiffres, -, _, , et / sont autorisés, et aucun autre dossier ne peut avoir la même référence. Envoyez-la avec chaque dossier : voir Envoyer des dossiers complets.
CusID	Non	Le client : l’identifiant de l’entité, tel qu’il figure dans la colonne ID de Gestion des entités.
ShipperID	Non	Le chargeur : un identifiant d’entité.
ReceiverID	Non	Le réceptionnaire : un identifiant d’entité.
JobType	Non	Les types de dossier : une liste d’identifiants de types de dossier, des nombres entiers, même pour un seul : [2]. Le support TrakIT peut vous donner les identifiants de vos types de dossier.
CargoType	Non	Le type de marchandise, sous forme de nombre : voir Types de marchandise.
IncoTerms	Non	Les Incoterms : un ou plusieurs parmi EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DPU, DAP et DDP, séparés par des virgules, par exemple CIF ou FOB,CIF. 100 caractères au plus.
Remarks	Non	Remarks For Job, partagées par tous les ordres de travail du dossier.
WOList	Oui	Les ordres de travail : une liste d’au moins un objet, avec les champs ci-dessous.

Champs des ordres de travail

Chaque élément de WOList est un ordre de travail.

Champ	Obligatoire	Signification
ContNum	Non	Le numéro de conteneur, 20 caractères au plus. TrakIT l’enregistre tel que vous l’envoyez : envoyez-le en majuscules, sans espaces. Deux ordres de travail d’une même requête ne peuvent pas avoir le même numéro de conteneur.
TypeCode	Non	Le type de chargement : le code ou le code alternatif d’un type de chargement actif, par exemple 22G1. TrakIT enregistre le code propre du type de chargement.
SealNum	Non	Le numéro de scellé, 100 caractères au plus : lettres de A à Z, chiffres, espaces et # $ % + , - . / @ _.
Commodity	Non	La marchandise, 500 caractères au plus.
Weight	Non	Le poids en kilogrammes, de 0 à 50 000 000. La valeur par défaut est 0.
OpID	Non	Le transporteur : un identifiant d’entité.
TransID	Non	Le transporteur routier : un identifiant d’entité.
BondAgentID	Non	L’agent de caution : un identifiant d’entité.
ClAgentID	Non	Le commissionnaire en douane : un identifiant d’entité.
Resp	Non	Le responsable : un identifiant utilisateur, par exemple JSMITH. Par défaut, l’utilisateur de l’API.
Priority	Non	La priorité de l’ordre de travail, un nombre entier : 1 Critical, 2 High, 3 Normal, 4 Low ou 5 Very Low. La valeur par défaut, y compris pour 0, est 3.
Remarks	Non	Internal Remarks.
CustRemarks	Non	Remarks For Customer.
Services	Non	Les services de l’ordre de travail : une liste d’identifiants de services, des nombres entiers, par exemple [4, 6]. Les administrateurs système voient les identifiants sous Workflow Services dans Tables de référence. Un service que le workflow ne propose pas est écarté.

CreateJob ne renseigne que les champs d’en-tête ci-dessus. Renseignez ensuite le transporteur routier de retour et Shipper Container avec UpdateWOHeader, les événements et les champs de données avec SaveSeqData, et les autres champs, comme le volume, les pays et la liste des lieux, sur l’ordre de travail dans TrakIT (Modifier un ordre de travail).

Types de marchandise

CargoType	Type de marchandise dans TrakIT	CargoType dans GetJob
0	Full Container Load (FCL)	FCL
1	Less than Container Load (LCL)	LCL
2	Bulk	Bulk
3	Break-Bulk	BreakBulk
4	Air Freight	Air
5	Charter	Charter
6	Bags	Bags
7	Tanker	Tanker
8	Pallets	Pallets
9	Bales	Bales
10	Boxes/Cartons	Boxes
11	Bagged & Bulk	BagBulk
12	FMCG	FMCG
13	Drums	Drums
14	Jerrycans	Jerrycans
15	Units	Units
16	Vehicles	Vehicles
17	Big Bags	BigBags
18	Empty Container	Empty
99	Other	Other

Règles

TrakIT contrôle d’abord le dossier, puis chaque ordre de travail dans l’ordre de WOList. Si un contrôle échoue, rien n’est créé : ni le dossier, ni aucun de ses ordres de travail. Info donne le message mais n’indique pas l’ordre de travail concerné.

Votre société peut aussi avoir ses propres validations, configurées par le support TrakIT : voir Validations et actions. Les opérations qui s’appliquent ici sont Create Job, Save WO Header, Save Job Header et Create WO. Leurs messages reviennent de la même façon dans Info.

La requête et le dossier :

Règle	Info en cas d’échec
L’en-tête Token contient un jeton valide.	Token missing in header, Token invalid or expired, ou une autre réponse listée dans Jeton de connexion
L’utilisateur est un administrateur système avec un accès à l’API.	API User must be SysAdmin with API Access
La requête a un corps JSON.	No request body found
WOList est une liste d’au moins un ordre de travail.	No WO list found
TD ne contient que les caractères autorisés.	... is not valid, commençant par le nom abrégé que votre installation donne à la référence du dossier : par défaut T/D is not valid
CusID, ShipperID et ReceiverID, s’ils sont envoyés, sont des identifiants d’entités.	No such entity
Leurs champs de données d’entité obligatoires sont renseignés.	Error: Entity '...' Mandatory data field '...' is missing
Les validations de votre société pour Create Job sont satisfaites.	Leurs propres messages
Aucun autre dossier n’a la même référence.	... '...' already exists in workflow ..., commençant par le nom que votre installation donne à la référence du dossier : par défaut Transport Document '...' already exists in workflow ...
WFID est l’identifiant d’un workflow, et IncoTerms compte 100 caractères au plus.	Unable to create job

Chaque ordre de travail :

Règle	Info en cas d’échec
Services ne contient que des nombres entiers.	Service IDs must be integers
Resp, s’il est envoyé, n’est pas vide.	Responsible Person must be specified.
Weight est compris entre 0 et 50 000 000.	Weight must be in range 0 to 50,000,000 Kg
TypeCode, s’il est envoyé, est le code ou le code alternatif d’un type de chargement actif.	Load Type is not valid
Si le conteneur figure dans la liste des conteneurs avec un type de chargement vérifié, TypeCode est ce type de chargement.	Load Type '...' does not match Container Master
Commodity ne contient pas de script.	Commodity contains invalid characters
SealNum ne contient que les caractères autorisés.	Seal Number contains invalid characters
Priority est compris entre 1 et 5.	Priority must be between 1 (Urgent) and 5 (On Hold)
SealNum compte 100 caractères au plus.	Seal Number can be a maximum of 100 characters
Aucun ordre de travail précédent de la requête n’a le même numéro de conteneur.	WO already exists
Les validations de votre société pour Save WO Header et Save Job Header sont satisfaites.	Leurs propres messages
La limite mensuelle de nouveaux ordres de travail de votre installation, s’il y en a une, n’est pas atteinte.	Monthly limit on WO creation has been reached
Les validations de votre société pour Create WO sont satisfaites.	Leurs propres messages
TransID, BondAgentID et ClAgentID, s’ils sont envoyés, sont des identifiants d’entités dont les champs de données d’entité obligatoires sont renseignés.	No such entity, Error: Entity '...' Mandatory data field '...' is missing
Resp est un identifiant utilisateur, OpID l’identifiant d’une entité, ContNum compte 20 caractères au plus et Commodity 500 au plus.	Unable to add new Work Order

Réponse

En cas de succès, Identity est l’identifiant du nouveau dossier, et RetInfo contient l’identifiant du dossier, sa référence et les identifiants de ses ordres de travail. RowsAffected vaut 0 et Scalar vaut null.

{
  "Code": 1,
  "Info": "",
  "RetInfo": {
    "JobID": 10457,
    "BOLNum": "EXBL2610045",
    "WOList": [48211, 48212]
  },
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 10457
}

Champ	Signification
JobID	L’identifiant du dossier, le même que Identity.
BOLNum	La référence du dossier telle que TrakIT l’a enregistrée : en majuscules, sans espaces, 30 caractères au plus. Lisez le dossier avec GetJob?Num= et cette valeur.
WOList	Les identifiants des nouveaux ordres de travail, dans l’ordre de WOList dans la requête. Lisez chacun d’eux avec GetWO.

Notes

Ce que TrakIT fait d’un nouveau dossier

• Chaque ordre de travail reçoit les événements, les champs de données et les KPI de son workflow qui s’appliquent à son client, à ses types de dossier et à ses services, avec leurs valeurs par défaut.
• Les champs de données des entités du dossier et de l’ordre de travail sont copiés dans les événements et les données de l’ordre de travail lorsque votre société l’a configuré : voir Copier les valeurs dans les ordres de travail.
• Le dossier reçoit son Workflow Serial si le workflow numérote ses dossiers : voir le Serial Format des paramètres du workflow.
• Un numéro de conteneur envoyé avec un type de chargement est ajouté à la liste des conteneurs s’il n’y figure pas encore.
• Une fois le dossier enregistré, TrakIT évalue les champs de données calculés, exécute les actions d’événements et de données qui sont dues, puis les actions de votre société pour Create Job et Create WO. Les utilisateurs abonnés aux notifications Create Job sont avertis de chaque nouvel ordre de travail.
• Le dossier et ses ordres de travail sont enregistrés comme créés par l’utilisateur de l’API.

Envoyer des dossiers complets

Envoyez ce qu’un utilisateur devrait saisir sur Créer un dossier :

• la référence du dossier, avec chaque dossier ;
• les champs d’en-tête que votre workflow rend Mandatory dans son onglet Header Fields ;
• une marchandise de la liste du workflow, s’il en a une ;
• des numéros de conteneur valides pour le workflow, et des types de dossier et des services qu’il autorise.

Nouvelles tentatives

Une référence de dossier ne peut être utilisée qu’une fois. Si une requête expire et que vous ne savez pas si le dossier a été créé, recherchez-le avec GetJob avant de renvoyer la requête. Renvoyée, elle est refusée avec ... already exists in workflow ....