Votre site e-commerce doit envoyer ses commandes dans NetSuite. Votre CRM doit récupérer les factures. Votre outil de paie doit déposer ses écritures. Derrière chacune de ces connexions, une même question technique : par quelle API passer ?
NetSuite en propose trois : SOAP, REST et les RESTlets. Pendant des années, le choix relevait surtout des préférences des développeurs. Ce n’est plus le cas : NetSuite a programmé la fin de SOAP, et le choix de l’API conditionne désormais la durée de vie de vos intégrations.
Chez SuiteVise, nous concevons et maintenons des intégrations NetSuite au quotidien. Voici, simplement, ce qui distingue ces trois API et comment choisir la bonne.
Les trois API NetSuite en deux mots
SOAP (SuiteTalk SOAP Web Services) : l’API historique de NetSuite. Elle repose sur des échanges XML et des contrats de service (WSDL) versionnés à chaque release. Robuste et très utilisée par les connecteurs du marché, elle est aujourd’hui en fin de vie.
REST (SuiteTalk REST Web Services) : l’API moderne de NetSuite. Elle échange des données en JSON, permet de lire, créer, modifier et supprimer la plupart des enregistrements, et donne accès à SuiteQL, un langage de requêtes proche du SQL. C’est l’API que NetSuite recommande pour toute nouvelle intégration.
RESTlets : ce ne sont pas une API « prête à l’emploi », mais des points d’entrée que vous développez vous-même en SuiteScript, à l’intérieur de NetSuite. Un RESTlet peut contenir toute la logique d’un processus métier : valider des données, créer plusieurs enregistrements, appliquer des règles spécifiques, le tout en un seul appel.
SOAP : une fin programmée
C’est le point le plus important de cet article. NetSuite a annoncé le retrait progressif de ses services web SOAP, au profit de l’API REST et de l’authentification OAuth 2.0.
Les grandes étapes du calendrier annoncé :
| Version NetSuite | Ce qui change |
|---|---|
| 2025.2 | Dernier endpoint SOAP prévu |
| 2026.1 | Plus de nouvel endpoint SOAP livré à chaque version ; NetSuite demande de construire toute nouvelle intégration en REST, avec OAuth 2.0 |
| 2027.1 | Plus de nouvelles intégrations construites en SOAP, ni avec l’authentification par jetons |
| 2027.2 | Seul l’endpoint SOAP 2025.2 reste supporté |
| 2028.2 | Retrait complet de SOAP : les intégrations SOAP cessent de fonctionner |
Chaque endpoint SOAP est supporté trois ans après sa sortie, et le plus ancien est désactivé à chaque nouvelle version. Une intégration qui pointe encore vers un vieil endpoint peut donc s’arrêter bien avant 2028.
Ce que cela signifie concrètement :
- Aucune nouvelle intégration ne devrait être construite en SOAP.
- Les intégrations SOAP existantes doivent passer au moins sur l’endpoint 2025.2, puis être migrées vers REST ou des RESTlets.
- Les connecteurs du marché (plateformes d’intégration, applications tierces) doivent être vérifiés : certains utilisent encore SOAP en arrière-plan.
REST, SOAP et RESTlets : le comparatif
| Critère | SOAP | REST | RESTlets |
|---|---|---|---|
| Format | XML | JSON | JSON, texte ou XML, selon le développement |
| Nature | API standard de NetSuite | API standard de NetSuite | Point d’entrée développé sur mesure |
| Avenir | Retrait complet en 2028.2 | API recommandée par NetSuite | Pérenne, basé sur SuiteScript |
| Authentification | Authentification par jetons (TBA) | OAuth 2.0 (jetons acceptés pour les intégrations existantes) | OAuth 2.0 (jetons acceptés pour les intégrations existantes) |
| Requêtes SuiteQL | Non | Oui | Possible dans le code |
| Logique métier | Côté système appelant | Côté système appelant | Dans NetSuite, dans le RESTlet |
| Nombre d’appels pour un processus | Souvent plusieurs | Plusieurs, parfois moins qu’en SOAP | Souvent un seul |
| Développement | Pas de code côté NetSuite | Pas de code côté NetSuite | Code SuiteScript à écrire et maintenir |
| Consommation des ressources NetSuite | Limites de concurrence | Limites de concurrence | Limites de concurrence et unités de gouvernance SuiteScript |
À retenir : les limites de concurrence sont communes aux trois API. Elles dépendent du niveau de service de votre compte et des licences SuiteCloud Plus éventuelles. Multiplier les intégrations, c’est partager le même nombre d’appels simultanés.
Quelle API pour quel besoin ?
Choisissez REST quand…
- Vous avez besoin d’opérations standards sur des enregistrements : créer un client, mettre à jour une commande, lire une facture.
- Vous voulez extraire des données de façon souple avec SuiteQL, par exemple pour alimenter un entrepôt de données ou un outil de reporting.
- Vous utilisez une plateforme d’intégration ou un connecteur qui sait parler REST.
- Vous voulez limiter le code à maintenir dans NetSuite.
C’est le choix par défaut pour une nouvelle intégration.
Choisissez un RESTlet quand…
- Le processus métier demande plusieurs opérations liées : créer une commande, ses lignes, réserver le stock et renvoyer un statut, en un seul appel.
- Vous avez besoin de règles de validation spécifiques côté NetSuite, avant d’enregistrer les données.
- Vous voulez réduire le nombre d’appels pour préserver vos limites de concurrence.
- L’API REST ne couvre pas le cas d’usage ou certains enregistrements spécifiques.
Le RESTlet est puissant, mais c’est du code : il doit être documenté, testé et maintenu à chaque mise à jour de NetSuite.
Gardez SOAP seulement…
Pour une intégration existante, le temps de la migrer, en passant au minimum sur l’endpoint 2025.2.
Et souvent, les deux
Dans la pratique, beaucoup d’architectures combinent REST pour le standard et RESTlets pour les processus complexes. C’est souvent l’approche la plus équilibrée : peu de code, mais du sur-mesure là où il apporte vraiment quelque chose.
Les points d’attention, quelle que soit l’API
- L’authentification : privilégiez OAuth 2.0, la méthode que NetSuite recommande et qu’il rend obligatoire pour toute nouvelle intégration à partir de la version 2027.1. L’authentification par jetons reste possible pour les intégrations existantes. Dans tous les cas, prévoyez un compte et un rôle dédiés à chaque intégration. N’utilisez jamais les identifiants d’un utilisateur réel.
- Les permissions : le rôle de l’intégration doit avoir uniquement les droits nécessaires. C’est une question de sécurité, mais aussi de traçabilité.
- La concurrence : surveillez le nombre d’appels simultanés. Au-delà de la limite, les appels sont rejetés. Regrouper les traitements et planifier les flux lourds aux heures creuses évite bien des incidents.
- La gestion des erreurs : une intégration doit détecter, journaliser et rejouer les appels en échec. Sinon, des commandes ou des factures disparaissent sans que personne ne s’en aperçoive.
- Les scripts existants : les appels par API déclenchent les scripts serveur et les workflows, mais pas les scripts côté client. Une règle de contrôle placée uniquement dans un script client ne s’appliquera pas aux données reçues par API.
- Les identifiants externes : utilisez des identifiants externes pour relier les enregistrements entre systèmes et éviter les doublons.
- La documentation : chaque flux doit être documenté (sens, fréquence, données, responsable), pour pouvoir le maintenir et le faire évoluer.
Questions fréquentes
Quelle est la différence entre REST et RESTlet dans NetSuite ?
L’API REST est une API standard fournie par NetSuite pour manipuler les enregistrements et lancer des requêtes SuiteQL. Un RESTlet est un point d’entrée que vous développez en SuiteScript, pour exécuter une logique métier sur mesure en un seul appel.
L’API SOAP de NetSuite va-t-elle disparaître ?
Oui. Selon le calendrier annoncé par NetSuite, l’endpoint 2025.2 est le dernier prévu, les nouvelles intégrations SOAP ne sont plus possibles à partir de 2027.1, et SOAP est retiré complètement avec la version 2028.2.
Faut-il migrer ses intégrations SOAP maintenant ?
Il faut au minimum les passer sur l’endpoint 2025.2 et planifier leur migration vers REST ou des RESTlets. Une intégration sur un endpoint ancien peut s’arrêter avant 2028.
Qu’est-ce que SuiteQL ?
C’est un langage de requêtes proche du SQL, accessible notamment via l’API REST. Il permet d’extraire des données de façon plus souple que les recherches enregistrées.
Les RESTlets consomment-ils des ressources NetSuite ?
Oui. Ils partagent les limites de concurrence avec les autres API et consomment des unités de gouvernance SuiteScript. Mais un RESTlet bien conçu remplace souvent plusieurs appels.
Quelle API utilise le connecteur MCP de NetSuite ?
Les outils standards de l’AI Connector Service s’appuient sur les services web REST de NetSuite.
En résumé : REST par défaut, RESTlets pour le sur-mesure, SOAP à migrer
Pour toute nouvelle intégration, l’API REST est le choix naturel : standard, moderne et recommandée par NetSuite. Les RESTlets viennent en complément pour les processus métier complexes, à condition d’assumer le code qu’ils impliquent. Quant à SOAP, son retrait est programmé : il est temps d’inventorier vos intégrations existantes et de planifier leur migration.
Vous ne savez pas quelles intégrations utilisent encore SOAP, ou vous préparez un nouveau flux avec NetSuite ? SuiteVise vous accompagne : inventaire de vos intégrations, choix de l’architecture, migration vers REST et développement de RESTlets. Prenons 30 minutes pour en parler.