Recherche et filtres

Faire une recherche

Pour effectuer une recherche textuelle ou numérique vous passez par le paramètre search qu'il faut inclure dans votre url, par exemple : /apps?search=<Votre recherche>

Filtrer les résultats

Pour filter les résultats on utilise le paramètre filters qui est un tableau d'objects.

Chaque filtre se compte des clés suivantes :

  • name : le nom du paramètre à filtrer
  • comparator : l'opérateur de comparaison (=, <, >, <=, >=, !=, LIKE, IN, REGEX)
  • value : la valeur que vous recherchez

Exemple

Pour faire une recherche sur l'identifiant d'un client (customer) on utilise sa clé d'identification (id) sous cette forme : customer.id

// filters[0][name] : customer.id
// filters[0][comparator] : =
// filters[0][value] : 218

var myHeaders = new Headers();

myHeaders.append("Authorization", "Bearer <token>");

var requestOptions = {
        method: 'GET',
        headers: myHeaders,
        redirect: 'follow'
};

fetch("https://api.sinao.app/v1/apps/invoices?filters[0][name]=customer.id&filters[0][comparator]==&filters[0][value]=218", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

Expansion des objets

Pour expandre des objets on utilise la clé expand dans votre query string. L'expansion d'objet va permettre d'afficher des informations des sous-objets en relation avec celui que vous êtes en train d'utiliser.

Exemple

Par exemple si nous voulons plus d'informations sur le customer d'une facture, on peut "expand" contact_infos en ajoutant expand[]=contact_infos à notre url, les objets que vous pouvez expand se trouvent sur notre fichier swagger.

var myHeaders = new Headers();

myHeaders.append("Authorization", "Bearer <token>");

var requestOptions = {
        method: 'GET',
        headers: myHeaders,
        redirect: 'follow'
};

fetch("https://api.sinao.app/v1/apps/:appId/invoices/:invoiceId?expand[]=contact_infos", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

Limiter le nombre de résultats

Si vous souhaitez limiter le nombre de résultats retourné par l'API, vous pouvez utiliser la clef limit dans votre url.

Exemple

Par exemple, nous voulons récupérer les 30 dernières factures créées, on ajoutera à notre url limit=30.

var myHeaders = new Headers();

myHeaders.append("Authorization", "Bearer <token>");

var requestOptions = {
        method: 'GET',
        headers: myHeaders,
        redirect: 'follow'
};

fetch("https://api.sinao.app/v1/apps/:appId/invoices?limit=30", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

Pagination

Pour pouvoir utiliser la pagination on se sert de deux paramètres, le premier est limit qui limitera le nombre de résultats à retourner sinon l'API va retourner toutes les entrées et offset qui permet d'afficher la page.

Exemple

Afficher la 5ème page avec 30 résultats par page (limit=30&offset=4).

var myHeaders = new Headers();

myHeaders.append("Authorization", "Bearer <token>");

var requestOptions = {
        method: 'GET',
        headers: myHeaders,
        redirect: 'follow'
};

fetch("https://api.sinao.app/v1/apps/:appId/invoices?limit=30&offset=4", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

Les métadonnées

Sinao se veut flexible, pour permettre une intégration avec vos applications externes (WooCommerce, Shopify, ect) nous avons sur la totalité de nos endpoints de création (POST / PUT) une clé metadata, cette clé permettra de faire la liaison entre vos identifiants d'objets et ceux sur Sinao mais pas que, vous pourrez stocker toutes les informations que vous souhaitez sous forme d'un objet.

Exemple

Nous avons un achat sur WooCommerce qui porte l'identifiant 320, nous allons créer une facture sur Sinao pour cet achat. Pour garder l'identifiant de votre achat WooCommerce sur la facture Sinao il suffit de l'envoyer dans la clé metadata.

var myHeaders = new Headers();

myHeaders.append("Authorization", "Bearer <token>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "contact_infos": {
    "id": 218,
    "type": "organization",
    "name": "SINAO",
    "location": "38100 Grenoble - France",
    "address": "29 Chemin de l'Église"
  },
  "title": "Facture pour l'achat WooCommerce numéro 320",
  "content": [
    {
      "lines": [
        {
          "detail": "Mon produit 1",
          "account_id": 57,
          "type": "product",
          "action": "sell",
          "quantity": 1,
          "amount_accurately": 500000000,
          "vat_percent": 2000
        }
      ]
    }
  ],
  "bank_details_id": 1,
  "metadata": {
    "woocommerce_order_id": 320 // L'identifiant de votre achat WooCommerce
  }
});

var requestOptions = {
        method: 'POST',
        headers: myHeaders,
        body: raw,
        redirect: 'follow'
};

fetch("https://api.sinao.app/v1/apps/:appId/invoices", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));