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
• full_quote_ref : recherche exacte 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
• period_end: période de fin

Le format des périodes peut être AAAA-MM (année-mois) ou bien AAAA-MM-JJ (année-mois-jour)

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"
  }]
}]

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": ID,
  "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"
  }]
}

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": ID,
   "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": ID,
  "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"
  }]
}

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": ID,
    "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

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

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é

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": ID,
  "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"
  }]
}

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_file_size":18884,
  "download_url":"https://www.facturation.pro/firms/FIRM_ID/assets/1/download",
  "visible": true
  }

POST https://www.facturation.pro/firms/FIRM_ID/emails.json?bill_id=QUOTE_ID

Permet d'envoyer un devis par courriel.

• Si vous avez définit un modèle d'envoi, ce modèle est utilisé pour générer le mail. Vous pouvez modifier le contenu du mail en précisant son titre et son message.
• Le champ "to" est automatiquement rempli avec l'adresse email enregistrée dans la fiche du client si vous ne précisez rien.
• Les champs "cc" et "bcc" sont automatiquement remplis avec les adresses que vous avez renseignées dans la page Paramètres / Email de votre compte si vous ne précisez rien.

Si vous avez définit un modèle d'envoi, ce modèle est utilisé pour générer le mail. Vous pouvez modifier le contenu du mail en précisant son titre et son message.

Remarques

• Cette fonctionnalité n'est accessible que si vous avez configuré votre propre serveur SMTP dans l'onglet "Paramètres" / "Email" de votre entreprise

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 '{
  "to": "machin@test.com",
  "cc": "bidule@test.com",
  "bcc": "boss@test.com",
  "subject": "Votre devis",
  "message": "Comme convenu, veuillez trouver ci-joint le devis pour nos travaux."
  }' \
  "https://www.facturation.pro/firms/FIRM_ID/emails.json?bill_id=ID"

Réponse

Status: 201 Created