Filtres de réponse API

Présentation des fonctionnalités

Les filtres de réponse API, également appelés 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 notes de frais, 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 afin d'appliquer automatiquement ce filtre à tous les appels de 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 Filtre API que celle 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 des appels d'approbateurs distants et des appels de moteurs fiscaux. Les appels de ce type vous permettent de spécifier un filtre pour simplifier le message envoyé à ces points de terminaison.

Ce que nous pensions

Les réponses API par défaut de Coupa peuvent contenir plus d’informations que ne le nécessitent vos systèmes tiers. 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'approbateur distant ou un service fiscal. Les filtres définis sur ces types d'appels vous permettent de spécifier les champs de ressources à envoyer dans le corps du message.

Vos filtres de réponse API peuvent réduire la sortie de la réponse à l'appel afin qu'elle envoie exactement ce dont votre service a besoin sans la surcharge nécessaire 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 dépenses
• Demandes

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

Comment cela fonctionne

Lorsque des filtres API Coupa sont utilisés pour limiter le volume de données nécessaire à la réponse, moins de données envoyées signifie moins de latence dans le temps de réponse. La simplification de la sortie au niveau nécessaire à l'intégration du système réduit à la fois le temps d'évaluation humaine initial et le temps de calcul pour l'analyse et le traitement. 

Les administrateurs Coupa et les utilisateurs d'intégration de systèmes disposant de l'autorisation api_filters/index peuvent consulter l'interface des filtres de réponse API dansConfiguration > Intégrations > FiltresAPI .

Les filtres prédéfinis sont étiquetés selon le modèle "default_[ResourceName]_filter" et sont des filtres prédéfinis qui représentent les meilleures pratiques. Ces filtres prédéfinis sont déjà réduits et n'incluent pas tous les champs disponibles (attributs), mais représentent plutôt les champs les plus fréquemment nécessaires aux efforts d'intégration. Vous pouvez ajouter ou supprimer d'autres champs de ressources pour modifier le jeu prédéfini initial en créant votre propre filtre ou en modifiant le filtre de ressources par défaut.  

Filtre API par défaut

Lorsque cette case est cochée, la case Par défaut [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 à cocher Par défaut est désactivée, ce filtre API peut être utilisé en ajoutant un paramètre de chaîne de requête :?filter='[API Filter Name]'à l'appel GET pour cette ressource.

Filtrer

Le filtre API est positif, ce qui signifie que les attributs listés sont affichés dans la réponse. Ajoutez ou supprimez ces attributs de ressource pour que le filtre transmette les attributs d'objet de ressource à votre système tiers et à l'option Enregistrer avant de tester. 

La syntaxe de filtre permet également de l'utiliser avec plusieurs types de documents. 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 pour l'appliquer à d'autres types de documents. Si un appel ou un hook Web utilise un filtre de réponse API pour un autre document, la spécification de filtre de l'autre document est ignorée.

Voici ci-dessous un exemple de syntaxe de 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.

Cliquez pour obtenir un exemple de syntaxe de filtre pour les lignes de demande et les modifications de ligne de commande avec du 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"
    ]
  },
  {
    "requisition_lines": [
      "id",
      "description",
      "line_num",
      "need_by_date",
      "order_line_id",
      "quantity",
      "receipt_required",
      "source_part_num",
      "unspsc_code",
      "status",
      "total",
      "line_type",
      "unit_price",
      {
        "dci_category": [
          "name",
          {
            "lookup": [
              "name"
            ]
          }
        ]
      },
      {
        "account": [
          "name",
          "code",
          "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_file_name",
          "file_file_size"
        ]
      },
      {
        "currency": [
          "code"
        ]
      },
      {
        "supplier": [
          "name",
          "display_name",
          "number",
          "pcard_account",
          {
            "custom_fields": [
              "payment_term_list"
            ]
          }
        ]
      },
      {
        "uom": [
          "code"
        ]
      }
    ]
  },
  {
    "order_line_changes": [
      "id",
      "created_at",
      "updated_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 prédéfinies si vous voulez le restaurer à sa liste d'origine ou 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'ID connue dans le champ Tester le filtre sur [Test Filter on] , puis en cliquant surTEST.  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êteChampsvous permet de passer les champs souhaités dans le corps de la réponse. Le format de la valeur deschampsest JSON. Reportez-vous à l'exemple ci-dessous :

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

Disponibilité

Cette fonctionnalité est disponible pour tous les clients Coupa.