Ressource (sdata)

De Wiki1000
(Différences entre les versions)
(→Modification des attributs privés)
(→Modèle de ressource (GET $template))
 
(77 révisions intermédiaires par un utilisateur sont masquées)
Ligne 1 : Ligne 1 :
 
__TOC__
 
__TOC__
 +
 +
==Prérequis==
 +
Les requêtes SData sont exécutées sur [[SData|le point d'accès SData du service]].
 +
 +
La forme simplifiée des urls est
 +
 +
<pre>http://hostname/sdata/ressource?paramètres</pre>
 +
 +
ou
 +
 +
<pre>http://hostname/sdata/societe/ressource?paramètres</pre>
 +
 +
Les requêtes sont authentifiées par un jeton d'authentification placé dans l'entête Authorization de la requêtes.
 +
 +
[[Gestion des jetons d'authentification (Administration)|Le jeton d'authentification peut être géré par le client dans l'administration.]]
 +
 +
Les requêtes doivent comporter les entêtes suivantes :
 +
 +
{|class="wikitable"
 +
|-
 +
|accept
 +
|application/json
 +
|-
 +
|Authorization
 +
|Bearer token
 +
|}
 +
 +
Les url des requêtes doivent être encodées, par exemple :
 +
 +
<pre>https://.../sdata/Société 1/ttiers...</pre>
 +
 +
doit être transmis encodé en
 +
 +
<pre>https://.../sdata.Soci%C3%A9t%C3%A9%201/ttiers....</pre>
 +
 +
==Sélection de version==
 +
Il es possible d'indiquer un numéro de version dans l'url de la requête.
 +
 +
Placez le numéro de version derrière le préfix sdata :
 +
 +
<pre>
 +
https://.../sdata/1/....
 +
</pre>
 +
 +
En absence de numéro de version la dernière version sera utilisée.
 +
 +
==Informations de version==
 +
Utilisez la fonction $version pour retrouver les informations de version
 +
 +
<pre>
 +
GET http://localhost:8080/sdata/$version
 +
{
 +
    "product": "Sage FRP 1000",
 +
    "version": "9.1.0.0",
 +
    "master": "1.22",
 +
    "apiMajor": 1,
 +
    "apiMinor": 0,
 +
    "debug": true,
 +
    "shareEnable": true
 +
}
 +
</pre>
 +
 +
<pre>
 +
GET https://localhost/sdata/$version?select=details
 +
{
 +
    "product": "Sage FRP 1000",
 +
    "version": "9.1.0.0",
 +
    "master": "1.22",
 +
    "apiMajor": 1,
 +
    "apiMinor": 1,
 +
    "debug": true,
 +
    "minors": [
 +
        {
 +
            "minor": 1,
 +
            "details": [
 +
                "Fix $batch : Error in commit don't return message and continue execution",
 +
                "Fix time measure decimal format use . instead of local",
 +
                "Add extension information to $schema",
 +
                "Add operations to $schema",
 +
                "Add select options to $schema"
 +
            ]
 +
        },
 +
        {
 +
            "minor": 0,
 +
            "details": [
 +
                "Add version information"
 +
            ]
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
 +
Le paramètre select accepte les options suivantes :
 +
 +
{|class="wikitable"
 +
|-
 +
!option
 +
!usage
 +
|-
 +
|details
 +
|Détails des modifications des versions mineurs
 +
|-
 +
|patches
 +
|Liste des patches installés
 +
|}
  
 
==Ressource (GET)==
 
==Ressource (GET)==
Ligne 45 : Ligne 150 :
 
|-
 
|-
 
|clause
 
|clause
−
|TTiers(code eq 'SYFRE1')
+
|TTiers(code eq 'ABI 007')
 
|}
 
|}
  
Ligne 62 : Ligne 167 :
 
|}
 
|}
  
−
===Gestion des rôles===
+
===Gestion des rôles dans les ressources===
−
La gestion des rôles de la ressource dépend du type de rôle :
+
La gestion des rôles de la ressource dépend du type et de la nature du rôle :
  
−
* Pour un rôle composition la ressource "composant" est retournée par valeur dans le corps de la ressource "composée"
+
{|class="wikitable"
−
* Pour un rôle qui n'est pas une composition la ressource "composant" est retournée par référence dans le corps de la ressource "composée"
+
|-
 +
!Type de rôle
 +
!Nature
 +
!Retour
 +
|-
 +
|Référence,Liste
 +
|Composition
 +
|Les ressources composants sont retournées dans le corps de la ressource composée
 +
|-
 +
|Référence
 +
| -
 +
|La ressource référencée est retournée par référence dans le corps de la ressource
 +
|-
 +
|Liste
 +
| -
 +
|Les ressources ne sont pas retournées. Pour obtenir ces ressources, il faut faire une requête sur la classe référencée filtrée sur la référence réciproque.
 +
|-
 +
|Association
 +
|Avec suppression en cascade
 +
|Les ressources associées sont considérées comme des composants et retournées dans le corps de la ressource composée.
 +
|-
 +
|Association
 +
| -
 +
|Les ressources ne sont pas retournées. Pour obtenir ces ressources, il faut faire une requête sur la classe associée filtrée sur la classe d'association
 +
|}
 +
 
 +
{{tip|Utilisez une vue pour retourner directement les attributs liés par des références, voir le paramètre select}}
  
 
===Gestion du périmètre société===
 
===Gestion du périmètre société===
Ligne 76 : Ligne 207 :
 
   METHOD https://host/sdata/society/package/class ...
 
   METHOD https://host/sdata/society/package/class ...
 
</pre>
 
</pre>
 +
 +
{{tip|Définir le contexte société dans l'url n'est utilisable que sur une base supportant le multi-société. Pour connaitre le statut multi-société, utilisez la requête $version ou bien interrogez [[Utilisation_du_contrôleur_de_partage_(API)|le contrôleur de partage]]}}
  
 
==Requête sur les ressources (GET)==
 
==Requête sur les ressources (GET)==
Ligne 105 : Ligne 238 :
 
|-
 
|-
 
|count
 
|count
−
|Taille de page
+
|Taille de page (*)
 
|Pagination : Taille de page
 
|Pagination : Taille de page
 
|-
 
|-
Ligne 119 : Ligne 252 :
 
|lt,le,gt,ge
 
|lt,le,gt,ge
 
|Pagination par clé : direction par rapport à startKey
 
|Pagination par clé : direction par rapport à startKey
 +
|-
 +
|dateFormat
 +
|noTime, locale, utc
 +
|Indique le format de date retourné pour les types de données date comptable
 
|}
 
|}
 +
 +
(*) Il existe une limite par défaut si la valeur de count n'est pas précisée.
  
 
Les valeurs passées en paramètre doivent être encodées en HTML  
 
Les valeurs passées en paramètre doivent être encodées en HTML  
Ligne 132 : Ligne 271 :
  
 
====Select====
 
====Select====
−
Select permet de définir les attributs a retourner, par défaut tous les attributs non vide sont retournés
+
Select permet de définir les attributs à retourner, par défaut tous les attributs non vide sont retournés
  
 
<pre>
 
<pre>
 
GET http://localhost:8080/sdata/gentiers/ttiers?select=code,caption
 
GET http://localhost:8080/sdata/gentiers/ttiers?select=code,caption
 
</pre>
 
</pre>
 +
 +
La présence du paramètre select conditionne la façon d'exécuter la requête.
 +
 +
Les formats possibles sont :
 +
 +
{|class="wikitable"
 +
|-
 +
!format
 +
!Usage
 +
!Génère l'utilisation d'une vue
 +
|-
 +
|x
 +
|Attribut x de la ressource
 +
|non
 +
|-
 +
|x.y
 +
|Attribut y de la ressource lié par de référence x (jointure exacte)
 +
|oui
 +
|-
 +
|x.+y
 +
|Attribut y de la ressource lié par de référence x (jointure externe)
 +
|oui
 +
|-
 +
|x as y
 +
|Attribut y de la ressource retourné sous l'alias x
 +
|oui
 +
|-
 +
|x as ope(y)
 +
|Opération sur l'attribut y de la ressource retourné sous l'alias x
 +
|oui
 +
|-
 +
|x as ope(y;z)
 +
|Opération sur les attributs y et z de la ressource retourné sous l'alias x
 +
|oui
 +
|}
 +
 +
Une vue sera utilisée si au moins un des membres de select nécessite l'utilisation d'une vue.
 +
 +
Pour les opérateurs utilisables consultez [[Vue_locale_(langage)|la page sur les vues locales]]
 +
 +
Notes :
 +
 +
* La sélection d'attribut référencé non défini peut générer l'absence de ressources dans le résultat, pour éviter ceci utilisez un spécificateur de jointure externe.
 +
* La sélection d'attribut référencé par un rôle liste peut générer plusieurs ressources dans le résultat correspondant à chaque ressource liée par la relation.
 +
* La séparation des paramètres pour les opérateurs ayant plusieurs paramètres utilise le séparateur ; et pas ,
 +
* Lorsqu'une vue est utilisée, les filtres et ordre de tri sont exprimés par rapport à la vue.
 +
 +
Par exemple :
 +
* TCompteGeneral?select=codeCompte&where=codeCompte ge '4'&orderBy=codeCompte
 +
mais
 +
* TCompteGeneral?select=code as codeCompte&where=code ge '4'&orderBy=code
 +
 +
====Dates comptables====
 +
Le paramètre dateFormat permet de définir le format des dates comptables retournées par l'API
 +
 +
{|class="wikitable"
 +
|-
 +
!Version API
 +
!dateFormat
 +
!Exemple
 +
!Format
 +
!Représente
 +
!Temps UTC
 +
|-
 +
|1.6
 +
|
 +
|2021-05-31T22:00:00Z
 +
|Format UTC
 +
|Un instant heure universelle
 +
|Le 31 Mai 2021 à 22 heure
 +
|-
 +
|1.7
 +
|
 +
|2021-06-01T00:00:00+02
 +
|Format UTC
 +
|Un instant heure universelle
 +
|Le 31 Mai 2021 à 22 heure
 +
|-
 +
|1.7
 +
|locale
 +
|2021-06-01T00:00:00
 +
|Format heure locale
 +
|Un instant heure locale
 +
|
 +
|-
 +
|1.7
 +
|noTime
 +
|2021-06-01
 +
|Format date locale
 +
|Une date locale
 +
|
 +
|-
 +
|1.7
 +
|UTC
 +
|2021-05-31T22:00:00Z
 +
|Format heure UTC
 +
|Un instant heure universelle
 +
|Le 31 Mai 2021 à 22 heure
 +
|}
 +
 +
{{warning|Pour les dates comptables, les formats UTC sont ambigus et peuvent générer des erreurs de conversion si les fuseaux horaire du serveur et du client sont différents}}
  
 
====Filtre====
 
====Filtre====
Ligne 154 : Ligne 394 :
 
|where=code%20eq%20%27ABI%20007%27
 
|where=code%20eq%20%27ABI%20007%27
 
|-
 
|-
−
|neq
+
|ne
 
|<>
 
|<>
 
|
 
|
Ligne 211 : Ligne 451 :
 
|value eq 1.0
 
|value eq 1.0
 
|-
 
|-
−
|date
+
|date (voir format)
−
|$updated > '2020-12-21T00:00:00'
+
|$updated > '2019-12-31T23:00:00Z'
 
|-
 
|-
−
|enum
+
|enum (par index)
−
|?
+
|value eq 1
 +
|-
 +
|enum (par constant)
 +
|value eq sens_credit
 +
|}
 +
 
 +
Format des paramètres date :
 +
 
 +
{|class="wikitable"
 +
|-
 +
!format
 +
!décodage
 +
!Exemple (1 jan. 2020 France)
 +
|-
 +
|AAAA-MM-DDTHH:MM:SS.MMMZ
 +
|ISO-8601 UTC
 +
|2019-12-31T23:00:00Z
 +
|-
 +
|AAAA-MM-DDTHH:MM:SS.MMM+OFFSET
 +
|ISO-8601 avec timezone
 +
|2019-12-31T23:00:00+1
 +
|-
 +
|AAAA-MM-DDTHH:MM:SS.MMM
 +
|ISO-8601 sans timezone
 +
|2020-01-01T00:00:00
 +
|-
 +
|AAA-MM-DD
 +
|Date au format ISO-8601
 +
|2020-01-01
 +
|-
 +
|DD/MM/AAAA
 +
|Date au format local
 +
|01/01/2020
 
|}
 
|}
  
Ligne 238 : Ligne 510 :
 
<pre>
 
<pre>
 
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=0
 
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=0
−
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=1
+
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=10
−
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=2
+
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=20
 
   ...
 
   ...
 
</pre>
 
</pre>
 +
 +
{{tip|Incrémentez startIndex du nombre de ressource retourné par la requête}}
  
 
====Pagination par clé====
 
====Pagination par clé====
Ligne 366 : Ligne 640 :
  
 
Lorsqu'une expression est utilisée la première ressource retournée par l'expression est utilisée.
 
Lorsqu'une expression est utilisée la première ressource retournée par l'expression est utilisée.
 +
 +
===Gestion des dates comptables===
 +
Pour les dates comptables, le serveur convertit la date reçu en heure locale puis conserve la partie date.
 +
 +
{|class="wikitable"
 +
|-
 +
!Format
 +
!Représente
 +
!Exemple
 +
!Interprète
 +
|-
 +
|locale
 +
|Une heure locale
 +
|2021-06-01T00:00:00
 +
|Conserve l’heure reçue en heure locale et conserve la date, la date sera toujours celle transmise.
 +
|-
 +
|noTime
 +
|Une date sans heure
 +
|2021-06-01
 +
|Conserve la date reçue sans conversion, la date sera toujours celle transmise.
 +
|-
 +
|UTC
 +
|Un instant universel UTC
 +
|2021-05-31T22:00:00Z
 +
2021-05-31T22:00:00+02
 +
|Convertit l’heure UTC en heure locale du service et conserve la date reçue, la date peut être différente de la date transmise si le client et le service ne sont pas dans le même fuseau horaire.
 +
|}
 +
 +
{{warning|Pour les dates comptables, les formats UTC sont ambigus et peuvent générer des erreurs de conversion si les fuseaux horaire du serveur et du client sont différents}}
  
 
==Modification de ressource (PUT)==
 
==Modification de ressource (PUT)==
Ligne 384 : Ligne 687 :
 
===Modification de rôle liste composition===
 
===Modification de rôle liste composition===
 
Par défaut les rôles composition sont gérés en remplacement, pour contrôler le mode de gestion des rôles utilisez un élément de contrôle "$" pour le rôle :
 
Par défaut les rôles composition sont gérés en remplacement, pour contrôler le mode de gestion des rôles utilisez un élément de contrôle "$" pour le rôle :
 +
 +
'''Exemple : Modification du rôle par remplacement des composants :'''
  
 
<pre>
 
<pre>
Ligne 420 : Ligne 725 :
 
}
 
}
 
</pre>
 
</pre>
 +
 +
'''Exemple : Modification du rôle par ajout de composant :'''
  
 
<pre>
 
<pre>
Ligne 460 : Ligne 767 :
 
}
 
}
 
</pre>
 
</pre>
 +
 +
'''Exemple : Modification du rôle par mise à jour de composant :'''
 +
 +
<pre>
 +
PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
 +
Request :
 +
{
 +
  "$":{
 +
    "sitesList:["update"]
 +
  },
 +
  "sitesList":[
 +
      {
 +
        "$key":"9D33A23CFA6A005500F6000001E30019",
 +
        "caption":"Site maj",
 +
      }
 +
  ]
 +
}
 +
</pre>
 +
  
 
{|class="wikitable"
 
{|class="wikitable"
Ligne 501 : Ligne 827 :
 
{{tip|Le périmètre courant de l'objet dépend de l'état de l'objet. Par exemple, si l'objet est de niveau activité et n'a pas de propriété défini pour la société courante, le périmètre courant sera l'activité, mais si l'objet a des propriétés définies pour la société courante alors le périmètre courant sera la société. Ne pas définir explicitement le niveau de partage peut amener à des ambiguïtés.}}
 
{{tip|Le périmètre courant de l'objet dépend de l'état de l'objet. Par exemple, si l'objet est de niveau activité et n'a pas de propriété défini pour la société courante, le périmètre courant sera l'activité, mais si l'objet a des propriétés définies pour la société courante alors le périmètre courant sera la société. Ne pas définir explicitement le niveau de partage peut amener à des ambiguïtés.}}
  
−
'''modification de la valeur de l'attribut privé pour les sociétés de l'activité du Tiers:'''
+
'''Modification de la valeur de l'attribut privé pour les sociétés de l'activité du Tiers (le tiers n'a pas de propriété défini pour la société S3):'''
 
<pre>
 
<pre>
 
PUT http://localhost:8080/sdata/S3/gentiers/ttiers(code eq 'ABI 00007')
 
PUT http://localhost:8080/sdata/S3/gentiers/ttiers(code eq 'ABI 00007')
Ligne 529 : Ligne 855 :
 
Les opérations des ressources correspondent aux méthodes publiques de cette ressource.
 
Les opérations des ressources correspondent aux méthodes publiques de cette ressource.
  
−
'''Méthode d'instance de ressource:'''
+
===Méthode d'instance de ressource===
  
 
<pre>
 
<pre>
Ligne 548 : Ligne 874 :
 
</pre>
 
</pre>
  
−
'''Méthode de classe de ressource, ou méthode de classe non persistante :'''
+
===Méthode de classe de ressource, ou méthode de classe non persistante===
  
 
<pre>
 
<pre>
Ligne 567 : Ligne 893 :
 
</pre>
 
</pre>
  
 +
===Passage des paramètres===
 
Les paramètres sont passés par nom et valeur.
 
Les paramètres sont passés par nom et valeur.
  
Ligne 593 : Ligne 920 :
 
|Enuméré (par valeur)
 
|Enuméré (par valeur)
 
|"p":1
 
|"p":1
 +
|-
 +
|Liste d'objets
 +
|"p":[ {$key:"key", $uuid:"uuid", $where:"expression"}, ...],
 
|}
 
|}
 +
 +
{{tip|Les références des objets passés dans des listes peuvent être définies par clé ($key), identifiant appelant ($uuid) ou expression ($where)
 +
Exemple :
 +
<pre>
 +
{
 +
"paramList":[
 +
    {"$key":"B5A28A92EB0C00020010000001F500A1"},
 +
    {"$where":"uneChaine like 'cN%'"}
 +
    ]
 +
}
 +
</pre>
 +
}}
 +
 +
===Résultat de type ressource===
 +
Lorsque l'opération retourne un objet ou une liste d'objets ceux-ci sont retournés sous forme de ressource.
 +
 +
Par exemple :
 +
 +
<source lang="delphi">
 +
//class Function GetWFClasseA(const iCode:string):WFClasseA;
 +
begin
 +
  Result := WFClasseA.Find('(unCode = %1)','unCode',True,[iCode]);
 +
end;
 +
</source>
 +
 +
<pre>
 +
POST http://localhost:8080/sdata/testsyfrewf/testapi/getwfclassea
 +
{
 +
    "result": {
 +
        "$baseUrl": "http://localhost:8080/sdata/testsyfrewf/",
 +
        "$title": "WFClasseA - -",
 +
        "$updated": "2021-01-29T12:41:41.015Z",
 +
        "$resources": [
 +
            {
 +
                "$key": "B5A28A92EB0C00020010000001B40002",
 +
                "$etag": "B5A28A92EB0C00020010000001B40002-0000028E00000001",
 +
                "stamp": "0000028E00000001",
 +
                "Caption": "Title 1",
 +
                "unBool": false,
 +
                "unCode": "A1",
 +
                "unCompteur": {
 +
                    "value": "aaaaaaaaaaky",
 +
                    "CounterName": "MonCompteur"
 +
                },
 +
                "unDouble": 0,
 +
                "uneChaine": "une chaine 1",
 +
                "unEntier": 10,
 +
                "unEtat": {
 +
                    "value": 1,
 +
                    "title": "Etat 1"
 +
                },
 +
                "unStatus": 0,
 +
                "WFClasseCList": [
 +
                    {
 +
                        "$key": "B5A28A92EB0C000200140000020E000A",
 +
                        "uneChaine": "Title 1-1",
 +
                        "unEntier": 0
 +
                    },
 +
                    {
 +
                        "$key": "B5A28A92EB0C000200140000020E000B",
 +
                        "uneChaine": "Title 1-0",
 +
                        "unEntier": 0
 +
                    },
 +
                    {
 +
                        "$key": "B5A28A92EB0C00020014000002100079",
 +
                        "uneChaine": "Title 1-0",
 +
                        "unEntier": 0
 +
                    },
 +
                    {
 +
                        "$key": "B5A28A92EB0C0002001400000210007A",
 +
                        "uneChaine": "Title 1-1",
 +
                        "unEntier": 0
 +
                    }
 +
                ]
 +
            }
 +
        ]
 +
    }
 +
}
 +
</pre>
 +
 +
<source lang="delphi">
 +
//Class Function GetWFClasseA(const iCodeLike:string):WFClasseAList;
 +
begin
 +
Result := WFClasseA.CreateListWhere('(unCode like %1)','','unCode',True,-1,[iCodeLike]);
 +
end;
 +
</source>
 +
 +
<pre>
 +
 +
POST http://localhost:8080/sdata/testsyfrewf/testapi/getwfclassealist
 +
{
 +
    "result": {
 +
        "$baseUrl": "http://localhost:8080/sdata/testsyfrewf/",
 +
        "$title": "WFClasseA - -",
 +
        "$updated": "2021-01-29T12:49:14.061Z",
 +
        "$resources": [
 +
            {
 +
                "$key": "B5A28A92EB0C00020010000001B40002",
 +
                "$etag": "B5A28A92EB0C00020010000001B40002-0000028E00000001",
 +
                "stamp": "0000028E00000001",
 +
                "Caption": "Title 1",
 +
                "unBool": false,
 +
                "unCode": "A1",
 +
                "unCompteur": {
 +
                    "value": "aaaaaaaaaaky",
 +
                    "CounterName": "MonCompteur"
 +
                },
 +
                "unDouble": 0,
 +
                "uneChaine": "une chaine 1",
 +
                "unEntier": 10,
 +
                "unEtat": {
 +
                    "value": 1,
 +
                    "title": "Etat 1"
 +
                },
 +
                "unStatus": 0,
 +
                "WFClasseCList": [
 +
                    {
 +
                        "$key": "B5A28A92EB0C000200140000020E000A",
 +
                        "uneChaine": "Title 1-1",
 +
                        "unEntier": 0
 +
                    },
 +
                    {
 +
                        "$key": "B5A28A92EB0C000200140000020E000B",
 +
                        "uneChaine": "Title 1-0",
 +
                        "unEntier": 0
 +
                    },
 +
                    {
 +
                        "$key": "B5A28A92EB0C00020014000002100079",
 +
                        "uneChaine": "Title 1-0",
 +
                        "unEntier": 0
 +
                    },
 +
                    {
 +
                        "$key": "B5A28A92EB0C0002001400000210007A",
 +
                        "uneChaine": "Title 1-1",
 +
                        "unEntier": 0
 +
                    }
 +
                ]
 +
            },
 +
            {
 +
                "$key": "B5A28A92EB0C00020010000001B4000E",
 +
                "$etag": "B5A28A92EB0C00020010000001B4000E-0000025000000025",
 +
                "stamp": "0000025000000025",
 +
                "Caption": "Title 1",
 +
                "unBool": false,
 +
                "unCode": "A1",
 +
                "unCompteur": {
 +
                    "value": "aaaaaaaaaalb",
 +
                    "CounterName": "MonCompteur"
 +
                },
 +
                "unDouble": 0,
 +
                "uneChaine": "U1",
 +
                "unEntier": 10,
 +
                "unEtat": {
 +
                    "value": 2,
 +
                    "title": "Etat 2"
 +
                },
 +
                "unStatus": 0
 +
            },
 +
            {
 +
                "$key": "B5A28A92EB0C00020010000001B4001A",
 +
                "$etag": "B5A28A92EB0C00020010000001B4001A-0000018B0000001A",
 +
                "stamp": "0000018B0000001A",
 +
                "Caption": "Title 1",
 +
                "unBool": false,
 +
                "unCode": "A1",
 +
                "unCompteur": {
 +
                    "value": "aaaaaaaaaale",
 +
                    "CounterName": "MonCompteur"
 +
                },
 +
                "unDouble": 0,
 +
                "uneChaine": "U1",
 +
                "unEntier": 10,
 +
                "unEtat": {
 +
                    "value": 0,
 +
                    "title": "Initial"
 +
                },
 +
                "unStatus": 0
 +
            },
 +
            ......
 +
        ]
 +
    }
 +
}
 +
</pre>
 +
 +
===Initialisation de la ressource===
 +
Il est possible d'initialiser la ressource avant d'exécuter la méthode, par exemple pour un processus :
 +
 +
<source lang="delphi">
 +
Type
 +
  TmyProcessus = class
 +
  public
 +
  procedure Execute(p:string);
 +
  property attString:string;
 +
  property attInt:Integer;
 +
  property attRef:TRefClass;
 +
  end;
 +
</source>
 +
 +
<pre>
 +
POST http://localhost:8080/sdata/testsyfrewf/myProcessus/execute
 +
Request:
 +
{
 +
"$resource":{
 +
"attString":"value 1",
 +
"attInt":100,
 +
"attRef":{"$url":"TRefClass('xxx')"},
 +
},
 +
"p":"value",
 +
}
 +
Response: 200 OK
 +
{
 +
    "result":""
 +
}
 +
</pre>
  
 
==Requête Batch (POST $batch)==
 
==Requête Batch (POST $batch)==
−
Une requête Batch permet de réaliser plusieurs opérations de type POST/PUT/DELETE en une seule fois.
+
Une requête Batch permet de réaliser plusieurs opérations de type GET,POST/PUT/DELETE/EXEC en une seule fois.
  
 
Une requête Batch contient un tableau de ressources, pour chaque ressource l'action et l'uri doivent être précisées :
 
Une requête Batch contient un tableau de ressources, pour chaque ressource l'action et l'uri doivent être précisées :
Ligne 629 : Ligne 1 173 :
 
</pre>
 
</pre>
  
 +
{{tip|Le format d'url complet de $Batch est https://hostname/service/server/sdata/l1000/-/-/$batch}}
 +
 +
===Gestion de la transaction dans un batch===
 
Par défaut les opérations réalisées sont unitaires (une transaction par ressource).
 
Par défaut les opérations réalisées sont unitaires (une transaction par ressource).
  
−
==Schéma d'une ressource (GET $schema)==
+
Pour réaliser une opération Batch atomique (une seule transaction longue) utilisez un élément de contrôle transaction :
  
 +
Lorsque l'opération est atomique la réponse contient un élément $batch indiquant le statut de l'opération.
 +
 +
Le code de retour http est le code de retour de la dernière opération réalisée.
 +
 +
<pre>
 +
POST http://localhost:8080/sdata/$batch
 +
{
 +
  "$": {"$transaction":["atomic"]},
 +
  "$resources":[
 +
      {
 +
        "$httpMethod":"PUT",
 +
        "$url":"gentiers/ttiers('9D33A23CFA6A005500F6000000285DAE')",
 +
        "$uuid":"1",
 +
        "capital":{"value":7200,"CodeDevise":"USD"}
 +
      },
 +
      {
 +
        "$httpMethod":"PUT",
 +
        "$url":"gentiers/ttiers('9D33A23CFA6A005500F600000023048C')",
 +
        "$uuid":"2",
 +
        "capital":{"value":1000,"CodeDevise":"EUR"}
 +
      }
 +
  ]
 +
}
 +
Response : 401
 +
{
 +
    "$baseUrl": "http://localhost:8080/sdata/l1000/-/-/",
 +
    "$title": "$batch - -",
 +
    "$resources": [
 +
        {
 +
            "$httpStatus": 200,
 +
            "$httpMethod": "PUT",
 +
            "$httpMessage": "OK",
 +
            "$etag": "9D33A23CFA6A005500F6000000285DAE-0000018C00000001"
 +
        },
 +
        {
 +
            "$httpStatus": 410,
 +
            "$httpMessage": "Already Deleted",
 +
            "$uuid": "2",
 +
            "$url": "gentiers/ttiers('9D33A23CFA6A005500F600000023048C')",
 +
            "$": {
 +
                "$diagnoses": [
 +
                    {
 +
                        "severity": "error",
 +
                        "message": "Already Deleted",
 +
                        "sdataCode": "ApplicationDiagnosis"
 +
                    }
 +
                ]
 +
            }
 +
        }
 +
    ],
 +
    "$batch": {
 +
        "$httpStatus": 400,
 +
        "$httpMessage": "ROLLBACK",
 +
        "$": {
 +
            "$diagnoses": [
 +
                {
 +
                    "severity": "error",
 +
                    "message": "Already Deleted",
 +
                    "sdataCode": "ApplicationDiagnosis",
 +
                    "entry": {
 +
                        "number": 2,
 +
                        "uuid": "2"
 +
                    }
 +
                }
 +
            ]
 +
        }
 +
    }
 +
}
 +
</pre>
 +
 +
'''$transaction :'''
 +
 +
{|class="wikitable"
 +
|-
 +
!Commande
 +
!Action
 +
|-
 +
|atomic
 +
|Démarre une transaction longue
 +
|-
 +
|flush
 +
|Force un batch de la transaction longue
 +
|-
 +
|commit
 +
|Valide la transaction longue
 +
|}
 +
{{Tip|L'élément de contrôle de transaction peut être placé au niveau d'un ordre du lot.}}
 +
 +
===Execution de méthode dans un batch===
 +
Utiliser le verbe EXEC pour exécuter une méthode
 +
 +
<pre>
 +
POST http://localhost:8080/sdata/$batch
 +
{
 +
  "$resources":[
 +
      {
 +
        "$httpMethod":"EXEC",
 +
        "$url":"testsyfrewf/wfprocessus/testmethod",
 +
        "$resource":{
 +
            "uneChaine":"value 1"
 +
        },
 +
        "p":"value 2"
 +
      }
 +
  ]
 +
}
 +
Response : 200 OK
 +
{
 +
    "$baseUrl": "http://localhost:8080/sdata/l1000/-/-/",
 +
    "$title": "$batch - -",
 +
    "$resources": [
 +
        {
 +
            "$httpStatus": 200,
 +
            "$httpMethod": "POST",
 +
            "$httpMessage": "Executed",
 +
            "$url": "testsyfrewf/wfprocessus/testmethod",
 +
            "$uuid": "",
 +
            "result": "value 1 value 2"
 +
        }
 +
    ]
 +
}
 +
</pre>
 +
 +
==Schéma d'une ressource (GET $schema)==
 
Le schéma d'une ressource retourne la structure de la classe.
 
Le schéma d'une ressource retourne la structure de la classe.
  
Ligne 640 : Ligne 1 310 :
 
{
 
{
 
     "title": "Libellé de la Classe A",
 
     "title": "Libellé de la Classe A",
 +
    "stereotype": "persistent",
 
     "properties": {
 
     "properties": {
 
         "unBool": {
 
         "unBool": {
Ligne 708 : Ligne 1 379 :
 
</pre>
 
</pre>
  
 +
Le contenu de la réponse peut être configurée avec le paramètre "select", à défaut toutes les informations sont retournées.
 +
 +
{|class="wikitable"
 +
|-
 +
!Paramètre
 +
!Usage
 +
|-
 +
|extensions
 +
|Retourne uniquement les attributs issus d'extension
 +
|-
 +
|properties
 +
|Retourne la liste de tous les attributs
 +
|-
 +
|selfProperties
 +
|Retourne uniquement les attributs de la classe elle même
 +
|-
 +
|operations
 +
|Retourne les opérations de la classe
 +
|-
 +
|compositions
 +
|Retourne le schéma des classes composants
 +
|}
 +
 +
Exemple : Retrouver uniquement les attributs d'extension d'une classe :
 +
 +
<pre>
 +
GET http://localhost:8080/sdata/ttiers/$schema?select=extensions
 +
{
 +
    "title": "Tiers",
 +
    "stereotype": "persistent",
 +
    "extensions": [
 +
        {
 +
            "class": "TTiers_esmPackage",
 +
            "title": "Extension de TTiers",
 +
            "package": "esmPackage"
 +
        }
 +
    ],
 +
    "properties": {
 +
        "esmCode": {
 +
            "type": "string",
 +
            "extension": "TTiers_esmPackage",
 +
            "title": "un code esm"
 +
        }
 +
    },
 +
    "$url": "http://localhost:8080/sdata/gentiers/TTiers/$schema"
 +
}
 +
</pre>
 +
 +
==Modèle de ressource (GET $template)==
 +
Le modèle de ressource retourne une ressource initialisée
 +
 +
<pre>
 +
GET http://localhost:8080/sdata/gcimport/TImportContratCommercial/$template
 +
Response : 200 OK
 +
 +
{
 +
    "$url": "http://localhost:8080/sdata/l1000/gcimport/-/TImportContratCommercial",
 +
    "stamp": "000001D900000001",
 +
    "acompte": 0,
 +
    "affaire": "",
 +
    "budget": "",
 +
    "Caption": "",
 +
    "commandeEngagement": false,
 +
    "commercial": "",
 +
    "coursDevise": {
 +
        "value": 1,
 +
        "CodeDevise": "",
 +
        "Date": "1899-12-30T00:00:00.000Z",
 +
        "TCConv": "",
 +
        "TCValue": 0,
 +
        "RPConv": "",
 +
        "RPValue": 0
 +
    },
 +
    "coursNegocie": false,
 +
    "dateCommande": "1899-12-30T00:00:00.000Z",
 +
    "dateLivraison": "1899-12-30T00:00:00.000Z",
 +
    "devise": "",
 +
    "donneeEDI1": "",
 +
    "donneeEDI2": "",
 +
    "donneeEDI3": "",
 +
    "donneeEDI4": "",
 +
    "donneeEDI5": "",
 +
    "echeancement": "",
 +
    "etablissement": "",
 +
    "exonereTaxe": "",
 +
    "exonereTVA": "",
 +
    "gestionTransport": {
 +
        "value": 0,
 +
        "title": "Automatique"
 +
    },
 +
    "immobilisation": {
 +
        "value": 0,
 +
        "title": "B&S"
 +
    },
 +
    "ImportCCDetailList": [],
 +
    "importeGMAO": false,
 +
    "importerRemisePied": false,
 +
    "ImportSiteAdresse": {},
 +
    "incoterm": "",
 +
    "MentionExonerationTVA": "",
 +
    "posteBudgetaire": "",
 +
    "pourcentAcompte": {
 +
        "value": 0,
 +
        "Decimales": 2
 +
    },
 +
    "pourcentRemisePied": {
 +
        "value": 0,
 +
        "Decimales": 2
 +
    },
 +
    "reference": "",
 +
    "referenceMandat": "",
 +
    "regimeTVA": "",
 +
    "roleTiers": "",
 +
    "roleTiersLivre": "",
 +
    "SessionImportation": {},
 +
    "typeFacturation": {
 +
        "value": 0,
 +
        "title": "HT"
 +
    }
 +
}
 +
</pre>
 +
 +
Voir aussi :
 +
 +
* [[SData|Point d'accès et url SData]]
 +
* [[Gestion des jetons d'authentification (Administration)|Gestion des jetons d'authentification]]
 +
 +
Voir aussi les exemples suivants :
 +
 +
* [[Utilisation du contrôleur de partage (API)|Utilisation du contrôleur de partage]]
 +
* [[Interrogation des écritures (API)|Interrogation des écritures avec l'API SData]]
 +
* [[Interrogation des fournisseurs (API)|Interrogation des fournisseurs avec l'API SData]]
 +
* [[Creation d'un fournisseur (API)|Création d'un fournisseur avec l'API SData]]
 +
* [[Import_de commandes_(API)|Import de commandes avec l'API SData]]
 +
* [[Import_d%27écritures_(API)|Import d'écritures avec l'API SData]]
 +
* [[Gestion des réceptions fournisseurs (API)|Gestion des réceptions fournisseurs avec l'API SData]]
 +
* [[Facturation d'un bon de livraison (API)|Facturation d'un bon de livraison avec l'API SData]]
 +
* [[Creation_d%27un_Tiers_et_son_compte_bancaire_(API)|Creation_d'un Tiers et son compte bancaire (API)]]
 
[[Category:SData]]
 
[[Category:SData]]

Version actuelle en date du 9 novembre 2021 à 10:14

Sommaire


Prérequis

Les requêtes SData sont exécutées sur le point d'accès SData du service.

La forme simplifiée des urls est 

http://hostname/sdata/ressource?paramètres

ou 

http://hostname/sdata/societe/ressource?paramètres

Les requêtes sont authentifiées par un jeton d'authentification placé dans l'entête Authorization de la requêtes.

Le jeton d'authentification peut être géré par le client dans l'administration.

Les requêtes doivent comporter les entêtes suivantes :

accept application/json
Authorization Bearer token

Les url des requêtes doivent être encodées, par exemple : 

https://.../sdata/Société 1/ttiers...

doit être transmis encodé en 

https://.../sdata.Soci%C3%A9t%C3%A9%201/ttiers....

Sélection de version

Il es possible d'indiquer un numéro de version dans l'url de la requête.

Placez le numéro de version derrière le préfix sdata : 

 https://.../sdata/1/....

En absence de numéro de version la dernière version sera utilisée.

Informations de version

Utilisez la fonction $version pour retrouver les informations de version 

GET http://localhost:8080/sdata/$version
{
    "product": "Sage FRP 1000",
    "version": "9.1.0.0",
    "master": "1.22",
    "apiMajor": 1,
    "apiMinor": 0,
    "debug": true,
    "shareEnable": true
}

GET https://localhost/sdata/$version?select=details
{
    "product": "Sage FRP 1000",
    "version": "9.1.0.0",
    "master": "1.22",
    "apiMajor": 1,
    "apiMinor": 1,
    "debug": true,
    "minors": [
        {
            "minor": 1,
            "details": [
                "Fix $batch : Error in commit don't return message and continue execution",
                "Fix time measure decimal format use . instead of local",
                "Add extension information to $schema",
                "Add operations to $schema",
                "Add select options to $schema"
            ]
        },
        {
            "minor": 0,
            "details": [
                "Add version information"
            ]
        }
    ]
}

Le paramètre select accepte les options suivantes :

option usage
details Détails des modifications des versions mineurs
patches Liste des patches installés

Ressource (GET)

Dans l'interface SData les ressources sont les objets de l'application.

Une ressource est identifié par son uri qui représente le chemin de la ressource.

L'uri est composé du chemin de la classe et d'un sélecteur qui est l'oid de l'objet.

Exemple : 

GET http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000000285DAE')
Response: 200 OK
{
   "$baseUrl":"http://localhost:8080/sdata/l1000/gentiers/-/",
   "$title":"TTiers - -",
   "$updated":"2020-12-22T08:10:09.740Z",
   "$resources":[
      {
         "$url":"TTiers('9D33A23CFA6A005500F6000000285DAE')",
         "$title":"ABI Jardin",
         "$updated":"2010-03-23T15:37:46.000Z",
         "$etag":"9D33A23CFA6A005500F6000000285DAE-000002C60000421C",
         "$key":"9D33A23CFA6A005500F6000000285DAE",
         "$baseUrl":"http://localhost:8080/sdata/l1000/GenTiers/-/",
         "stamp":"000002C60000421C",
         .... Attribute list ...
      }
   ]
}

Sélecteur de ressource

Un sélecteur permet de retrouver une ressource spécifique, il est possible de rechercher une ressource par clé ou clause

Sélecteur Exemple
Clé TTiers('9D33A23CFA6A005500F6000000285DAE')
clause TTiers(code eq 'ABI 007')

Code de retour HTTP

Code Résultat
200 La ressource existe
404 La ressource n'existe pas

Gestion des rôles dans les ressources

La gestion des rôles de la ressource dépend du type et de la nature du rôle :

Type de rôle Nature Retour
Référence,Liste Composition Les ressources composants sont retournées dans le corps de la ressource composée
Référence - La ressource référencée est retournée par référence dans le corps de la ressource
Liste - Les ressources ne sont pas retournées. Pour obtenir ces ressources, il faut faire une requête sur la classe référencée filtrée sur la référence réciproque.
Association Avec suppression en cascade Les ressources associées sont considérées comme des composants et retournées dans le corps de la ressource composée.
Association - Les ressources ne sont pas retournées. Pour obtenir ces ressources, il faut faire une requête sur la classe associée filtrée sur la classe d'association
Tip-20px.png Tip : Utilisez une vue pour retourner directement les attributs liés par des références, voir le paramètre select

Gestion du périmètre société

Par défaut, les requêtes s'exécutent dans le contexte société défini dans le jeton d'authentification.

Vous pouvez définir le contexte société dans le l'url de la requête : 

  METHOD https://host/sdata/society/package/class ...
Tip-20px.png Tip : Définir le contexte société dans l'url n'est utilisable que sur une base supportant le multi-société. Pour connaitre le statut multi-société, utilisez la requête $version ou bien interrogez le contrôleur de partage

Requête sur les ressources (GET)

Une requête sur les ressources est une requête sur une classe du modèle. 

GET http://localhost:8080/sdata/gentiers/ttiers?parameters

Paramètres de la requête

Paramètre valeur Usage
select liste d'attributs séparés par des virgules Liste des attributs à retourner
where Expression objet Filtre de la requête
orderBy Attribut de tri Ordre de tri de la requête
count Taille de page (*) Pagination : Taille de page
startIndex Index de page Pagination par page : Numéro de page (0 première)
startKey Valeur de clé ou de tri Pagination par clé : Clé de position
keyDirection lt,le,gt,ge Pagination par clé : direction par rapport à startKey
dateFormat noTime, locale, utc Indique le format de date retourné pour les types de données date comptable

(*) Il existe une limite par défaut si la valeur de count n'est pas précisée.

Les valeurs passées en paramètre doivent être encodées en HTML

Exemple : 

where=code eq 'ABI 007'

doit être encodée en : 

where=code%20eq%20%27ABI%20007%27

Select

Select permet de définir les attributs à retourner, par défaut tous les attributs non vide sont retournés 

GET http://localhost:8080/sdata/gentiers/ttiers?select=code,caption

La présence du paramètre select conditionne la façon d'exécuter la requête.

Les formats possibles sont :

format Usage Génère l'utilisation d'une vue
x Attribut x de la ressource non
x.y Attribut y de la ressource lié par de référence x (jointure exacte) oui
x.+y Attribut y de la ressource lié par de référence x (jointure externe) oui
x as y Attribut y de la ressource retourné sous l'alias x oui
x as ope(y) Opération sur l'attribut y de la ressource retourné sous l'alias x oui
x as ope(y;z) Opération sur les attributs y et z de la ressource retourné sous l'alias x oui

Une vue sera utilisée si au moins un des membres de select nécessite l'utilisation d'une vue.

Pour les opérateurs utilisables consultez la page sur les vues locales

Notes :

  • La sélection d'attribut référencé non défini peut générer l'absence de ressources dans le résultat, pour éviter ceci utilisez un spécificateur de jointure externe.
  • La sélection d'attribut référencé par un rôle liste peut générer plusieurs ressources dans le résultat correspondant à chaque ressource liée par la relation.
  • La séparation des paramètres pour les opérateurs ayant plusieurs paramètres utilise le séparateur ; et pas ,
  • Lorsqu'une vue est utilisée, les filtres et ordre de tri sont exprimés par rapport à la vue.

Par exemple :

  • TCompteGeneral?select=codeCompte&where=codeCompte ge '4'&orderBy=codeCompte

mais

  • TCompteGeneral?select=code as codeCompte&where=code ge '4'&orderBy=code

Dates comptables

Le paramètre dateFormat permet de définir le format des dates comptables retournées par l'API

Version API dateFormat Exemple Format Représente Temps UTC
1.6 2021-05-31T22:00:00Z Format UTC Un instant heure universelle Le 31 Mai 2021 à 22 heure
1.7 2021-06-01T00:00:00+02 Format UTC Un instant heure universelle Le 31 Mai 2021 à 22 heure
1.7 locale 2021-06-01T00:00:00 Format heure locale Un instant heure locale
1.7 noTime 2021-06-01 Format date locale Une date locale
1.7 UTC 2021-05-31T22:00:00Z Format heure UTC Un instant heure universelle Le 31 Mai 2021 à 22 heure
Exclam-20px.png Attention : Pour les dates comptables, les formats UTC sont ambigus et peuvent générer des erreurs de conversion si les fuseaux horaire du serveur et du client sont différents

Filtre

Opérateurs:

opérateur équivalence exemple encoded
eq = where=code eq 'ABI 007' where=code%20eq%20%27ABI%20007%27
ne <>
lt <
le <=
gt >
ge >=
like like where=code like 'ABI %' where=code%20like%20%27ABI %25%27
in in

Valeurs des paramètres:

Les valeurs des paramètres sont passées en littérale

Type de donnée exemple
Chaîne code eq 'xxx'
boolean flag eq true
numérique value eq 1
flottant value eq 1.0
date (voir format) $updated > '2019-12-31T23:00:00Z'
enum (par index) value eq 1
enum (par constant) value eq sens_credit

Format des paramètres date :

format décodage Exemple (1 jan. 2020 France)
AAAA-MM-DDTHH:MM:SS.MMMZ ISO-8601 UTC 2019-12-31T23:00:00Z
AAAA-MM-DDTHH:MM:SS.MMM+OFFSET ISO-8601 avec timezone 2019-12-31T23:00:00+1
AAAA-MM-DDTHH:MM:SS.MMM ISO-8601 sans timezone 2020-01-01T00:00:00
AAA-MM-DD Date au format ISO-8601 2020-01-01
DD/MM/AAAA Date au format local 01/01/2020

Ordre de tri

Tri ascendant : 

orderby=code

Tri descendant : 

orderby=code%20desc

GET http://localhost:8080/sdata/gentiers/ttiers?orderBy=code%20desc

Pagination par page

Utiliser orderBy, count et startIndex 

GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=0
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=10
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=20
  ...
Tip-20px.png Tip : Incrémentez startIndex du nombre de ressource retourné par la requête

Pagination par clé

Utiliser orderBy, startKey et keyDirection 

GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startKey=1B28EFFFF1C3000200F6000000230893&keyDirection=lt

Création de ressource (POST)

POST http://localhost:8080/sdata/gentiers/ttiers
Request:
{
   "code":"SYFRE1",
   "caption":"syfre 1",
   "sitesList":[
      {
         "code":"SITE1",
         "caption":"site1 de syfre1",
         "adresse":{
            "nomRueVoie":"rue de la pompe",
            "ville":"Clichy",
            "codePostal":"92100",
            "pays":{
               "$key":"9D33A23CFA6A005500150000001700FD"
            }
         }
      }
   ]
}
Response: 200 OK
{
    "$resources": [
        {
            "$key": "9D33A23CFA6A005500F6000001E20022",
            "$url": "http://localhost:8080/sdata/l1000/gentiers/-/TTiers('9D33A23CFA6A005500F6000001E20022')",
            ... attribute list ...
        } 
     ]
}

Gestion du périmètre de partage

Le niveau de partage d'une ressource de niveau activité peut être contrôlé par des propriétés de contrôle au niveau de la définition de la ressource :

Contrôle Usage
$shareId Valeur du périmètre sur lequel créer l'objet
$shareLevel Niveau de partage sur lequel créer l'objet (0:dossier,1:activité ou 2:société) 
POST https://localhost/sdata/S3/gentiers/ttiers
Request:
{
   "$shareLevel":2,
   "code":"SYFRES3-2",
   "caption":"syfre S3-2",
   "sitesList":[
      {
         "code":"SITE1",
         "caption":"site 1",
         "adresse":{
            "nomRueVoie":"rue de la pompe",
            "ville":"Clichy",
            "codePostal":"92100",
            "pays":{
               "$key":"9D33A23CFA6A005500150000001700FD"
            }
         }
      }
   ]
}
Response : 201 OK
Tip-20px.png Tip : Par défaut la ressource sera créée au niveau activité

Gestion des rôles

La création de ressource dans les rôles dépend de la nature du rôle.

  • Pour les rôles de type composition les ressources liées sont créés simultanément.
  • Pour les rôles qui ne sont pas des compositions les ressources liées sont rattachés.

Identification des références

Par clé: 

{
  "pays":{
    "$key":"9D33A23CFA6A005500150000001700FD"
  }
}

Par uri: 

{
  "pays":{
    "$url":TPays("9D33A23CFA6A005500150000001700FD")
  }
}

Par expression: 

{
  "pays":{
    "$where":"codeISO = 'FRA'",
    "$orderby":"codeISO"
  }
}

Lorsqu'une expression est utilisée la première ressource retournée par l'expression est utilisée.

Gestion des dates comptables

Pour les dates comptables, le serveur convertit la date reçu en heure locale puis conserve la partie date.

Format Représente Exemple Interprète
locale Une heure locale 2021-06-01T00:00:00 Conserve l’heure reçue en heure locale et conserve la date, la date sera toujours celle transmise.
noTime Une date sans heure 2021-06-01 Conserve la date reçue sans conversion, la date sera toujours celle transmise.
UTC Un instant universel UTC 2021-05-31T22:00:00Z

2021-05-31T22:00:00+02

Convertit l’heure UTC en heure locale du service et conserve la date reçue, la date peut être différente de la date transmise si le client et le service ne sont pas dans le même fuseau horaire.
Exclam-20px.png Attention : Pour les dates comptables, les formats UTC sont ambigus et peuvent générer des erreurs de conversion si les fuseaux horaire du serveur et du client sont différents

Modification de ressource (PUT)

PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Request:
{
"codeSIRET":"12345678"
}
Response: 200 OK
[
{ 
.... resource modified ...
}
]

Modification de rôle liste composition

Par défaut les rôles composition sont gérés en remplacement, pour contrôler le mode de gestion des rôles utilisez un élément de contrôle "$" pour le rôle :

Exemple : Modification du rôle par remplacement des composants : 

PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Request :
{
   "sitesList":[
      {
         "code":"SITE3",
         "caption":"site3 de syfre1",
         "adresse":{
            "nomRueVoie":"rue Mogador",
            "ville":"Paris",
            "codePostal":"75008",
            "pays":{
               "$where":"codeISO = 'FRA'",
               "$orderby":"codeISO"
            }
         }
      }
   ]
}
Response: 200 OK
{
    "$resources": [
        {
            "$key": "9D33A23CFA6A005500F6000001E30019",
            "$url": "/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E30019')",
            "stamp": "000001710000002A",
            ....
            "sitesList": [
            ... Site3 has been added, other sites has been removed.
            ... There is one site left in the list
           ]
    ]
}

Exemple : Modification du rôle par ajout de composant : 

PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Request :
{
   "$":{
     "sitesList:["create"]
   },
   "sitesList":[
      {
         "code":"SITE3",
         "caption":"site3 de syfre1",
         "adresse":{
            "nomRueVoie":"rue Mogador",
            "ville":"Paris",
            "codePostal":"75008",
            "pays":{
               "$where":"codeISO = 'FRA'",
               "$orderby":"codeISO"
            }
         }
      }
   ]
}
Response: 200 OK
{
    "$resources": [
        {
            "$key": "9D33A23CFA6A005500F6000001E30019",
            "$url": "/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E30019')",
            "stamp": "000001710000002A",
            ....
            "sitesList": [
                ... Site3 has been added, other sites are not affected
                ... There is one site more in the list
            }
           ]
    ]
}

Exemple : Modification du rôle par mise à jour de composant : 

PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Request :
{
   "$":{
     "sitesList:["update"]
   },
   "sitesList":[
      {
         "$key":"9D33A23CFA6A005500F6000001E30019", 
         "caption":"Site maj",
      }
   ]
}


contrôle action
create Les nouvelles ressources sont ajoutées au rôle
update Les ressources existantes dans le rôle sont mise à jour
delete Les ressources existantes et non présentes dans la requête sont supprimées

La valeur par défaut est "create","update","delete"

Modification des attributs privés

Par défaut les attributs privés sont modifiés sur le niveau de partage correspondant au périmètre société, pour contrôler le niveau de partage des attributs privés utilisez un élément de contrôle $sharePrivateLevel.

sharePrivateLevel Périmètre de définition
absent Périmètre courant de l'objet
0 Dossier
1 Activité
2 Société
Tip-20px.png Tip : Le périmètre courant de l'objet dépend de l'état de l'objet. Par exemple, si l'objet est de niveau activité et n'a pas de propriété défini pour la société courante, le périmètre courant sera l'activité, mais si l'objet a des propriétés définies pour la société courante alors le périmètre courant sera la société. Ne pas définir explicitement le niveau de partage peut amener à des ambiguïtés.

Modification de la valeur de l'attribut privé pour les sociétés de l'activité du Tiers (le tiers n'a pas de propriété défini pour la société S3): 

PUT http://localhost:8080/sdata/S3/gentiers/ttiers(code eq 'ABI 00007')
{
"modeReglementDecaissement":{"$where":"code eq 'CHQ'"},
}


Modification de la valeur de l'attribut privé pour la société S3 : 

PUT http://localhost:8080/sdata/S3/gentiers/ttiers(code eq 'ABI 00007')
{
"$sharePrivateLevel":2,
"modeReglementDecaissement":{"$where":"code eq 'CBB'"},
}

Suppression de ressource (DELETE)

DELETE http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Response: 200 OK

Opération sur une ressource (POST)

Les opérations des ressources correspondent aux méthodes publiques de cette ressource.

Méthode d'instance de ressource

POST http://localhost:8080/sdata/testsyfrewf/wfclassea('B5A28A92EB0C00020010000000DB0006')/testmethode
Request:
{
"pString":"value1",
"pInteger":1,
"pFloat":1.2,
"pEnum":1,
"pBoolean":false
}

Response: 200 OK
{
    "result": "pString:value1 pInteger:1 pBoolean:false pFloat:1,2 pEnum:1"
}

Méthode de classe de ressource, ou méthode de classe non persistante

POST http://localhost:8080/sdata/testsyfrewf/myProcessus/testmethode
Request:
{
"pString":"value1",
"pInteger":1,
"pFloat":1.2,
"pEnum":1,
"pBoolean":false
}

Response: 200 OK
{
    "result": "pString:value1 pInteger:1 pBoolean:false pFloat:1,2 pEnum:1"
}

Passage des paramètres

Les paramètres sont passés par nom et valeur.

Les types de paramètres et de retour supportés sont :

Type Exemple
Chaîne "p":"xxx"
Entier "p":1
Boolean "p":true
Flottant "p":1.1
Datetime "p":"2020-12-25T01:01:01"
Enuméré (par valeur) "p":1
Liste d'objets "p":[ {$key:"key", $uuid:"uuid", $where:"expression"}, ...],
Tip-20px.png Tip : Les références des objets passés dans des listes peuvent être définies par clé ($key), identifiant appelant ($uuid) ou expression ($where)

Exemple : 

{
"paramList":[
    {"$key":"B5A28A92EB0C00020010000001F500A1"},
    {"$where":"uneChaine like 'cN%'"}
    ]
}

Résultat de type ressource

Lorsque l'opération retourne un objet ou une liste d'objets ceux-ci sont retournés sous forme de ressource.

Par exemple : 

//class Function GetWFClasseA(const iCode:string):WFClasseA;
begin
  Result := WFClasseA.Find('(unCode = %1)','unCode',True,[iCode]);
end;
POST http://localhost:8080/sdata/testsyfrewf/testapi/getwfclassea
{
    "result": {
        "$baseUrl": "http://localhost:8080/sdata/testsyfrewf/",
        "$title": "WFClasseA - -",
        "$updated": "2021-01-29T12:41:41.015Z",
        "$resources": [
            {
                "$key": "B5A28A92EB0C00020010000001B40002",
                "$etag": "B5A28A92EB0C00020010000001B40002-0000028E00000001",
                "stamp": "0000028E00000001",
                "Caption": "Title 1",
                "unBool": false,
                "unCode": "A1",
                "unCompteur": {
                    "value": "aaaaaaaaaaky",
                    "CounterName": "MonCompteur"
                },
                "unDouble": 0,
                "uneChaine": "une chaine 1",
                "unEntier": 10,
                "unEtat": {
                    "value": 1,
                    "title": "Etat 1"
                },
                "unStatus": 0,
                "WFClasseCList": [
                    {
                        "$key": "B5A28A92EB0C000200140000020E000A",
                        "uneChaine": "Title 1-1",
                        "unEntier": 0
                    },
                    {
                        "$key": "B5A28A92EB0C000200140000020E000B",
                        "uneChaine": "Title 1-0",
                        "unEntier": 0
                    },
                    {
                        "$key": "B5A28A92EB0C00020014000002100079",
                        "uneChaine": "Title 1-0",
                        "unEntier": 0
                    },
                    {
                        "$key": "B5A28A92EB0C0002001400000210007A",
                        "uneChaine": "Title 1-1",
                        "unEntier": 0
                    }
                ]
            }
        ]
    }
}

//Class Function GetWFClasseA(const iCodeLike:string):WFClasseAList;
begin
 Result := WFClasseA.CreateListWhere('(unCode like %1)','','unCode',True,-1,[iCodeLike]);
end;

POST http://localhost:8080/sdata/testsyfrewf/testapi/getwfclassealist
{
    "result": {
        "$baseUrl": "http://localhost:8080/sdata/testsyfrewf/",
        "$title": "WFClasseA - -",
        "$updated": "2021-01-29T12:49:14.061Z",
        "$resources": [
            {
                "$key": "B5A28A92EB0C00020010000001B40002",
                "$etag": "B5A28A92EB0C00020010000001B40002-0000028E00000001",
                "stamp": "0000028E00000001",
                "Caption": "Title 1",
                "unBool": false,
                "unCode": "A1",
                "unCompteur": {
                    "value": "aaaaaaaaaaky",
                    "CounterName": "MonCompteur"
                },
                "unDouble": 0,
                "uneChaine": "une chaine 1",
                "unEntier": 10,
                "unEtat": {
                    "value": 1,
                    "title": "Etat 1"
                },
                "unStatus": 0,
                "WFClasseCList": [
                    {
                        "$key": "B5A28A92EB0C000200140000020E000A",
                        "uneChaine": "Title 1-1",
                        "unEntier": 0
                    },
                    {
                        "$key": "B5A28A92EB0C000200140000020E000B",
                        "uneChaine": "Title 1-0",
                        "unEntier": 0
                    },
                    {
                        "$key": "B5A28A92EB0C00020014000002100079",
                        "uneChaine": "Title 1-0",
                        "unEntier": 0
                    },
                    {
                        "$key": "B5A28A92EB0C0002001400000210007A",
                        "uneChaine": "Title 1-1",
                        "unEntier": 0
                    }
                ]
            },
            {
                "$key": "B5A28A92EB0C00020010000001B4000E",
                "$etag": "B5A28A92EB0C00020010000001B4000E-0000025000000025",
                "stamp": "0000025000000025",
                "Caption": "Title 1",
                "unBool": false,
                "unCode": "A1",
                "unCompteur": {
                    "value": "aaaaaaaaaalb",
                    "CounterName": "MonCompteur"
                },
                "unDouble": 0,
                "uneChaine": "U1",
                "unEntier": 10,
                "unEtat": {
                    "value": 2,
                    "title": "Etat 2"
                },
                "unStatus": 0
            },
            {
                "$key": "B5A28A92EB0C00020010000001B4001A",
                "$etag": "B5A28A92EB0C00020010000001B4001A-0000018B0000001A",
                "stamp": "0000018B0000001A",
                "Caption": "Title 1",
                "unBool": false,
                "unCode": "A1",
                "unCompteur": {
                    "value": "aaaaaaaaaale",
                    "CounterName": "MonCompteur"
                },
                "unDouble": 0,
                "uneChaine": "U1",
                "unEntier": 10,
                "unEtat": {
                    "value": 0,
                    "title": "Initial"
                },
                "unStatus": 0
            },
            ......
        ]
    }
}

Initialisation de la ressource

Il est possible d'initialiser la ressource avant d'exécuter la méthode, par exemple pour un processus : 

Type
  TmyProcessus = class
  public
   procedure Execute(p:string);
   property attString:string;
   property attInt:Integer;
   property attRef:TRefClass;
  end;
POST http://localhost:8080/sdata/testsyfrewf/myProcessus/execute
Request:
{
"$resource":{
 "attString":"value 1",
 "attInt":100,
 "attRef":{"$url":"TRefClass('xxx')"},
},
"p":"value",
}
Response: 200 OK
{
    "result":""
}

Requête Batch (POST $batch)

Une requête Batch permet de réaliser plusieurs opérations de type GET,POST/PUT/DELETE/EXEC en une seule fois.

Une requête Batch contient un tableau de ressources, pour chaque ressource l'action et l'uri doivent être précisées : 

POST http://.../sdata/$batch
{
   "$resources":[
      {
         "$httpMethod":"POST",
         "$url":"gentiers/ttiers",
         "code":"SYFRE2",
         "caption":"syfre 2",
         "sitesList":[
            {
               "code":"SITE1",
               "caption":"site2 de syfre2",
               "adresse":{
                  "nomRueVoie":"rue de la pompe",
                  "ville":"Clichy",
                  "codePostal":"92100",
                  "pays":{
                     "$where":"codeISO = 'FRA'",
                     "$orderby":"codeISO"
                  }
               }
            }
         ]
      }
   ]
}
Tip-20px.png Tip : Le format d'url complet de $Batch est https://hostname/service/server/sdata/l1000/-/-/$batch

Gestion de la transaction dans un batch

Par défaut les opérations réalisées sont unitaires (une transaction par ressource).

Pour réaliser une opération Batch atomique (une seule transaction longue) utilisez un élément de contrôle transaction :

Lorsque l'opération est atomique la réponse contient un élément $batch indiquant le statut de l'opération.

Le code de retour http est le code de retour de la dernière opération réalisée. 

POST http://localhost:8080/sdata/$batch
{
   "$": {"$transaction":["atomic"]},
   "$resources":[
      {
         "$httpMethod":"PUT",
         "$url":"gentiers/ttiers('9D33A23CFA6A005500F6000000285DAE')",
         "$uuid":"1",
         "capital":{"value":7200,"CodeDevise":"USD"}
      },
      {
         "$httpMethod":"PUT",
         "$url":"gentiers/ttiers('9D33A23CFA6A005500F600000023048C')",
         "$uuid":"2",
         "capital":{"value":1000,"CodeDevise":"EUR"}
      }
   ]
}
Response : 401
{
    "$baseUrl": "http://localhost:8080/sdata/l1000/-/-/",
    "$title": "$batch - -",
    "$resources": [
        {
            "$httpStatus": 200,
            "$httpMethod": "PUT",
            "$httpMessage": "OK",
            "$etag": "9D33A23CFA6A005500F6000000285DAE-0000018C00000001"
        },
        {
            "$httpStatus": 410,
            "$httpMessage": "Already Deleted",
            "$uuid": "2",
            "$url": "gentiers/ttiers('9D33A23CFA6A005500F600000023048C')",
            "$": {
                "$diagnoses": [
                    {
                        "severity": "error",
                        "message": "Already Deleted",
                        "sdataCode": "ApplicationDiagnosis"
                    }
                ]
            }
        }
    ],
    "$batch": {
        "$httpStatus": 400,
        "$httpMessage": "ROLLBACK",
        "$": {
            "$diagnoses": [
                {
                    "severity": "error",
                    "message": "Already Deleted",
                    "sdataCode": "ApplicationDiagnosis",
                    "entry": {
                        "number": 2,
                        "uuid": "2"
                    }
                }
            ]
        }
    }
}

$transaction :

Commande Action
atomic Démarre une transaction longue
flush Force un batch de la transaction longue
commit Valide la transaction longue
Tip-20px.png Tip : L'élément de contrôle de transaction peut être placé au niveau d'un ordre du lot.

Execution de méthode dans un batch

Utiliser le verbe EXEC pour exécuter une méthode 

POST http://localhost:8080/sdata/$batch
{
   "$resources":[
      {
         "$httpMethod":"EXEC",
         "$url":"testsyfrewf/wfprocessus/testmethod",
         "$resource":{
            "uneChaine":"value 1"
         },
         "p":"value 2"
      }
   ]
}
Response : 200 OK
{
    "$baseUrl": "http://localhost:8080/sdata/l1000/-/-/",
    "$title": "$batch - -",
    "$resources": [
        {
            "$httpStatus": 200,
            "$httpMethod": "POST",
            "$httpMessage": "Executed",
            "$url": "testsyfrewf/wfprocessus/testmethod",
            "$uuid": "",
            "result": "value 1 value 2"
        }
    ]
}

Schéma d'une ressource (GET $schema)

Le schéma d'une ressource retourne la structure de la classe. 

GET http://localhost:8080/sdata/testsyfrewf/wfclassea/$schema
Response : 200 OK
{
    "title": "Libellé de la Classe A",
    "stereotype": "persistent",
    "properties": {
        "unBool": {
            "type": "boolean",
            "title": "Un Bool"
        },
        "unCode": {
            "type": "string",
            "title": "Un code"
        },
        "unCompteur": {
            "type": "string"
        },
        "unDerive": {
            "type": "string",
            "title": "Un dérivé"
        },
        "unDouble": {
            "type": "double",
            "title": "Un double"
        },
        "uneChaine": {
            "type": "string",
            "title": "une chaine"
        },
        "unEmail": {
            "type": "string",
            "title": "Un email"
        },
        "unEntier": {
            "type": "int",
            "title": "Un Entier"
        },
        "unEtat": {
            "type": "integer",
            "title": "Un Etat"
        },
        "unStatus": {
            "type": "int",
            "title": "Statut de l'objet (Panel)"
        },
        "WFClasseBRef": {
            "type": {
                "$ref": "http://localhost:8080/sdata/l1000/testsyfrewf/-/WFClasseB/$schema",
                "$relationship": "reference"
            },
            "title": "Référence B"
        },
        "WFClasseCList": {
            "type": "array",
            "item": {
                "title": "Classe C",
                "properties": {
                    "uneChaine": {
                        "type": "string",
                        "title": "une chaine"
                    },
                    "unEntier": {
                        "type": "int",
                        "title": "un entier"
                    }
                }
            }
        }
    },
    "$url": "http://localhost:8080/sdata/l1000/testsyfrewf/-/WFClasseA/$schema"
}

Le contenu de la réponse peut être configurée avec le paramètre "select", à défaut toutes les informations sont retournées.

Paramètre Usage
extensions Retourne uniquement les attributs issus d'extension
properties Retourne la liste de tous les attributs
selfProperties Retourne uniquement les attributs de la classe elle même
operations Retourne les opérations de la classe
compositions Retourne le schéma des classes composants

Exemple : Retrouver uniquement les attributs d'extension d'une classe : 

GET http://localhost:8080/sdata/ttiers/$schema?select=extensions
{
    "title": "Tiers",
    "stereotype": "persistent",
    "extensions": [
        {
            "class": "TTiers_esmPackage",
            "title": "Extension de TTiers",
            "package": "esmPackage"
        }
    ],
    "properties": {
        "esmCode": {
            "type": "string",
            "extension": "TTiers_esmPackage",
            "title": "un code esm"
        }
    },
    "$url": "http://localhost:8080/sdata/gentiers/TTiers/$schema"
}

Modèle de ressource (GET $template)

Le modèle de ressource retourne une ressource initialisée 

GET http://localhost:8080/sdata/gcimport/TImportContratCommercial/$template
Response : 200 OK

{
    "$url": "http://localhost:8080/sdata/l1000/gcimport/-/TImportContratCommercial",
    "stamp": "000001D900000001",
    "acompte": 0,
    "affaire": "",
    "budget": "",
    "Caption": "",
    "commandeEngagement": false,
    "commercial": "",
    "coursDevise": {
        "value": 1,
        "CodeDevise": "",
        "Date": "1899-12-30T00:00:00.000Z",
        "TCConv": "",
        "TCValue": 0,
        "RPConv": "",
        "RPValue": 0
    },
    "coursNegocie": false,
    "dateCommande": "1899-12-30T00:00:00.000Z",
    "dateLivraison": "1899-12-30T00:00:00.000Z",
    "devise": "",
    "donneeEDI1": "",
    "donneeEDI2": "",
    "donneeEDI3": "",
    "donneeEDI4": "",
    "donneeEDI5": "",
    "echeancement": "",
    "etablissement": "",
    "exonereTaxe": "",
    "exonereTVA": "",
    "gestionTransport": {
        "value": 0,
        "title": "Automatique"
    },
    "immobilisation": {
        "value": 0,
        "title": "B&S"
    },
    "ImportCCDetailList": [],
    "importeGMAO": false,
    "importerRemisePied": false,
    "ImportSiteAdresse": {},
    "incoterm": "",
    "MentionExonerationTVA": "",
    "posteBudgetaire": "",
    "pourcentAcompte": {
        "value": 0,
        "Decimales": 2
    },
    "pourcentRemisePied": {
        "value": 0,
        "Decimales": 2
    },
    "reference": "",
    "referenceMandat": "",
    "regimeTVA": "",
    "roleTiers": "",
    "roleTiersLivre": "",
    "SessionImportation": {},
    "typeFacturation": {
        "value": 0,
        "title": "HT"
    }
}

Voir aussi :

Voir aussi les exemples suivants :

Récupérée de « https://frp.sage.fr/wiki1000/index.php?title=Ressource_(sdata)&oldid=14102 »
Outils personnels