Answer - OUI

API complète de helpdesk et de ticketing pour la gestion du support client

Introduction

L’API Answer offre une solution complète de helpdesk et de ticketing. Elle vous permet de gérer les tickets de support, les échanges avec les clients, les articles de la base de connaissances et la collaboration d’équipe via une interface RESTful.

Authentification

L’API Answer utilise des tokens JWT Bearer pour l’authentification. Obtenez un token en échangeant vos identifiants de clé d’API.

POST /v1/auth/token

Échange une clé d’API contre un token d’authentification JWT.

Corps de la requête

{
  "api_key": "your_api_key_here",
  "api_secret": "your_api_secret_here"
}

Réponse

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Déroulement de l’authentification :

Échangez votre clé d’API contre un token JWT via POST /v1/auth/token
Incluez le token dans toutes les requêtes suivantes
Les tokens expirent après la durée de vie (TTL) configurée (par défaut : 1 heure)

Limites de débit

Les requêtes d’API sont limitées en débit selon votre offre d’abonnement :

En-têtes de limite de débit : Consultez X-RateLimit-Remaining et X-RateLimit-Reset dans les réponses.

Offre	Requêtes/minute	Requêtes/jour
Gratuit	30	1,000
Starter	60	10,000
Professional	120	100,000
Enterprise	Illimité	Illimité

Contrôle de santé

GET /health

Vérifie l’état de santé de l’API et des services. Aucune authentification requise.

Réponse

{
  "status": "healthy",
  "timestamp": "2024-01-22T14:00:00Z",
  "version": "1.0.0",
  "services": {
    "database": "connected",
    "cache": "connected",
    "queue": "connected"
  }
}

Tickets

Gérez les tickets de support avec des opérations CRUD complètes, la gestion des statuts, les affectations, et plus encore.

GET /v1/tickets

Récupère une liste paginée de tickets, avec filtrage et tri facultatifs.

Paramètres

Paramètre	Type	Description
page optionnel	integer	Numéro de page (par défaut : 1)
per_page optionnel	integer	Résultats par page (par défaut : 20, max : 100)
status optionnel	string	Filtrer par statut : open, pending, resolved, closed
priority optionnel	string	Filtrer par priorité : low, medium, high, urgent
assigned_to optionnel	integer	Filtrer par ID de l’agent assigné
category_id optionnel	integer	Filtrer par ID de catégorie
search optionnel	string	Rechercher dans le sujet et le contenu
sort optionnel	string	Champ de tri : created_at, updated_at, priority
order optionnel	string	Ordre de tri : asc, desc (par défaut : desc)

Réponse

{
  "success": true,
  "data": [
    {
      "id": 1234,
      "subject": "Cannot login to my account",
      "content": "I've been trying to login but keep getting an error...",
      "status": "open",
      "priority": "high",
      "category": {
        "id": 5,
        "name": "Account Issues"
      },
      "requester": {
        "id": 101,
        "name": "John Doe",
        "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser."
      },
      "assigned_to": {
        "id": 15,
        "name": "Support Agent"
      },
      "tags": ["login", "authentication"],
      "reply_count": 3,
      "created_at": "2024-01-20T10:30:00Z",
      "updated_at": "2024-01-22T14:00:00Z",
      "first_response_at": "2024-01-20T11:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

POST /v1/tickets

Crée un nouveau ticket de support.

Paramètres

Champ	Type	Description
subject requis	string	Sujet du ticket (max : 255 caractères)
content requis	string	Description/contenu du ticket
requester_email requis	string	E-mail du demandeur du ticket
requester_name optionnel	string	Nom du demandeur
priority optionnel	string	low, medium, high, urgent (par défaut : medium)
category_id optionnel	integer	ID de la catégorie à affecter
assigned_to optionnel	integer	ID de l’agent à affecter
tags optionnel	array	Tableau de chaînes de tags
metadata optionnel	object	Objet de métadonnées personnalisées

GET /v1/tickets/{id}

Récupère un ticket avec tous ses détails, y compris les réponses et les pièces jointes.

Paramètres

Paramètre	Type	Description
id requis	integer	ID du ticket

Réponse

{
  "success": true,
  "data": {
    "id": 1234,
    "subject": "Cannot login to my account",
    "content": "I've been trying to login but keep getting an error...",
    "content_html": "<p>I've been trying to login...</p>",
    "status": "open",
    "priority": "high",
    "category": {
      "id": 5,
      "name": "Account Issues",
      "color": "#ff5722"
    },
    "requester": {
      "id": 101,
      "name": "John Doe",
      "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "avatar_url": null
    },
    "assigned_to": {
      "id": 15,
      "name": "Support Agent",
      "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser."
    },
    "watchers": [
      {"id": 16, "name": "Manager"}
    ],
    "tags": ["login", "authentication"],
    "replies": [
      {
        "id": 5001,
        "content": "Thank you for contacting us...",
        "author": {"id": 15, "name": "Support Agent"},
        "is_internal": false,
        "created_at": "2024-01-20T11:15:00Z"
      }
    ],
    "attachments": [
      {
        "id": 801,
        "filename": "screenshot.png",
        "file_size": 102400,
        "mime_type": "image/png",
        "url": "/v1/attachments/801/download"
      }
    ],
    "activity_log": [
      {
        "action": "status_changed",
        "from": "new",
        "to": "open",
        "user": {"id": 15, "name": "Support Agent"},
        "timestamp": "2024-01-20T11:00:00Z"
      }
    ],
    "metadata": {},
    "created_at": "2024-01-20T10:30:00Z",
    "updated_at": "2024-01-22T14:00:00Z",
    "first_response_at": "2024-01-20T11:15:00Z",
    "resolved_at": null
  }
}

PUT /v1/tickets/{id}

Met à jour les propriétés d’un ticket existant.

Réponse

{
  "success": true,
  "data": {
    "id": 1234,
    "status": "pending",
    "priority": "urgent",
    "updated_at": "2024-01-22T16:00:00Z"
  },
  "message": "Ticket updated successfully"
}

DELETE /v1/tickets/{id}

Supprime un ticket et toutes les données associées (réponses, pièces jointes).

Réponse

{
  "success": true,
  "message": "Ticket deleted successfully"
}

Attention : Cette action est irréversible. Envisagez d’archiver plutôt que de supprimer.

Réponses

Gérez les réponses aux tickets, y compris les notes internes et les réponses visibles par le client.

GET /v1/tickets/{ticket_id}/replies

Liste toutes les réponses d’un ticket donné.

Paramètres

Paramètre	Type	Description
include_internal	boolean	Inclure les notes internes (par défaut : true pour les agents)

Réponse

{
  "success": true,
  "data": [
    {
      "id": 5001,
      "ticket_id": 1234,
      "content": "Thank you for contacting us. We're looking into this.",
      "content_html": "<p>Thank you for contacting us...</p>",
      "is_internal": false,
      "author": {
        "id": 15,
        "name": "Support Agent",
        "type": "agent"
      },
      "attachments": [],
      "created_at": "2024-01-20T11:15:00Z"
    },
    {
      "id": 5002,
      "ticket_id": 1234,
      "content": "[Internal] Escalating to engineering team",
      "is_internal": true,
      "author": {
        "id": 15,
        "name": "Support Agent",
        "type": "agent"
      },
      "created_at": "2024-01-21T09:00:00Z"
    }
  ]
}

POST /v1/tickets/{ticket_id}/replies

Ajoute une réponse à un ticket. Il peut s’agir d’une réponse publique ou d’une note interne.

Corps de la requête

{
  "content": "Thank you for your patience. We've identified the issue and it should be resolved now.",
  "is_internal": false,
  "notify_requester": true,
  "update_status": "resolved"
}

Pièces jointes

POST /v1/tickets/{ticket_id}/attachments

Téléverse une pièce jointe sur un ticket. Utilise l’encodage multipart/form-data.

Paramètres

Champ	Type	Description
file requis	file	Fichier à téléverser (max : 10 Mo)

Réponse

{
  "success": true,
  "data": {
    "id": 802,
    "ticket_id": 1234,
    "filename": "error-log.txt",
    "original_filename": "error-log.txt",
    "file_size": 2048,
    "mime_type": "text/plain",
    "url": "/v1/attachments/802/download"
  }
}

GET /v1/attachments/{id}/download

Télécharge un fichier de pièce jointe.

Utilisateurs

Gérez les utilisateurs, y compris les clients et les agents de support.

GET /v1/users

Liste tous les utilisateurs avec des options de filtrage.

Paramètres

Paramètre	Type	Description
type	string	customer, agent, admin
search	string	Rechercher par nom ou e-mail
organization_id	integer	Filtrer par organisation

Réponse

{
  "success": true,
  "data": [
    {
      "id": 101,
      "name": "John Doe",
      "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "type": "customer",
      "organization": {
        "id": 50,
        "name": "Acme Corp"
      },
      "ticket_count": 5,
      "created_at": "2023-06-15T10:00:00Z"
    }
  ],
  "pagination": {...}
}

POST /v1/users

Crée un nouvel utilisateur.

Corps de la requête

{
  "name": "Jane Smith",
  "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
  "type": "customer",
  "organization_id": 50,
  "phone": "+1234567890",
  "metadata": {
    "company_size": "50-100"
  }
}

Organisations

Gérez les organisations clientes à des fins de regroupement et de reporting.

GET /v1/organizations

Liste toutes les organisations.

Réponse

{
  "success": true,
  "data": [
    {
      "id": 50,
      "name": "Acme Corp",
      "domain": "acme.com",
      "user_count": 15,
      "ticket_count": 42,
      "created_at": "2023-01-10T08:00:00Z"
    }
  ]
}

POST /v1/organizations

Crée une nouvelle organisation.

Corps de la requête

{
  "name": "Tech Solutions Inc",
  "domain": "techsolutions.com",
  "notes": "Enterprise customer",
  "metadata": {
    "plan": "enterprise",
    "account_manager": "John"
  }
}

Catégories

Gérez les catégories de tickets pour l’organisation et le routage.

GET /v1/categories

Liste toutes les catégories de tickets.

Réponse

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "General Inquiry",
      "slug": "general",
      "color": "#3b82f6",
      "parent_id": null,
      "ticket_count": 150
    },
    {
      "id": 5,
      "name": "Account Issues",
      "slug": "account",
      "color": "#ef4444",
      "parent_id": null,
      "ticket_count": 75
    }
  ]
}

POST /v1/categories

Crée une nouvelle catégorie.

Corps de la requête

{
  "name": "Billing",
  "slug": "billing",
  "color": "#10b981",
  "parent_id": null,
  "description": "Billing and payment related issues"
}

Webhooks

Configurez des webhooks pour recevoir des notifications en temps réel sur les événements des tickets.

GET /v1/webhooks

Liste tous les webhooks configurés.

Réponse

{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://example.com/webhooks/answer",
      "events": ["ticket.created", "ticket.updated", "reply.created"],
      "is_active": true,
      "secret": "whsec_****",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /v1/webhooks

Créer un nouvel abonnement webhook.

Corps de la requête

{
  "url": "https://your-app.com/webhooks/answer",
  "events": ["ticket.created", "ticket.updated", "reply.created"],
  "secret": "your_webhook_secret"
}

Statistiques

Accédez à des données complètes d’analyse et de reporting.

GET /v1/stats/overview

Récupère les statistiques générales du helpdesk.

Paramètres

Paramètre	Type	Description
from_date	date	Date de début (AAAA-MM-JJ)
to_date	date	Date de fin (AAAA-MM-JJ)

Réponse

{
  "success": true,
  "data": {
    "tickets": {
      "total": 1500,
      "open": 45,
      "pending": 23,
      "resolved": 1200,
      "closed": 232
    },
    "response_times": {
      "average_first_response": 3600,
      "average_resolution": 86400,
      "sla_compliance": 94.5
    },
    "agent_performance": [
      {
        "agent_id": 15,
        "name": "Support Agent",
        "tickets_resolved": 150,
        "avg_response_time": 2800,
        "satisfaction_rating": 4.8
      }
    ],
    "by_category": [
      {"category": "Account Issues", "count": 350},
      {"category": "Billing", "count": 280},
      {"category": "Technical", "count": 420}
    ],
    "by_priority": {
      "low": 300,
      "medium": 800,
      "high": 350,
      "urgent": 50
    },
    "trends": {
      "daily_created": [...],
      "daily_resolved": [...]
    }
  }
}

GET /v1/stats/agents

Récupère les statistiques détaillées de performance des agents.

Réponse

{
  "success": true,
  "data": [
    {
      "agent_id": 15,
      "name": "Support Agent",
      "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "metrics": {
        "tickets_assigned": 200,
        "tickets_resolved": 180,
        "tickets_open": 20,
        "avg_first_response_time": 1800,
        "avg_resolution_time": 43200,
        "satisfaction_score": 4.8,
        "sla_compliance": 96.5
      },
      "activity": {
        "replies_sent": 450,
        "internal_notes": 120,
        "tickets_reassigned": 15
      }
    }
  ]
}

Codes d’erreur

Code	Statut	Description
`UNAUTHORIZED`	401	Token d’authentification invalide ou manquant
`FORBIDDEN`	403	Droits insuffisants pour cette action
`NOT_FOUND`	404	Ressource introuvable
`VALIDATION_ERROR`	400	Échec de la validation de la requête
`RATE_LIMIT_EXCEEDED`	429	Trop de requêtes
`INTERNAL_ERROR`	500	Erreur interne du serveur

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The subject field is required",
    "details": {
      "subject": ["This field is required"]
    }
  }
}

Introduction

Authentification

POST /v1/auth/token

Corps de la requête

Réponse

Limites de débit

Contrôle de santé

GET /health

Réponse

Tickets

GET /v1/tickets

Paramètres

Réponse

POST /v1/tickets

Paramètres

GET /v1/tickets/{id}

Paramètres

Réponse

PUT /v1/tickets/{id}

Réponse

DELETE /v1/tickets/{id}

Réponse

Réponses

GET /v1/tickets/{ticket_id}/replies

Paramètres

Réponse

POST /v1/tickets/{ticket_id}/replies

Corps de la requête

Pièces jointes

POST /v1/tickets/{ticket_id}/attachments

Paramètres

Réponse

GET /v1/attachments/{id}/download

Utilisateurs

GET /v1/users

Paramètres

Réponse

POST /v1/users

Corps de la requête

Organisations

GET /v1/organizations

Réponse

POST /v1/organizations

Corps de la requête

Catégories

GET /v1/categories

Réponse

POST /v1/categories

Corps de la requête

Webhooks

GET /v1/webhooks

Réponse

POST /v1/webhooks

Corps de la requête

Statistiques

GET /v1/stats/overview

Paramètres

Réponse

GET /v1/stats/agents

Réponse

Codes d’erreur

Menu