{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"45a1c51b-e735-4e4e-9eef-26777e77188d","name":"Documentation technique","description":"Bienvenue sur la documentation technique de Publidata !\n\n# La plateforme\n\nPublidata est une plateforme de gestion de l’information permettant d’administrer les types de données suivantes :\n\n- Villes (city)\n- Départements (department)\n- Régions (region)\n- Etablissements publics (etablissement_public)\n- Élu.e.s (elect)\n- Équipements (facility)\n- Artistes (performer)\n- Compétences des organisations (skill)\n- Services (service)\n - Collectes des déchets (waste_collection)\n - Menus des cantines (canteen_menu)\n - Formations (formation)\n - etc.\n- Actualités (news)\n- Evénements (event)\n- Groupes d'événements (event_group)\n- Projets (project)\n \n\n\"\"\n\nChaque type de données est interreliées aux autres par un mécanisme de relation automatique (un événement a lieu dans un équipement qui est lui même géré par une organisation, dans une ville, d’une agglomération etc.) et de relation déclarative (une actualité parle d’un événement, d’un lieu etc.).\n\nToutes ces informations sont restituées par API au travers de dispositifs et chaque fiche renseignée dans Publidata peut être associée et diffusée sur un ou plusieurs dispositifs.\n\n**Exemple :** la fiche Théâtre a été associée / diffusée sur l’application mobile de Dreux (géré par Neocity), sur le site Internet (géré par Proximit) et sur Google My Business.\n\n# Les dispositifs\n\nLes applications développées sur Publidata sont stockées sous la forme de dispositifs (aka des instances) et chaque fiche présente dans Publidata peut être associée et diffusée sur un ou plusieurs dispositifs.\n\n**La liste des dispositifs :** [https://www.publidata.io/instances](https://www.publidata.io/instances)\n\nChaque dispositif est accessible en API via un endpoint namespacé.\n\n_Exemple :_ [https://api.publidata.io/v2/dreux-application-mobile/events](https://api.publidata.io/v2/dreux-application-mobile/events)\n\n\"\"\n\n# Importation des données\n\nL'importation de données dans Publidata peut être réalisé de deux manières :\n\n- via des solutions tierces type OpenDataSoft / ESRI (SIG) etc. avec lesquelles nous sommes interconnectés en lecture / écriture\n- via des fichiers sources (CSV/XLS/JSON etc.)\n \n\n# S'interconnecter avec Publidata\n\nPour s'interconnecter avec Publidata, via nos API, et réutiliser les informations saisies sur la plateforme nous vous recommandons :\n\n1. D'avoir un compte vous permettant d'accéder à la plateforme et de paramètrer votre [dispositif](https://docs.publidata.io/?version=latest#les-dispositifs).\n2. D'utiliser la [version 2 ⭐](https://docs.publidata.io/?version=latest#627fd224-23a2-44a6-8bc0-6aab55c1b90b) de nos API.\n3. De contacter nos développeurs à l'adresse [tech@publidata.io](mailto:tech@publidata.io), par chat sur la plateforme Publidata ou via notre Slack afin qu'ils vous accompagnent dans la mise en place de votre projet d'interconnexion.\n \n\n### I. Interconnexion classique (SEO)\n\nL'interconnexion classique consiste à copier entièrement les enregistrements récupérés via nos API dans vos bases de données afin de ne pas provoquer de latence lors de la consommation des pages par les visiteurs du site et ainsi optimiser votre référencement SEO.\n\n🔗️ Les endpoints d'API à utiliser sont : [http://publidata.io/api/v2/{nom-de-l-instance}/{type-d-enregistrement}](http://publidata.io/api/v2/{nom-de-l-instance}/{type-d-enregistrement}) (exemple : [https://api.publidata.io/v2/tmvl-agenda/events](https://api.publidata.io/v2/tmvl-agenda/events))\n\nPour cela nous préconisons 2 modes :\n\n**1\\. Interconnexion par import cyclique**\n\nL’importation cyclique consiste à importer à interval régulier (ex : x fois par jour, idéalement en heures creuses) les enregistrements disponibles par API en réalisant des opérations de création, mise à jour et suppression.\n\nCe mode d’interconnexion nécessite une gestion du côté agence / prestataire des différences sur les enregistrements via les timestamps (created_at et updated_at) et en cas d’absence d’un enregistrement retournés précédemment sur nos API.\n\nNous ne recommandons néanmoins par ce mode d’interconnexion car il ne permet pas la mise à jour temps-réel des pages et informations présentes sur le site.\n\n**2\\. Interconnexion temps-réel / par webhooks (notre recommandation)**\n\nL’interconnexion temps-réel consiste à la mise en place d’une url côté agence / prestataire qui sera appelée lors de chaque modification opérée sur les fiches diffusés sur le dispositif.\n\nCes instructions sont appelées webhook et prennent la forme d’une requête POST comprenant les paramètres suivants :\n\n- action : type d'action (create / update / destroy)\n- instance : slug de l'instance du dispositif\n- type : type de l'objet (event / news / facility etc.)\n- id : uuid de l'objet\n \n\nCf : [Les webhooks](https://docs.publidata.io/?version=latest#webhooks)\n\nDe cette manière, une modification réalisée sur la Plateforme est communiquée instantanément à l’ensemble des réutilisateurs qui peuvent déclencher, selon l’action présente dans le webhook, la mise à jour de l’enregistrement.\n\n**A noter que :** de votre côté, nous vous recommandons d'implémenter un gestionnaire de queue / background jobs qui sera chargé de stocker les instructions reçues par les webhooks et de les traiter au fur et à mesure.\n\n### II. Interconnexion pour la recherche (Elasticsearch)\n\nPour une application ou page dédiée à la recherche via un champ texte, des filtres (dates, lieux, types, thèmes, tags etc.) ou des critères géographiques nous vous recommandons d'utiliser directement nos API de recherche Elasticsearch.\n\nCette méthode d'interconnexion privilégie la rapidité tout en permettant des requêtes facettées pouvant être complexe.\n\n🔗 Les endpoints d'API à utiliser sont : [http://publidata.io/api/v2/search](http://publidata.io/api/v2/search) (exemple : [https://api.publidata.io/v2/search?instances\\[\\]=64&types\\[\\]=events](https://api.publidata.io/v2/search?instances[]=64&types[]=events))\n\n⚠️ Le format des enregistrements retournés par cette API est différent de celui-ci proposé par l'interconnexion classique.\n\nLa documentation complète de cette API est disponible à cette adresse : [https://docs.publidata.io/?version=latest#9cc02e83-edb1-4aec-a3ce-1ceaca9e20f3](https://docs.publidata.io/?version=latest#9cc02e83-edb1-4aec-a3ce-1ceaca9e20f3)\n\n# Webhooks\n\n### Principe\n\nAfin de prévenir les réutilisateurs d'un contenu présent sur Publidata nous vous donnons la possibilité d'attacher à chaque dispositif des urls cibles sur laquelle / lesquelles nous vous enverrons une requête de type « webhook » pour vous informer lors de chaque modification (création, modification, suppression).\n\nLes requêtes envoyées prennent la forme d'une requête POST prenant la forme suivante :\n\n\\[POST\\] `https://www.mon-site.com/hooks` (Content-Type: application/json)\n\n```\n{\n \"action\": \"update\",\n \"type\": \"facility\", \n \"id\": \"y7KpS6Dgxv\",\n \"instance\": 1\n}\n\n```\n\n### Propriétés\n\n- `action` (type de modification) :`create`, `update`, `destroy`.\n- `type` (d'enregistrement) : `city`, `company`, `department`, `elect`, `etablissement_public`, `event_group`, `event`, `facility`, `news`, `non_profit`, `performer`, `project`, `region`, `skill`, `service`, `page`.\n- `id` (idenfiant de l'enregistrement) : `y7KpS6Dgxv`.\n- `instance`: (identifiant de mon dispositif).\n \n\n### Utilisation\n\nℹ️ Pour mettre en place les webhooks nous vous recommandons de nous solliciter (par mail à [tech@publidata.io](mailto:tech@publidata.io) ou via le chat présent dans la plateforme) afin d'obtenir le rôle agence / prestataire qui vous ouvrira les droits à des fonctionnalités supplémentaires vous permettant de déclencher manuellement l'envoi de webhooks.\n\n1. Mettre en place une url sur votre dispositif (site, back-office, cms) pour recevoir les webhooks. Le format de votre url est libre néanmoins le contenu envoyé sera toujours une requête POST avec les propriétés énoncées ci-dessus.\n2. Ajouter l'url que vous venez de créer dans la rubrique webhooks de votre dispositif (dans Publidata à cette adresse : [http://publidata.io/instances](http://publidata.io/instances)) ou contacter un administrateur à [tech@publidata.io](mailto:tech@publidata.io).\n3. Mettez à jour une fiche dans Publidata pour vérifier le bon fonctionnement.\n \n\n# Support\n\nPour toute question ou précision n'hésitez pas à nous contacter via [tech@publidata.io](mailto:tech@publidata.io) ou via le chat présent dans la plateforme.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"3604358","team":99236,"collectionId":"45a1c51b-e735-4e4e-9eef-26777e77188d","publishedId":"RznBLfDq","public":true,"publicUrl":"https://docs.publidata.io","privateUrl":"https://go.postman.co/documentation/3604358-45a1c51b-e735-4e4e-9eef-26777e77188d","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"0075F1"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2023-01-24T12:52:49.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/be0121d7988b4484e6ae0776b6a8e350b9694c9f5f5f0d7f88816b6b7252b684","favicon":"https://res.cloudinary.com/postman/image/upload/v1579194309/team/klgdn9c4bwrq6npkmhn0.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://docs.publidata.io/view/metadata/RznBLfDq"}