Index par titre

API

Usage Méthode Chemin
pousser un document POST /api/documents/push/
liste des documents récents GET /api/documents/recently-added/
valider le hash d'un document POST /api/validation/<document-type>/
lister les validations de documents GET /api/validation/<document-type>/?user_nameid=YYY
autoriser un jeton OAuth2 de récupération de document GET /api/oauth2/get-document/authorize
obtenir un jeton OAuth2 de récupération de document GET /api/oauth2/get-document/token
récupérer un document avec un jeton OAuth2 GET /api/oauth2/get-document/
pousser un document temporaire via OAuth2 POST /api/oauth2/put-document/
faire accepter un document temporaire via OAuth2 GET /api/oauth2/put-document/<document-pk>/authorize/

Pousser un document

Requête

POST /api/documents/push/ HTTP/1.1
Content-Type: application/json
Content-Size: xxx


{
   "user_nameid": "YYYY",
   "origin": "mairie de yyy - service enfance",
   "file_b64_content": "contenu du fichier en base64",
   "file_name": "nom du fichier",
   "deletable_by_user": true,
}
Champ du contenu Usage
user_nameid l'identifiant Publik de l'utilisateur
origin l'origine du fichier, ex.: le nom d'une entité administrative
file_b64_content le contenu du fichier sous forme de chaîne encodée en base64
file_name le nom du fichier
deletable_by_user booléen, est-ce que le fichier peut-être supprimer par l'utilisateur ou n'est pas sous son contrôle

Si l'origine indiquée n'existe pas encore, la valeur sera slugifiée et utilisée pour la créer implicitement.

Réponse

{
   "result": 1,
   "data": {
     "id": null
   }
}

Liste des documents récents

GET /api/documents/recently-added/ HTTP/1.1

Cette API renvoit au plus les dix documents les plus récents parmi ceux crées il y a moins de quatorze jours.
Cette API est la seule à récupérer l'utilisateur depuis la requête (via signature Publik).

Content-Type: application/json


{
   "result": 1,
   "data": [
     {
        "label": "<nom du fichier>",
        "url": "https://fargo.<domain>.fr/12/download/fichier.pdf" 
     }
   ]
}

Validation des documents

Les types de document validables sont à définir dans les settings de fargo, via la variable FARGO_DOCUMENT_TYPES qui est une liste de dictionnaire, ex.:

FARGO_DOCUMENT_TYPES = [
    {
        'name': 'avis-d-imposition',
        'label': u'Avis d\'imposition',
        'metadata': [
            {
                'label': u'Personne-s concernée-s',
                'varname': 'personnes_concernees',
                'type': 'string',
            },
            {
                'label': u'Année',
                'varname': 'annee',
                'type': 'string',
            },
            {
                'label': u'Revenu fiscal de référence',
                'varname': 'revenu_fiscal_de_reference',
                'type': 'string',
            },
        ],
    },
]

Les champs de ce dictionnaire sont :

Valider le hash d'un document

Requête

POST /api/validation/avis-d-imposition/ HTTP/1.1
Content-Type: application/json
Content-Size: xxx


{
  "user_nameid": "YYY",
  "origin": "slug d'une origine déclarée dans l'admin",
  "content_hash": "hash sha1 du document validé",
  "start": "2019-01-01",
  "end": "2019-12-31",
  "creator": "Jean Darmette",
  "created": "2019-01-02",
  "personnes_concernees": "John Doe, Jane Doe",
  "annee": "2016",
  "revenu_fiscal_de_reference": "24678",
}

Ici l'origine ne sera pas créer automatiquement (contrairement à l'API de push), un slug doit être utilisé.

Champ Usage
user_nameid identifiant Publik de l'utilisateur
origin slug de l'origine
content_hash hash SHA-1 du document validé, ex.: 3f786850e387550fdab836ed7e6dc881de23001b
start date au format ISO-8601 de début de validité de la validation du document
end date au format ISO-8601 de fin de validité de la validation du document
creator agent/service ayant créé la validation
created date au format ISO-8601 de création de la validation du document

Les champs suivants correspondent aux champs de métadonnées définis pour le document, ils doivent valider les

Réponse

{
   "result": 1
   "data": {
      "origin": "mairie-de-xxx-service-enfance",
      "url": "https://fargo.<domaine>.fr/api/validation/avis-d-imposition/10/",
      "id": 10,
      "content_hash": "hash sha1 du document validé",
      "start": "2019-01-01",
      "end": "2019-12-31",
      "creator": "Jean Darmette",
      "created": "2019-01-02",
      "personnes_concernees": "John Doe, Jane Doe",
      "annee": "2016",
      "revenu_fiscal_de_reference": "24678" 
    }
}

Lister les validations de document

Requête

GET /api/validation/avis-d-imposition/?user_nameid=YYY
Accept: application/json

Réponse

Content-Type: application/json
Content-Size: xxx



[
  "result": 1,
  "data": [
    {
      "origin": "mairie-de-xxx-service-enfance",
      "url": "https://fargo.<domaine>.fr/api/validation/avis-d-imposition/10/",
      "id": 10,
      "content_hash": "hash sha1 du document validé",
      "start": "2019-01-01",
      "end": "2019-12-31",
      "creator": "Jean Darmette",
      "created": "2019-01-02",
      "personnes_concernees": "John Doe, Jane Doe",
      "annee": "2016",
      "revenu_fiscal_de_reference": "24678" 
    }
  ]
]

Évolutions

L'API est baroque comparée à nos autres APIs, il faudrait :

Demandes telles que comprises à Alfortville

Cas d'usage

En ligne

Cas de l'adresse, faisant partie des données du profil du compte usager

Cas des revenus

Au guichet

Cas de l'adresse, faisant partie des données du profil du compte usager

Cas des revenus

Liste des justificatifs données avec meta-data et dates de validité par défauts

Plutôt que d'avoir une vision par document administratif justificatif, retenir les données qui sont attestées

Tentative de généralisation depuis cas d'Alfortville (https://dev.entrouvert.org/projects/alfortville-gru/wiki/Cas_d'usages#section-12)
Avec ajouts d'autres cas de demandes de justificatifs par villes :
http://www.paris.fr/arc-en-ciel#renseignements-pratiques_2

Données qui pourraient être attestées au niveau du compte Publik (sont des attributs du compte usager)

Identité de l'usager
Domicile de l'usager

Données qui sont attestées au sein d'un formulaire (ne sont pas des attributs du compte usager) et seraient vraiment ré-utilisées de formulaire en formulaire

Revenus du requérant (ou du conjoint)
QF CAF du foyer

Données demandées dans le cas du bloc famille à Alfortville

Situation familiale
Identité du conjoint
Identité d'un enfant

NB : la première vision (Alfortville) nous a amené à renseigner plusieurs enfants (https://dev.entrouvert.org/projects/fargo/repository/revisions/86cb54b4a189d2b478c0cb3cf8ebaeb4678704df/diff/fargo/settings.py), ne permet pas généricité totale (peut y avoir plus de 4 enfants) et plus compréhensible si un set de données / enfant pour ré-utiliser dans autre formulaire (où ce n'est pas toute la fratrie qui peut être concerné)

Demandes de ville veille sur le sujet porte-documents

Alfortville

cf. CCTP p15

L’espace d’échange ou coffre-fort individuel
Dans cet espace seront déposés par l’Usager les pièces justificatives pour constituer ou faire évoluer ses dossiers. De même dans cet espace la collectivité pourra y déposer les courriers de réponses et tout autre document relatif aux prestations de l’Usager.
Les pièces justificatives pourront être déposées aux formats PDF et image standard et serontsoumises à période de validité en fonction de leur type.

Validation des données Usagers :
La collectivité se positionnera pendant les premiers ateliers fonctionnels sur la validation des pièces justificatives et la nécessité de les stocker dans cet espace.
Les modalités de validation des données Usagers seront fonction des parcours Usagers :
- Si numérisation depuis le guichet virtuel, passage au guichet une fois pour validation
- Si centre d'appels ou courrier, modalités guichet virtuel
- Si passage au guichet, numérisation ou simple validation visuelle par agent traitant
Dans l’hypothèse d’un lien vers un espace certifié de type digipost ou France Connect, les pièces justificatives pourront ne pas avoir besoin de validation supplémentaires (CAF ou Impôts par
exemple)
Chaque pièce justificative pourra donc faire l’objet d’un traitement post dépôt pour validation et avoir une date de validité, traitée automatiquement (date atteinte implique notification pour l’Usager et les agents traitants)

En découles des cas d'usages tels qu'imaginés par Brice, à écouter Alfortville

Blois

cf. CCTP p25

Dans son espace personnel, l’utilisateur pourra :
(...)

Niort

cf. CCTP p25

Cela nécessite (...), un espace de téléchargement de toutes les pièces administratives que l’usager doit fournir et que la municipalité peut lui transmettre (Coffre-fort numérique).

Note Brice : dans le cas de Niort, le coffre-fort est cité uniquement comme espace de dépôt accessible à l'administration, et non à l'initiative de l'usager

Nîmes

cf. CCTP p17

5.3.10 - Gestion du porte document
Afin de diminuer les coûts d’exploitation de la solution, dans la mesure du possible le porte document à utiliser sera celui du site de l’état, actuellement « mon.service-public.fr », qui devient France CONNECT . Une interface est à réaliser.
Le porte document est une fonction mis à disposition des usagers afin de leur faciliter la gestion des pièces justificatives. Ce porte document est actif et intelligent. Ceci implique plusieurs fonctions :

Développer

git clone git@git.entrouvert.org:fargo
mkvirtualenv fargo
workon fargo
pip install -U pip
cd fargo
pip install -e .

Relevant Art

eBox (porte-documents de l'administration belge)

Spécification

Le porte-feuille de document permettra à une personne de stocker des documents et de les utiliser sur différents services en ligne via des web-services avec une autorisation basée sur le protocole OAuth 2.0. Il sera possible pour un télé-service de proposer de nouveaux documents à un utilisateur si celui-ci l'aura préalablement autorisé à le faire, et ce pour une durée déterminée. Ces fichiers ne seront pas automatiquement introduits dans le porte-feuille, mais gardés dans un section "Réception de nouveaux documents" jusqu'à acceptation par l'utilisateur. Les fichiers déposés par un télé-service ne pourront pas être modifiés, seulement supprimés, et garderont une trace de leur origine qui pourra être transmise à un télé-service tiers.

Les documents seront des fichiers ayant éventuellement un type et une date de validité.

Les documents seront chiffrés avec une clé personnelle, cette clé personnelle sera conservée dans un cookie de session chiffré durant toute nouvelle session mais ne sera jamais copiée sur un stockage persistant par le porte-document. Cette clé ne servira qu'au chiffrement/déchiffrement des données mais pas à l'authentification qui pourra provenir d'un système plus classique de SSO.

Intégration

Lors de la demande d'autorisation le téléservice pourra indiquer s'il désire que les pages du porte-document soit habillées, si celui-ci sera utilisé en pleine page, ou non habillées. si celui-ci s'ouvrira dans une iframe ou une popup. Dans le cas d'utilisation d'une iframe ou d'une popup, le contenu présenté sur l'URL de retour du téléservice devra se charger de fermer ceux-ci.

Diagramme de séquence récupération d'un document

title Récupération d'un document participant "Navigateur" as N participant "Téléservice" as T participant "Porte-document" as F N->T: l'utilisateur accède à son téléservice note over T: pendant ce temps authentification potentielle\nde l'utilisateur au niveau du téléservice T->N: le téléservice est présenté à l'utilisateur N->T: l'utilisateur demande à attacher un document\nà une demande qu'il prépare T->N: le téléservice redirige le navigateur sur\nla page d'autorisation OAuth2.0 du porte-document N->F: le navigateur récupère la page d'autorisation du porte documents note over F: pendant ce temps authentification potentielle\nde l'utilisateur au niveau du porte-document F->N: le porte document affiche à l'utilisateur\nune vue de ses documents note over F: la vue des documents éventuellement\nrestreinte à certains types de documents si une\nindication à été transmis par le téléservice\ndans la demande d'autorisation N->F: l'utilisateur sélectionne un document F->N: le porte-document renvoie le navigateur sur\nle télé-service avec un code d'autorisation (protocole OAuth 2.0) N->T: le navigateur procède à la redirection T->F: le télé-service transforme son code d'autorisation\nen un jeton d'accès ou « access token »\nqui lui permettra d'appeler le web-service\nde récupération de fichier F->T: le porte-document retourne un jeton d'accès\nvalide pour une durée T et uniquement pour\nle ficher sélectionné précédemment par l'utilisateur T->F: le télé-service appelle le web-service de\nrécupération de fichier en utilisant le jeton d'accès\npour son authentification note over F: le porte-document recherche le jeton dans sa base\net retrouve le fichier associé ainsi que\nla durée de vie du jeton, il vérifie l'existence\ndu fichier et la fraîcheur du jeton F->T: le porte-document retourne le fichier ainsi\nque ses éventuelles métadonnées: type, date de validité, origine. T->N: le télé-service ré-affiche la page de demande\nen prenant en compte le nouveau document attaché

Diagramme de séquence de dépôt d'un document

title Récupération d'un document participant "Navigateur" as N participant "Téléservice" as T participant "Porte-document" as F N->T: l'utilisateur accède à son téléservice note over T: pendant ce temps authentification potentielle\nde l'utilisateur au niveau du téléservice T->N: le téléservice indique à l'utilisateur\nqu'un nouveau document est disponible ou\npourra être disponible, et permet de le récupérer dans son porte-document N->T: l'utilisateur demande à permettre au\ntéléservice de déposer un document\nmaintenant ou plus tard, d'un certain type T->N: le téléservice redirige le navigateur sur\nla page d'autorisation OAuth2.0 du porte-document N->F: le navigateur récupère la page d'autorisation du porte documents note over F: pendant ce temps authentification potentielle\nde l'utilisateur au niveau du porte-document F->N: le porte document affiche à l'utilisateur\n un formulaire lui demandant s'il désire\npermettre au télé-service de déposer un\ndocument tout de suite ou plus tard d'un certain\ntype, ex.: Attestation d'inscription N->F: l'utilisateur autorise le téléservice F->N: le porte-document renvoie le navigateur sur\nle télé-service avec un code d'autorisation (protocole OAuth 2.0) N->T: le navigateur procède à la redirection T->F: le télé-service transforme son code d'autorisation\nen un jeton d'accès ou « access token »\nqui lui permettra d'appeler le web-service\nde dépôt de fichier maintenant ou plus tard note over T: un certain temps peut se passer\navant que le téléservice ne décide\nde déposer un document T->F: une procédure vient de se terminer sur\nle téléservice et un document est déposé\nsur le porte-document, si l'évènement est\ndans la fenêtre de durée de vie du jeton\nd'accès obtenu, le téléservice appelle\nsimplement le web-service de dépôt de\nfichier avec son jeton, il ne peut\ndéposer un fichier que d'un certain type F->T: le porte-document accepte la demande et\ndépose le fichier dans la liste des nouveaux\ndocuments de l'utilisateur et l'informe par un email

Suite à ces échanges l'utilisateur pourra consulter le nouveau document dans son porte-document.

Wiki

Spécification
Développer
Demandes de ville, veille sur le sujet
API