API et intégrations

Les signalements publiés sont accessibles par une API JSON, par Open311 (compatible avec les SIG comme ArcGIS ou QGIS et les GMAO), par des webhooks et par un widget à intégrer.

Principes

• Chaque site a sa propre API, à son adresse : ici https://scopemy.city.
• Seuls les signalements publiés après modération et leurs champs publics sortent. Sur le site d'une collectivité : ses signalements ; sur scopemy.city : tous, sauf ceux qu'une collectivité garde internes.
• La lecture est ouverte, sans clé. Une clé d'API (en-tête X-Api-Key), créée par l'administration de la collectivité, relève la limite de débit ; une clé en écriture permet de déposer des demandes par Open311.
• Limite : 120 requêtes par minute et par adresse IP, 600 par clé. Au-delà : réponse 429 avec l'en-tête Retry-After.
• Pagination par curseur (champ pagination.suivant, en-tête Link). Réponses en cache public avec ETag : renvoyez If-None-Match pour obtenir un 304.
• Données sous licence CC BY 4.0. Données ouvertes

Spécification OpenAPI 3.1 : openapi.yaml · openapi.json

curl -H 'Accept: application/json' 'https://scopemy.city/api/v1/signalements?statut=resolu&limite=20'

API JSON

Open311 GeoReport v2

Format JSON uniquement. Les services sont les catégories du site, les demandes sont les signalements publiés ; status vaut open (nouveau, en cours) ou closed (résolu, rejeté).

Données ouvertes

Webhooks

Une collectivité peut abonner une adresse https à ces événements (administration, page API). Nous lui envoyons un POST JSON dans les 5 minutes ; un signalement pas encore publié n'y figure qu'avec sa référence, sa catégorie, ses statuts, sa position et ses dates.

Chaque envoi est signé dans l'en-tête X-Scopemy-Signature : t=horodatage,v1=HMAC-SHA256 du texte « t.corps » avec votre secret. Vérifiez-le, en temps constant, et refusez un horodatage de plus de 5 minutes. X-Scopemy-Delivery donne un identifiant stable : ignorez un envoi déjà reçu.

$corps = file_get_contents('php://input');
[$t, $sig] = sscanf($_SERVER['HTTP_X_SCOPEMY_SIGNATURE'] ?? '', 't=%d,v1=%s');
$attendu = hash_hmac('sha256', $t . '.' . $corps, $secret);
if (!$sig || !hash_equals($attendu, $sig) || abs(time() - $t) > 300) {
    http_response_code(400); exit;
}
$evenement = json_decode($corps, true);   // id, type, tenant, data.signalement
http_response_code(204);

Toute réponse 2xx vaut réception. Sinon, nous réessayons jusqu'à 8 fois, en doublant l'attente (1 min, 2 min, 4 min…, 6 h au plus). Les redirections ne sont pas suivies.

Widget pour le site de la commune

Collez ce code dans une page du site de la commune pour afficher la carte et les derniers signalements, à la marque de la collectivité. Le site doit d'abord être autorisé dans l'administration (page API).

<script src="https://scopemy.city/embed.js" data-vue="carte-liste" data-hauteur="560" async></script>

Options : data-vue (carte-liste, carte ou liste), data-hauteur (en pixels, ou auto), data-lang (fr, de, it, en). Le widget ne pose aucun cookie.