Liste des clients

GET /firms/FIRM_ID/customers.json

liste des clients, par groupe de 30 résultats.

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
  • company : recherche partielle sur le nom de société
  • last_name : recherche partielle sur le nom de famille
  • email : recherche partielle sur l'email
  • with_sepa : par défaut, les données SEPA ne sont pas exportées. Seule la clé API de l'administrateur de la société permet d'exporter les données SEPA, et vous devez explicitement demander ces informations en utilisant la valeur 1.
  • mode : en l'absence de précision, le système retourne uniquement les clients actifs. Vous pouvez utiliser les valeurs suivantes pour retourner différents groupes de clients:
    • all : retourne tous les clients (actifs ou archivés)
    • company : retourne uniquement les professionnels actifs
    • individual : retourne uniquement les particuliers actifs
    • archived : retourne uniquement les clients archivés

Tri

Par défaut, les clients sont triés par ordre croissant de nom mnémotechnique.
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
    • last_invoice : tri par date de dernière facture au client
    • last_paid : tri par date de dernier paiement du client
    • created : tri par date de création
    • updated : tri par date de dernière modification

Requête

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

Réponse

[{
  "account_code": "411PANDORA",
  "api_custom": null,
  "api_id": null,
  "category_id": 4847,
  "city": "Neuilly-sur-Seine",
  "civility": null,
  "company_name": "pandora",
  "country": "FR",
  "currency": "EUR",
  "default_vat": null,
  "discount": null,
  "email": null,
  "fax": "",
  "first_name": "",
  "id": 180371,
  "individual": false,
  "language": null,
  "last_invoiced_on": "2012-07-28",
  "last_name": "",
  "mobile": "",
  "pay_before": "30fm",
  "penalty": null,
  "phone": "",
  "short_name": "pandora",
  "siret": "53165179200016",
  "street": "171 avenue Charles de Gaulle",
  "validity": null,
  "vat_exemption": null,
  "vat_number": "",
  "website": null,
  "zip_code": "92200"
}, {
  "account_code": "411SPOTIFY",
  "api_custom": null,
  "api_id": null,
  "category_id": null,
  "city": "Paris",
  "civility": null,
  "company_name": "spotify",
  "country": "FR",
  "currency": "EUR",
  "default_vat": null,
  "discount": null,
  "email": null,
  "fax": "",
  "first_name": "",
  "id": 180369,
  "individual": false,
  "language": null,
  "last_invoiced_on": "2013-02-28",
  "last_name": "",
  "mobile": "",
  "pay_before": "30",
  "penalty": null,
  "phone": "",
  "short_name": "spotify",
  "siret": null,
  "street": "11 bis rue christophe colomb",
  "validity": null,
  "vat_exemption": null,
  "vat_number": "",
  "website": null,
  "zip_code": "75008"
}]

Détail d'un client

GET /firms/FIRM_ID/customers/ID.json

Affiche le détail du client n° ID

Paramètres optionnels :

  • with_sepa: par défaut, les données SEPA ne sont pas retournée par l'API. Seule la clé API de l'administrateur de la société permet d'accéder aux données SEPA, et vous devez explicitement demander ces informations en utilisant la valeur 1. Lorsque vous demandez à accéder aux informations SEPA avec une clé API autre que celle de l'administrateur du compte, le système retourne une erreur de type 403

Requête

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

Réponse

{
  "account_code": "411PANDORA",
  "api_custom": null,
  "api_id": null,
  "category_id": 4847,
  "city": "Neuilly-sur-Seine",
  "civility": null,
  "company_name": "pandora",
  "country": "FR",
  "currency": "EUR",
  "default_vat": null,
  "discount": null,
  "email": null,
  "fax": "",
  "first_name": "",
  "id": 180371,
  "individual": false,
  "language": null,
  "last_invoiced_on": "2012-07-28",
  "last_name": "",
  "mobile": "",
  "pay_before": "30fm",
  "penalty": null,
  "phone": "",
  "short_name": "pandora",
  "siret": "53165179200016",
  "street": "171 avenue Charles de Gaulle",
  "validity": null,
  "vat_exemption": null,
  "vat_number": "",
  "website": null,
  "zip_code": "92200"
}

Créer un client

POST /firms/FIRM_ID/customers.json

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

Remarque

Par défaut, en l'absence d'indication spécifique, chaque client créé est de type professionnel, et si vous n'avez pas indiqué de nom d'entreprise, celui ci est automatiquement dérivé du prénom et du nom du client. Lorsque vous créez un client particulier, vous devez donc le préciser en affectant la valeur true au champ individual.

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 '{"company_name":"A small company","individual":false}' \
 https://www.facturation.pro/firms/FIRM_ID/customers.json

Réponse

Status: 201 Created
Location: /firms/FIRM_ID/customers/180374.json

{
  "account_code": "411ASMALLCO",
  "api_custom": null,
  "api_id": null,
  "category_id": null,
  "city": null,
  "civility": null,
  "company_name": "A small company",
  "country": null,
  "currency": "EUR",
  "default_vat": null,
  "discount": null,
  "email": null,
  "fax": null,
  "first_name": null,
  "id": 180374,
  "individual": false,
  "language": null,
  "last_invoiced_on": null,
  "last_name": null,
  "mobile": null,
  "pay_before": null,
  "penalty": null,
  "phone": null,
  "short_name": "A small company",
  "siret": null,
  "street": null,
  "validity": null,
  "vat_exemption": null,
  "vat_number": null,
  "website": null,
  "zip_code": null
}

Modifier un client

PATCH /firms/FIRM_ID/customers/ID.json

Mise à jour d'un client existant.

Requête

curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
 -H 'Content-Type: application/json; charset=utf-8' \
 -X PATCH \
 -d '{"company_name":"A big company","email":"boss@bigcompany.com"}' \
 https://www.facturation.pro/firms/FIRM_ID/customers/180371.json

Réponse

Status: 200 OK

Supprimer un client

DELETE /firms/FIRM_ID/customers/ID.json

Supprime le client identifié par son ID, ainsi que tous les devis associés à ce client.
Un client ne peut être supprimé que s'il n'a jamais été facturé.

Requête

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

Réponse

Status: 200 OK

Devis

GET /firms/FIRM_ID/customers/ID/quotes.json

liste des devis du client ID, par groupe de 30 résultats.

Requête

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

Réponse

Cette fonction est un raccourci vers la liste des devis, liste restreinte aux devis du client ID.
La réponse est donc une redirection vers la requête à exécuter sur la liste des devis.

Status: 302 Redirected
Location: /firms/FIRM_ID/quotes.json?customer_id=180371

Factures

GET /firms/FIRM_ID/customers/ID/invoices.json

liste des factures du client ID, par groupe de 30 résultats.

Requête

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

Réponse

Cette fonction est un raccourci vers la liste des factures, liste restreinte aux factures du client ID.
La réponse est donc une redirection vers la requête à exécuter sur la liste des factures.

Status: 302 Redirected
Location: /firms/{FIRM_ID}/invoices.json?customer_id=180371

Liste des champs

Champs Libellé Type Accès
id Identifiant int(11) lecture seule
company_name Société string(255) lecture/écriture
civility Civilité string(255) lecture/écriture
first_name Prénom string(255) lecture/écriture
last_name Nom string(255) lecture/écriture
short_name Nom mnémotechnique string(255) lecture/écriture
street Adresse string(255) lecture/écriture
city Ville string(255) lecture/écriture
zip_code Code postal string(20) lecture/écriture
country Pays
Code ISO à 2 lettres du pays, en majuscules
string(2) lecture/écriture
phone Téléphone string(255) lecture/écriture
fax Fax string(255) lecture/écriture
email Email text lecture/écriture
mobile Mobile string(255) lecture/écriture
website Site web string(255) lecture/écriture
notes Notes internes text lecture/écriture
vat_number N° TVA string(30) lecture/écriture
siret Siret string(100) lecture/écriture
category_id Catégorie int(11) lecture/écriture
account_code Compte client string(11) lecture/écriture
accounting_entry Compte d'imputation string(8) lecture/écriture
created_at Créé le datetime(3) lecture seule
updated_at Modifié le datetime(3) lecture seule
sepa_iban IBAN
Lecture autorisée uniquement avec la clé API de l'administrateur de l'entreprise
string(34) lecture/écriture
sepa_bic BIC
Lecture autorisée uniquement avec la clé API de l'administrateur de l'entreprise
string(11) lecture/écriture
sepa_rum RUM
Lecture autorisée uniquement avec la clé API de l'administrateur de l'entreprise
string(35) lecture/écriture
api_id API - Référence numérique libre bigint(20) lecture/écriture
api_custom API - Texte libre string(255) lecture/écriture
individual Particulier boolean lecture/écriture
reference Référence client string(255) lecture/écriture
penalty Pénalités de retard decimal(8,3) lecture/écriture
discount Taux d'escompte decimal(8,3) lecture/écriture
pay_before Délai de paiement string(255) lecture/écriture
validity Durée de validité d'un devis int(11) lecture/écriture
last_invoiced_on Dernière facture le date lecture seule
last_paid_on Dernier règlement le date lecture seule
currency Devise string(3) lecture/écriture
language Langue des PDF string(255) lecture/écriture
default_vat Taux de TVA decimal(8,3) lecture/écriture
vat_country Code pays des taux TVA à appliquer string(3) lecture/écriture
vat_exemption Motif d'exonération de TVA string(255) lecture/écriture
field1 Champ libre 1 string(255) lecture/écriture
field2 Champ libre 2 string(255) lecture/écriture
field3 Champ libre 3 string(255) lecture/écriture
field4 Champ libre 4 string(255) lecture/écriture
field5 Champ libre 5 string(255) lecture/écriture
soft_deleted Enregistrement marqué comme à supprimer boolean lecture seule
hard_delete_on Date définitive de la suppression date lecture seule

Champs utilisant des valeurs spécifiques

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

language

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

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
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
MRO : Ouguiya mauritanien
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