API ChouetteCopro

URL de base

https://www.chouettecopro.com/api/v1

L'API ChouetteCopro est une API REST basée sur le standard JSON:API. Cela permet de bénéficier d'une documentation exhaustive, d'un écosystème de clients compatibles et de répondre aux problématiques usuelles comme la pagination, le tri, le cache ou les réponses partielles.

Elle utilise des fonctionnalités HTTP classiques comme les codes d'erreurs HTTP, l'authentification avec Basic Auth et les verbes HTTP.

Les données renvoyées sont au format JSON.

Authentification

Exemple de requête

curl "https://www.chouettecopro.com/api/v1/condominia"
  -u 5687c0fd-42f4-4dbe-8ad3-608b6b93f7ac:

curl utilise l'option -u pour indiquer l'identifiant Basic Auth. L'ajout de : empêche curl de demander un mot de passe

La clé API indiquée est une clé factice. Pour tester avec votre compte, utilisez votre propre clé API.

L'authentification se fait en indiquant la clé API du compte utilisateur dans les requêtes API. Les droits d'accès correspondent à ceux de l'utilisateur sur l'application ChouetteCopro. Cette clé est secrète, veillez à ne pas la rendre accessible publiquement (code source versionné, code client d'un site web public...).

L'authentification se fait via la méthode HTTP Basic Auth. Il faut indiquer la clé API dans le champ username. Le mot de passe n'est pas nécessaire.

JSON:API

Données liées

Exemple de requête

curl "https://www.chouettecopro.com/api/v1/tickets/1234?include=comments,pictures,author"
  -u <api_key>

JSON:API permet de récupérer des informations liées à la ressource en cours dans la même requête. Il est par exemple possible pour un ticket donné de récupérer également ses commentaires, ses ordres de service et son auteur.

Le paramètre include permet d'indiquer les données souhaitées dans une chaîne séparée par des virgules.

La section Données liées de chaque ressource recense les données qu'il est possible de récupérer.

Pour plus d'informations, consulter la documentation de include de JSON:API`.

Copropriétés

L'objet copropriété

Attributs

Nom	Description
`short_title`	Le nom et l'adresse

Données liées

tickets : les signalements de la copropriété
pictures : les images de la copropriété
picture : l'image principale de la copropriété

Liste des copropriétés

GET /api/v1/condominia

Exemple de requête

curl "https://www.chouettecopro.com/api/v1/condominia"
  -u {api_key}

Exemple de réponse

{
    "data": [
        {
            "id": "123",
            "type": "condominia",
            "links": {
                "self": "https://www.chouettecopro.com/api/v1/condominia/123"
            },
            "attributes": {
                "short_title": "Résidence Jean Moulin (75001 Paris)"
            },
            "relationships": {
                "tickets": {
                    "links": {
                        "self": "https://www.chouettecopro.com/api/v1/condominia/123/relationships/tickets",
                        "related": "https://www.chouettecopro.com/api/v1/condominia/123/tickets"
                    }
                },
                "picture": {
                    "links": {
                        "self": "https://www.chouettecopro.com/api/v1/condominia/123/relationships/picture",
                        "related": "https://www.chouettecopro.com/api/v1/condominia/123/picture"
                    }
                },
                "pictures": {
                    "links": {
                        "self": "https://www.chouettecopro.com/api/v1/condominia/123/relationships/pictures",
                        "related": "https://www.chouettecopro.com/api/v1/condominia/123/pictures"
                    }
                }
            }
        },
        {...}
    ]
}

Renvoie la liste des copropriétés auxquelles l'utilisateur a accès.

Arguments en query string

Nom	Description
`include`	La liste des données liées à récupérer

Retour

Un objet avec une propriété data contenant un tableau de copropriétés.

Détail d'une copropriété

GET /api/v1/condominia/{id}

Exemple de requête

curl "https://www.chouettecopro.com/api/v1/condominia/123"
  -u {api_key}

Exemple de réponse

{
    "data": {
        "id": "123",
        "type": "condominia",
        "links": {
            "self": "https://www.chouettecopro.com/api/v1/condominia/123"
        },
        "attributes": {
            "short_title": "Résidence Jean Moulin (75001 Paris)"
        },
        "relationships": {
            "tickets": {
                "links": {
                    "self": "https://www.chouettecopro.com/api/v1/condominia/123/relationships/tickets",
                    "related": "https://www.chouettecopro.com/api/v1/condominia/123/tickets"
                }
            },
            "picture": {
                "links": {
                    "self": "https://www.chouettecopro.com/api/v1/condominia/123/relationships/picture",
                    "related": "https://www.chouettecopro.com/api/v1/condominia/123/picture"
                }
            },
            "pictures": {
                "links": {
                    "self": "https://www.chouettecopro.com/api/v1/condominia/123/relationships/pictures",
                    "related": "https://www.chouettecopro.com/api/v1/condominia/123/pictures"
                }
            }
        }
    }
}

Renvoie les informations de la copropriété.

Arguments de l'URL

Nom	Description
`id`	L'identifiant de la copropriété

Arguments en query string

Nom	Description
`include`	La liste des données liées à récupérer

Retour

Un objet avec une propriété data contenant l'objet copropriété.

Signalements

L'objet signalement

Attributs

Nom	Description
`body`	Le message du ticket
`entrance`	Le nom ou numéro de l'entrée d'immeuble
`closed`	`true` si le ticket est fermé, `false` s'il est ouvert
`created_at`	La date de création du ticket
`updated_at`	La date de dernière mise à jour du ticket

Données liées

condominium : la copropriété dans laquelle a été déclaré le signalement
category : la catégorie du signalement
author : l'auteur du signalement
comments : les commentaires sur le signalement
service_orders : les ordres de service affectés au signalement
planned_intervention_dates : les dates d'intervention planifiées pour le signalement

Liste des signalements

Détail d'un signalement

Commentaires

Ordres de service

Catégories de signalement

Auteurs

Images

Errors

This error section is stored in a separate file in includes/_errors.md. Slate allows you to optionally separate out your docs into many files...just save them to the includes folder and add them to the top of your index.md's frontmatter. Files are included in the order listed.

The Kittn API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.