alegra-api-client

Client léger et typé en TypeScript pour l'API Alegra, orienté vers la couche d'intégration. Il couvre l'authentification, la pagination et la gestion des rate limits avec des tentatives sur les ressources contacts, articles et factures. C'est un projet non officiel, sans affiliation avec Alegra, et sa documentation est en espagnol car, selon l'auteur, elle est peu disponible. Authentification Utilise HTTP Basic avec l'e-mail et le jeton API (pas le mot de passe). Le jeton est généré dans Alegra, dans la section intégrations/API du compte. L'URL de base indiquée est https://api.alegra.com/api/v1 et un échec d'authentification répond par HTTP 401. Le README recommande de sauvegarder les identifiants dans des variables d'environnement et non dans le code ; un fichier .env.example est inclus. Pagination L'API renvoie au maximum 30 enregistrements par page via les paramètres start (offset) et limit. Le client expose un générateur asynchrone pour parcourir page par page sans tout charger en mémoire, ainsi que des méthodes pour obtenir une seule page ou collecter tous les résultats. Les ressources disponibles et leurs méthodes sont : contacts (listar, obtener, paginar, listarTodos), items (listar, obtener, paginar, listarTodos) et facturas (listar, obtener, paginar, listarTodas). Pour les endpoints non couverts, on peut utiliser le client direct avec un appel request générique acceptant des paramètres de requête. Rate limits et tentatives Le README documente une limite de 150 requêtes par minute par utilisateur (environ 2,5 par seconde). En cas de dépassement, l'API répond HTTP 429 et informe l'état dans les en-têtes X-Rate-Limit-Limit, X-Rate-Limit-Remaining et X-Rate-Limit-Reset (secondes restantes pour réinitialiser la fenêtre) ; selon l'auteur, Alegra n'envoie pas de Retry-After. Le client tente automatiquement de renvoyer la requête en cas de 429 et 5xx : pour le 429, il attend la durée indiquée par X-Rate-Limit-Reset (ou Retry-After si présent) et, à défaut, applique un backoff exponentiel avec jitter. Les erreurs 4xx ne font l'objet d'aucune tentative, et des tentatives sont également prévues en cas de pannes réseau. Options configurables mentionnées : minRequestIntervalMs (espacement préventif entre requêtes), maxRetries, retryBaseMs et timeoutMs. Le timeout par requête est implémenté avec AbortController. Si les tentatives s'épuisent face à un 429, AlegraRateLimitError est lancé, pouvant inclure retryAfterSeconds. Erreurs Sont exposées les classes AlegraApiError (avec status, endpoint et body) et AlegraRateLimitError pour distinguer les erreurs d'API des limites d'utilisation épuisées. Prérequis et développement Nécessite Node.js 18 ou supérieur pour l'utilisation de fetch natif, et n'a aucune dépendance au moment de l'exécution ; il se présente comme portable vers Node, Deno et les environnements edge. Le flux de développement inclut npm run build, des tests avec vitest sur fetch simulé et des données fictives, ainsi qu'une vérification des types (lint:types). Les exemples utilisent des données fictives et des identifiants via variables d'environnement. Licence MIT ; la version listée dans le changelog est 0.1.0, première version publique. Portée Le README lui-même avertit que le tableau résumé de l'API Alegra inclus doit être mis à jour si l'API officielle change, et que ce résumé existe en raison de la rareté de la documentation en espagnol. Aucune affirmation de performance ni comparaison avec d'autres clients n'est proposée.