Conventions API
Format des réponses, versioning, pagination et bonnes pratiques communes à Plus et Pro.
Dans cet article
URL de base
Toutes les requêtes sont des appels HTTPS vers l'API Njanggo. Le préfixe global est /api. L'API Pro versionnée utilise le namespace /api/v1.
| Environnement | URL |
|---|---|
| Production | https://api.njanggo.com/api |
| Pro (v1) | https://api.njanggo.com/api/v1 |
| OpenAPI (Pro) | https://api.njanggo.com/v1/openapi.json |
Versioning
Les routes Plus (webhooks calendrier, ICS, widget) utilisent le chemin actuel /api/calendars/.... Les routes Pro sont versionnées sous /api/v1 pour garantir la stabilité de vos intégrations lors des évolutions.
Les changements breaking seront publiés sous un nouveau prefix (/v2) avec une période de dépréciation annoncée dans le changelog.
Format des réponses
Les réponses JSON suivent une enveloppe cohérente. Succès :
{
"data": { ... }
}Erreur :
{
"statusCode": 422,
"message": "Validation failed",
"errors": [
{ "field": "startAt", "message": "La date de fin doit être postérieure au début" }
]
}Pagination
Les listes (invités, commandes, livraisons webhook) acceptent ?page= et ?limit=. La réponse inclut un objet meta :
| Champ meta | Description |
|---|---|
| page | Page courante (1-indexed) |
| limit | Éléments par page |
| total | Nombre total d'éléments |
| totalPages | Nombre total de pages |
Idempotence
Les webhooks incluent un X-Njanggo-Delivery-Id unique. Votre endpoint doit traiter chaque ID une seule fois — Njanggo peut renvoyer un webhook en cas d'échec réseau.
Pour les remboursements Pro, utilisez un header optionnel Idempotency-Key: <uuid> pour éviter les doubles remboursements en cas de retry.