markdown 通过API Mapado实现活动

Posted 2021-05-05

Pour tout ce qui est "activité", le mieux est de passer par l'API "media" dont [la doc se trouve ici](https://api.mapado.net/v2/docs).

Voici quelques détails à savoir :

- il y a différents types d'activités, par exemple les activités et les places (qui sont des fiches lieux). Les activités peuvent être rattachées à une place. Tous sont accessibles depuis /v2/activities.
- l'identifiant d'une activité/place est le champs apiSlug. Il correspond théoriquement à l'url sur mapado.com, en remplaçant le slash par un double tiret (c'est généralement le cas, mais pas garanti). Par exemple pour https://www.mapado.com/villeurbanne/le-transbordeur-3 , l'apiSlug sera /v2/activities/villeurbanne--le-transbordeur-3 .
- concernant l'adressHash, vous pouvez utiliser celle ci dans vos tests si vous ne souhaitez pas renseigner de place : 0ed43aaaf869fd554257e95963335120 .

Voici la liste des champs disponibles pour la création d'activités :

- title
- description
- imageList : est une liste de path d'image (je vous ai mis l'appel CURL pour les générer plus bas)
- place : apiSlug du lieu (activité de type place) ou se déroule l'activité.
- priceList : liste des tarifs affichés sur mapado. A savoir que ce champs facilite grandement l'activation de la billetterie car ces tarifs seront proposés lors de l'activation de la billetterie sur cette événement
- formattedSchedule : la ou les dates de l'activité. L'API est assez tolérante et accepte des valeurs comme "30/01/2020. 15/02/2020." , mais aussi des textes plus complexes tel que "le 13 janvier" ou "du 14 au 18 février 2019 à 15h"
- addressHash : l'adresse ou se déroule l'activité. Cette adresse sera affichée sur les fiches sur mapado.com, en revanche, si l'activité possède une place, l'adresse de la place sera utilisée/affichée en priorité.

Les champs obligatoires sont : `title`, `description` et `formattedSchedule`.

Voici un exemple CURL d'upload d'image, afin d'en récupérer le path (à envoyer dans imageList) :

```sh
curl 'https://www.mapado.com/image/upload/?width=160&height=100' \
  -H 'Origin: https://www.mapado.com' \
  -H 'Content-type: application/x-www-form-urlencoded' \
  -H 'Accept: */*' \
  -H 'Referer: https://www.mapado.com/create-activity' \
  -H 'X-Requested-With: XMLHttpRequest' \
  -H 'Connection: keep-alive' \
  --data 'url=IMAGE_URL'\
  --compressed
```

Je vous joins également un exemple CURL complet et fonctionnel pour créer une activité :

```sh
curl --request POST \
  --url 'https://api.mapado.net/v2/activities.json?fields=title%2Cdescription%2CimageList%2CaddressHash%2CformattedSchedule%2CpriceList%2Cplace' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
	"title": "L'\''Autruche et le Petit Relou",
	"description": "Au cœur du pays des mille forêts d'\''où viennent toutes les histoires a lieu une tragédie sans précédent...",	
	"imageList": [
            "2018/7/12/5b4705a59893a-4341412.jpg"
	],
	"addressHash": "0ed43aaaf869fd554257e95963335120", 
	"formattedSchedule": "25/12/2020. 01/01/2021.", 
	"priceList": [
		{
			"type": "default",
			"value": 1000,
			"currency_code": "EUR",
			"name": "Tarif de test",
			"description": "Ceci est la description inutile du tarif de test"
		},
		{
			"type": "reduced",
			"value": 500,
			"currency_code": "EUR",
			"name": "Tarif de test numéro 2",
			"description": "Ceci est la description inutile du tarif de test numéro 2"
		}
	],
	"place": "/v2/activities/privas--theatre-de-la-chataigne-dor"
}'
```

Pour éditer une activité, il faut faire un appel avec la méthode `PATCH` sur l'url de l'activité, 
par exemple `https://api.mapado.net/v2/activities/mapado-city--my-activity.json?fields=title`
qui permet de ne mettre à jour qu'une partie de l'activité si vous le désirez.

L'endpoint reprend la signature de la création d'activité.

Les valeurs qui ne sont pas passées ne seront pas impactées dans l'activité de base. (si elles sont passées à `null`, elles seront bien mises à null par contre)

[documentation](https://api.mapado.net/v2/docs#operation/patchActivityItem)

Pour info, les modifications sont mises en cache sur Mapado, du coup, il faut quelques heures avant que les modifications soient visibles. (Il n'y a pas de cache sur l'API cela dit).

Pour ce qui est de la suppression d'activités, il suffit de faire un PATCH classique en mettant le nouveau champs `trashStatus` à "trashed" (ainsi qu'en ajoutant le field trashStatus dans l'url). 

De cette manière elle ne sera plus visible sur mapado.com grand public et se retrouvera dans la corbeille sur votre espace pro ( https://www.mapado.com/admin/activities?trash=1 ) . 

L'activité reste également disponible via l'API en GET mais avec le champs `&trashStatus=trashed`.

Ci-dessous un exemple CURL pour supprimer une activité :

```sh
curl --request PATCH \
  --url 'https://api.mapado.net/v2/activities/lyon--my-activity.json?fields=trashStatus' \
  --header 'authorization: Bearer MY_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
	"trashStatus": "trashed"
}
'
```