API Documents - gestion du partage documentaire

API Documents - gestion du partage documentaire

API Documents - gestion du partage documentaire

Des fichiers de nombreux types (pdf, doc, ...) peuvent être partagés sur la plateforme.
intentPlatform vous propose un service de partage de document.

Méthodes

intentPlatform vous permet de réaliser plusieurs actions sur les documents :
  • Ajouter - Partager
  • Consulter
  • Télécharger
  • Modifier
  • Supprimer
Actions
Verbe
Route
Ajouter un document
POST
/api/documents/v1/documents
Rechercher un document
GET
/api/documents/v1/documents
Consulter les caractéristiques d'un document par son identifiant technique
GET
/api/documents/v1/documents/{id}
Télécharger un document
GET
/api/documents/v1/documents/{id}/download
Modifier un document
PATCH
/api/documents/v1/documents/{id}
Supprimer un document
DELETE
/api/documents/v1/documents/{id}

Description des champs

Champs
Description
Exemple
title*
Titre du document
quitus2732B.pdf
elementType*
Ressource sur laquelle le document est lié
intervention
elementReference*
Référence de la ressource liée au document
inter-2020TX
description
Description du document
Quitus d'intervention en date du 23/01/2020
intent_creationDate
Date de création du document
2017-02-21T07:45:56
intent_expirationDate
Date d'expiration du document
2021-03-01
intent_contractReference
Référence du contrat sur lequel le document est rattaché
contract_001
*champ obligatoire
Un document doit être rattaché à une ressource via le champ "elementType" :
Ressource
Exemples de document
Patrimoine (asset)
Règlement intérieur, diagnostic amiante, diagnostic énergétique, guide d'utilisation, rapport d'installation, guide technique ...
Operations (intervention, quotation, reservation, request, ticket)
Quitus d'intervention, devis, photographie ...
Contrat (contract)
Version électronique du contrat, CCTP, avenants ...
Ajout d'informations complémentaires

Vous pouvez ajouter des informations complémentaires à votre document en ajoutant des tags libres avec un couple "clé : valeur". Par exemple :
  • type : diagnostic amiante
  • source : application amiante 2000
Format de date ISO-8601

IntentPlatform utilise des dates au format ISO-8601
 https://fr.wikipedia.org/wiki/ISO_8601 
 https://www.iso.org/iso-8601-date-and-time-format.html 

Pour information :
Lorsqu'une date est postée au format : 2017-10-25T02:30:53Z → alors le Z signifie qu'il s'agit du fuseau horaire UTC

Comme indiqué dans la documentation spécialisée, il est aussi possible d'écrire la date sous la forme : 2017−10−25T02:30:53+01:00
→ ce qui implique un fuseau UTC + 1h00 (soit la France, à l'heure d'hiver)

Cela étant, puisque la grande majorité des utilisateurs IntentPlatform sont en France, nous avons mis en place un mécanisme permettant de lire un format du type 2017-10-25T02:30:53 comme étant une date basée sur le fuseau Central European Time : CET / Paris.

Import

Pour importer les documents, nous proposons deux protocoles :
  • via une route API d'import
  • via serveur FTP sur lequel IntentPlatform viendra régulièrement récupérer les fichiers
La taille maximale d'un fichier est de 100Mo.

Import via API

Requêtes

Url de la requête

En-tête requête HTTP

La transmission des fichiers via l'API Documents se réalise en utilisant, dans le Header de la requête, un "Content-Type: multipart/form-data"

Réponse

Si le document a correctement été posté sur intentPlatform, vous recevrez une réponse 201.

Import via FTP

Pour nous transmettre des fichiers via un serveur FTP, vous devez mettre à disposition :
  • le serveur FTP avec les fichiers (rangés dans votre arborescence)
  • l'adresse de votre serveur FTP, ainsi que les identifiants de connexion
  • un fichier de déclaration au format csv
Extension du fichier et encodage

Les fichiers de déclaration des documents doivent être au format csv. L'extension des fichiers soit être ".csv" en minuscule et pas en majuscule.

Les fichiers doivent être encodés en UTF-8 afin que les caractères spéciaux (é,à,è, etc.) soient correctement pris en compte dans intentPlatform.
Hébergement du serveur FTP ou SFTP

Le serveur FTP ou SFTP doit être hébergé et maintenu par vos soins.

Fichier de déclaration

Attribut
Description
Exemple
fileFullPath*
Le chemin d'accès au fichier, depuis la racine du FTP
/01/001/quitus.pdf
elementType*
asset : pour un élément de patrimoine
intervention : pour une demande d'intervention et un ticket d'intervention
quotation : pour un devis
reservation : pour une réserve
contract : pour un contrat
intervention
elementRef
Référence de la ressource liée au document
inter-2020TX
title
Titre du document
CR d'intervention du 27/01/2017
description
Description du document
Chez Madame Dupont
intent_contractReference
La référence du contrat sur lequel le document sera partagé
XLF-2020-04
intent_creationDate
La date à laquelle le fichier a été créé (ISO-8601)
2017-02-21
intent_expirationDate
La date jusqu'à laquelle le fichier est valable (ISO-8601)
2021-03-01
Tags libres
L'ensemble des tags ou mots-clefs de description du fichier
type : diagnostic
*champ obligatoire
Le fichier ci-dessous donne un exemple de ce qui est attendu.
Les 2 premières lignes en rouge du fichier sont à caractères informatives. Elles ne sont pas à indiquer dans le fichier transmis sur le serveur.