API | Blog de iSignif

Vous êtes développeur et vous souhaitez utiliser notre API pour automatiser la signification de vos demandes? iSignif met à disposition une API RESTful qui vous permet de faire vos demandes sans quitter votre application.

Notre API est documentée au format OpenAPI et disponible en ligne:

consulter la documentation OpenAPI

Nous mettons à disposition un environnement de test disponible à l’addresse suivante: https://test.isignif.fr

Sommaire

Sommaire
Normes
Workflow d’un acte
Exemple d’une demande de création d’un acte
Exemple de gestion de signification d’un acte

Normes

Afin de rendre cette API utilisable, nous avons respecté deux principales normes:

API RESTful qui spécifie comment accéder et comment interagir avec des ressources
JSON:API qui définit l’organisation du document JSON

Workflow d’un acte

Création d’un acte
Paramétrage & ajout de significations
Confirmation de l’acte

Exemple d’une demande de création d’un acte

Dans cet exemple nous allons faire le tour d’une demande de signification en utilisant l’API d’iSignif.

Nous utiliserons cURL qui a l’avantage d’être présent sur la plupart des systèmes d’exploitation.

Obtenir un jeton d’authentification

La plupart des actions disponibles via l’API de iSignif demande une authentification. Afin de pouvoir signifier, vous devez donc créer un compte et obtenir un jeton d’authentification qui nous permettra de retrouver votre utilisateur sur la plateforme.

Avant tout, vous avez besoin de créer votre profil. Nous avons deux types de comptes:

le type advocate qui peut demander la signification d’acte
le type bailiff qui peut demander la signification d’acte ET les signifier

Commençons donc par créer un compte de type advocate. En suivant la convention REST, vous pouvez deviner qu’il suffit de faire une requête de type POST sur la ressource advocate. Vous devez fournir les paramètres nécessaires à la création d’un compte.

Voici un exemple avec le minimum d’informations nécessaire:

$ curl -X POST \
       -d 'advocate[firstname]=Alexandre' \
       -d 'advocate[lastname]=Rousseau' \
       -d 'advocate[email]=isignif_api@dispostable.com' \
       -d 'advocate[password]=isignif_api' \
       -d 'advocate[password_confirmation]=isignif_api' \
       -d 'advocate[address_1]=2 rue des Lilas' \
       -d 'advocate[zip_code]=69001' \
       -d 'advocate[town]=Lyon' \
       https://test.isignif.fr/api/v1/advocates

A la suite de cette demande, vous allez recevoir un email de confirmation à l’adresse que vous avez renseignée.

Tant que l'adresse n'est pas confirmée, vous ne pouvez pas recevoir de jetons.

Il suffit maintenant d’obtenir un jeton d’authentification en utilisant la ressource tokens:

$ curl -X POST \
       -d 'user[email]=isignif_api@dispostable.com' \
       -d 'user[password]=isignif_api' \
       https://test.isignif.fr/api/v1/tokens

Vous obtenez une réponse de cette forme

{
    "token":"eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjAsImVtYWlsIjoiaXNpZ25pZl9hcGlAZGlzcG9zdGFibGUuY29tIiwiZmlyc3RuYW1lIjoiQWxleGFuZHJlIiwibGFzdG5hbWUiOiJSb3Vzc2VhdSIsImV4cCI6MTU2OTg0NTk3MX0.rMqkGMN4Zr6WA7hTjxY8qUVPiNu2vYSLDP4k0EtpJ4A"
}

Utiliser le jeton d’authentification

Pour les lecteurs les plus avertis, vous pouvez remarquer que le jeton est de type JWT. Il est donc possible de le décoder (à l’aide d’une librairie comme jwt-decode par exemple) et d’extraire ses informations:

{
    "user_id": 120,
    "email": "isignif_api@dispostable.com",
    "firstname": "Alexandre",
    "lastname": "Rousseau",
    "exp": 1569845971
}

Vous remarquez certainement la clef exp qui contient le timestamp de la date d’expiration du jeton. Elle est de 24h à partir de la date de création du jeton. Passé cette date, il faudra en générer un autre.

Utilisons donc le user_id récupéré dans le JWT pour consulter nos informations:

$ curl -H "Authorization: eyJhb...k0EtpJ4A" https://test.isignif.fr/api/v1/advocates/120

{
    "data": {
        "id": "120",
        "type": "advocate",
        "attributes": {
            "email": "isignif_api@dispostable.com",
            "firstname": "Alexandre",
            "lastname": "Rousseau",
            "activated": true,
            // ...
        },
        "relationships": {
            "acts": {
                "data": []
            }
        },
        "links": {
            "self": "https://test.isignif.fr/advocates/120.json"
        }
    },
    "included": []
}

Et voilà.

Si vous êtes fin connaisseur, vous reconnaissez sûrement la syntaxe JSON:API. Cette syntaxe permet de structurer le format du JSON.

Créer un acte

Maintenant que nous avons un jeton d’authentification nous pouvons effectuer une demande de signification. Cette demande est un acte.

Un acte est lié à un type d’acte qui définit son prix. Utilisons donc l’API afin de trouver quel type d’acte nous voulons signifier. Vous pouvez utiliser le paramètre term pour filtrer les résultats.

Voici un exemple en cherchant “nantissement”:

$ curl http://localhost:3000/api/v1/act_types?term=nantissement

{
    "data": [
        {
            "id": "196",
            "type": "act_type",
            "attributes": {
                "name": "Signification à la société du nantissement des parts sociales"
            },
        },
        // ...
    ]
}

Maintenant que nous avons un act_type_id, nous pouvons créer un acte.

$ curl -X POST \
       -H "Authorization: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjAsImVtYWlsIjoiaXNpZ25pZl9hcGlAZGlzcG9zdGFibGUuY29tIiwiZmlyc3RuYW1lIjoiQWxleGFuZHJlIiwibGFzdG5hbWUiOiJSb3Vzc2VhdSIsImV4cCI6MTU2OTg0NTk3MX0.rMqkGMN4Zr6WA7hTjxY8qUVPiNu2vYSLDP4k0EtpJ4A" \
       -d 'act[act_type_id]=196' \
       https://test.isignif.fr/api/v1/acts

{
    "data": {
        "id": "99",
        "type": "act",
        "attributes": {
            "advocate_id": 120,
            "act_type_id": 196,
            "current_step": "created",
            // ...
        },
        "relationships": {
            // ...
        },
        "links": {
            "self": "https://test.isignif.fr/acts/99.json"
        }
    },
    "included": []
}

Et voilà! Mais ce n’est pas terminé. Il nous reste deux choses à faire:

ajouter des significations sur cet acte
le confirmer

Ajouter des significations

Une signification est attachée à une ville que nous devons chercher:

$ curl -X POST -d 'term=villejuif'  https://test.isignif.fr/api/v1/towns/search

[
    {
        "text":"Villejuif (94800)",
        "id":10435
    }
]

Nous pouvons donc noter ce town_id et créer la signification:

$ curl -X POST \
       -H "Authorization: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjAsImVtYWlsIjoiaXNpZ25pZl9hcGlAZGlzcG9zdGFibGUuY29tIiwiZmlyc3RuYW1lIjoiQWxleGFuZHJlIiwibGFzdG5hbWUiOiJSb3Vzc2VhdSIsImV4cCI6MTU2OTg0NTk3MX0.rMqkGMN4Zr6WA7hTjxY8qUVPiNu2vYSLDP4k0EtpJ4A" \
       -d 'signification[name]=Chez mémé' \
       -d 'signification[town_id]=10435' \
       https://test.isignif.fr/api/v1/acts/99/significations

Vous pouvez consulter toutes les significations créées sur l’acte avec cette requête:

$ curl -H "Authorization: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjAsImVtYWlsIjoiaXNpZ25pZl9hcGlAZGlzcG9zdGFibGUuY29tIiwiZmlyc3RuYW1lIjoiQWxleGFuZHJlIiwibGFzdG5hbWUiOiJSb3Vzc2VhdSIsImV4cCI6MTU2OTg0NTk3MX0.rMqkGMN4Zr6WA7hTjxY8qUVPiNu2vYSLDP4k0EtpJ4A" \
       https://test.isignif.fr/api/v1/acts/99

{
    "data": {
        "id": "99",
        "type": "act",
        // ...
    },
    "included": [
        {
            "id": "196",
            "type": "act_type",
            "attributes": {
                "name": "Signification aux créanciers de l’acte de nantissement de l’outillage et du matériel d’équipement"
            },
            // ...
        },
        {
            "id": "132",
            "type": "signification",
            "attributes": {
                "name": "Chez mémé",
                "created_at": "2019-09-29T19:59:52.000+02:00",
                "updated_at": "2019-09-29T19:59:52.000+02:00",
                "bailiff_id": 36,
                "act_id": 99,
                "town_id": 10435,
                "bailiff_comment": null
            },
            // ...
        }
    ]
}

Confirmer notre acte

Il est maintenant temps de confirmer notre acte. Cette action aura pour conséquence de valider l’acte et de contacter tous les huissiers sélectionnés pour les significations.

$ curl -X POST \
       -H "Authorization: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjAsImVtYWlsIjoiaXNpZ25pZl9hcGlAZGlzcG9zdGFibGUuY29tIiwiZmlyc3RuYW1lIjoiQWxleGFuZHJlIiwibGFzdG5hbWUiOiJSb3Vzc2VhdSIsImV4cCI6MTU2OTg0NTk3MX0.rMqkGMN4Zr6WA7hTjxY8qUVPiNu2vYSLDP4k0EtpJ4A" \
       https://test.isignif.fr/api/v1/acts/99/confirm

Vous pouvez constater que le statut de l’acte vient de changer en consultant l’historique de l’acte:

$ curl -H "Authorization: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMjAsImVtYWlsIjoiaXNpZ25pZl9hcGlAZGlzcG9zdGFibGUuY29tIiwiZmlyc3RuYW1lIjoiQWxleGFuZHJlIiwibGFzdG5hbWUiOiJSb3Vzc2VhdSIsImV4cCI6MTU2OTg0NTk3MX0.rMqkGMN4Zr6WA7hTjxY8qUVPiNu2vYSLDP4k0EtpJ4A" \
       https://test.isignif.fr/api/v1/acts/99/act_histories

{
    "data": [
        {
            "id": "178",
            "type": "act_history",
            "attributes": {
                "step": "created",
                "user_id": 120,
                "act_id": 99,
                "signification_id": null,
                "created_at": "2019-09-29T19:29:35.000+02:00",
                "updated_at": "2019-09-29T19:29:35.000+02:00"
            },
            // ...
        },
        {
            "id": "180",
            "type": "act_history",
            "attributes": {
                "step": "confirmed",
                "user_id": 120,
                "act_id": 99,
                "signification_id": null,
                "created_at": "2019-09-29T20:14:06.000+02:00",
                "updated_at": "2019-09-29T20:14:06.000+02:00"
            },
            // ...
        }
    ],
    "included": [
        // ...
    ]
}

TODO

Exemple de gestion de signification d’un acte

TODO