Filtres de réponse API

Revised: 26 August 2020

Vue d'ensemble des fonctionnalités

Les filtres de réponse API, également appelés filtres ou filtres API, simplifient la sortie de réponse et améliorent considérablement les performances. Les administrateurs Coupa peuvent créer et gérer des filtres de réponse API pour obtenir des dépenses, des demandes, des factures, des bons de commande et des ressources utilisateur. Vous pouvez désigner un filtre par défaut pour une ou plusieurs de ces ressources pour appliquer automatiquement ce filtre à tous les appels sur ce contrôleur et vous pouvez définir un filtre à appliquer à plusieurs types de ressources. Vous pouvez tester le filtre API à partir de la même page de détails du filtre API utilisée pour la configuration et il conserve également un historique des modifications apportées au filtre.

Les filtres peuvent également être utilisés avec les appels de l'approbateur à distance et les appels du moteur fiscal. Les appels de ces types vous permettent de spécifier un filtre pour simplifier le message envoyé à ces points de terminaison.

Les champs nouvellement ajoutés dans les API n'apparaîtront dans les réponses de l'API que lorsqu'ils sont accompagnés d'un champ spécifique mentionné dans les filtres de réponse de l'API ou le paramètre de requête « champs ».

Ce que nous pensions

Les réponses API par défaut de Coupa peuvent contenir plus d'informations que ce dont vos systèmes tiers ont besoin. Ils peuvent renvoyer de nombreux niveaux d'associations dont votre service n'a peut-être pas besoin.

Les appels peuvent également envoyer plus d'informations que nécessaire pour un service d'approbation à distance ou un service fiscal. Les filtres définis sur ces types d'appel vous permettent de spécifier quels champs de ressources sont envoyés dans le corps du message.

Vos filtres de réponse API peuvent réduire la sortie de la réponse d'appel afin qu'elle envoie exactement ce dont votre service a besoin sans les frais généraux nécessaires pour gérer plus que ce dont votre service externe a besoin. 

Des filtres de réponse API peuvent être créés pour les ressources suivantes :

  • Factures
  • En-têtes de commande
  • Lignes de commande
  • Utilisateurs
  • En-têtes de dépenses
  • Lignes de frais
  • Demandes

La page de création de filtre API permet une itération rapide et maintient un historique des modifications,afin que vous puissiez rapidement tester votre filtre, vérifier la réponse et la modifier pour obtenir exactement ce dont vous avez besoin.

Comment ça marche

Lorsque les filtres de l'API Coupa sont utilisés pour limiter le volume de données nécessaires à la réponse, moins de données envoyées signifie une latence plus faible dans le temps de réponse. La simplification de la sortie à ce qui est nécessaire pour l'intégration du système réduit à la fois le temps d'évaluation humaine initiale et plus tard le temps de calcul pour l'analyse et le traitement. 

Les administrateurs Coupa et les utilisateurs d'intégration de systèmes avec l'autorisation api_filters/index peuvent voir l'interface API Response Filters dans Setup > Integrations > API Filters.

API Filters.png

Les filtres initialement ensemencés sont étiquetés à l'aide du motif « default_[ResourceName]_filter » et sont des filtres prédéfinis qui représentent les meilleures pratiques. Ces filtres ensemencés sont déjà réduits et n'incluent pas tous les champs disponibles (attributs), mais représentent plutôt les champs les plus couramment nécessaires aux efforts d'intégration. Vous pouvez ajouter ou supprimer plus de champs de ressources pour modifier l'ensemble initial en créant votre propre filtre ou en modifiant le filtre de ressources par défaut.  

Filtres API Detail.png

Filtre API par défaut

Lorsqu'elle est cochée, la case Default applique le filtre à tous les appels API pour OBTENIR cette ressource. Chaque ressource ne peut avoir qu'un seul filtre API par défaut.

Lorsque la case Par défaut est désactivée, ce filtre API peut être utilisé en ajoutant une chaîne de requête param : ?filter='[Nom du filtre API]' à l'appel GET pour cette ressource.

Filtre

Le filtre API est positif, ce qui signifie que les attributs répertoriés sont affichés dans la réponse. Ajoutez ou supprimez ces attributs de ressource afin que le filtre passe les attributs d'objet de ressource à votre système tiers et enregistrez avant le test. 

La syntaxe du filtre permet également une utilisation avec plus d'un type de document. Par défaut, un nouveau filtre contiendra des attributs qui correspondent à la ressource sélectionnée à la première étape de la création du filtre, mais vous pouvez ajouter du texte de filtre à appliquer à d'autres types de documents. Si un appel ou un crochet Web utilise un filtre de réponse API pour un autre document, la spécification de filtre pour l'autre document est simplement ignorée.

Vous trouverez ci-dessous un exemple de capture d'écran de la syntaxe du filtre avec deux types de documents en surbrillance. Sous le graphique, vous pouvez cliquer pour développer le même filtre avec du texte sélectionnable.

Réponse de l'API filter.png

Cliquez pour un exemple de syntaxe de filtre pour les lignes de demande et les modifications de ligne de commande avec texte sélectionnable.
[
"id",
  "created_at",
  "updated_at",
  "need_by_date",
  "status
",   "submitted_at
",   "ship_to_attention
",   "line_count
", "exported
", "total
",
  {"custom_fields
" : ["migrated_po_number
",       "last_integrated_successfully
"
]
},
  {"currency
" : [
"code", "decimals
"
]
},
  {"requested_by
" : [
"id",
      "login",
      "fullname",
      "email", "work_level
"
]
},
  {"ship_to
_address" : [
"name",
      "location_code
", "street1
", "street2
", "city
", "state",
      "postal_code",
      "vat_number",
      "local_tax_number",
    "company_code"
]
},
  {
"réquisition_lines
" : [
"id", "description
", "line_num",
      "need_by_date",
      "order_line
_id",
      "quantity", receipt "_required
",       "part_source_num
",
      "unspsc_code
", "status",
      "total" line_type
        "
," unit_price
          ",
          {" d
            "category", "{
" name ",
"
          lookup "
],
      {
" account
          "
}," name
          "," name
          "segment_1",
          "segment_2",
          "segment_3",
          {
"account_type" : [
"name"
           
]
         
}]},
      {
"ul_contract
" : ["name
", "description
",           "external_ref_num
"
]
},
      {"custom_fields
" : ["ext_line_num
", "material_type
",
]
},
      {
"commodity" : [
"name",
          "category", "subcategory
"
]
},
      {"account_allocations"
          : ["amount
",
            "pct",
          {"account
"
              : ["name
", "code",
              "segment_1",
              "segment_2",
                "segment_3",
              {
"account_type" : ["name
"
               
           
]
             
         
}]},
      {"attachments
"
          : ["id",
          "created_at
", "updated_at",
          "
type",
          "intent", "file_file_name
", "file_file_size
"
]
},
      {
"currency" : ["code
"
]
},
      {
"supplier" : [name ", display
_name",
          "number
", "pcard_account
",
          {"custom_fields
" : [payment_term_list
           
]
         
},
      {
"uom
" code ": ["
       
]
     
},
  {
"order_line" : "changes
" created_id
      "," updated_id,
      "_at",
      "line_num",
      "description",
      "need_by_date",
      "order_header_change_id",
      "order_line_id",
      "price",
      "quantity",
      "total",
      "paid_amount",
      {
"custom_fields" : {}
}
]
},
  {
"current_approval" : [
"id",
      "approvable_type",
      "approvable_id",
      "delegate_id"
]
},
  {
"created_by" : [
"id",
      "login",
      "fullname",
      "email",
      "work_level"
]
},
  {
"updated_by" : [
"id",
      "login",
      "fullname",
      "email",
      "work_level"
]
},
  {
"preparer" : [
"id",
      "login",
      "fullname",
      "email",
      "work_level"
]
}
]

Réinitialiser

Vous pouvez réinitialiser le filtre aux valeurs initialement initialisées si vous souhaitez le restaurer à sa liste d'origine ou vous pouvez développer l'historique des modifications pour référence.

Test

Vous pouvez vérifier la réponse de sortie de votre filtre en entrant d'abord une valeur d'identifiant connue dans le champ Filtre de test activé, puis en cliquant sur TEST.  Toute la sécurité de rôle standard s'applique à ce que vous pouvez voir avec le test, mais votre filtre API enregistré répond avec le sous-ensemble spécifié de champs de paramètres dans un format JSON facile à lire.

En tant qu'opérateur

L'opérateur de requête de champs vous permet de passer les champs que vous voulez dans le corps de la réponse. Le format de la valeur des champs est JSON. Veuillez vous reporter à l'exemple ci-dessous :

?fields=["id","invoice_number",{"invoice_lines" :["id","line_num"]}]

Disponibilité

Cette fonction est disponible pour tous les clients Coupa.

 

Une partie ou la totalité de cette page peut avoir été traduite par machine. Toutes nos excuses pour les inexactitudes.