Référence API

Plan Business

Intégrez CleverInvo dans votre flux de travail. Gérez les clients, créez des factures et téléchargez des PDF de manière programmatique.

Authentification

Toutes les requêtes API nécessitent un token Bearer. Créez une clé API depuis votre tableau de bord, puis incluez-la dans l'en-tête Authorization.

curl -X GET https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer cinv_your_api_key"

Clients

GET/api/v1/clients

Lister tous les clients actifs. Supporte la pagination et la recherche.

Réponse
{
  "data": [
    {
      "id": "clx...",
      "name": "Acme Corp",
      "email": "[email protected]",
      "address": "123 Main St, New York, NY 10001",
      "taxId": "US-123456789",
      "phone": "+1-555-0100",
      "notes": "Net 30 terms",
      "isActive": true,
      "createdAt": "2024-01-15T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/clients

Créer un nouveau client. Soumis à la limite de clients de votre plan.

Corps de la requête
{
  "name": "Acme Corp",
  "email": "[email protected]",
  "address": "123 Main St, New York, NY 10001",
  "taxId": "US-123456789",
  "phone": "+1-555-0100",
  "notes": "Net 30 terms"
}
Réponse
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
GET/api/v1/clients/:id

Obtenir un client unique par ID.

Réponse
{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}
PUT/api/v1/clients/:id

Mettre à jour un client. Tous les champs peuvent être modifiés.

Corps de la requête
{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+1-555-0200"
}
Réponse
{
  "data": {
    "id": "clx...",
    "name": "Acme Corporation",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0200",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
}
DELETE/api/v1/clients/:id

Suppression douce d'un client. Définit isActive à false. Les clients avec des factures existantes ne peuvent pas être supprimés définitivement.

Réponse
204 No Content

Factures

GET/api/v1/invoices

Lister les factures. Supporte la pagination, la recherche et le filtrage par clientId ou statut.

Réponse
{
  "data": [
    {
      "id": "clx...",
      "clientId": "clx...",
      "invoiceNumber": "INV-0001",
      "currency": "USD",
      "issueDate": "2024-06-01",
      "dueDate": "2024-07-01",
      "subtotal": 5000.00,
      "taxTotal": 500.00,
      "discountTotal": 0,
      "total": 5500.00,
      "status": "SENT",
      "createdAt": "2024-06-01T00:00:00.000Z",
      "client": {
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
POST/api/v1/invoices

Créer une facture et générer automatiquement le PDF. Soumis aux limites du plan.

Corps de la requête
{
  "clientId": "clx...",
  "invoiceNumber": "INV-0042",
  "currency": "USD",
  "issueDate": "2024-06-01",
  "dueDate": "2024-07-01",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Thank you for your business",
  "terms": "Payment due within 30 days"
}
Réponse
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 5500.00,
    "status": "DRAFT"
  }
}
GET/api/v1/invoices/:id

Obtenir les détails complets de la facture, y compris les éléments de ligne et les informations du client.

Réponse
{
  "data": {
    "id": "clx...",
    "clientId": "clx...",
    "invoiceNumber": "INV-0042",
    "currency": "USD",
    "issueDate": "2024-06-01",
    "dueDate": "2024-07-01",
    "lineItems": [
      {
        "description": "Web Development",
        "quantity": 40,
        "unitPrice": 125.00,
        "amount": 5000.00,
        "taxRate": 10
      }
    ],
    "subtotal": 5000.00,
    "taxTotal": 500.00,
    "discountTotal": 0,
    "total": 5500.00,
    "status": "SENT",
    "notes": "Thank you for your business",
    "terms": "Payment due within 30 days",
    "sentViaEmail": true,
    "sentAt": "2024-06-01T12:00:00.000Z",
    "paidAt": null,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "client": {
      "name": "Acme Corp",
      "email": "[email protected]"
    }
  }
}
PUT/api/v1/invoices/:id

Mettre à jour une facture. Seules les factures brouillon peuvent être modifiées.

Corps de la requête
{
  "dueDate": "2024-07-15",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 50,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Updated scope"
}
Réponse
{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 6875.00,
    "status": "DRAFT"
  }
}
DELETE/api/v1/invoices/:id

Supprimer définitivement une facture et son PDF généré.

Réponse
204 No Content
GET/api/v1/invoices/:id/pdf

Télécharger la facture au format PDF. Retourne un PDF binaire avec l'en-tête Content-Disposition.

Réponse
Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-0042.pdf"

<binary PDF data>

Pagination

Les endpoints de liste acceptent les paramètres de requête suivants :

ParamètrePar défautDescription
page1Numéro de page (min : 1)
limit20Éléments par page (1–100)
search—Filtrer par nom, e-mail ou numéro de facture (max 255 caractères)
clientId—Filtrer les factures par client (factures uniquement)
status—Filtrer par statut : DRAFT, SENT, VIEWED, PAID, PARTIALLY_PAID, OVERDUE
GET /api/v1/clients?page=2&limit=10&search=acme

Erreurs

L'API retourne des codes de statut HTTP standard. Les réponses d'erreur incluent un corps JSON avec un champ error.

StatutDescription
400Bad Request — paramètres invalides ou champs requis manquants
401Unauthorized — clé API invalide ou manquante
403Forbidden — limite du plan atteinte (clients, factures ou fonctionnalité)
404Not Found — la ressource n'existe pas ou n'est pas accessible
429Too Many Requests — limite de débit dépassée
500Internal Server Error — échec inattendu, réessayez plus tard
{
  "error": "Missing required field: name"
}

Limites de débit

Les requêtes API sont limitées à 120 requêtes par minute par clé API.

Lorsque la limite est dépassée, les requêtes retournent 429 Too Many Requests. Attendez avant de réessayer.