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/ID.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": ID,
"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/ID.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/ID.json"
Réponse
Status: 200 OK
Archiver
POST /firms/FIRM_ID/customers/ID/archive.json
Archive le client identifié par son ID, ce qui permet de le masquer de la liste des clients.
Requête
curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
-X POST \
"https://www.facturation.pro/firms/FIRM_ID/customers/ID/archive.json"
Réponse
Status: 200 OK
Désarchiver
POST /firms/FIRM_ID/customers/ID/unarchive.json
Restaure le client archivé, identifié par son ID. Ce client peut à nouveau être facturé et redevient visible dans la liste des clients.
Requête
curl -i -S -u login:password -H 'User-Agent: MonApp (moi@exemple.com)' \
-X POST \
"https://www.facturation.pro/firms/FIRM_ID/customers/ID/unarchive.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/ID/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/ID/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 de facturation | 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 |
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 |
sepa_signature_on |
Date de signature du mandat SEPA
Lecture autorisée uniquement avec la clé API de l'administrateur de l'entreprise |
date | 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
language
fr : Français
en : Anglais
es : Espagnol
nl : Néerlandais
pay_before
0 : A réception
cash : Comptant
15 : 15 jours nets, à compter de la livraison
30 : 30 jours nets, à compter de la livraison
45 : 45 jours nets, à compter de la livraison
60 : 60 jours nets, à compter de la livraison
7fm : 7 jours fin de mois, à compter de la livraison
30fm : 30 jours fin de mois, à compter de la livraison
45fm : 45 jours fin de mois, à compter de la livraison
0fm10 : fin de mois le 10, à compter de la livraison
0fm20 : fin de mois le 20, à compter de la livraison
30fm10 : 30 jours fin de mois le 10, à compter de la livraison
30fm20 : 30 jours fin de mois le 20, à compter de la livraison
15-inv : 15 jours nets, à compter de la facturation
30-inv : 30 jours nets, à compter de la facturation
45-inv : 45 jours nets, à compter de la facturation
60-inv : 60 jours nets, à compter de la facturation
7fm-inv : 7 jours fin de mois, à compter de la facturation
30fm-inv : 30 jours fin de mois, à compter de la facturation
45fm-inv : 45 jours fin de mois, à compter de la facturation
0fm10-inv : fin de mois le 10, à compter de la facturation
0fm20-inv : fin de mois le 20, à compter de la facturation
30fm10-inv : 30 jours fin de mois le 10, à compter de la facturation
30fm20-inv : 30 jours fin de mois le 20, à compter de la facturation
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
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
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
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
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
SHP : Livre
GIP : Livre de Gibraltar
FKP : Livre des Îles Malouines
LBP : Livre libanaise
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
TOP : Pa'anga des Tonga
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
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
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
VUV : Vatu du Vanuatu
KPW : Won nord-coréen
KRW : Won sud-coréen
PLN : Zloty polonais