API REST · Intégrations

Documentation API Kolirys

Automatisez la facturation et la gestion clients depuis votre ERP, votre site ou vos scripts. Authentification par jetons, réponses JSON, sans système de crédits.

Vue d'ensemble

L'API Kolirys expose un point d'entrée unique en POST. Chaque action est déclenchée par le nom de commande dans l'URL. Les réponses sont toujours renvoyées en JSON.

URL de base

https://www.kolirys.fr/api/{TOKEN_USER}/{TOKEN_SECRET}/{COMMAND}

Méthode

POST

Content-Type

application/json

Commandes disponibles

6 — clients, documents, PDF

Authentification

Deux jetons privés identifient votre compte. Ils sont disponibles dans votre espace membre Kolirys : Mon compte → API (réservé aux comptes éligibles à l'API).

TOKEN_USER et TOKEN_SECRET doivent être transmis dans l'URL. Ne les exposez jamais côté client (navigateur, application mobile publique). Appelez l'API depuis votre serveur.

Format des requêtes

Le corps de la requête contient un objet JSON avec une clé options. Selon la commande, options est soit un identifiant numérique, soit une chaîne JSON sérialisée.

Exemple — requête avec options objet (GenerateDocument, CreateCustomer…)

{
  "options": "{\"typeDocument\":\"INVOICE\",\"lines\":[{\"TITLE\":\"Prestation\",\"PRICE_UNIT\":100,\"QUANTITY\":1,\"VAT\":20}]}"
}

Exemple — requête avec identifiant (DeleteCustomer, GetDocumentPDF)

{
  "options": 12345
}

Exemple cURL (PHP)

// Configuration
$TOKEN_USER   = 'VOTRE_TOKEN_USER';
$TOKEN_SECRET = 'VOTRE_TOKEN_SECRET';
$COMMAND      = 'GetCustomers';
$OPTIONS      = [];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL            => "https://www.kolirys.fr/api/{$TOKEN_USER}/{$TOKEN_SECRET}/{$COMMAND}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => json_encode([
        'options' => json_encode($OPTIONS)
    ]),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
]);

$response = json_decode(curl_exec($curl), true);
curl_close($curl);

if ($response['Success']) {
    // Traitement OK
} else {
    // $response['ErrorMessage']
}

Réponses & erreurs

Toutes les commandes renvoient la même enveloppe JSON. En cas de succès, Data contient le résultat métier.

Réponse succès

{
  "Success": true,
  "ErrorMessage": null,
  "Data": { ... }
}

Réponse erreur

{
  "Success": false,
  "ErrorMessage": "Les jetons sont invalides.",
  "ErrorType": "INVALID_TOKEN"
}
ErrorType Signification
INVALID_TOKENJetons incorrects ou inconnus.
NO_SUBSCRIBECompte non éligible à l'API.
NO_OPTIONSParamètre options manquant.
REQUEST_ERRORRequête mal formée ou commande inconnue.
REQUEST_GENERATE_DOCUMENT_FAILEDParamètres document incomplets.
REQUEST_GENERATE_DOCUMENT_TYPE_FAILEDtypeDocument doit être INVOICE, QUOTATION ou CREDIT.
REQUEST_CREATE_CUSTOMER_FAILEDChamps client obligatoires manquants.
CUSTOMER_NO_EXISTClient introuvable pour ce compte.
DOCUMENT_NO_EXISTDocument introuvable ou non validé.
POST

GenerateDocument

Crée un devis, une facture ou un avoir avec ses lignes. Le document est enregistré en brouillon sauf si vous demandez la finalisation.

Paramètres options

ChampTypeDescription
typeDocument requisstringINVOICE (facture), QUOTATION (devis), CREDIT (avoir)
numberDocumentstringNuméro personnalisé (facultatif)
customText1 / customText2stringTextes libres sur le document
customerIDintID d'un client existant
finalizeDocumentbooltrue pour valider et générer le PDF (défaut : false)
sendToCustomerboolEnvoi e-mail au client si document finalisé
lines[]arrayLignes du document (voir ci-dessous)

Champs d'une ligne (lines[])

ChampDescription
TITLELibellé / description
REFERENCERéférence article
PRICE_UNITPrix unitaire HT
QUANTITYQuantité
DISCOUNTRemise en %
VATTaux de TVA en %
TYPE1 = prestation de service · 2 = vente de marchandise

Exemple

{
  "typeDocument": "INVOICE",
  "numberDocument": "F-2026-0042",
  "customerID": 23,
  "finalizeDocument": false,
  "lines": [
    {
      "TITLE": "Main d'œuvre peinture",
      "REFERENCE": "MO-001",
      "PRICE_UNIT": 34.95,
      "QUANTITY": 12,
      "DISCOUNT": 10,
      "VAT": 20,
      "TYPE": 1
    }
  ]
}

Réponse Data

{
  "UrlDocument": "https://www.kolirys.fr/document/create/invoice",
  "ID": 98765,
  "Generated": false,
  "Sended": false,
  "ErrorsGeneration": null
}
POST

CreateCustomer

Crée un client particulier ou professionnel dans votre carnet d'adresses Kolirys.

Paramètres options

ChampDescription
typeCustomer requis1 = particulier · 2 = professionnel
firstName / lastNameObligatoires si particulier
companyName / companySiretObligatoires si professionnel
mail, phone, adress, zip, city, countryFacultatifs
tvaNumberNuméro de TVA intracommunautaire (facultatif)

Exemple — client professionnel

{
  "typeCustomer": 2,
  "companyName": "Acme SARL",
  "companySiret": "12345678900012",
  "mail": "contact@acme.fr",
  "city": "Lyon"
}

Réponse Data

{ "ID_Customer": 456 }
POST

GetCustomers

Liste tous vos clients, avec filtres de recherche optionnels (correspondance partielle).

Paramètres options facultatif

Filtres disponibles : firstName, lastName, companyName, companySiret, mail, phone, adress, zip, city, country, typeCustomer, tvaNumber.

Exemple — recherche par e-mail

{ "mail": "@acme.fr" }

Réponse Data

{
  "Customers": [
    {
      "id": 456,
      "firstName": null,
      "lastName": null,
      "companyName": "Acme SARL",
      "mail": "contact@acme.fr",
      "typeCustomer": 2
    }
  ]
}
POST

UpdateCustomer

Met à jour les informations d'un client existant.

Paramètres options

ChampDescription
customer_id requisIdentifiant du client à modifier
Autres champs clientSeuls les champs fournis sont mis à jour

Exemple

{
  "customer_id": 456,
  "phone": "06 12 34 56 78",
  "city": "Paris"
}

Réponse

{ "Success": true, "Data": null }
POST

DeleteCustomer

Supprime définitivement un client à partir de son identifiant.

Paramètres options

Identifiant numérique du client (ex. : 456).

Exemple — corps de requête

{ "options": 456 }
POST

GetDocumentPDF

Retourne l'URL publique du PDF d'un document déjà validé.

Paramètres options

Identifiant numérique du document (ex. : 98765).

Réponse Data

{
  "URL": "https://www.kolirys.fr/uploads/documents/...",
  "TIMESTAMP_DOCUMENT": "2026-06-11",
  "NUMBER_DOCUMENT": "F-2026-0042",
  "TYPE_DOCUMENT": "invoice"
}