Référence API

Présentation

L'API Check-in ARTISAN vous permet d'intégrer votre entreprise de terrain à votre propre site web ou à des applications externes. Que vous souhaitiez afficher votre profil entreprise, synchroniser vos données clients et chantiers, ou exporter vos factures vers votre logiciel de comptabilité, l'API vous donne un accès programmatique complet à vos données.

Principaux cas d'usage :

• Afficher les informations de votre entreprise sur votre propre site web.
• Créer un portail client personnalisé.
• Exporter les données de visites terrain et de facturation vers votre logiciel de comptabilité.
• Automatiser des flux de travail avec d'autres outils métiers.

URL de base

Toutes les requêtes API sont adressées à :

https://checkinartisan.app/api/v1/

Toutes les réponses sont au format JSON. Les dates et horodatages utilisent le format ISO 8601.

Authentification

La plupart des endpoints de l'API nécessitent une authentification via un jeton Bearer. Vous générez ces jetons depuis le panneau d'administration, sous Compte Check-in ARTISAN > Jetons API.

Incluez le jeton dans l'en-tête Authorization de chaque requête authentifiée :

Authorization: Bearer votre-jeton-api-ici

Chaque jeton est rattaché à une seule entreprise. Vous pouvez créer plusieurs jetons pour la même entreprise (par exemple, un par intégration).

Bonnes pratiques de sécurité :

• Traitez les jetons API comme des mots de passe. Ne les incluez jamais dans le code source.
• Utilisez un jeton par intégration pour pouvoir révoquer individuellement les accès.
• Révoquez les jetons inutilisés immédiatement.

Endpoints publics

Ces endpoints ne nécessitent aucune authentification. Ils sont conçus pour une intégration sur des sites publics.

GET /api/v1/companies/{slug}

Retourne le profil public d'une entreprise.

Paramètres : {slug} est l'identifiant unique de votre entreprise (visible dans l'URL de votre espace d'administration).

Réponse :

{
  "data": {
    "slug": "swift-plumbing",
    "name": "Swift Plumbing & Co.",
    "description": "Plomberie professionnelle pour particuliers et professionnels.",
    "phone": "+33 1 23 45 67 89",
    "mobile": null,
    "email": "contact@swiftplumbing.fr",
    "website": "https://swiftplumbing.fr",
    "address": "12 Rue des Artisans",
    "address2": null,
    "zip_code": "75001",
    "city": "Paris",
    "country": "FR",
    "opening_hours": { "monday": "8:00-18:00" },
    "social": {
      "facebook": null,
      "instagram": "https://instagram.com/swiftplumbing",
      "twitter": null,
      "youtube": null
    },
    "locale": "fr",
    "currency": "EUR",
    "timezone": "Europe/Paris"
  }
}

Endpoints authentifiés

Tous les endpoints ci-dessous nécessitent un jeton Bearer valide dans l'en-tête Authorization.

GET /api/v1/company

Retourne le profil complet de l'entreprise associée au jeton API, y compris le plan d'abonnement actif.

Réponse : identique à l'endpoint public, avec en plus un champ "plan" ("free", "solo" ou "pro").

Clients

GET /api/v1/customers

Liste tous les clients de votre entreprise.

Paramètres de requête :

Réponse :

{
  "data": [
    {
      "id": 1,
      "first_name": "Marie",
      "last_name": "Dupont",
      "full_name": "Marie Dupont",
      "email": "marie@exemple.fr",
      "phone": "+33 6 12 34 56 78",
      "mobile": null,
      "address": "12 Rue des Artisans",
      "address2": null,
      "zip_code": "75001",
      "city": "Paris",
      "country": "FR",
      "notes": null,
      "send_sms": true,
      "is_walk_in": false,
      "created_at": "2026-01-15T10:30:00+01:00",
      "updated_at": "2026-01-15T10:30:00+01:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 25,
    "total": 72
  }
}

POST /api/v1/customers

Crée un nouveau client.

Corps de la requête :

{
  "first_name": "Marie",
  "last_name": "Dupont",
  "email": "marie@exemple.fr",
  "phone": "+33 6 12 34 56 78",
  "mobile": "+33 7 98 76 54 32",
  "address": "12 Rue des Artisans",
  "address2": "Apt 3B",
  "zip_code": "75001",
  "city": "Paris",
  "country": "FR",
  "notes": "Préfère les rendez-vous le matin.",
  "send_sms": true
}

Réponse (201) : le client créé (mêmes champs que la liste).

GET /api/v1/customers/{id}

Récupère un client avec ses chantiers.

Réponse : mêmes champs que la liste, avec en plus un tableau jobs :

{
  "data": {
    "id": 1,
    "first_name": "Marie",
    "last_name": "Dupont",
    "full_name": "Marie Dupont",
    "email": "marie@exemple.fr",
    "phone": "+33 6 12 34 56 78",
    "mobile": null,
    "address": "12 Rue des Artisans",
    "address2": null,
    "zip_code": "75001",
    "city": "Paris",
    "country": "FR",
    "notes": null,
    "send_sms": true,
    "is_walk_in": false,
    "created_at": "2026-01-15T10:30:00+01:00",
    "updated_at": "2026-01-15T10:30:00+01:00",
    "jobs": [
      { "id": 12, "title": "Réparation plomberie salle de bain" }
    ]
  }
}

PUT /api/v1/customers/{id}

Met à jour un client. Envoyez uniquement les champs à modifier. Accepte les mêmes champs que POST /api/v1/customers, tous optionnels.

DELETE /api/v1/customers/{id}

Supprime un client. Retourne 204 No Content.

Chantiers

GET /api/v1/jobs

Liste tous les chantiers de votre entreprise.

Paramètres de requête :

Réponse :

{
  "data": [
    {
      "id": 12,
      "customer_id": 1,
      "job_type_id": 3,
      "title": "Réparation plomberie salle de bain",
      "description": "Remplacement mitigeur et rejointement baignoire.",
      "address": "12 Rue des Artisans, Paris",
      "status": "in_progress",
      "created_at": "2026-02-01T09:00:00+01:00",
      "updated_at": "2026-02-10T14:30:00+01:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 25,
    "total": 47
  }
}

POST /api/v1/jobs

Crée un nouveau chantier.

Réponse (201) : le chantier créé.

GET /api/v1/jobs/{id}

Récupère un chantier avec le client, le type de travaux et le nombre de visites terrain.

Réponse :

{
  "data": {
    "id": 12,
    "customer_id": 1,
    "job_type_id": 3,
    "title": "Réparation plomberie salle de bain",
    "description": "Remplacement mitigeur et rejointement baignoire.",
    "address": "12 Rue des Artisans, Paris",
    "status": "in_progress",
    "created_at": "2026-02-01T09:00:00+01:00",
    "updated_at": "2026-02-10T14:30:00+01:00",
    "customer": {
      "id": 1,
      "full_name": "Marie Dupont"
    },
    "job_type": {
      "id": 3,
      "name": "Plomberie"
    },
    "site_visits_count": 2
  }
}

Le champ job_type.name est retourné dans la langue de l'entreprise (fr ou en).

PUT /api/v1/jobs/{id}

Met à jour un chantier. Envoyez uniquement les champs à modifier. Accepte job_type_id, title, description, address et status.

DELETE /api/v1/jobs/{id}

Supprime un chantier. Retourne 204 No Content.

Visites terrain

GET /api/v1/site-visits

Liste les visites terrain de votre entreprise.

Paramètres de requête :

Réponse :

{
  "data": [
    {
      "id": 7,
      "job_id": 12,
      "customer_id": 1,
      "team_member_id": 2,
      "scheduled_at": "2026-03-20T09:00:00+01:00",
      "duration_minutes": 120,
      "status": "scheduled",
      "notes": "Le client sera présent dès 9h.",
      "created_at": "2026-03-01T11:00:00+01:00",
      "updated_at": "2026-03-01T11:00:00+01:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 5
  }
}

POST /api/v1/site-visits

Crée une nouvelle visite terrain.

Réponse (201) : la visite terrain créée.

GET /api/v1/site-visits/{id}

Récupère une visite terrain avec les détails du chantier, du client et du technicien.

Réponse :

{
  "data": {
    "id": 7,
    "job_id": 12,
    "customer_id": 1,
    "team_member_id": 2,
    "scheduled_at": "2026-03-20T09:00:00+01:00",
    "duration_minutes": 120,
    "status": "scheduled",
    "notes": "Le client sera présent dès 9h.",
    "created_at": "2026-03-01T11:00:00+01:00",
    "updated_at": "2026-03-01T11:00:00+01:00",
    "job": {
      "id": 12,
      "title": "Réparation plomberie salle de bain"
    },
    "customer": {
      "id": 1,
      "full_name": "Marie Dupont"
    },
    "team_member": {
      "id": 2,
      "name": "Jean Martin"
    }
  }
}

PUT /api/v1/site-visits/{id}

Met à jour une visite terrain. Envoyez uniquement les champs à modifier. Accepte scheduled_at, duration_minutes, notes, status et team_member_id.

DELETE /api/v1/site-visits/{id}

Supprime une visite terrain. Retourne 204 No Content.

Factures

Les factures utilisent un système de numérotation séquentielle immuable. Pour garantir l'intégrité de l'audit, les factures ne peuvent pas être modifiées ni supprimées via l'API.

GET /api/v1/invoices

Liste les factures de votre entreprise.

Paramètres de requête :

Réponse :

{
  "data": [
    {
      "id": 42,
      "invoice_number": "FA260200042",
      "customer_id": 1,
      "paid": true,
      "total_with_tax": 180.00,
      "notes": "Merci pour votre confiance !",
      "created_at": "2026-02-15T10:00:00+01:00",
      "updated_at": "2026-02-15T10:00:00+01:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 25,
    "total": 38
  }
}

GET /api/v1/invoices/{id}

Récupère une facture avec ses lignes et les coordonnées du client.

Réponse :

{
  "data": {
    "id": 42,
    "invoice_number": "FA260200042",
    "customer_id": 1,
    "paid": true,
    "total_with_tax": 180.00,
    "notes": "Merci pour votre confiance !",
    "created_at": "2026-02-15T10:00:00+01:00",
    "updated_at": "2026-02-15T10:00:00+01:00",
    "customer": {
      "id": 1,
      "full_name": "Marie Dupont",
      "email": "marie@exemple.fr"
    },
    "lines": [
      {
        "id": 101,
        "item_id": 5,
        "description": "Réparation plomberie - salle de bain",
        "quantity": 1,
        "unit_price_with_tax": 180.00,
        "discount_percent": 0,
        "line_total_with_tax": 180.00
      }
    ]
  }
}

POST /api/v1/invoices

Crée une nouvelle facture. Le numéro de facture est attribué automatiquement.

Corps de la requête :

{
  "customer_id": 1,
  "paid": false,
  "notes": "Merci pour votre confiance !",
  "lines": [
    {
      "item_id": 5,
      "description": "Réparation plomberie - salle de bain",
      "quantity": 1,
      "price_with_tax": 180.00,
      "discount": 0
    }
  ]
}

*Obligatoire uniquement lorsque le tableau lines est présent.

Réponse (201) : la facture créée au même format que GET /api/v1/invoices/{id}.

Réponses d'erreur

L'API retourne des codes HTTP standards. Les réponses d'erreur incluent un corps JSON avec un champ error et, pour les erreurs de validation, un champ messages.

Exemple d'erreur de validation :

{
  "error": "Validation failed.",
  "messages": {
    "first_name": ["The first name field is required."],
    "email": ["The email must be a valid email address."]
  }
}

Pagination

Tous les endpoints de liste retournent des résultats paginés avec un objet meta :

{
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 25,
    "total": 118
  }
}

Utilisez les paramètres page et per_page pour naviguer dans les résultats.

Premiers pas

1. Connectez-vous à votre espace d'administration Check-in ARTISAN.
2. Allez dans Compte Check-in ARTISAN > Jetons API.
3. Cliquez sur Générer un jeton, donnez-lui un nom et copiez le jeton affiché.
4. Utilisez ce jeton dans l'en-tête Authorization: Bearer de toutes vos requêtes authentifiées.
5. Testez avec une requête simple vers /api/v1/company pour vérifier que votre jeton fonctionne.

Support

Pour toute question sur l'intégration de l'API, contactez-nous via la page Contact ou consultez la documentation complète.