Tickets

Créez un ticket au nom d’un de vos clients — typiquement en réaction à un événement métier (paiement échoué, commande bloquée, intégration en erreur).

Endpoint

POST /tickets/api-create

Prérequis

Le client doit déjà exister dans SupportDesk (identifié par son externalId). Appelez PATCH /customers/:externalId d’abord si nécessaire.

Body

Champ	Type	Requis	Description
customerExternalId	string	✅	externalId du client
subject	string	✅	Sujet du ticket
description	string	✅	Description (Markdown supporté)
priority	LOW | MEDIUM | HIGH | URGENT | CRITICAL	—	Défaut: MEDIUM
category	string	—	Catégorie libre
metadata	object	—	Données libres (orderId, errorCode, etc.)
tagIds	string[]	—	IDs (UUID) des tags à attacher

Le champ channel est automatiquement positionné à API.

Exemple

curl

curl -X POST https://supportdesk.innovartx.com/api/v1/tickets/api-create \
  -H "X-API-Key: $SUPPORTDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerExternalId": "user_42",
    "subject": "Paiement échoué pour la commande #12345",
    "description": "La tentative de paiement a échoué avec le code CARD_DECLINED. Le client a été notifié par email.",
    "priority": "HIGH",
    "metadata": { "orderId": "12345", "amount": 99.9 }
  }'

Node.js

await fetch('https://supportdesk.innovartx.com/api/v1/tickets/api-create', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SUPPORTDESK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerExternalId: 'user_42',
    subject: 'Paiement échoué pour la commande #12345',
    description: 'La tentative de paiement a échoué…',
    priority: 'HIGH',
    metadata: { orderId: '12345', amount: 99.9 },
  }),
});

Python (requests)

import os, requests

requests.post(
    'https://supportdesk.innovartx.com/api/v1/tickets/api-create',
    headers={'X-API-Key': os.environ['SUPPORTDESK_API_KEY']},
    json={
        'customerExternalId': 'user_42',
        'subject': 'Paiement échoué pour la commande #12345',
        'description': 'La tentative de paiement a échoué…',
        'priority': 'HIGH',
        'metadata': {'orderId': '12345', 'amount': 99.9},
    },
)

PHP (curl)

$ch = curl_init('https://supportdesk.innovartx.com/api/v1/tickets/api-create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'customerExternalId' => 'user_42',
        'subject' => 'Paiement échoué pour la commande #12345',
        'description' => 'La tentative de paiement a échoué…',
        'priority' => 'HIGH',
        'metadata' => ['orderId' => '12345', 'amount' => 99.9],
    ]),
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('SUPPORTDESK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
curl_exec($ch);
curl_close($ch);

Réponse

{
  "success": true,
  "data": {
    "id": "clyyyyy",
    "ticketNumber": "INV-1042",
    "subject": "Paiement échoué pour la commande #12345",
    "status": "IN_PROGRESS",
    "priority": "HIGH",
    "channel": "API",
    "customer": { "id": "clxxxxxx", "externalId": "user_42", "email": "jean@acme.com" },
    "assignedAgent": { "id": "…", "name": "Agent N1", "email": "agent@acme.com" },
    "createdAt": "2026-04-18T10:00:00Z"
  },
  "timestamp": "2026-04-18T10:00:00Z"
}

Si un agent de niveau N1 est disponible, le ticket est automatiquement assigné et l’agent reçoit une notification par email et dans le dashboard en temps réel.

Erreurs

Code HTTP	Code métier	Cause
400	VALIDATION_ERROR	Champs invalides ou manquants
403	PLAN_LIMIT_REACHED	Quota mensuel de tickets atteint sur votre plan
404	CUSTOMER_NOT_FOUND	L’externalId ne correspond à aucun client de votre app

Voir Erreurs.