Liste des devis

GET /firms/FIRM_ID/quotes.json

Liste des devis, par groupe de 30 résultats.

Chaque devis est composé d'un ensemble de lignes de facturation (items).

Optimisation des requêtes

Par défaut, l'API retourne les informations de chaque devis, sauf les lignes de facturation et les fichiers joints, afin d'optimiser les performances de vos requêtes. Pour obtenir les lignes de facturation d'un devis spécifique (ou bien la liste des pièces jointes), il vous suffit de faire une requête sur le devis concerné.

Vous avez la possibilité d'inclure les lignes de facturation et la liste des fichiers joints de chaque devis retourné dans la réponse en utilisant le paramètre 'with_details':

  • with_details :
    • 1 pour inclure les lignes de facturation et la liste des pièces jointes
    • 0 (par défaut) pour ne pas inclure les lignes de facturation et la liste des pièces jointes

Paramètres optionnels

  • page : numéro de page
  • api_id : recherche exacte sur le champ api_id
  • api_custom : recherche partielle sur le champ api_custom
  • quote_ref : recherche partielle sur le numéro de devis
  • customer_id : afficher uniquement les devis d'un client spécifique
  • title : recherche partielle sur le l'objet du devis
  • company : recherche partielle sur le nom de société
  • last_name : recherche partielle sur le nom de famille
  • status: recherche sur un statut de devis. Les valeurs possibles sont:
    • pending : En cours (devis non soldés en attente ou accepté)
    • to_invoice : A facturer (devis acceptés et non soldés)
    • invoiced : Soldé
    • 0 : En attente
    • 1 : Accepté
    • 9 : Refusé

Recherche par périodes

Vous pouvez limiter votre recherche à une période spécifique en utilisant les paramètres optionnels suivants:

  • period_start: période de début (format: MM/AAAA)
  • period_end: période de fin (format: MM/AAAA)

Tri

Par défaut, les devis sont triés par ordre décroissant de numéro de devis.
Vous pouvez trier les résultats selon différentes méthodes en utilisant les paramètres suivants:

  • sort:
    • asc: tri croissant
    • desc: tri décroissant
  • order : type de tri
    • customer: tri par nom mnémotechnique de client
    • total: tri par montant total de facturation
    • billed: tri par date de devis
    • created: tri par date de création d'un devis (ie date à laquelle l'enregistrement a été créé)
    • updated: tri par date de dernière modification d'un devis (ie date à laquelle l'enregistrement a été modifié pour la dernière fois)

Requête

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 https://www.facturation.pro/firms/FIRM_ID/quotes.json

Réponse

[{
  "amount_invoiced": "0.0",
  "api_custom": null,
  "api_id": null,
  "category_id": null,
  "currency": "EUR",
  "customer_id": 180369,
  "discount": "0.0",
  "draft": false,
  "fully_invoiced": false,
  "id": 411583,
  "ignore_quote": false,
  "information": "",
  "invoiced_on": "2013-07-29",
  "language": "fr",
  "pay_before": "30",
  "penalty": "0.0",
  "precompte": null,
  "quote_ref": 2,
  "quote_status": 0,
  "rebate_percentage": "0.0",
  "service_personne": false,
  "tax_percent": null,
  "tax_title": null,
  "term_on": "2013-08-28",
  "title": null,
  "total": "459.0",
  "vat_exemption": null,
  "invoice_ids": [],
  "items": [{
    "id": 949159,
    "nature": 9,
    "optional": false,
    "position": 1,
    "product_id": null,
    "quantity": "1.0",
    "style": null,
    "title": "Affichage publicitaire - Appel \u00e0 facture n\u00b03148",
    "total": "459.0",
    "unit_price": "459.0",
    "vat": "0.200"
  }]
}, {
  "amount_invoiced": "0.0",
  "api_custom": null,
  "api_id": null,
  "category_id": 4867,
  "currency": "EUR",
  "customer_id": 180366,
  "discount": "0.0",
  "draft": false,
  "fully_invoiced": false,
  "id": 411582,
  "ignore_quote": false,
  "information": "",
  "invoiced_on": "2013-07-29",
  "language": "fr",
  "pay_before": "60fm",
  "penalty": "0.0",
  "precompte": null,
  "quote_ref": 1,
  "quote_status": 0,
  "rebate_percentage": "0.0",
  "service_personne": false,
  "tax_percent": null,
  "tax_title": null,
  "term_on": "2013-08-28",
  "title": null,
  "total": "1458.27",
  "vat_exemption": null,
  "invoice_ids": [],
  "items": [{
    "id": 949158,
    "nature": 9,
    "optional": false,
    "position": 1,
    "product_id": 0,
    "quantity": "1.0",
    "style": null,
    "title": "Affichage de publicit\u00e9 d\u00e9cembre 2012",
    "total": "1458.27",
    "unit_price": "1458.27",
    "vat": "0.200"
  }]
}]

Détail d'un devis

GET /firms/FIRM_ID/quotes/ID.json

Affiche le détail du devis n° ID

Chaque devis est composé d'une ou plusieurs lignes de facturation (items)

Requête

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 https://www.facturation.pro/firms/FIRM_ID/quotes/ID.json

Réponse

{
  "amount_invoiced": "0.0",
  "api_custom": null,
  "api_id": null,
  "category_id": null,
  "currency": "EUR",
  "customer_id": 180369,
  "discount": "0.0",
  "draft": false,
  "fully_invoiced": false,
  "id": ID,
  "ignore_quote": false,
  "information": "",
  "invoiced_on": "2013-07-29",
  "language": "fr",
  "pay_before": "30",
  "penalty": "0.0",
  "precompte": null,
  "quote_ref": 2,
  "quote_status": 0,
  "rebate_percentage": "0.0",
  "service_personne": false,
  "tax_percent": null,
  "tax_title": null,
  "term_on": "2013-08-28",
  "title": null,
  "total": "459.0",
  "vat_exemption": null,
  "invoice_ids": [],
  "items": [{
    "id": 949159,
    "nature": 9,
    "optional": false,
    "position": 1,
    "product_id": null,
    "quantity": "1.0",
    "style": null,
    "title": "Affichage publicitaire - Appel \u00e0 facture n\u00b03148",
    "total": "459.0",
    "unit_price": "459.0",
    "vat": "0.200"
  }]
}

Créer un devis

POST /firms/FIRM_ID/quotes.json

Création d'un nouveau devis. On obtient en retour le code JSON de l'enregistrement créé, avec l'ID qui lui a été attribué.

Un devis doit au moins contenir une ligne de facturation (champs items)

Le total de chaque ligne de facturation ainsi que le total du devis sont calculés automatiquement et ne doivent pas être transmis.

Requête

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 -H 'Content-Type: application/json; charset=utf-8' \
 -X POST \
 -d '{
   "currency": "EUR",
   "customer_id": 180366,
   "invoiced_on": "2013-07-29",
   "language": "fr",
   "pay_before": "60fm",
   "penalty": "0.0",
   "title": "Facturation mensuelle",
   "items": [{
     "position": 1,
     "quantity": "1.0",
     "title": "Affichage pub 1",
     "unit_price": "500",
     "vat": "0.200"
   }, {
     "position": 2,
     "quantity": "1.0",
     "title": "Affichage pub 2",
     "unit_price": "200",
     "vat": "0.200"
   }]
 }' \
 https://www.facturation.pro/firms/FIRM_ID/quotes.json

Réponse

Status: 201 Created
Location: /firms/{FIRM_ID}/quotes/#{new-quote-id}.json

{
  "amount_invoiced": "0.0",
  "api_custom": null,
  "api_id": null,
  "category_id": null,
  "currency": "EUR",
  "customer_id": 180366,
  "discount": null,
  "draft": false,
  "fully_invoiced": false,
  "id": 411585,
  "ignore_quote": false,
  "information": null,
  "invoiced_on": "2013-07-29",
  "language": "fr",
  "pay_before": "60fm",
  "penalty": "0.0",
  "precompte": null,
  "quote_ref": 4,
  "quote_status": 0,
  "rebate_percentage": "0.0",
  "service_personne": false,
  "tax_percent": null,
  "tax_title": null,
  "term_on": "2013-08-28",
  "title": "Facturation mensuelle",
  "total": "700.0",
  "vat_exemption": null,
  "items": [{
    "id": 949162,
    "nature": 9,
    "optional": false,
    "position": 1,
    "product_id": null,
    "quantity": "1.0",
    "style": null,
    "title": "Affichage pub 1",
    "total": "500.0",
    "unit_price": "500.0",
    "vat": "0.200"
  }, {
    "id": 949163,
    "nature": 9,
    "optional": false,
    "position": 2,
    "product_id": null,
    "quantity": "1.0",
    "style": null,
    "title": "Affichage pub 2",
    "total": "200.0",
    "unit_price": "200.0",
    "vat": "0.200"
  }]
}

Modifier un devis

PATCH /firms/FIRM_ID/quotes/ID.json

Mise à jour d'un devis existant.
Un devis doit toujours contenir au moins une ligne de facturation:

  • Pour ajouter une ligne de facturation, l'id de l'item doit être vide.
  • Pour modifier une ligne de facturation, l'id de l'item doit être spécifié.
  • Pour supprimer une ligne de facturation, il suffit de passer l'id et un champ "_destroy" avec la valeur "1"

Requête

Dans l'exemple ci dessous, on ajoute une ligne de facturation et on supprime la ligne existante

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 -H 'Content-Type: application/json; charset=utf-8' \
 -X PATCH \
 -d '{
    "id": "ID",
    "api_custom": null,
    "api_id": null,
    "customer_id": "143",
    "title": "Creation internet",
    "quote_status": "1",
    "discount": "0.0",
    "information": "TEST",
    "pay_before": "30",
    "penalty": "3.0",
    "items": [{
      "position": "1",
      "product_id": "10",
      "quantity": "1.0",
      "title": "Campagne pub",
      "unit_price": "300.0",
      "nature": "2"
    }, {
      "id": "889",
      "_destroy": "1"
    }]
  }'
  https://www.facturation.pro/firms/FIRM_ID/quotes/ID.json

Réponse

Status: 200 OK

Supprimer un devis

DELETE /firms/FIRM_ID/quotes/ID.json

Supprime le devis identifié par son ID.

Requête

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 -X DELETE \
  https://www.facturation.pro/firms/FIRM_ID/quotes/ID.json

Réponse

Status: 200 OK

Télécharger PDF

GET /firms/FIRM_ID/quotes/ID.pdf

Télécharger le devis n° ID au format PDF

Requête

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 -o devis.pdf https://www.facturation.pro/firms/FIRM_ID/quotes/ID.pdf

Réponse

Vous obtenez le fichier PDF du devis demandé

Convertir en facture

POST /firms/FIRM_ID/quotes/ID/invoice.json

Conversion du devis ID en facture.

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 -X POST \
  https://www.facturation.pro/firms/FIRM_ID/quotes/ID/invoice.json

Réponse

Status: 201 Created
Location: /firms/FIRM_ID/invoices/411584.json

{
  "api_custom": null,
  "api_id": null,
  "category_id": null,
  "currency": "EUR",
  "customer_id": 180366,
  "external_ref": null,
  "discount": null,
  "draft": false,
  "id": 411584,
  "information": null,
  "invoice_ref": "201307-4",
  "invoiced_on": "2013-07-29",
  "language": "fr",
  "paid_on": null,
  "pay_before": "60fm",
  "payment_mode": 0,
  "payment_ref": null,
  "penalty": "0.0",
  "precompte": null,
  "quote_id": null,
  "rebate_percentage": "0.0",
  "service_personne": false,
  "tax_percent": null,
  "tax_title": null,
  "term_on": "2013-09-30",
  "title": "Facturation mensuelle",
  "total": "700.0",
  "vat_exemption": null,
  "items": [{
    "id": 949167,
    "nature": 9,
    "optional": false,
    "position": 1,
    "product_id": null,
    "quantity": "1.0",
    "style": null,
    "title": "Affichage pub 1",
    "total": "500.0",
    "unit_price": "500.0",
    "vat": "0.200"
  }, {
    "id": 949168,
    "nature": 9,
    "optional": false,
    "position": 2,
    "product_id": null,
    "quantity": "1.0",
    "style": null,
    "title": "Affichage pub 2",
    "total": "200.0",
    "unit_price": "200.0",
    "vat": "0.200"
  }]
}

Ajouter une pièce jointe

POST /firms/FIRM_ID/quotes/ID/upload.json

Ajoute une pièce jointe au devis ID.

Paramètres

  • Le fichier doit être transmis sous forme de formulaire multipart (ie "multipart/form-data"), à l'aide de la variable upload_file.
  • Par défaut, le fichier sera stocké avec le nom qu'il avait sur votre système. Si vous le souhaitez, vous pouvez forcer un autre nom de fichier à l'aide de la variable filename
  • Si vous souhaitez rendre visible ce fichier au client, il suffit de l'indiquer en affectant la valeur 1 la variable visible

Requête

Cette requête ajoute le fichier stocké dans "/tmp/test.pdf" du poste local au devis possédant l'ID 1, en le renommant en "justificatif.pdf" et en le rendant visible par le client

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 -F "upload_file=@/tmp/test.pdf" \
 https://www.facturation.pro/firms/FIRM_ID/quotes/1/upload.json?filename=justificatif.pdf&visible=1

Réponse

Status: 201 Created
Location: /firms/FIRM_ID/assets/1.json

{
  "id": 1,
  "quote_id": 1,
  "document_file_name":"justificatif.pdf",
  "document_content_type":"application/pdf",
  "document_file_size":18884,
  "download_url":"https://www.facturation.pro/firms/6761/assets/1/download",
  "visible": true
}

Liste des champs

Champs Libellé Type Accès
id Identifiant int(11) lecture seule
customer_id Client int(11) lecture/écriture
customer_identity Nom de la société ou du client lecture seule
title Objet string(255) lecture/écriture
language Langue du PDF string(2) lecture/écriture
category_id Catégorie int(11) lecture/écriture
followup_id Suivi commercial int(11) lecture/écriture
invoiced_on Date du devis date lecture/écriture
term_on Valide jusqu'au date lecture/écriture
draft Brouillon boolean lecture seule
total Montant total HT decimal(15,3) lecture seule
total_with_vat Montant total TTC decimal(15,3) lecture seule
currency Devise string(3) lecture/écriture
rebate_percentage Réduction globale decimal(8,3) lecture/écriture
vat_exemption Motif d'exonération de TVA string(255) lecture/écriture
vat_country Code pays des taux TVA à appliquer string(2) lecture/écriture
tax_title Intitulé de la taxe additionnelle sur le total HT string(255) lecture/écriture
tax_percent Pourcentage de la taxe additionnelle sur le total HT decimal(5,2) lecture/écriture
penalty Pénalités de retard decimal(8,3) lecture/écriture
pay_before Délai de paiement string(16) lecture/écriture
discount Taux d'escompte decimal(8,3) lecture/écriture
precompte Precompte boolean lecture/écriture
activity_title Nature de l'activité string(255) lecture/écriture
service_personne Service à la personne boolean lecture/écriture
accounting_entry Compte d'imputation string(8) lecture/écriture
information Informations complémentaires text lecture/écriture
internal_note Note interne text lecture/écriture
created_at Créé le datetime(3) lecture seule
updated_at Modifié le datetime(3) lecture seule
user_id Géré par int(11) lecture/écriture
api_id API - Référence numérique libre bigint(20) lecture/écriture
api_custom API - Texte libre string(255) lecture/écriture
quote_status Statut du devis int(11) lecture/écriture
quote_ref Devis n° int(11) lecture seule
ignore_quote Ne pas faire de suivi de facturation boolean lecture/écriture
fully_invoiced Devis soldé? boolean lecture seule
amount_invoiced Montant déjà facturé decimal(15,3) lecture seule
invoice_ids Tableau des IDs des factures associées à ce devis array lecture seule
estimated_total_in_main_currency Total TTC estimé en euro lecture seule
soft_deleted Enregistrement marqué comme à supprimer boolean lecture seule
hard_delete_on Date définitive de la suppression date lecture seule

Ligne de facturation

Champs Libellé Type Accès
id Identifiant int(11) lecture seule
quantity Quantité decimal(12,4) lecture/écriture
title Libellé text lecture/écriture
unit_price Prix unitaire HT decimal(15,3) lecture/écriture
vat Taux de TVA decimal(5,3) lecture/écriture
product_id Identifiant du produit int(11) lecture/écriture
position Ligne n° int(11) lecture/écriture
total Total HT decimal(15,3) lecture seule
optional En option
Ce champ n'est utilisé que pour les devis. Lorsque la valeur de ce champ est 'true', la ligne est considérée comme une option, elle n'est donc pas prise en compte dans le calcul du total, et toutes les lignes optionnelles sont regroupées en fin de devis dans un bloc spécifique.
boolean lecture/écriture
style Style de formattage
Par défaut (ie valeur vide), ce champ indique une ligne de facturation standard. La valeur 'comment' permet d'indiquer qu'il s'agit d'une ligne de commentaire, la valeur 'title' permet d'indiquer qu'il s'agit d'une ligne de titre (mise en gras automatiquement) et la valeur 'new_page' permet d'indiquer qu'il s'agit d'un saut de page.
string(20) lecture/écriture
nature Type
la nature de la prestation n'est à préciser que pour les auto-entrepreneurs et les micro-entrepreneurs, afin de calculer correctement les cotisations sociales.
int(11) lecture/écriture

Champs utilisant des valeurs spécifiques

nature

1 : Vente
2 : BIC - Prestations de service commerciales ou artisanales
3 : BNC - Prestation non commerciale
9 : Non applicable

language

fr : Français
en : Anglais
es : Espagnol
nl : Néerlandais

pay_before

0 : A réception
cash : Comptant
15 : 15 jours nets
30 : 30 jours nets
45 : 45 jours nets
60 : 60 jours nets
7fm : 7 jours fin de mois
30fm : 30 jours fin de mois
45fm : 45 jours fin de mois
0fm10 : fin de mois le 10
0fm20 : fin de mois le 20
30fm10 : 30 jours fin de mois le 10
30fm20 : 30 jours fin de mois le 20

currency

EUR : euro
USD : dollar US
GBP : livre sterling
CHF : franc suisse
CAD : dollar canadien
AUD : dollar australien
NZD : dollar néo-zélandais
JPY : yen japonais
HKD : dollar de Hong Kong
CNY : yuan chinois
RUB : rouble russe
ILS : shekel israélien
AFN : Afghani afghan
MRO : Ancienne ouguiya mauritanienne
XAG : Argent
MGA : Ariary malgache
THB : Baht thailandais
PAB : Balboa panaméen
ETB : Birr éthiopien
BTC : Bitcoin
VEF : Bolivar fuerte vénézuélien
BOB : Boliviano bolivien
GHS : Cedi ghanéen
SVC : Colon salvadorien
CRC : Colón costaricien
NIO : Cordoba d'or nicaraguayen
DKK : Couronne danoise
ISK : Couronne islandaise
NOK : Couronne norvégienne
SEK : Couronne suedoise
CZK : Couronne tchèque
GMD : Dalasi gambien
MKD : Denar macédonien
DZD : Dinar algérien
BHD : Dinar bahreïni
IQD : Dinar irakien
JOD : Dinar jordanien
KWD : Dinar koweïtien
LYD : Dinar libyen
RSD : Dinar serbe
TND : Dinar tunisien
AED : Dirham des Émirats arabes unis
MAD : Dirham marocain
STD : Dobra santoméen
ZWL : Dollar Zimbabwéen
BSD : Dollar bahaméen
BBD : Dollar barbadien
BMD : Dollar bermudien
BZD : Dollar bélizien
BND : Dollar de Brunei
FJD : Dollar de Fidji
SGD : Dollar de Singapour
TTD : Dollar de Trinité-et-Tobago
XCD : Dollar des Caraïbes orientales
SBD : Dollar des Salomon
KYD : Dollar des îles Caïmans
SRD : Dollar du Suriname
GYD : Dollar guyanien
JMD : Dollar jamaïcain
LRD : Dollar libérien
NAD : Dollar namibien
VND : Dong vietnamien
AMD : Dram arménien
XDR : Droit de Tirage Spécial
CVE : Escudo cap-verdien
AWG : Florin arubais
ANG : Florin des Antilles néerlandaises
HUF : Forint hongrois
XAF : Franc CFA (XAF)
XOF : Franc CFA (XOF)
XPF : Franc CFP (XPF)
DJF : Franc Djibouti
BIF : Franc burundais
KMF : Franc comorien
CDF : Franc congolais
GNF : Franc guinéen
RWF : Franc rwandais
HTG : Gourde haïtienne
PYG : Guaraní paraguayen
UAH : Hryvnia ukrainienne
PGK : Kina papou-néo-guinéen
LAK : Kip laotien
HRK : Kuna croate
MWK : Kwacha malawien
ZMW : Kwacha zambien
AOA : Kwanza angolais
MMK : Kyat
GEL : Lari géorgien
ALL : Lek albanais
HNL : Lempira hondurien
SLL : Leone sierra-léonais
MDL : Leu moldave
RON : Leu roumain
BGN : Lev bulgare (ancien)
SZL : Lilangeni swazilandais
TRY : Lire turque
GGP : Livre
SHP : Livre
GIP : Livre de Gibraltar
JEP : Livre de Jersey
FKP : Livre des Îles Malouines
LBP : Livre libanaise
IMP : Livre mannoise
SDG : Livre soudanaise
SYP : Livre syrienne
EGP : Livre égyptienne
LSL : Loti lesothan
AZN : Manat azerbaïdjanais
BAM : Mark convertible de Bosnie-Herzégovine
MZN : Metical mozambicain
NGN : Naira nigérien
ERN : Nakfa érythréen
BTN : Ngultrum bhoutanais
TWD : Nouveau dollar de Taïwan
TMT : Nouveau manat turkmène
XAU : Or
MRU : Ouguiya mauritanienne
TOP : Pa'anga des Tonga
XPD : Palladium
MOP : Pataca
ARS : Peso argentin
CLP : Peso chilien
COP : Peso colombien
CUC : Peso convertible cubain
CUP : Peso cubain
DOP : Peso dominicain
MXN : Peso mexicain
PHP : Peso philippin
UYU : Peso uruguayen
XPT : Platine
BWP : Pula botswanais
GTQ : Quetzal guatémaltèque
ZAR : Rand sud-africain
IRR : Rial iranien
OMR : Rial omanais
KHR : Riel cambodgien
MYR : Ringgit malaisien
QAR : Riyal qatarien
SAR : Riyal saoudien
YER : Riyal yéménite
BYR : Rouble biélorusse (ancien)
BYN : Rouble biélorusse (nouveau)
INR : Roupie indienne
IDR : Roupie indonésienne
MUR : Roupie mauricienne
NPR : Roupie népalaise
PKR : Roupie pakistanaise
SCR : Roupie seychelloise
LKR : Roupie srilankaise
MVR : Rufiyaa maldivienne
BRL : Réal bresilien
KES : Shilling kényan
UGX : Shilling ougandais
SOS : Shilling somalien
TZS : Shilling tanzanien
PEN : Sol péruvien
KGS : Som kirghiz
TJS : Somoni tadjik
UZS : Sum ouzbek
BDT : Taka bangladais
WST : Tala samoan
KZT : Tenge kazakh
MNT : Tugrik mongol
CLF : Unidad de fomento chilienne
VUV : Vatu du Vanuatu
KPW : Won nord-coréen
KRW : Won sud-coréen
PLN : Zloty polonais

quote_status

0 : En attente
1 : Accepté
9 : Refusé