L'API publique de Ziggu expose 28 ressources réparties sur 55 endpoints, des projets et des unités jusqu'aux points de réserve, décisions, échéances et messages, à 60 requêtes par minute.
https://api.ziggu.app/public au format JSON:API.ziggu-integration-token, qui porte le slug de votre intégration et votre jeton, accordé par organisation sur demande.L'API publique de Ziggu expose 28 ressources sur 55 endpoints, en sept familles : structure du projet, personnes, réserves et suivi après livraison, décisions, argent, documents et messages. C'est toute la surface. Ce qui sort de ces sept familles n'est pas accessible depuis l'API, quoi qu'en dise la page produit d'à côté.
Une chose surprend chaque équipe le premier après-midi. Les noms dans l'API ne sont pas les noms sur le site. Un développeur cherche issues, un chef de projet appelle la même chose Reports. Les deux ont raison, et un tableau de correspondance vous épargne une heure de confusion au lancement.
| Famille | Ressources dans l'API | Comment cela s'appelle dans Ziggu |
|---|---|---|
| Structure du projet | projects, phases, lots, buildings, units, spaces, fractions | Projets |
| Personnes | customers, unit_customers, companies, partners, employees (lecture seule) | Clients et partenaires |
| Réserves et suivi | issues, issue_lists, issue_list_types, issue_categories, issue_statuses, tickets (lecture), ticket_categories (lecture) | Reports |
| Décisions | decisions, decision_types, decision_type_categories (lecture), proposals | Decisions and Approvals |
| Argent | installments, installments/groups | La couche financière de Client Updates |
| Documents | documents, attachment_categories | Documents |
| Messages | messages (GET et POST uniquement) | Conversations |
Lisez cette dernière colonne avant de nommer quoi que ce soit dans votre propre système. Un champ issue_status qui arrive dans un tableau de bord consulté chaque jour par vos chefs de projet sera lu comme un outil de suivi de bugs, pas comme une liste de réserves.
Un projet se divise en phases, lots et bâtiments, et ceux-ci portent les unités ; une unité porte ensuite ses espaces. Chaque clé étrangère suit cette ligne, donc un appel filtré à n'importe quel niveau renvoie la branche située en dessous.
fractions se tient à côté de cette ligne plutôt que dedans : elle porte un projet, une unité et une échéance, et constitue donc le lien entre une unité et ce qui lui est facturé.
Deux points à connaître avant d'écrire les jointures. Les phases, lots et bâtiments portent chacun units_count et units_active_count, donc un cumul pour le reporting ne demande aucune agrégation de votre côté. Et tout niveau sauf le projet et l'unité est facultatif : une unité peut dépendre directement d'un projet.
L'authentification passe par un en-tête propre, ziggu-integration-token, qui contient le slug de votre intégration et votre jeton. Ce n'est pas OAuth 2.0 et il n'y a pas de bearer token. L'accès est accordé par organisation, sur demande : décrivez à notre équipe ce que vous voulez construire, et elle met l'intégration en place avec vous.
La limite est de 60 requêtes par minute, comptées sur l'ensemble des endpoints et non par ressource. Prévoyez donc une synchronisation nocturne plutôt qu'une boucle par enregistrement.
L'API n'est pas en lecture seule. La plupart des ressources acceptent POST, PUT ou PATCH, et plusieurs acceptent DELETE. messages est l'exception qui piège : elle accepte GET et POST, vous pouvez donc publier dans une conversation mais pas modifier ni supprimer ce qui s'y trouve.
Les réponses suivent JSON:API. Un import à plat vous donne une seule colonne data : prévoyez de déplier data et attributes, et de résoudre les relations qui arrivent sous forme de références et non d'objets imbriqués.
La disponibilité est publiée plutôt que promise : sur les 60 derniers jours, l'API a tourné à 99,997 %, sur la même page de statut publique que l'application et le site.
Quatre possibilités présentes sur le site de Ziggu n'ont pas d'endpoint derrière elles, et le savoir d'avance vaut mieux que n'importe quelle liste de fonctionnalités.
Il n'y a pas de ressource tasks. La gestion des tâches est une fonctionnalité du produit, et elle n'est pas exploitable via l'API publique. Si votre tableau de bord a besoin de l'état des tâches, il lui faut une autre voie.
Il n'y a pas de jalons. phases existe et on le prend souvent pour cela, mais une phase est un niveau de structure qui porte des lots et des bâtiments, pas une date sur une ligne du temps. Ce que vous bâtissez sur des jalons dans l'API repose sur une ressource qui n'existe pas.
Forms et Workflows n'ont pas non plus d'endpoint. Les réponses aux formulaires et l'état d'un workflow restent dans le produit.
Il n'y a pas de webhooks. Rien dans l'API ne vous pousse quoi que ce soit : chaque intégration est donc un appel à votre rythme, dans la limite des 60 par minute. Ce seul fait décide en général de l'architecture : un changement dans Ziggu devient visible dans votre système au prochain appel, pas au moment où il se produit.
| Fonctionnalité sur le site | Endpoint dans l'API publique |
|---|---|
| Reports | Oui : issues, issue_lists, tickets |
| Decisions and Approvals | Oui : decisions, proposals |
| Documents | Oui : documents, attachment_categories |
| Conversations | En partie : messages, GET et POST seulement |
| Client Updates | En partie : installments et installments/groups |
| Gestion des tâches | Non |
| Forms | Non |
| Workflows | Non |
Si vous cherchez une connexion avec un outil précis plutôt qu'une liste de ressources, l'aperçu des intégrations est le chemin le plus court.
La référence complète est une spécification OpenAPI 3.0.3, publiée sur api.ziggu.app/api_docs, et elle décrit chaque endpoint avec ses champs et ses relations. C'est la source de référence : là où cette page et la spécification divergent, c'est la spécification qui a raison.
Pour démarrer, contactez notre équipe avec l'intégration que vous avez en tête. L'accès se met en place par organisation, et c'est de cette même conversation que vient votre jeton.
