🔥 CityScan devient Modelo Insight ! Découvrez la nouvelle solution tout-en-un sur modelo.fr

Introduction au développement

Standards

HTTP

Nos APIs s’efforcent d’utiliser au maximum les standards REST et de garder une harmonie dans les façons de faire.

  • Un POST pour une création d’entité.
  • Un DELETE pour une suppression.
  • Un format standard pour les résultats paginés.
  • Limiter le nesting.

 

Nous vous détaillons champ par champ les erreurs dans les payloads d’entrée.

				
					{
    "message": "Erreur dans le payload envoyé",
    "details": {
        "titleFont": [
            "The selected choice is invalid."
        ],
        "variant": [
            "la valeur envoyée \"xxx\" ne fait pas partie de cette liste -> [curvy, bubble, spiral, vanguard, panoramic, technologic]"
        ],
        "coverVariant": [
            "la valeur envoyée \"yyy\" ne fait pas partie de cette liste -> [curvy, vanguard, panoramic]"
        ]
    }
}
				
			

Vous pouvez ainsi afficher ces erreurs à votre utilisateur, mais nous vous conseillons surtout de les utiliser à des fins de debug dans votre intégration.

Status code Summary Signification

200

OK
Récupération d'une ou plusieurs entités (GET). Action ou modification effective (POST).

201

CREATED
Création d'une entité avec succès (requête POST).

204

NO CONTENT
Suppression d'une entité avec succès (requête DELETE).

401

UNAUTHORIZED
Erreur d'authentification (Bearer manquant ou incorrect).

403

FORBIDDEN
Opération interdite. Incohérence métier ou droits incorrects.

404

NOT FOUND
Ressource introuvable. Généralement, quand il y a un identifiant dans l'URL et qu'il est introuvable (inexistant ou non lié à l'utilisateur).

409

CONFLICT
Une ressource dupliquée, ou une action en conflit avec une autre, interdite par une règle métier.

422

UNPROCESSABLE ENTITY
Erreur dans le payload. Vérifiez le format form-data ou raw/json. Vérifiez le typage et que les valeurs soient bien incluses dans les enums autorisés.

500, 502, 503, 504

SERVER ERRORS
Un problème serveur de notre côté. Ces erreurs sont rares et nous vous serions reconnaissants de nous prévenir lorsque vous les rencontrez.
PAGINATION

Voici le format classique de notre pagination. Chaque requête paginée accepte les paramètres page, pour cibler le numéro de la page de résultats à charger, et limit, pour décider de la valeur de itemsPerPage.

				
					{
    "items": [
        {
            "id": 6607,
            "createdAt": "2024-08-29 10:54:37",
            "updatedAt": "2024-08-29 10:54:59",
            "otherFields": ...
        },
        {
            "id": 6606,
            "createdAt": "2024-08-29 10:42:01",
            "updatedAt": "2024-08-29 10:42:47",
            "otherFields": ...
        }, ...
    ],
    "pagination": {
        "page": 1,
        "totalPages": 12,
        "itemsPerPage": 30,
        "totalItems": 341
    }
}
				
			
FORMAT

Le payload d’entrée peut être en form-data ou en raw/json. Les réponses en json (sauf pour les ressources image, pdf, etc.).

ENVIRONNEMENTS

Production et Staging. Pensez bien à switcher l’environnement sur Postman. Si vous avez effectué des tests en prod, n’hésitez pas à nous contacter pour faire le ménage avant votre mise en production de l’intégration CityScan.

🔐 L’authentification

📛 Obsolète

On n’utilise plus le header ApiKey. Les anciennes APIs continuent cependant de fonctionner sous ce modèle.

🔑 JWT auth

On fonctionne désormais exclusivement via Bearer Token, à durée de vie limitée. Demandez un token via l’API d’authentification pour l’injecter dans les autres APIs en tant que Bearer Token.

Le Postman est rempli de Pre-Scripts et Post-Scripts qui requêtent et sauvegardent les tokens dans des variables d’environnements ou de collection et réutilisent ces variables dans les différentes APIs. Inspirez-vous librement de ces pratiques pour vos développements. Voici un exemple de récupération du token dans la variable de collection reseller_token visible dans le Script Post-response de l’API d’authentification

				
					let jsonData = pm.response.json();
pm.test("Status code is 200", () => {
  pm.response.to.have.status(200);
});
if (pm.response.code == 200) {
    pm.test("Response has token", () => {
      pm.expect(jsonData).to.have.property('token');
    });
    pm.collectionVariables.set("reseller_token", jsonData.token ?? null);
}
				
			
Exemple PHP

Il n’existe pas de librairie CityScan backend. Voici donc un exemple inline d’authentification puis utilisation d’une API simple en GET.

				
					<?php

// Step 1: Authenticate and retrieve the JWT token
$authUrl = 'https://api.cityscan.fr/resellers/security/login';
$authData = [
    'identifier' => 'your-identifier-here', // Replace with your identifier
    'secret' => 'your-secret-here' // Replace with your secret
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $authUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($authData));

$response = curl_exec($ch);
curl_close($ch);

$authResponse = json_decode($response, true);
$token = $authResponse['token'] ?? null;

if ($token) {
    // Step 2: Use the token to make the second API call
    $apiUrl = 'https://api.cityscan.fr/resellers/bundles';

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $token"
    ]);

    $apiResponse = curl_exec($ch);
    curl_close($ch);

    // Output the result of the second API call
    echo $apiResponse;
} else {
    echo "Authentication failed. Please check your credentials.";
}

?>
				
			

🤐 Confidentialité

CityScan n’utilisera jamais les données issues de nos clients et partenaires à des fins commerciales. Toute la donnée que vous décidez de synchroniser avec notre base de données sert uniquement à l’expérience utilisateur (affichage dans les rapports, aide facilité pour l’équipe support). Les mails ne sont ajoutés à aucune liste de diffusion ou newsletter.

Entités

Resellers

Les partenaires revendeurs (voir la section rôles).

Companies

Les sociétés. Généralement une agence immobilière qui souscrit pour une équipe d’agents immobiliers. C’est elle qui est facturée. Des personnalisations peuvent être appliquées au niveau société/agence pour être héritées à tous les enfants.

Users

L’utilisateur authentifié final.

Stratégie de synchronisation (pour les revendeurs)

Si CityScan est une offre payante

Vous ne devriez pas synchroniser votre base de données avec la nôtre. Nous recommandons plutôt de créer la société et les utilisateurs seulement au moment de l’abonnement au package CityScan payant.

Si CityScan est inclus pour tous vos utilisateurs

Préparez et exécutez un script pour créer toutes les sociétés et leur associer tous les utilisateurs. Veillez à ajouter chaque nouvel utilisateur à la base CityScan.

Une fois un utilisateur créé et existant dans la base CityScan, toute modification apportée à cet utilisateur devrait être synchronisée avec nous (nom, prénom, société, téléphone, mail, etc.) pour assurer la cohérence.