Service de validation de SARI (AVS) Manuel technique

Sur cette page

1.0 Aperçu

Le service de validation du Système automatisé de référence à l'importation (SARI) est un service Web permettant de valider plusieurs produits du SARI au moyen d'une seule demande. L'information, une fois transmise au service en format XML, est alors validée, et un message de réponse est généré.

2.0 Descripteurs de service

Accédez la description de service.

Le langage WSDL fournit la description du service dans un format XML, qui pourrait être utilisé par les programmeurs pour créer une interface au service.

Les schémas qui définissent le format XML utilisé dans les demandes et les réponses sont disponibles aux adresses suivantes :

Schéma de la demande de validation

SEA/AM

DII 

Schéma de la réponse de validation

Accédez le Schéma de la réponse de validation

3.0 Appel du service

Le service dispose d'une méthode unique pouvant être appelée : « ValidateRequirements ». Cette méthode compte quatre paramètres, qui sont tous obligatoires.

xmlContent

Un tableau d'octets incluant le contenu XML à valider. Le contenu doit être validé selon le schéma publié identifié par le paramètre « schemaVersion ».

schemaVersion

Une chaîne de caractères désignant la version du schéma utilisée.

Pour les demandes dans le SEA/MDM AM, utiliser la version « 1.0 ».

Pour les demandes de DII, utiliser la version « 2.0 ».

key

Une chaîne de caractères incluant un identificateur unique au courtier et qui est assignée par l'ACIA. Cette clé doit être valide pour que l'importateur ou le courtier accède au système.

lang

Un nombre entier désignant la langue dans laquelle le service doit fournir des messages d'erreur : 1=Anglais, 2=Français

3.1 Restrictions

  • Le format XML est restreint par le schéma. Le schéma comprend des restrictions sur la longueur des chaînes de caractères et l'ordre des éléments.
  • La grosseur totale du message ne peut pas dépasser 500 ko.
  • Un maximum de 400 produits peut être validé dans une demande.
  • Le transfert de fichiers volumineux via une connexion lente pourrait causer une erreur de temporisation.

Remarque

Comme chaque produit compte dans la limite des 400 produits, il est recommandé de prétraiter la demande afin d'enlever les doubles.

3.2 Format de la demande

3.2.1 SEA/MDM AMG

Pour soumettre une demande dans le Système d'examen avant l'arrivée/Mainlevée contre documentation minimale pour les autres ministères gouvernemental SEA/MDM AMG, fournir le paramètre « schemaVersion » 1.0. La demande XML doit être valide selon le schéma publié vr_in_1.0.xsd, sinon le système retournera une erreur de code. L'élément racine du schéma de la demande est « ValidateTransaction ». Cet élément peut contenir de 1 à 999 groupes de produits. Chaque groupe peut contenir de 1 à 999 produits, bien que le service soit limité à un nombre maximal déterminé de produits dans tous les groupes (consultez Restrictions). L'élément d'un produit doit au moins avoir un « HSNumber ». Voici un exemple :

Description des éléments :

ValidateTransaction

Nœud racine, obligatoire.

CommodityGroup

Utilisé pour définir des groupes de produits. Cet élément permet aux systèmes de regrouper des ensembles de produits pour la validation. Un code d'identification de l'attribut (chaîne de caractères) est nécessaire afin que la réponse puisse afficher un nombre d'erreurs par groupe. Il doit y avoir au moins un groupe.

Commodity

Cet élément définit un produit du SARI et nécessite un code d'identification de l'attribut (chaîne de caractères). S'il y a des erreurs présentes, la réponse associera l'erreur au ID fourni. Il doit y avoir au moins un produit par groupe.

HSNumber

Le « nombre S.H. » ou « code S.H. ». L'application Web de SARI fournit un code de six (6) caractères bien que le champ accepte jusqu'à dix (10) caractères pour les codes tarifaires de l'ASFC (seuls les six (6) premiers caractères sont lus). Le « HSNumber » doit être fourni pour chaque produit.

RequirementId

Code d'identification de l'exigence déterminé par l'application Web de SARI. Ce champ n'est pas toujours nécessaire.

RequirementVersion

Version de l'exigence déterminée par l'application Web de SARI. Ce champ n'est pas toujours nécessaire.

AirsCode

Extension ADG ou « code SARI ». Ce code a toujours six (6) caractères (p. ex. « 940000 »). Ce champ n'est pas toujours nécessaire.

DestinationProvince

Code de deux (2) caractères qui désigne la province de destination (p. ex. « ON », « BC »). Ce champ n'est pas toujours nécessaire.

OriginCountry

Code de deux (2) caractères qui désigne le pays d'origine du produit (p. ex. « US », « NZ »). Ce champ n'est pas toujours nécessaire.

OriginState

Code de deux (2) caractères qui désigne l'état original du produit. Ce champ sert uniquement pour les produits provenant des États-Unis (p. ex. « NY », « TN »). Ce champ n'est pas toujours nécessaire.

Enduse

Code de deux (2) ou trois (3) caractères pour l'usage final (p. ex. « 01 », « 14 »). Ce champ n'est pas toujours nécessaire.

Miscellaneous

Code de un (1) ou deux (2) ou trois (3) caractères pour le champ divers (p. ex. « 01 », « 34 »). Ce champ n'est pas toujours nécessaire.

Registration

Cet élément peut se répéter et est utilisé pour identifier les enregistrements qui appartiennent aux exigences associées à ce produit. L'élément ne contient pas de données. Le code d'enregistrement est identifié au moyen de l'attribut « registrationId ».

Un exemple de demande XML. Cette demande ne comprend que deux (2) groupes et trois (3) produits.

<?xml version="1.0"?>
<ValidateTransaction>
<CommodityGroup commodityGroupId="A1">
<Commodity commodityId="GGL023--0001">
<HSNumber>020500</HSNumber>
<RequirementId>21247</RequirementId>
<RequirementVersion>14</RequirementVersion>
<AirsCode>512700</AirsCode>
<OriginCountry>US</OriginCountry>
<OriginState>TN</OriginState>
<Enduse>69</Enduse>
<Miscellaneous>34</Miscellaneous>
<Registration registrationId="14" />
<Registration registrationId="28" />
<Registration registrationId="40" />
<Registration registrationId="41" />
<Registration registrationId="98" />
<Registration registrationId="99" />
<Registration registrationId="102" />
<Registration registrationId="104" />
<Registration registrationId="105" />
<Registration registrationId="111" />
<Registration registrationId="120" />
<Registration registrationId="121" />
<Registration registrationId="132" />
<Registration registrationId="141" />
<Registration registrationId="318" />
</Commodity>
</CommodityGroup>
<CommodityGroup commodityGroupId="A2">
<Commodity commodityId="GHL030--0001">
<HSNumber>960000</HSNumber>
</Commodity>
<Commodity commodityId="GHL030--0002">
<HSNumber>920000</HSNumber>
</Commodity>
</CommodityGroup>
</ValidateTransaction>

Dans l'exemple ci-dessus, le premier produit a une exigence #21247, version 14. Il s'agit d'un produit réglementé qui nécessite la sélection des codes « origin », « enduse », et « miscellaneous ». Les codes d'enregistrement énumérés sont ceux indiqués dans la page « SEA/MDM AMG » de l'application Web de SARI (dans cet exemple, deux enregistrements sont manquants). Les produits du deuxième groupe sont des produits non réglementés et, de ce fait, ne sont pas associés à des enregistrements ou à des attributs SARI.

Voici d'autres éléments qui n'étaient pas dans l'exemple :

<DestinationProvince>BC</DestinationProvince>

3.2.2 Déclaration d'importation intégrée (DII)

Pour soumettre une DII, fournir le paramètre « schemaVersion » 2.0. La demande XML doit être valide selon le schéma publié vr_in_2.0.xsd, sinon le système retournera une erreur de code. L'élément racine du schéma de la demande est « ValidateIIDTransaction ». Cet élément peut contenir de 1 à 999 groupes de produits. Chaque groupe peut contenir de 1 à 999 produits, bien que le service soit limité à un nombre maximal déterminé de produits dans tous les groupes (consultez Restrictions). L'élément d'un produit doit au moins avoir un « HSNumber ». Voici un exemple :

Description des éléments :

ValidateIIDTransaction

Nœud racine, obligatoire.

CommodityGroup

Utilisé pour définir des groupes de produits. Cet élément permet aux systèmes de regrouper des ensembles de produits pour la validation. Un code d'identification de l'attribut (chaîne de caractères) est nécessaire afin que la réponse puisse afficher un nombre d'erreurs par groupe. Il doit y avoir au moins un groupe.

Commodity

Cet élément définit un produit du SARI et nécessite un code d'identification de l'attribut (chaîne de caractères). S'il y a des erreurs présentes, la réponse associera l'erreur au ID fourni. Il doit y avoir au moins un produit par groupe.

HSNumber

Le « nombre S.H. » ou « code S.H. ». L'application Web de SARI fournit un code de six (6) caractères bien que le champ accepte jusqu'à dix (10) caractères pour les codes tarifaires de l'ASFC (seuls les six (6) premiers caractères sont lus). Le « HSNumber » doit être fourni pour chaque produit.

AirsCode

Extension ADG ou « code SARI ». Ce code a toujours six (6) caractères (p. ex. « 940000 »). Ce champ n'est pas toujours nécessaire.

DestinationProvince

Code de deux (2) caractères qui désigne la province de destination (p. ex. « ON », « BC »). Ce champ n'est pas toujours nécessaire.

OriginCountry

Code de deux (2) caractères qui désigne le pays d'origine du produit (p. ex. « US », « NZ »). Ce champ n'est pas toujours nécessaire.

OriginState

Code de deux (2) caractères qui désigne l'état original du produit. Ce champ sert uniquement pour les produits provenant des États-Unis (p. ex. « NY », « TN »). Ce champ n'est pas toujours nécessaire.

Enduse

Code de deux (2) ou trois (3) caractères pour l'usage final (p. ex. « 01 », « 14 »). Ce champ n'est pas toujours nécessaire.

Miscellaneous

Code de un (1) ou deux (2) ou trois (3) caractères pour le champ divers (p. ex. « 01 », « 34 »). Ce champ n'est pas toujours nécessaire.

Registrations
LPCA matérialisés

Cet élément peut se répéter et est utilisé pour identifier les LPCA – documents qui nécessitent une version électronique. L'élément ne contient pas de données. Le code de LPCA est identifié au moyen de l'attribut « registrationId ».

LPCA dématérialisés

Cet élément peut se répéter et est utilisé pour identifier les LPCA – documents qui ne nécessitent pas une version électronique. L'élément ne contient pas de données. Le code de LPCA est identifié au moyen de l'attribut « registrationId ».

Registration

Cet élément peut se répéter et est utilisé pour identifier les enregistrements qui appartiennent aux exigences associées à ce produit. L'élément ne contient pas de données. Le code d'enregistrement est identifié au moyen de l'attribut « registrationId ».

Un exemple de demande XML. Cette demande ne comprend que deux (2) groupes et trois (3) produits.

<?xml version="1.0"?>
<ValidateIIDTransaction>
<CommodityGroup commodityGroupId="A1">
<Commodity commodityId="GGL023--0001">
<HSNumber>020500</HSNumber>
<RequirementId>21247</RequirementId>
<RequirementVersion>14</RequirementVersion>
<AirsCode>512700</AirsCode>
<OriginCountry>US</OriginCountry>
<OriginState>TN</OriginState>
<Enduse>69</Enduse>
<Miscellaneous>34</Miscellaneous>
<Registration registrationId="14" />
<Registration registrationId="28" />
<Registration registrationId="40" />
<Registration registrationId="41" />
<Registration registrationId="98" />
<Registration registrationId="99" />
<Registration registrationId="102" />
<Registration registrationId="104" />
<Registration registrationId="105" />
<Registration registrationId="111" />
<Registration registrationId="120" />
<Registration registrationId="121" />
<Registration registrationId="132" />
<Registration registrationId="141" />
<Registration registrationId="318" />
</Commodity>
</CommodityGroup>
<CommodityGroup commodityGroupId="A2">
<Commodity commodityId="GHL030--0001">
<HSNumber>960000</HSNumber>
</Commodity>
<Commodity commodityId="GHL030--0002">
<HSNumber>920000</HSNumber>
</Commodity>
</CommodityGroup>
</ValidateIIDTransaction>

Dans l'exemple ci-dessus, il s'agit d'un produit réglementé qui nécessite la sélection des codes « origin », « enduse », et « miscellaneous ». Les codes d'enregistrement énumérés sont ceux indiqués dans la page « DII » de l'application Web de SARI (dans cet exemple, deux enregistrements sont manquants). Les produits du deuxième groupe sont des produits non réglementés et, de ce fait, ne sont pas associés à des enregistrements ou à des attributs SARI.

Voici d'autres éléments qui n'étaient pas dans l'exemple :

<DeliveryPartyProvince>BC</DeliveryPartyProvince>
<DematerializedLpco registrationId="14"/>

3.3 Validation

La validation des produits n'aura lieu que si le format XML est valide. Le temps de traitement variera selon le nombre de produits dans la demande. Une grande demande (plus de 300 produits) peut prendre une minute ou plus. Une fois validé, le résultat est envoyé sous la forme d'un document XML.

3.4 Format de la réponse

Si l'exemple de message XML ci-dessus était envoyé au Service de validation du SARI avec une clé Web valide, la réponse suivante serait générée (Remarque : bien que le format ne change pas, les exigences du SARI sont sujettes à des modifications au fil du temps, de sorte que les résultats obtenus au moyen de cet exemple peuvent varier).

<ValidateTransactionResult errorCount="1">
<CommodityGroup commodityGroupId="A1" errorCount="1">
<Commodity commodityId="GGL023--0001">
<Error>MISSING OR INVALID REGISTRATION NUMBER</Error>
</Commodity>
</CommodityGroup>
<CommodityGroup commodityGroupId="A2" errorCount="0" />
</ValidateTransactionResult>

Il y avait une (1) erreur dans l'ensemble de la demande, tel qu'indiqué dans l'élément du premier niveau <ValidateTransactionResult errorCount="1">. Le nombre d'erreurs par groupe s'affiche dans l'en-tête de chaque groupe. S'il n'y a pas d'erreur de produits dans un groupe, l'élément « CommodityGroup » sera vide. S'il y a une erreur, le produit en cause sera listé en compagnie d'un élément erreur incluant un message décrivant la cause de l'erreur. Dans cet exemple, le premier produit n'avait pas le bon groupe d'enregistrements.

3.5 Erreurs de protocole SOAP

Les erreurs reliées à SARI sont retournées à même la réponse XML si la demande était par ailleurs valide. Dans le cas d'une demande invalide, l'erreur de protocole SOAP sera renvoyée par le service. La section Détail de l'erreur de protocole SOAP inclut les renseignements suivants :

ErrorCode

Un code qui décrit le type d'erreur :

ERR001 = erreur du système

ERR002 = XML invalide

ERR003 = contenu XML vide

ERR004 = la version du schéma n'est pas supportée

ERR005 = clé invalide

ERR006 = demande excessive (trop de produits)

ErrorMessage

Un message d'erreur général qui décrit le type d'erreur.

ErrorDetail

Détails au sujet de l'erreur.

RequestId

Un identificateur associé à la demande.

Ce qui suit est un exemple de la partie Détail du message d'erreur de protocole :

<ServiceFaultContract xmlns=http://cfia-airs.inspection.gc.ca xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ErrorCode>ERR002</ErrorCode>
<ErrorMessage>The XML is invalid.</ErrorMessage>
<ErrorDetail>Data at the root level is invalid. Line 1, position 1.</ErrorDetail>
<RequestId>R#000005</RequestId>
</ServiceFaultContract>

Dans les cas où la demande XML n'était pas valide selon le schéma, les erreurs suivant l'analyse du code sont renvoyées dans le champ ErrorDetail. (Remarque : la portion Détail du message d'erreur n'est pas disponible en français.)

Explication des codes d'erreur :

ERR001 (erreur du système)

Une erreur inconnue est survenue. Essayez de faire votre demande de nouveau plus tard. Si le problème persiste, veuillez communiquer avec l'administrateur de système.

ERR002 (XML invalide)

Selon le schéma, le paramètre « xmlContent » n'était pas valide. Les erreurs spécifiques suivant l'analyse du code seront disponibles dans « ErrorDetail ».

ERR003 (contenu XML vide)

Aucune donnée dans le paramètre « xmlContent ».

ERR004 (la version du schéma pas supportée)

Le paramètre « schemaVersion » n'est pas n'est valide.

ERR005 (clé invalide)

Le paramètre « Key » n'est pas une clé Web valide.

ERR006 (demande excessive)

La demande dépassait le nombre maximal de produits autorisés. « ErrorDetail » affichera le maximum autorisé.

Date de modification :