Nos APIs s’efforcent d’utiliser au maximum les standards REST et de garder une harmonie dans les façons de faire.
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. | 
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
    }
} 
				
			
		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.).
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.
 
													On n’utilise plus le header ApiKey. Les anciennes APIs continuent cependant de fonctionner sous ce modèle.
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);
} 
				
			
		Il n’existe pas de librairie CityScan backend. Voici donc un exemple inline d’authentification puis utilisation d’une API simple en GET.
				
					 '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.";
}
?> 
				
			
		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.
Les partenaires revendeurs (voir la section rôles).
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.
L’utilisateur authentifié final.
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.