Mise à jour d'un champ d'une offre

Introduction

Notre client l'ADT 79 nous demande de modifier le type d'équipement de l'hôtel d'identifiant "HOTAQU000V501RBS" en "Hôtel-Restaurant" au lieu de "Hôtel".
Pour celà, il nous a fourni des clés d'authentification :

client_id : $1$cdt79.tourinsoft.com
client_secret: test

1. Récupération du token d'authentification

La première étape consiste à récupérer un token pour pouvoir accéder aux apis sécurisées. Pour celà, nous effectuons un appel au /token en mode client_credentials

GET /token

application/x-www-form-urlencoded

Exemple:

    POST /token HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    Host: api-v3.tourinsoft.com
    Connection: Keep-Alive
    grant_type=client_credentials&client_secret=secret&client_id=%241%24cdt79.tourinsoft.com

Réponse :

On récupère ainsi l' access_token qui va nous permettre d'authentifier toutes nos requêtes.

application/json, text/json

Exemple:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
X-Powered-By: ASP.NET
Date: Thu, 18 Jul 2019 15:05:49 GMT
{
    "access_token": "TOKEN",
    "token_type": "bearer",
    "expires_in": 86399
}

2. Récupération de l'identifiant du bordereau Hôtel

Maintenant que nous avons récupéré le token, nous allons rechercher l'identifiant du bordereau Hôtel. Pour cela, on va utiliser l'api Bordereaux en ne sélectionnant que les propriétés qui nous intéressent (id, title et code) comme suit et récupérer l'identifiant dans la réponse :

GET /api/bordereaux

application/json

Exemple:

    GET /api/bordereaux?fields=id,title,code HTTP/1.1
    Content-Type: application/json
    Host: api-v3.tourinsoft.com
    Accept-Encoding: gzip,deflate
    Authorization: Bearer TOKEN
    Connection: Keep-Alive

Réponse :

application/json, text/json

Exemple:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
X-Powered-By: ASP.NET
Date: Thu, 18 Jul 2019 15:05:49 GMT
[
    
    {
        "id": "19E17AF0-4680-4B1B-886A-BC147C3DDAE1",
        "title": "Fêtes et manifestations",
        "code": "FMA"
    },
    {
        "id": "3FC42F0F-6AA1-43A6-B694-E4FFDC505ACE",
        "title": "Hébergements locatifs (meublés et chambres d'hôtes)",
        "code": "HLO"
    },
    {
        "id": "1E8DC626-51A5-4ADF-9637-8E14925C1B6F",
        "title": "Hôtels",
        "code": "HOT"
    },
    {
        "id": "19CF534C-C722-405A-8021-3007CA115CF6",
        "title": "Patrimoine culturel",
        "code": "PCU"
    },
    {
        "id": "06ABA3B8-E254-4933-9593-117F61236D78",
        "title": "Patrimoine naturel",
        "code": "PNA"
    }
]

3. Récupération de l'identifiant du champ à mettre à jour

Nous connaissons l'identifiant du bordereau Hôtel ("1E8DC626-51A5-4ADF-9637-8E14925C1B6F"), nous allons donc à présent rechercher les infos sur le champ à modifier. Pour cela, nous allons rechercher l'information dans les metadata du bordereau Hôtel.

GET /api/bordereaux/{bordereauId}/metadata

application/json

Exemple:

    GET /api/bordereaux/1E8DC626-51A5-4ADF-9637-8E14925C1B6F/metadata?fields=children/children(key,title,children(key,metaType,listeId,title,acces)) HTTP/1.1
    Content-Type: application/json
    Host: api-v3.tourinsoft.com
    Accept-Encoding: gzip,deflate
    Authorization: Bearer TOKEN
    Connection: Keep-Alive

Réponse :

application/json, text/json

Exemple:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
X-Powered-By: ASP.NET
Date: Thu, 18 Jul 2019 15:05:49 GMT
{
    "children": [
        {
            "children": [
                {
                    "key": "46c",
                    "title": "Type d'équipement",
                    "children": [
                        {
                            "metaType": 5,
                            "listeId": "CA027769-8FA8-41BF-8B25-3F58D2B50F8C",
                            "key": "2s",
                            "title": "Type d'équipement",
                            "acces": 2
                        }
                    ]
                },
                {
                    "key": "4bu",
                    "title": "Classement",
                    "children": [
                        {
                            "metaType": 5,
                            "listeId": "6EF1C2F4-E0E2-42EB-B109-2A307B35DE57",
                            "key": "w1",
                            "title": "Classement",
                            "acces": 2
                        },
                        {
                            "metaType": 9,
                            "listeId": null,
                            "key": "8qt",
                            "title": "CAS 1",
                            "acces": 2
                        },
                        {
                            "metaType": 9,
                            "listeId": null,
                            "key": "8qu",
                            "title": "CAS 2",
                            "acces": 2
                        },
                        {
                            "metaType": 8,
                            "listeId": null,
                            "key": "8qv",
                            "title": "Cas 3",
                            "acces": 2
                        },
                        {
                            "metaType": 1,
                            "listeId": null,
                            "key": "8qw",
                            "title": "Descriptif classement",
                            "acces": 2
                        }
                    ]
                }
            ]
        }       
    ]
}

Nous avons donc nos informations via le premier noeud : rubrique "46c" et champ "2s". On constate que nous avons bien un accès en Modification (acces=2) sur le champ et que ce champ est un champ de type Liste (metaType=5). Pour mettre à jour ce champ, il faut connaître les valeurs que l'on peut lui affecter.

4. Récupération de l'id de l'item "Hôtel-Restaurant"

L'identifiant de l'item de liste "Hôtel-Restaurant" peut être récupérer en interrogeant l'api listes

GET /api/listes/{listeId}/items

application/json

Exemple:

    GET /api/listes/CA027769-8FA8-41BF-8B25-3F58D2B50F8C/items?fields=id,libelle HTTP/1.1
    Content-Type: application/json
    Host: api-v3.tourinsoft.com
    Accept-Encoding: gzip,deflate
    Authorization: Bearer TOKEN
    Connection: Keep-Alive

Réponse :

application/json, text/json

Exemple:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
X-Powered-By: ASP.NET
Date: Thu, 18 Jul 2019 15:05:49 GMT
[
    {
        "id": "44e4e652-17c7-4d9d-b650-4d391e09686f",
        "libelle": "Hôtel"
    },
    {
        "id": "e7a46519-7433-4bd0-ac66-6d2453f1cbed",
        "libelle": "Hôtel - Restaurant"
    }
]

Nous avons récupéré l'identifiant de l'item que l'on va devoir renseigner. Une dernière étape avant de procéder à la mise à jour : récupérer l'identifiant de l'occurrence à mettre à jour.

5. Récupération de l'id d'occurrence à mettre à jour

L'identifiant de l'occurrence à mettre à jour se récupère en interrogeant l'api Offres. Cette api retournant des objets pouvant être volumineux, il est utile de filtrer le résultat à l'aide de l'opérateur fields. Ici, on recherche l'id d'occurrence pour la rubrique "46c" dont la valeur du champ "2s" est égale à "44e4e652-17c7-4d9d-b650-4d391e09686f" (l'item "Hôtel")

GET /api/offres/{offreId}

application/json

Exemple:

    GET /api/offres/HOTAQU000V501RBS?fields=rubriques/46c/occurrences/*/champs/2s HTTP/1.1
    Content-Type: application/json
    Host: api-v3.tourinsoft.com
    Accept-Encoding: gzip,deflate
    Authorization: Bearer TOKEN
    Connection: Keep-Alive

Réponse :

application/json, text/json

Exemple:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
X-Powered-By: ASP.NET
Date: Thu, 18 Jul 2019 15:05:49 GMT
{
    "rubriques": {
        "46c": {
            "occurrences": {
                "226710281600000014": {
                    "champs": {
                        "2s": {
                            "value": "44e4e652-17c7-4d9d-b650-4d391e09686f"
                        }
                    }
                }
            }
        }
    }
}

L'identifiant de l'occurrence à mettre à jour sera donc "226710281600000014". Cette fois nous avons toutes les informations, on peut mettre à jour notre champ :

6. Mise à jour du champ

Nous allons désormais procéder à la mise à jour du champ :

PUT /api/offres/{offreId}/rubriques/{rKey}/occurrences/{occId}/champs/{cKey}

application/json

Exemple:

    PUT /api/offres/HOTAQU000V501RBS/rubriques/46c/occurrences/226710281600000014/champs/2s HTTP/1.1
    Content-Type: application/json
    Host: api-v3.tourinsoft.com
    Accept-Encoding: gzip,deflate
    Authorization: Bearer TOKEN
    Connection: Keep-Alive
{
	"typeChamp": 5,
	"langue": "fr-FR",
	"valeur": "e7a46519-7433-4bd0-ac66-6d2453f1cbed"
}

Réponse :

application/json, text/json

Exemple:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/10.0
Access-Control-Allow-Origin: *
X-Powered-By: ASP.NET
Date: Thu, 18 Jul 2019 15:05:49 GMT
{
	"typeChamp": 5,
	"langue": "fr-FR",
	"valeur": "e7a46519-7433-4bd0-ac66-6d2453f1cbed"
}

Il est possible que vous rencontriez un message d'erreur comme un code 409 qui vous indique que l'offre ne peut pas être modifiée au moment de l'appel car elle est en cours de modification par une autre personne. Dans ce cas précis, il faut mettre en place une temporisation de quelques minutes et retenter l'opération.