---
openapi: "3.0.2"
info:
  title: "Harvest API - Documents O2S"
  description: "# API de gestion des documents O2S\nCette API offre différents services\
    \ permettant de gérer des documents O2S ainsi que les informations liées.\n\n\
    Pour ce faire, plusieurs ressources sont à disposition, à savoir :\n- `Document`\
    \ : Permet de gérer l'entité de base de cette API que sont les documents.\n- `Caté\
    gorie` : Permet de gérer les catégories des documents.\n\n## Règlement Général\
    \ sur la Protection des Données (RGPD)\n\n  Dans le cadre de la mise à disposition\
    \ de l’API, HARVEST s’engage à effectuer pour le compte du Client responsable\
    \ de traitement, les opérations de traitement de données à caractère personnel\
    \ en qualité de sous-traitant. A ce titre, **HARVEST et le Client s’engagent à\
    \ respecter la réglementation en vigueur applicable au traitement de données à\
    \ caractère personnel** en particulier, le règlement (UE) 2016/679 du Parlement\
    \ européen et du Conseil du 27 avril 2016 (ci-après le « RGPD »).\n\n  L’API peut\
    \ vous permettre de renseigner librement des propriétés typées et non typées.\
    \ HARVEST attire votre attention sur la **nécessité**, lors de la complétude de\
    \ ces propriétés, **de respecter les dispositions du RGPD**. Dès lors, seules\
    \ les données adéquates, pertinentes et strictement nécessaires au regard de la\
    \ finalité des traitements réalisés par l’API doivent être transmises.\n\n  L’\
    API contient par ailleurs des **zones de commentaires libres** dans lesquelles\
    \ vous devez impérativement **rédiger des commentaires objectifs, jamais excessifs\
    \ ou insultants**. Aussi, vous devez **exclure toute donnée considérée comme sensible**\
    \ (origine raciale ou ethnique, opinions politiques, philosophiques ou religieuses,\
    \ appartenance syndicale, données relatives à la santé ou à la vie sexuelle, infractions,\
    \ condamnations, mesure de sûreté). En cas de doute, vous pouvez contacter votre\
    \ DPO qui vous indiquera ce qu’il est possible de rédiger pour ne pas porter atteinte\
    \ aux droits des personnes concernées."
  version: "0.9.3"
  x-logo:
      url: "zelogo.png"
      backgroundColor: "#012233"
      altText: "Logo Harvest"
servers: []
security:
- JWT: []
tags:
- name: "Authent"
  description: "## Généralité\nPour utiliser l'API O2S, vous devez préalablement vous\
    \ authentifier en suivant le protocole OAuth2\n\"password grant type\" afin de\
    \ récupérer un jeton (JWT) d'accès.\n\n## Informations nécessaires\nLes informations\
    \ nécessaires à l'obtention d'un jeton sont constituées :\n- d'informations fournies\
    \ par Harvest qui sont spécifiques à votre application (client_id + client_secret)\n\
    - d'informations spécifiques à un utilisateur O2S (username + password) dont l'API\
    \ reprendra l'identité.\n\nIl vous faut renseigner ces informations dans la ressource\
    \ en entrée du service d'obtention d'un nouveau jeton.\n\n## Utilisation du jeton\
    \ d'accès\nLe jeton JWT doit être fourni lors de l'appel de chaque requête à l'API.\
    \ Il doit être ajouté dans\n**l'entête HTTP Authorization** comme ceci :\n`Authorization:\
    \ Bearer <JWT>`"
  x-displayName: "Sécurité"
- name: "Problem"
  description: "Les réponses principales de l'API sont décrites au niveau de chacune\
    \ de ses ressources (GET, POST, PUT, DELETE...).\n\nCelles qui n'y sont pas spé\
    cifiées sont celles retournées en cas de problème soit avec la requête elle-mê\
    me soit avec le serveur ou son environnement.\n\nLes statuts HTTP concernés par\
    \ ces dernières sont les 4xx (hors 404) et 5xx.\n\nLe format des réponses répond\
    \ au schéma [Problem Zalando](docs/Problem/ProblemJson-schema-1.yaml)."
  x-displayName: "Réponse en cas de problème"
- name: "DocumentsO2S"
  description: "Opérations sur les documents O2S"
  x-displayName: "Document"
- name: "DocumentsCategoriesO2S"
  description: "Opérations sur les catégories des documents O2S"
  x-displayName: "Catégorie"
paths:
  /auth/realms/AppUsers/protocol/openid-connect/token:
    post:
      tags:
      - "Authent"
      description: "Le jeton JWT d'accès à exploiter est retourné dans valeur de la\
        \ propriété `access_token`.\n\nIl doit être précisé dans **l'entête HTTP**\
        \ de toutes les requêtes (sauf celle d'authentification)\ncomme ceci :\n\n\
        `Authorization: Bearer <access_token>`"
      operationId: "OAuthPasswordAuthenticate"
      requestBody:
        $ref: "#/components/requestBodies/OAuthPassword"
      responses:
        "200":
          description: "200 OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuth200"
        "400":
          description: "Erreur OAuth 400 (Bad Request)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErr"
              example:
                error: "invalid_request"
                error_description: "Missing form parameter: grant_type"
        "401":
          description: "Erreur OAuth 401 (Unauthorized)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthErr"
              example:
                error: "invalid_grant"
                error_description: "Invalid user credentials"
      servers:
      - url: "https://auth-r7.harvest.fr"
        description: "Authentification O2S (recette)"
      - url: "https://auth.harvest.fr"
        description: "Authentification O2S (production)"
  /documents:
    summary: "Path used to manage the list of documents."
    description: "The REST endpoint/path used to list and create zero or more `Document`\
      \ entities.  This path contains a `GET` and `POST` operation to perform the\
      \ list and create tasks, respectively."
    get:
      tags:
      - "DocumentsO2S"
      summary: "Lister des Documents"
      description: "Récupère une liste de `Document` correspondant aux critères facultatifs\
        \ de recherche.<br>\nPar défaut :\n  * aucun filtre n'est appliqué (permet\
        \ de récupérer tous les Documents)\n  * le nombre d'éléments retournés est\
        \ limité à 20"
      operationId: "getDocuments"
      parameters:
      - name: "contactId"
        in: "query"
        description: "Référence (id) du contact détenteur des documents recherchés"
        required: false
        style: "form"
        explode: true
        schema:
          type: "string"
        example: "ec3dee9a-a6fc-11e9-b9bd-0050568a56f0"
      - name: "type"
        in: "query"
        required: false
        style: "form"
        explode: true
        schema:
          $ref: "#/components/schemas/TypeDoc"
      - name: "contenu"
        in: "query"
        description: "Permet d'indiquer si le contenu du document est récupéré."
        required: false
        style: "form"
        explode: true
        schema:
          type: "boolean"
          default: false
      - name: "limit"
        in: "query"
        description: "Nombre maximum de documents à retourner"
        required: false
        style: "form"
        explode: true
        schema:
          type: "integer"
          default: 20
      - name: "offset"
        in: "query"
        description: "Indice (0-based) du premier document à retourner"
        required: false
        style: "form"
        explode: true
        schema:
          type: "integer"
          default: 0
      responses:
        "200":
          description: "Retourne l'ensemble complet des `Document`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Documents"
    post:
      tags:
      - "DocumentsO2S"
      summary: "Créer un Document"
      description: "Crée un nouvel `Document`."
      operationId: "createDocument"
      requestBody:
        description: "Les données d'un `Document` à créer."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TypeDocument"
        required: true
      responses:
        "201":
          description: "Le `Document` a correctement été créé."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/documentId"
  /documents/{documentId}:
    summary: "Path used to manage a single Document."
    description: "The REST endpoint/path used to get, update, and delete single instances\
      \ of an `Document`.  This path contains `GET`, `PUT`, and `DELETE` operations\
      \ used to perform the get, update, and delete tasks, respectively."
    get:
      tags:
      - "DocumentsO2S"
      summary: "Obtenir un Document"
      description: "Récupère les données d'un unique `Document`."
      operationId: "getDocument"
      parameters:
      - name: "documentId"
        in: "path"
        description: "Référence (id) du document"
        required: true
        style: "simple"
        explode: false
        schema:
          $ref: "#/components/schemas/TypeId"
      - name: "contenu"
        in: "query"
        description: "Permet d'indiquer si le contenu du document est récupéré."
        required: false
        style: "form"
        explode: true
        schema:
          type: "boolean"
          default: true
      responses:
        "200":
          description: "Retourne les données d'un unique `Document`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TypeDocument"
        "404":
          description: "Le `Document` spécifié est inexistant."
    put:
      tags:
      - "DocumentsO2S"
      summary: "Mettre à jour un Document"
      description: "Met à jour un `Document` existant."
      operationId: "updateDocument"
      parameters:
      - name: "documentId"
        in: "path"
        description: "Référence (id) du document"
        required: true
        style: "simple"
        explode: false
        schema:
          $ref: "#/components/schemas/TypeId"
      requestBody:
        description: "Les données d'un `Document` à mettre à jour."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TypeDocument"
        required: true
      responses:
        "204":
          description: "Le `Document` spécifié a été correctement mis à jour."
        "404":
          description: "Le `Document` spécifié est inexistant."
    delete:
      tags:
      - "DocumentsO2S"
      summary: "Supprimer un Document"
      description: "Supprime un `Document` existant."
      operationId: "deleteDocument"
      parameters:
      - name: "documentId"
        in: "path"
        description: "Référence (id) du document"
        required: true
        style: "simple"
        explode: false
        schema:
          $ref: "#/components/schemas/TypeId"
      responses:
        "204":
          description: "Le `Document` spécifié a été supprimé."
        "404":
          description: "Le `Document` spécifié est inexistant."
  /categories-documents:
    summary: "Path used to manage the list of categorie documents."
    description: "The REST endpoint/path used to list and create zero or more `CategoriesDocument`\
      \ entities.  This path contains a `GET` and `POST` operation to perform the\
      \ list and create tasks, respectively."
    get:
      tags:
      - "DocumentsCategoriesO2S"
      summary: "Lister les catégories des Documents"
      description: "Récupère une liste de `Catégories Document` correspondant aux\
        \ critères de recherche.<br>"
      operationId: "getCategoriesDocuments"
      parameters:
      - name: "contactId"
        in: "query"
        description: "Référence (id) du contact"
        required: true
        style: "form"
        explode: true
        schema:
          $ref: "#/components/schemas/TypeId"
        example: "ec3dee9a-a6fc-11e9-b9bd-0050568a56f0"
      responses:
        "200":
          description: "Retourne l'ensemble complet des `CategoriesDocument`."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TypeDocumentCategories"
              example:
              - nom: "Email"
                id: "f3a79c3b-ae2a-11e9-bc38-0050568a56f0"
              - nom: "Mon dossier"
                id: "6505c667-4d37-11ec-a6eb-0050568ae49b"
                parent-id: "f3a79c3b-ae2a-11e9-bc38-0050568a56f0"
              - nom: "Email niveau 1"
                id: "6505c667-4d37-11ec-a6eb-0050568ae49b"
                parent-id: "f3a79c3b-ae2a-11e9-bc38-0050568a56f0"
              - nom: "Conformité"
                id: "f39c042f-ae2a-11e9-bc38-0050568a56f0"
              - nom: "Mon dossier"
                id: "cf843b40-543a-11ec-82f4-0050568ae49b"
                parent-id: "f39c042f-ae2a-11e9-bc38-0050568a56f0"
              - nom: "Conformité niveau 2"
                id: "6028c884-543c-11ec-82f4-0050568ae49b"
                parent-id: "cf843b40-543a-11ec-82f4-0050568ae49b"
        "400":
          description: "Cette requête nécessite au moins un paramètre, ex: contactId"
components:
  schemas:
    OAuthPassword:
      required:
      - "client_id"
      - "client_secret"
      - "grant_type"
      - "password"
      - "username"
      type: "object"
      properties:
        grant_type:
          type: "string"
          description: "Méthode d'authentification OAuth à définir obligatoirement\
            \ à `password`."
          enum:
          - "password"
        client_id:
          type: "string"
          description: "Identifiant de l'application cliente."
        client_secret:
          type: "string"
          description: "Secret de l'application cliente."
        username:
          type: "string"
          description: "Identifiant de connexion de l'utilisateur."
        password:
          type: "string"
          description: "Mot de passe de l'utilisateur."
    OAuth200:
      type: "object"
      properties:
        access_token:
          type: "string"
          description: "Jeton d'accès émis par le serveur d'autorisation."
        expires_in:
          type: "integer"
          description: "Si le jeton d'accès expire, le serveur retourne la durée (en\
            \ secondes) pendant laquelle le jeton\nd'accès est accordé."
          format: "int32"
        refresh_expires_in:
          type: "integer"
          description: "Si le jeton d'accès expire, le serveur retourne la durée (en\
            \ secondes) pendant laquelle le jeton\nd'actualisation est accordé."
          format: "int32"
        refresh_token:
          type: "string"
          description: "Si le jeton d'accès expire, ce jeton d'actualisation doit\
            \ être utilisé pour obtenir un autre jeton d'accès."
        token_type:
          type: "string"
          description: "Le type du jeton \"bearer\"."
        not-before-policy:
          type: "integer"
          format: "int32"
        session_state:
          type: "string"
        scope:
          type: "string"
      description: "Réponse OAuth 200 (OK)"
      example:
        access_token: "eyJhbGciOi...fgWOZZmV7Q"
        expires_in: 86400
        refresh_expires_in: 86400
        refresh_token: "eyJhbGciOi...KiIVIifWw"
        token_type: "bearer"
        not-before-policy: 1602682985
        session_state: "85d20350-891b-4dad-b6ed-c411c6ac870c"
        scope: "..."
    OAuthErr:
      type: "object"
      properties:
        error:
          type: "string"
          description: "Description courte de l'erreur."
        error_description:
          type: "string"
          description: "Description détaillée de l'erreur."
    TypeDoc:
      type: "string"
      description: "Le type de document:\n * IDENTITE\n * JUSTIFICATIF_DOMICILE\n\
        \ * JUSTIFICATIF_AUTRE\n * INFORMATION_LEGALE\n * AUTRE\n"
      enum:
      - "IDENTITE"
      - "JUSTIFICATIF_DOMICILE"
      - "JUSTIFICATIF_AUTRE"
      - "INFORMATION_LEGALE"
      - "AUTRE"
    TypeDocument:
      type: "object"
      properties:
        id:
          type: "string"
          description: "Identification du document."
        libelle:
          type: "string"
          description: "Libellé générique du document."
        type:
          $ref: "#/components/schemas/TypeDoc"
        dateCreation:
          type: "string"
          description: "Date et heure de création d'un document."
          format: "date-time"
        dateMaj:
          type: "string"
          description: "Dernière date et heure de modification d'un document."
          format: "date-time"
        contenu:
          description: "Extension `Contenu` d'un `document`."
          allOf:
          - $ref: "#/components/schemas/TypeDocumentContenu"
        ressourcesLiees:
          type: "array"
          description: "Extension `RessourcesLiees` d'un `document`."
          items:
            $ref: "#/components/schemas/TypeDocumentRessourceLiee"
        metaDonnees:
          type: "object"
          properties:
            donnees:
              type: "array"
              items:
                $ref: "#/components/schemas/TypeDocumentMetaDonnee"
          description: "Extension `MetaDonnees` d'un `document`."
    TypeDocumentContenu:
      type: "object"
      properties:
        nature:
          type: "string"
          description: "Permet d'identifier plus précisément la nature du contenu,\
            \ le cas échéant."
        format:
          type: "string"
          description: "Permet d'identifier le format des données. Par exemple, utilisation\
            \ d'un type MIME\n\n* TXT\n* JPEG\n* PNG\n* GIF\n* PDF"
          enum:
          - "TXT"
          - "JPEG"
          - "PNG"
          - "GIF"
          - "PDF"
          - "AUTRE"
        donnees:
          maxItems: 20
          type: "array"
          description: "Permet de renseigner un ou plusieurs documents textes ou numé\
            risés (par exemple ou le recto verso d'un document comme la carte nationale\
            \ d'identité, etc.)."
          items:
            $ref: "#/components/schemas/TypeDonneeDocumentContenu"
    TypeDonneeDocumentContenu:
      type: "string"
      description: "texte encodé en base64."
    TypeDocumentRessourceLiee:
      type: "object"
      properties:
        type:
          type: "string"
          description: "Permet de renseigner le type du contact :\n * CONTACT\n"
          enum:
          - "CONTACT"
        id:
          type: "string"
          description: "Permet de référencer l'id du contact."
    TypeDocumentMetaDonnees:
      maxItems: 20
      type: "array"
      items:
        $ref: "#/components/schemas/TypeDocumentMetaDonnee"
    TypeDocumentMetaDonnee:
      allOf:
      - $ref: "#/components/schemas/TypeMetaDonnee"
    TypeDocumentCategories:
      type: "array"
      items:
        $ref: "#/components/schemas/TypeDocumentCategorie"
    TypeDocumentCategorie:
      type: "object"
      properties:
        nom:
          type: "string"
          description: "Nom de la catégorie."
        id:
          type: "string"
          description: "Référence (id) de la catégorie."
        parent-id:
          type: "string"
          description: "Référence (id) de la catégorie-parent."
    TypeMetaDonnee:
      type: "object"
      properties:
        cle:
          type: "string"
          description: "Permet de renseigner la clé d'une méta donnée."
        valeur:
          type: "string"
          description: "Permet de renseigner la valeur d'une méta donnée."
        app:
          type: "string"
          description: "Permet de renseigner l'application utilisée de la méta donné\
            e."
    documentId:
      properties:
        id:
          description: "Référence (id) du document"
          allOf:
          - $ref: "#/components/schemas/TypeId"
    contactId:
      properties:
        id:
          description: "Référence (id) du contact"
          allOf:
          - $ref: "#/components/schemas/TypeId"
    Documents:
      type: "array"
      items:
        $ref: "#/components/schemas/TypeDocument"
    TypeId:
      maxLength: 100
      minLength: 1
      type: "string"
  parameters:
    documentId:
      name: "documentId"
      in: "path"
      description: "Référence (id) du document"
      required: true
      style: "simple"
      explode: false
      schema:
        $ref: "#/components/schemas/TypeId"
    contactId:
      name: "contactId"
      in: "query"
      description: "Référence (id) du contact"
      required: true
      style: "form"
      explode: true
      schema:
        $ref: "#/components/schemas/TypeId"
      example: "ec3dee9a-a6fc-11e9-b9bd-0050568a56f0"
  requestBodies:
    OAuthPassword:
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: "#/components/schemas/OAuthPassword"
          examples:
            OAuth2PasswordPayload:
              value:
                grant_type: "password"
                client_id: "clientId"
                client_secret: "clientSecret"
                username: "username"
                password: "password"
      required: true
  securitySchemes:
    JWT:
      type: "http"
      description: "Identification via token JWT"
      scheme: "bearer"
      bearerFormat: "JWT"
x-tagGroups:
  - name: "Aspects techniques"
    tags:
    - "Authent"
    - "Problem"
  - name: "Opérations sur les ressources"
    tags:
    - "DocumentsO2S"
    - "DocumentsCategoriesO2S"
