Passer au contenu
Français
Portail client
Contact
  • Il n'y a aucune suggestion car le champ de recherche est vide.

Documentation API

Emplacement : Documentation SDS

Modalités techniques d'accès aux API pour l'EDI Douane

  • Terme
  • Certifie
  • API
  • Token
  • REST
  • HTTP
  • HTTPS
  • OAuth
  • OAuth2.0
  • Correspondant Entreprise
  • Compte API

INTRODUCTION

Ce document a pour objectif de fournir aux opérateurs les informations leurs permettant de s’interfacer en mode EDI avec des API avec le système informatique douanier. Ce nouvel EDI remplacera progressivement la solution EDI « Mareva » qui restera le mode d’interconnexion pour DeltaG, DeltaXI, DeltaXE, DeltaT, ICS, ECS, Gamma, Isope et Pablo. Le nouvel EDI est mis en place avec les applications DeltaH7, Gamma2, DeltaIE et PNTS.

Ces modalités font suite à un contrat d’utilisation de l’EDI Douane via API conclu entre l’opérateur et la Douane (effectuer la demande au service gestionnaire de certification : certification-edi@douane.finances.gouv.fr en précisant le numéro SIRET de votre entreprise, le logiciel utilisé par votre société et le compte douane.gouv du correspondant entreprise qui sera le gestionnaire du compte API). Si vous ne disposez pas encore de compte douane.gouv, merci de vous rapprocher de votre PAE (pôle action économique).

Ce document décrit le process à suivre et l’architecture technique à mettre en œuvre. Les paramètres techniques (chapitre 4 du présent document) seront communiqués lors de la remise du contrat d’utilisation. Une version restreinte de ce document est publiée sur le portail de la Douane ( http://douane.gouv.fr ).

Le service gestionnaire de certification va également être votre interlocuteur pour créer et habiliter votre compte API tel que décrit dans le présent document. Il vous transmettra les coordonnées des services douaniers qui seront ensuite vos interlocuteurs pour la réalisation des tests libres et la certification des solutions logicielles.

ARCHITECTURE TECHNIQUE

L’architecture fonctionnelle mise en œuvre lors d’un appel aux API fournies par la Douane est présentée ci-dessous. Elle se base sur l’utilisation des standards OAuth2 :

L’appel à une API Douane s’effectue en REST via HTTPS et nécessite l’obtention d’un jeton d’accès (Access Token) auprès du serveur d’autorisation de la Douane.

Le jeton d’accès est valable pour toutes les connexions entre l’application de l’opérateur et toutes les API de la Douane selon les habilitations accordées au compte API utilisé par l’application de l’opérateur.

La récupération du jeton d’accès est soumise à une authentification préalable. Pour ce faire, l’application appelante utilise un compte API enregistré auprès de la Douane et s’authentifie auprès du serveur d’autorisation de la Douane.

Une fois cette authentification réussie, l’application récupère le jeton d’accès, constitué d’une chaîne de caractères opaque. Ce jeton d’accès devra être ajouté à l’en-tête HTTPS de chaque requête REST envoyée à l’API (Une information complémentaire sera fournie dans la version technique de ce document).

La validité de ce jeton d’accès est limitée dans le temps. Lorsque le jeton expire, l’application doit se ré-authentifier auprès du serveur d’autorisation afin de récupérer un nouveau jeton.

Cette durée est fixée à 5 min.

Le chapitre 3 (Demande d’accès aux api) présente les étapes de l’établissement d’une connexion avec la Douane. Ceci nécessite en particulier la création du compte API permettant la récupération du jeton d’accès et son habilitation pour l’API Douane souhaitée.

Les paramètres techniques nécessaires à la création des requêtes d’obtention du jeton d’accès et d’appel aux API sont présentés en chapitre 4 (Existe uniquement dans la documentation technique).

Demande d’accès aux api

PRINCIPES GÉNÉRAUX

Lorsqu’un organisme externe à la Douane souhaite utiliser une ou plusieurs API de la Douane, il est nécessaire d’échanger un ensemble d’informations entre cet organisme et la Douane. Cet échange d’information est matérialisé par une demande d’accès aux API.

Pour ces échanges, un correspondant entreprise devra être désigné et habilité pour la création et la gestion des comptes API. Ces étapes sont explicitées dans la section 3.2.

Pour être nommé en tant que Correspondant Entreprise, un formulaire existe sur le lien suivant : Formulaire Administrateur Douane (Correspondant Entreprise / Gestionnaire Service en Ligne)

Etape 1 : Le Correspondant Entreprise devra :

  • Créer le compte API nécessaire (cf 3.2.1)
  • Puis demander l’habilitation du compte API pour initier une demande d’accès aux API souhaitées. (cf 3.2.2)

Etape 2 : La Douane examinera cette demande d’habilitation et d’accès, et si elle est approuvée :

  • Fournira une documentation technique développeur comprenant

    • les URL d’accès à utiliser pour

      • le serveur d’autorisation
      • les serveurs d’API

  • des exemples d’utilisation pour les demandes de jeton

  • la documentation d’utilisation des API souhaitées (Disponible en téléchargement sur le portail douane.gouv.fr)
  • La douane adressera en retour les accréditations nécessaires à l’obtention de jetons d’accès
  • Donnera les habilitations nécessaires au(x) compte(s) API

CRÉATION ET HABILITATION DE COMPTE API

Création d'un compte API

Après avoir obtenu le droit de gérer les comptes API, le correspondant entreprise aura accès à un nouvel espace, dédié à l'administration des comptes API, dans l'application « Correspondant Entreprise » (anciennement Admin Prodouane).

Sur cette page, le correspondant entreprise visualisera l'ensemble des comptes API dans son périmètre. Il aura également la possibilité d'en créer via le bouton « +Ajouter un compte API ».

Après avoir cliqué sur ce bouton, plusieurs informations seront demandées pour pouvoir procéder à la création du compte :

  1. Identifiant – Correspond au nom donné au compte API
  2. Email – Adresse mail dédiée au compte API
  3. SIRET1 – Si le correspondant entreprise est habilité sur plusieurs SIRET, il devra choisir celui sur lequel le compte API sera rattaché (il ne peut y avoir qu’un compte API rattaché à un SIRET)
  4. Mot de passe – Choix d'un mot de passe robuste pour le compte

NB : Le mot de passe du nouveau compte technique doit respecter les conditions de sécurité suivantes : 12 caractères constitués de majuscules, minuscule, chiffres, caractères spéciaux.

1 Si le SIRET souhaité n'apparaît pas, le correspondant entreprise n'est pas habilité pour cet établissement (voir paragraphe 3.1).

Une fois le compte créé, il apparaît sur l'écran principal.

L'interface utilisateur apporte des informations via l'utilisation de code couleur et de pictogrammes dans les colonnes Hab. et Actions (Pictogramme « « ! » dans un cercle rouge » sur l'image ci- dessus). Voici la signification de ces codes :

  • Rouge + Picto « ! » dans un cercle rouge : Le compte API n'a aucune habilitation
  • Jaune + Picto « ! » dans un triangle jaune : Le compte API est habilité mais certaines

données requises sont manquantes sur une ou plusieurs API

Vert + Aucun Picto : Le compte API est habilité et les données concernant les API sont complètes.

Demande d’habilitation d'un compte API

Après avoir créé un compte API, il est nécessaire de l'habiliter sur une API pour pouvoir l'utiliser. Pour cela, le correspondant entreprise doit faire une demande pour que le compte API ait le droit en accès sur l'API ciblée.

Cette demande doit être adressée à la Douane en indiquant :

  • L’identifiant de l’opérateur de l’établissement opérateur (SIRET)
  • L’identifiant du compte API créé
  • Les API sur lesquelles le compte API sera habilité

Finalisation d'un compte API

Après traitement de la demande par la Douane,

a) Si l'API ne nécessite pas de données complémentaires, le code couleur passera au vert et le compte API sera prêt à être utilisé.

b) Si l'API nécessite la saisie de données complémentaires, une fois le droit attribué, le code couleur évoluera pour passer du rouge au jaune. Cela signifie que le compte possède désormais au moins une habilitation et qu'il est nécessaire de compléter les valeurs attendues.

Le correspondant entreprise devra alors les renseigner avant d'utiliser ce compte.

Pour cela dans la liste des comptes, il faut tout d'abord identifier le compte API et cliquer sur la ligne du tableau afin d'afficher les détails et habilitations de ce compte.

La section API habilitées liste l'ensemble des API ainsi que les valeurs associées aux différents champs à renseigner.

Pour saisir ou modifier les valeurs, cliquer sur le bouton «Modifier» sous le nom de l'API.

Deux données sont modifiables pour chaque API :

  • url : il s’agit de l’adresse commune des endpoints qui doivent être exposés pour recevoir les appels retours de la Douane

    • le nom de domaine devra au préalable avoir été ouvert sur le réseau de la Douane,
    • pour cela adresser une demande à l’adresse de contact Douane de l’API concernée ;
    • le changement d’une URL n’est pas pris en compte immédiatement mais au plus tard au bout de 4h, toute modification devra donc être préparée avec le contact Douane de l’API concernée pour éviter toute rupture de service.

  • token : c’est le jeton d’authentification vers le SI opérateur

    • le changement d’une URL n’est pas pris en compte immédiatement mais au plus tard au bout de 15 minutes, toute modification devra donc être préparée avec le contact Douane de l’API concernée pour éviter toute rupture de service.

Si une API nécessite plus de données complémentaires, il convient de se référer à la documentation spécifique à l’utilisation de cette API.

Après avoir enregistré, le compte API passe en vert au niveau du tableau. Cela signifie que ce compte technique est prêt à être utilisé.

Modification du compte api

Depuis l'interface ci-dessous, il est possible au correspondant entreprise de modifier les informations suivantes concernant le compte :

  • Email : Cette adresse servira pour notifier les administrateurs du compte API de changements ou d’incidents.
  • Mot de passe

La modification du mot de passe par le correspondant entreprise est une opération pouvant impacter l'utilisation du compte API par des tiers s’ils ne sont pas synchronisés sur ce changement. Avant cette opération, le correspond entreprise doit s'assurer que le changement, à effet immédiat, est pris en compte de manière synchronisée avec tous les systèmes informatiques qui utilisent ce compte API.

Le compte API est un compte douane.gouv (anciennement appelé compte Prodouane). Le changement de mot de passe, la fréquence de renouvellement, l’information aux clients et la bonne synchronisation du changement du mot de passe relèvent de la responsabilité de l’opérateur. Les opérateurs doivent se conformer aux bonnes pratiques concernant la gestion des mots de passe.

Source : https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/4256563201