🔗 Aller sur Sinao

Recherche, Filtres et Expand

L'API de Sinao dispose des paramètres : search, filters et expand pour chercher, flitrer et obtenir les relations d'un objet

Suggest Edits

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>

Par exemple, rechercher la.les facture.s adressée.s à Sinao

var myHeaders = new Headers();

var app_id = 16; // your app id
var search = "sinao";

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

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

fetch(`https://api.sinao.app/v1/apps/${app_id}/invoices?search=${search}`, requestOptions)
		.then(response => response.text())
		.then(result => console.log(result))
		.catch(error => console.log('error', error));

"data": [
  {
    "id": 2576,
    "number": "FAC-02390",
    "delivered_at": null,
    "written_at": "2023-10-23T09:56:57.000000Z",
    "title": null,
    "details": "Référence devis : DEV-00091\r",
    "reference": null,
    "bank_details_id": 2,
    "related_quote_id": 462,
    "status": "final",
    "customer_email": null,
    "amount": 1200,
    "amount_tax": 120,
    "credit_note_id": null,
    "stocks_are_pending_back": null,
    "payment_period": 30,
    "payment_methods": "virement bancaire, chèque",
    "payment_deadline_at": "2023-11-22T10:56:57.000000Z",
    "author_user_id": 35,
    "tags": [],
    "legal_notice": "",
    "imported_at": null,
    "related_recurring_invoice_id": null,
    "sepa_direct_debit_exported_at": null,
    "email_sent_at": null,
    "validated_at": "2023-10-23T15:05:25.000000Z",
    "paid_at": null,
    "columns": {
      "due": false,
      "amount": "P.U HT",
      "discount": false,
      "progress": false,
      "quantity": "Qte",
      "subtotal": "Total HT",
      "designation": "Designation",
      "line_number": false,
      "vat_percent": "TVA %",
      "quantity_name": false,
      "amount_with_taxes": false,
      "info_total_quantity": false
    },
    "metadata": null,
    "totals": {
      "due": 1320,
      "taxes": {
        "vat": {
          "1000": 120,
          "total": 120
        },
        "total": 120
      },
      "subtotal": {
        "57": {
          "1000": 1200
        },
        "total": 1200
      },
      "before_downpayments": {
        "due": 1320,
        "taxes": {
          "vat": {
            "1000": 120,
            "total": 120
          },
          "total": 120
        },
        "subtotal": {
          "57": {
            "1000": 1200
          },
          "total": 1200
        }
      }
    },
    "created_at": "2023-10-23T09:56:57.000000Z",
    "updated_at": "2023-10-23T15:05:25.000000Z",
    "note": null,
    "email_viewed_at": null,
    "email_complaint_at": null,
    "email_bounced_at": null,
    "yousign_sent_at": null,
    "yousign_signed_at": null,
    "foreign_currency": null,
    "amount_net_foreign_currency": null,
    "contact_infos": {
      "type": "organization",
      "id": 27844,
      "name": "SINAO",
      "address": "29 Chemin de l'Église",
      "address2": null,
      "location": "38100 Grenoble - France",
      "details": null,
      "image": null,
      "email": null
    },
    "third_account": false,
    "locale_currency": "EUR",
    "discount": {
      "name": null,
      "amount": null,
      "percent": null
    },
    "vat_exemption": {
      "exempted": false,
      "reason": "micro",
      "article": "TVA non applicable, art. 293 B du CGI"
    },
    "downpayment_request": null,
    "is_late": false,
    "will_be_late_at": "2023-11-22T10:56:57.000000Z",
    "due_date": "2023-11-22T10:56:57.000000Z"
  },
  {
    "id": 1445,
    "number": "FAC-01349",
    "delivered_at": "2022-04-20T22:00:00.000000Z",
    "written_at": "2022-05-05T07:13:32.000000Z",
    "title": null,
    "details": null,
    "reference": null,
    "bank_details_id": 2,
    "related_quote_id": null,
    "status": "paid",
    "customer_email": null,
    "amount": 40000,
    "amount_tax": 8000,
    "credit_note_id": null,
    "stocks_are_pending_back": null,
    "payment_period": 30,
    "payment_methods": null,
    "payment_deadline_at": "2022-06-04T07:13:32.000000Z",
    "author_user_id": 940,
    "tags": [
      "RELANCE SINAO 17/06"
    ],
    "legal_notice": null,
    "imported_at": null,
    "related_recurring_invoice_id": null,
    "sepa_direct_debit_exported_at": null,
    "email_sent_at": "2022-06-17T09:31:05.000000Z",
    "validated_at": "2022-05-05T09:13:44.000000Z",
    "paid_at": "2022-07-04T22:00:00.000000Z",
    "columns": {
      "due": false,
      "amount": "P.U HT",
      "discount": false,
      "progress": false,
      "quantity": "Qte",
      "subtotal": "Total HT",
      "designation": "Designation",
      "vat_percent": false,
      "quantity_name": false,
      "amount_with_taxes": false,
      "info_total_quantity": false
    },
    "metadata": null,
    "totals": {
      "due": 48000,
      "taxes": {
        "vat": {
          "2000": 8000,
          "total": 8000
        },
        "total": 8000
      },
      "subtotal": {
        "57": {
          "2000": 40000
        },
        "total": 40000
      },
      "before_downpayments": {
        "due": 48000,
        "taxes": {
          "vat": {
            "2000": 8000,
            "total": 8000
          },
          "total": 8000
        },
        "subtotal": {
          "57": {
            "2000": 40000
          },
          "total": 40000
        }
      }
    },
    "created_at": "2022-05-05T09:13:32.000000Z",
    "updated_at": "2022-07-05T14:44:24.000000Z",
    "note": null,
    "email_viewed_at": "2022-06-20 09:03:01",
    "email_complaint_at": null,
    "email_bounced_at": null,
    "yousign_sent_at": null,
    "yousign_signed_at": null,
    "foreign_currency": null,
    "amount_net_foreign_currency": null,
    "contact_infos": {
      "type": "organization",
      "id": 19402,
      "name": "CMV",
      "address": "8 Rue Paul Langevin",
      "address2": null,
      "location": "47300 Villeneuve-sur-Lot - France",
      "details": null,
      "image": null,
      "email": null
    },
    "third_account": false,
    "locale_currency": "EUR",
    "discount": {
      "name": "Remise",
      "amount": null,
      "percent": null
    },
    "vat_exemption": {
      "exempted": false,
      "reason": "micro",
      "article": "TVA non applicable, art. 293 B du CGI"
    },
    "downpayment_request": {
      "amount": 0,
      "percent": 0,
      "value": 0
    },
    "is_late": false,
    "will_be_late_at": false,
    "due_date": "2022-06-04T07:13:32.000000Z"
  }
]

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 1

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

// comme filters est un array, si vous souhaitez les factures du client 218 ou 220, ajoutez
// filters[1][name] : customer.id
// filters[1][comparator] : =
// filters[1][value] : 220


var myHeaders = new Headers();

var app_id = 16; // your app id

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

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

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

"data": [
  {invoice ojbect #1},
  {invoice ojbect #2},
  etc...
 ]

Exemple 2

Pour faire une recherche sur le nom d'un client (customer) on utilise sa clé d'identification (name) sous cette forme : customer.name

// filters[0][name] : customer.name
// filters[0][comparator] : LIKE
// filters[0][value] : %sinao%



var myHeaders = new Headers();

var app_id = 16; // your app id

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

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

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

"data": [
  {invoice ojbect #1},
  {invoice ojbect #2},
  etc...
 ]

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 app_id = 16; // your app id
var invoice_id = 10 // your invoive id

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

fetch(`https://api.sinao.app/v1/apps/${app_id}/invoices/${invoice_id}?expand[]=contact_info`, 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 app_id = 16; // your app id

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

fetch(`https://api.sinao.app/v1/apps/${app_id}/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 app_id = 16; // your app id

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

fetch(`https://api.sinao.app/v1/apps/${app_id}/invoices?limit=30&offset=`, 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 app_id = 16; // your app id

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": {
    "zapier": {
      "invoiceId": 320 // L'identifiant de votre achat WooCommerce
    }
  }
});

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

fetch(`https://api.sinao.app/v1/apps/${app_id}/invoices`, requestOptions)
		.then(response => response.text())
		.then(result => console.log(result))
		.catch(error => console.log('error', error));

Updated 6 months ago