Guide complet d'intégration de l'API Gridky v3 dans WordPress

11 juin 2025• Wordpress•9 Minutes
gridky

Retour d’expérience technique sur l’intégration complète de l’API Gridky pour la synchronisation automatique de programmes immobiliers neufs.

Qu’est-ce que Gridky et pourquoi l’intégrer ?

Gridky : La plateforme de référence pour l’immobilier neuf

Gridky est une plateforme SaaS spécialisée dans la gestion et la commercialisation de programmes immobiliers neufs. Elle centralise toutes les informations relatives aux projets immobiliers : programmes, lots, prix, disponibilités, documents commerciaux, et bien plus encore.

À qui s’adresse cette intégration ?

Cette solution technique s’adresse principalement aux :

  • Promoteurs immobiliers qui souhaitent automatiser la diffusion de leurs programmes
  • Agents immobiliers spécialisés dans le neuf qui veulent synchroniser leur catalogue
  • Plateformes de vente en ligne nécessitant des données immobilières à jour
  • Développeurs WordPress travaillant sur des sites immobiliers
  • Agences web créant des solutions pour le secteur immobilier

Les enjeux de la synchronisation automatique

Sans intégration API, la gestion manuelle des programmes immobiliers pose plusieurs défis :

  • Mise à jour fastidieuse : modification manuelle de centaines de programmes
  • Risque d’erreurs : informations obsolètes ou incorrectes
  • Perte de temps : ressaisie répétitive des mêmes données
  • Manque de réactivité : retard dans la publication des nouveautés

L’intégration de l’API Gridky v3 résout ces problématiques en automatisant complètement la synchronisation bidirectionnelle entre Gridky et WordPress.

Architecture technique recommandée

Stratégie de synchronisation hybride

Notre retour d’expérience sur l’intégration pour l’extension Les Programmes Neufs (LPN) nous a menés à adopter une approche hybride combinant :

1. Synchronisation complète périodique (nocturne)

  • Import/mise à jour de tous les programmes
  • Détection des suppressions
  • Réconciliation des données
  • Avantage : résilience et cohérence globale

2. Webhooks temps réel

  • Notifications instantanées des changements
  • Mise à jour immédiate des nouveautés
  • Avantage : réactivité maximale

Cette stratégie garantit une synchronisation fiable même en cas de panne temporaire des webhooks.

Gestion des types de fiscalité

Point important : L’endpoint programsPinel sera supprimé prochainement car cette fiscalité n’existe plus.

Les endpoints à utiliser sont :

  • /v3/programsPersonalResidency (Résidence Principale)
  • /v3/programsControlledPrice (Prix Maîtrisé)
  • /v3/programsReducedVAT (TVA Réduite)

Implémentation technique détaillée

Configuration de base de l’API

class GridkyAPI {
    private $base_url = 'https://api.gridky.com/v3/';
    private $token;
    
    public function __construct($bearer_token) {
        $this->token = $bearer_token;
    }
    
    private function make_request($endpoint, $params = []) {
        $url = $this->base_url . $endpoint;
        if (!empty($params)) {
            $url .= '?' . http_build_query($params);
        }
        
        $response = wp_remote_get($url, [
            'headers' => [
                'Authorization' => 'Bearer ' . $this->token,
                'Accept' => 'application/json'
            ],
            'timeout' => 30
        ]);
        
        return json_decode(wp_remote_retrieve_body($response), true);
    }
}

Récupération optimisée des programmes

Règle importante : Ne jamais inclure properties lors de la récupération en masse car cela provoque des erreurs 504 Gateway Timeout.

function sync_programs_by_fiscality($fiscality_type) {
    $gridky = new GridkyAPI(get_option('gridky_api_token'));
    $page = 1;
    $all_programs = [];
    
    do {
        // Pagination recommandée : 100 par page
        $params = [
            'include' => 'municipality,promoter', // SANS properties !
            'per_page' => 100,
            'page' => $page
        ];
        
        $response = $gridky->make_request($fiscality_type, $params);
        
        if (empty($response['data'])) break;
        
        $all_programs = array_merge($all_programs, $response['data']);
        $page++;
        
        // Respect du rate limit : 240 calls/minute
        usleep(250000); // 0.25 seconde entre chaque appel
        
    } while (!empty($response['data']));
    
    return $all_programs;
}

Récupération des propriétés par programme

Pour éviter les timeouts, récupérez les propriétés séparément pour chaque programme :

function get_program_properties($program_uuid, $fiscality_type) {
    $gridky = new GridkyAPI(get_option('gridky_api_token'));
    
    // Mapping des types de fiscalité vers les endpoints propriétés
    $property_endpoints = [
        'programsPersonalResidency' => 'propertiesPersonalResidency',
        'programsControlledPrice' => 'propertiesControlledPrice',
        'programsReducedVAT' => 'propertiesReducedVAT'
    ];
    
    $endpoint = $property_endpoints[$fiscality_type];
    
    $params = [
        'filter[programs][0]' => $program_uuid,
        'include' => 'images,program.municipality',
        'per_page' => 100
    ];
    
    return $gridky->make_request($endpoint, $params);
}

Fonction de synchronisation complète

function wp_lpn_sync_complete() {
    $fiscality_types = [
        'programsPersonalResidency',
        'programsControlledPrice', 
        'programsReducedVAT'
    ];
    
    foreach ($fiscality_types as $type) {
        echo "Synchronisation de $type...\n";
        
        // 1. Récupération de tous les programmes
        $api_programs = sync_programs_by_fiscality($type);
        
        // 2. Comparaison avec WordPress
        $wp_programs = get_wordpress_programs($type);
        
        // 3. Import des nouveaux programmes
        $new_programs = array_diff_key($api_programs, $wp_programs);
        foreach ($new_programs as $program) {
            import_new_program($program, $type);
        }
        
        // 4. Mise à jour des programmes existants
        $existing_programs = array_intersect_key($api_programs, $wp_programs);
        foreach ($existing_programs as $program) {
            update_existing_program($program, $type);
        }
        
        // 5. Suppression des programmes obsolètes
        $obsolete_programs = array_diff_key($wp_programs, $api_programs);
        foreach ($obsolete_programs as $program) {
            delete_obsolete_program($program['uuid']);
        }
    }
    
    echo "Synchronisation terminée.\n";
}

Configuration des Webhooks temps réel

Sécurisation de l’endpoint webhook

Gridky utilise une signature HMAC SHA256 pour sécuriser les appels webhook :

// Endpoint : /wp-json/lpn/v1/webhook/gridky
function handle_gridky_webhook() {
    $body = file_get_contents('php://input');
    $signature = $_SERVER['HTTP_SIGNATURE'] ?? '';
    $secret = get_option('gridky_webhook_secret');
    
    // Vérification de la signature
    $expected_signature = hash_hmac('sha256', $body, $secret);
    
    if (!hash_equals($signature, $expected_signature)) {
        http_response_code(401);
        exit('Unauthorized');
    }
    
    $data = json_decode($body, true);
    process_webhook_event($data);
    
    http_response_code(200);
    echo json_encode(['success' => true]);
}

Traitement des événements webhook

function process_webhook_event($data) {
    $event_type = $data['type'] ?? '';
    $payload = $data['payload'] ?? [];
    
    switch ($event_type) {
        case 'program.created':
        case 'program.updated':
            sync_single_program($payload['identifier']);
            break;
            
        case 'program.deleted':
            delete_program_by_uuid($payload['identifier']);
            break;
            
        case 'property.created':
        case 'property.updated':
            sync_single_property($payload['identifier']);
            break;
            
        case 'property.deleted':
            delete_property_by_uuid($payload['identifier']);
            break;
    }
}

Optimisations et bonnes pratiques

Respect des limites de l’API

Rate limiting Gridky : 240 appels par minute maximum

class GridkyRateLimiter {
    private $calls_made = 0;
    private $minute_start;
    
    public function __construct() {
        $this->minute_start = time();
    }
    
    public function wait_if_needed() {
        $elapsed = time() - $this->minute_start;
        
        if ($elapsed >= 60) {
            $this->calls_made = 0;
            $this->minute_start = time();
        }
        
        if ($this->calls_made >= 240) {
            sleep(60 - $elapsed);
            $this->calls_made = 0;
            $this->minute_start = time();
        }
        
        $this->calls_made++;
    }
}

Gestion des erreurs et retry

function safe_api_call($callback, $max_retries = 3) {
    $attempt = 0;
    
    while ($attempt < $max_retries) {
        try {
            return $callback();
        } catch (Exception $e) {
            $attempt++;
            
            if ($attempt >= $max_retries) {
                error_log("API call failed after $max_retries attempts: " . $e->getMessage());
                throw $e;
            }
            
            // Attente progressive : 1s, 2s, 4s...
            sleep(pow(2, $attempt - 1));
        }
    }
}

Optimisation des performances WordPress

function batch_update_programs($programs, $batch_size = 50) {
    $batches = array_chunk($programs, $batch_size);
    
    foreach ($batches as $batch) {
        // Désactiver temporairement les hooks pour améliorer les performances
        wp_defer_term_counting(true);
        wp_defer_comment_counting(true);
        
        foreach ($batch as $program) {
            update_wordpress_program($program);
        }
        
        // Réactiver les hooks
        wp_defer_term_counting(false);
        wp_defer_comment_counting(false);
        
        // Pause entre les batches
        usleep(100000); // 0.1 seconde
    }
}

Surveillance et monitoring

Logs détaillés

function log_sync_activity($message, $level = 'info') {
    $timestamp = date('Y-m-d H:i:s');
    $log_entry = "[$timestamp] [$level] $message" . PHP_EOL;
    
    file_put_contents(
        WP_CONTENT_DIR . '/gridky-sync.log', 
        $log_entry, 
        FILE_APPEND | LOCK_EX
    );
}

Dashboard de synchronisation

Créez une page d’administration WordPress pour :

  • Lancer la synchronisation manuelle
  • Consulter les logs d’activité
  • Afficher les statistiques (programmes synchronisés, erreurs, etc.)
  • Configurer les paramètres API

Résultats et métriques

Performance de synchronisation

D’après notre expérience sur l’extension LPN :

  • 2 410 programmes Personal Residency synchronisés
  • 265 programmes Reduced VAT traités
  • Temps de synchronisation : ~30 minutes pour l’import complet
  • Taux de succès : 99.8% après optimisations

Problèmes courants et solutions

Timeouts lors de l’import

  • Cause : inclusion de properties dans les requêtes de masse
  • Solution : récupération séparée des propriétés

Écarts de nombres entre API et WordPress

  • Cause : programmes changeant de type de fiscalité
  • Solution : vérification des UIDs dans tous les types

Programmes sans propriétés

  • Cause : décalage temporel entre création programme et propriétés
  • Solution : re-synchronisation différée

Conclusion

L’intégration de l’API Gridky v3 dans WordPress représente un gain de temps considérable pour les professionnels de l’immobilier neuf. La stratégie hybride (synchronisation nocturne + webhooks) assure une fiabilité maximale tout en conservant la réactivité temps réel.

Points clés à retenir :

  • Pagination à 100 pour optimiser les performances
  • Respect du rate limit (240 calls/minute)
  • Récupération séparée des programmes et propriétés
  • Webhooks sécurisés avec signature HMAC
  • Gestion d’erreurs robuste avec retry automatique

Cette approche technique éprouvée vous permettra de créer une synchronisation automatique fiable entre Gridky et WordPress, libérant vos équipes des tâches répétitives pour se concentrer sur la commercialisation.

Besoin d’aide pour votre intégration Gridky ?

Chez Pixfeed, nous accompagnons régulièrement nos clients dans l’intégration d’APIs complexes comme Gridky. Si vous rencontrez des difficultés techniques ou souhaitez déléguer cette intégration, nous serions ravis d’échanger sur votre projet.

webhook

Ecrire un commentaire

© 2025 Pixfeed. | Tous droits réservés.

Privacy Preference Center

Privacy Preferences