V2 vs v1
La mise à jour en version 2.0 des API Zoho a eu un impact important sur l'utilisation des API et des fonctions (anciennement les fonctions personnalisées). Le fonctionnement des API est sensiblement le même, mais la syntaxe, la sortie et les méthodes sont différentes.
L'objectif de ce document est d'indiquer clairement les différences entre les deux API et aussi d'améliorer la compréhension de la version 2.0 pour les utilisateurs.
Différences de la V2 :
- Les formats d'entrée et de réponse de l'API sont uniquement compatibles JSON.
- Les API seront authentifiées par le protocole OAuth 2.0.
- Dans la version 2, il y a des noms d'API pour les modules, les champs et les listes associées, et non plus des étiquettes comme dans les API de la version 1.0.
- Les limites d'appel de l'API sont basées sur une fenêtre glissante de 24 heures, alors qu'en V 1.0, la limite d'appel de l'API est basée sur le fuseau horaire PST.
- Valeurs d'horodatage données au format ISO 8601 : (2018-03-28T10:32:45+05:30).
- Tous les noms d'API commençant par $ sont des attributs en lecture seule.
- Quand vous faites une requête GET sur un enregistrement, la réponse pour les champs vides est JSON Null.
- Les noms d'API des modules peuvent être récupérés à l'aide de l'URL de demande "https://www.zohoapis.com/crm/v2/settings/modules"
- Dans les API de mise à jour et/ou d'insertion, des actions automatisées comme le workflow, l'approbation et le blueprint peuvent être déclenchées pour tous les enregistrements en utilisant la clé “trigger”:["approval", "workflow", "blueprint"]
- Dans les API GET, les réponses auront une info JSONObject. Ex :
"info": {
"per_page": 200,
"count": 1,
"page": 1,
"more_records": false
}- page : pour obtenir la liste des enregistrements des pages respectives. La valeur par défaut est 1.
- per_page : pour obtenir la liste des enregistrements disponibles par page. La valeur par défaut est 200.
- more_records pour savoir s'il faut faire un appel API supplémentaire pour récupérer l'ensemble d'enregistrements suivant.
- getMyRecords (API v1.0) peut être récupéré avec searchRecords de l'API v2.0
Changements d'attribut de champ :
| Dans l'API v1.0 | Équivalent dans la version 2.0 de l'API |
|---|---|
| {MODULE}ID (Ex. LEADID, CONTACTID, etc) | id |
| SMOWNERID | Id donné dans le JSONObject Owner. |
| {MODULE} OWNER (Ex. Propriétaire du prospect, du dossier) | nom donné dans le JSONObject Owner. |
| SMCREATORID | Id donné dans le JSONObject Created_by. |
| Created By | Nom donné dans le JSONObject Created_by. |
| MODIFIEDBY | Id donné dans le JSONObject Modified_by. |
| Modified By | Nom donné dans le JSONObject Modified_by. |
Types de format du champ :
| Type de champ | Format V1.0 | Format V2.0 |
|---|---|---|
| Ligne unique | <FL val="Single_Line 1"> <![CDATA[this is single line]]> </FL> | "Single_Line_1": “This is single line”, |
| Plusieurs lignes | <FL val="Multi-Line 1"><![CDATA[this is multi line second line]]></FL> | "Multi_Line_1": "This is \multi line\second line", |
| <FL val="Email"><![CDATA[email@zoho.com]]><FL> | "Email_1": "email1@email.com", | |
| Téléphone | <FL val="Phone 1"><![CDATA[9900000000]]></FL> | "Phone_1": "9900000000", |
| Liste de choix | <FL val="picklist1"><![CDATA[one]]></FL> | "picklist1": "one", |
| Sélection multiple | <FL val="Multi-Select 1"><![CDATA[Option1;Option 2]]></FL> | "Multi_Select_1": [ "Option 1", "Option 2" ] |
| Date | <FL val="Date 1"><![CDATA[2018-03-29]]></FL> | "Date_1": "2018-03-29", |
| Date/Heure | <FL val="Date/Time 1"><![CDATA[2018-04-07 10:00:00]]></FL> | "Date_Time_1": "2018-04-07T10:00:00+05:30", |
| Nombre | <FL val="Number 1"><![CDATA[50000]]></FL> | "Number_1": 50000, |
| Devise | <FL val="Currency 1"><![CDATA[230000500]]></FL> | "Currency_1": 230000500, |
| Décimal | <FL val="Decimal 1"><![CDATA[1234.9]]></FL> | "Decimal_1": 1234.9, |
| Pourcentage | <FL val="Percent 1"><![CDATA[12.3]]></FL> | "Percent_1": 12.3, |
| Nombre entier long | <FL val="Long Integer 1"><![CDATA[6780000000780000]]></FL> | "Long_Integer_1": "6780000000780000", |
| Case à cocher | <FL val="Checkbox 1"><![CDATA[true]]></FL> | "Checkbox_1": true, |
| URL | <FL val="URL 1"><![CDATA[https://www.zoho.com]]></FL> | "URL_1": "https://www.zoho.com", |
| Recherche | <FL val="Lookup 1"><![CDATA[9500495sam]]></FL> | "Lookup_1": { "name": "9500495sam", "id": "1386586000001815005" } |
| Propriétaire de l'enregistrement | <FL val="SMOWNERID">1386586000000078001</FL> <FL val="Lead Owner"<>![CDATA[BruceWills]]></FL> | "Owner": { "name": "Bruce Wills", "id": "1386586000000078001" }, |
| Disposition | S/O | "Lookup_1": { "name": "9500495sam", "id": "1386586000001815005" } |
Méthodes API
| Nom de la méthode | Objectif |
|---|---|
| getRecords | Pour récupérer toutes les données utilisateur spécifiées dans la requête API |
| getRecordById | Pour récupérer des enregistrements individuels en fonction de l'ID d'enregistrement |
| getDeletedRecordIds | Pour récupérer la liste des ID des enregistrements supprimés à partir de la corbeille |
| insertRecords | Pour insérer des enregistrements dans le module Zoho CRM requis |
| updateRecords | Pour mettre à jour ou modifier les enregistrements dans Zoho CRM |
| getSearchRecordsByPDC | Pour rechercher les valeurs basées sur des colonnes prédéfinies |
| deleteRecords | Pour supprimer les enregistrements sélectionnés |
| convertLead | Pour convertir les prospects en potentiel, comptes et contacts |
| getRelatedRecords | Pour récupérer les enregistrements associés à un module principal |
| getFields | Pour récupérer les détails des champs disponibles dans un module |
| updateRelatedRecords | Pour mettre à jour les enregistrements relatifs à un autre enregistrement |
| getUsers | Pour récupérer la liste des utilisateurs de votre organisation |
| uploadFile | Pour joindre un fichier à un enregistrement |
| delink | Pour dissocier la relation parent/enfant des enregistrements |
| downloadFile | Pour télécharger un fichier joint à un enregistrement |
| deleteFile | Pour supprimer un fichier joint à un enregistrement |
| uploadPhoto | Pour ajouter une photo à un contact ou un prospect |
| downloadPhoto | Pour télécharger la photo d'un contact ou d'un prospect |
| deletePhoto | Pour supprimer une photo d'un contact ou d'un prospect |
| getModules | Pour récupérer tous les modules à partir du compte Zoho CRM |
| searchRecords | Pour récupérer les enregistrements correspondant à vos critères de recherche |