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
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, NOT LIKE
) - 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 about 1 month ago