04_Publication_BAL - BaseAdresseNationale/api-depot GitHub Wiki

Comment publier une BAL

La mise à jour des adresses d'une commune est réalisée par le dépôt d'une nouvelle BAL qui écrase l'ancienne. Dans l'API, cette opération est appelée revision. Chaque commune dispose de 0 ou plusieurs revisions qui ont été publiées par différents clients habilités sur son territoire. La création d'une revision suit le processus suivant :

  • Étape 1 : création de la revision avec contexte d'authentification
  • Étape 2 : téléversement du fichier au format BAL 1.3 ou 1.4
  • Étape 3 : validation
  • Étape 4 : soumission finale de la revision et prise en compte effective de la BAL

4 requêtes HTTP successives sont nécessaires pour réaliser le processus en entier.

Authentification

Puisque l'authentification de l'utilisateur est déléguée au client de l'API, il est de la responsabilité du client de l'API de fournir un contexte lors de la publication d'une BAL. Chaque client de l'API dispose d'un token permanent, qui pourra être renouvelé à la demande. Il doit être conservé de façon sécurisée.

Le jeton doit être passé à l'API via l'en-tête HTTP Authorization.

Exemple : Authorization: Bearer f66gdjfehfv66DBD

Étape 1 : création de la revision avec contexte d'authentification

Lors de la création d'une revision, vous aurez besoin :

  • du token (jeton)
  • du codeCommune
  • le contexte utilisateur doit être renseigné. Il est composé de 3 champs optionnels (mais fortement recommandés) :
    • Nom de la personne nomComplet qui effectue le dépôt.
    • Nom de l'organisation organisation
    • Champs libre clé/valeur extras : peut-être utilisé pour stocker des identifiants internes au client, des données additionnelles - actuellement non supportées par l'API, mais jugées utiles par l'éditeur. Attention ces champs sont publiques.

Requète:


POST  /communes/27115/revisions                  --> Obligatoire
​
# Header
Authorization: Token xxxxxxxxxxxxxxxxx           --> Obligatoire
Content-Type: application/json
​
# Body
{
  "context": {
    "nomComplet": "Alice Bob",          --> Optionnel mais recommandé
    "organisation": "Mairie de Breux-sur-Avre",  --> Optionnel mais recommandé
    "extras": {
      "internal_id": "9990"
    }                                            --> Optionnel
  }
}

Réponse:

# Header
Content-Type: application/json

# Body
{
  "id": "507f191e810c19729de860ea"               --> revisionId pour l'étape 2,3 et 4
  "codeCommune": "27115",
  "context": {
    "nomComplet": "Alice Bob"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {},
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[email protected]"
  },
  "status": "pending",
  "isReady": false,
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": null
}

Étape 2 : téléversement du fichier au format BAL 1.3 ou 1.4

  • Pour le téléversement, vous aurez besoin : du token, de la revisionId et du fichier BAL.
  • En option : le Content-Length du fichier et sa signature MD5

Requète:

PUT /revisions/507f191e810c19729de860ea/files/bal --> Obligatoire
​
# Header
Authorization: Token xxxxxxxxxxxxxxxxx            --> Obligatoire
Content-Type: text/csv
Content-Length: 2133                              --> Optionnel mais recommandé
Content-MD5: 1234567890abcdedf1234567890abcdedf   --> Optionnel mais recommandé
​
# Body (Binary)
@@@ fichier BALC @@@                              --> Obligatoire, taille max 50mb

Réponse:

200 Success
​
# Header
Content-Type: application/json
​
# Body
{
  "id": "507f199710c19729de860ea",            --> Identifiant du fichier
  "revisionId": "507f191e810c19729de860ea",   --> Identifiant de révision
  "type": "bal",
  "size": 2133,
  "hash": "51ca0bce566423b6c5a321e911438c57195adf747d066e0dd4b212d43c0f4c6e",
  "createdAt": "2020-01-01T00:00:00Z"
}

Étape 3 : validation

Pour la validation, vous aurez besoin du token, de la revisionId Vous pouvez vérifier vos BAL directement avec le validateur BAL en ligne ou via le validateur BAL api

Requète:

POST  /revisions/507f191e810c19729de860ea/compute       --> Obligatoire

# Header
Authorization: Token xxxxxxxxxxxxxxxxx                  --> Obligatoire

Réponse :

200 Success

# Header
Content-Type: application/json

# Body
{
  "id": "507f191e810c19729de860ea"
  "codeCommune": "27115",
  "context": {
    "nomComplet": "Alice Bob"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[email protected]"
  },
  "status": "pending",
  "isReady": true,
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": null
}

Si le fichier soumis n'est pas valide, la valeur isReady reste à false et validation.valid est false.

Étape 4 : publication de la revision

  • Pour la publication vous aurez besoin du token, de la revisionId
  • Lorsque isReady :true la revision peut être publiée.

Requète:

POST  /revisions/507f191e810c19729de860ea/publish   --> Obligatoire

# Header
Authorization: Token xxxxxxxxxxxxxxxxx              --> Obligatoire

Réponse :

200 Success

# Header
Content-Type: application/json

# Body
{
  "id": "507f191e810c19729de860ea"
  "codeCommune": "27115",
  "context": {
    "nomComplet": "Alice Bob"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[email protected]"
  },
  "status": "published",
  "isCurrent": true,     
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": "2020-01-01T01:00:00Z"
}

Si isCurrent : true alors la BAL est en production !

Tester que la BAL est publiée

Deux route pour vérifier que votre publication a bien été prise en compte Vous n'avez pas besoin de token pour cette partie

Vérifier la Révision

  • Pour récupérer la révision courant vous aurez besoin du codeCommune

Requète:

GET  /communes/27115/current-revision   --> Obligatoire

Réponse:

200 Success

# Header
Content-Type: application/json

# Body
{
  "id": "507f191e810c19729de860ea"
  "codeCommune": "27115",
  "context": {
    "nomComplet": "Alice Bob"
    "organisation": "Mairie de Breux-sur-Avre",
    "extras": {
      "internal_id": "9990"
    }
  },
  "validation": {
    "valid": true,
    "errors": []
  },
  "client": {
    "name": "Éditeur d’adresses",
    "email": "[email protected]"
  },
  "status": "published",
  "isCurrent": true,     
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-01T00:00:00Z",
  "publishedAt": "2020-01-01T01:00:00Z"
}

Vérifier que les informations retourné (id, publishedAt et codeCommune) sont bien les mêmes que vous avez obtenu en réponse a la publication /revisions/{id}/publish

Vérifier le fichier BAL

  • Pour récupérer le fichier de la révision courant vous aurez besoin du codeCommune

Requète:

GET  /communes/27115/current-revision/files/bal/download   --> Obligatoire

Cela devrait vous renvoyé exactement le même fichier que vous avez uploadé dans l'étape 2 de la publication