Réponses

Vue d'ensemble

L'API Oquira suit des conventions de réponse cohérentes sur tous les endpoints. Comprendre ces patterns vous aidera à intégrer plus efficacement.

Réponses de Succès

Toutes les réponses réussies incluent un indicateur success défini à true et un payload data contenant les informations demandées.

Ressource Unique

Lors de la récupération d'une seule ressource :

{
  "success": true,
  "data": {
    "id": "srv_7k92m1",
    "name": "Service Client",
    "status": "active",
    "createdAt": "2024-01-15T08:00:00Z",
    "updatedAt": "2024-03-20T10:00:00Z"
  }
}

Liste de Ressources

Lors de la récupération de plusieurs ressources, la réponse inclut des métadonnées de pagination :

{
  "success": true,
  "data": [
    { "id": "srv_7k92m1", "name": "Service Client" },
    { "id": "srv_8n3p5q", "name": "Support Technique" }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "limit": 10,
    "hasMore": true
  }
}

Listes Vides

Quand aucune ressource ne correspond à la requête :

{
  "success": true,
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "limit": 10,
    "hasMore": false
  }
}

Pagination

Pour les endpoints de liste, utilisez ces paramètres de requête pour paginer :

Exemple

curl -X GET "https://api.oquira.com/v1/business/services?page=2&limit=20" \
  -H "X-API-Key: votre_cle_api"

Métadonnées de Réponse

Réponses d'Erreur

Lorsqu'une erreur survient, la réponse inclut success: false et un objet error avec les détails :

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Les données fournies sont invalides",
    "details": {
      "field": "email",
      "reason": "Doit être une adresse email valide"
    },
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Champs de l'Objet Erreur

Suivi des Requêtes

Chaque requête API se voit attribuer un requestId unique. Cet identifiant est inclus dans :

• Tous les corps de réponse (succès et erreur)
• L'en-tête de réponse X-Request-ID

Identifiants de Requête Personnalisés

Vous pouvez fournir votre propre identifiant de requête pour suivre les requêtes à travers vos systèmes :

curl -X GET "https://api.oquira.com/v1/business/services" \
  -H "X-API-Key: votre_cle_api" \
  -H "X-Request-ID: votre-id-personnalise-123"

L'API renverra votre ID dans la réponse et les logs, facilitant la corrélation des requêtes.

Conseil : Loggez toujours le requestId lors de vos appels API. Cela aide notre équipe de support à diagnostiquer les problèmes rapidement.

En-têtes de Réponse Courants

Toutes les réponses API incluent ces en-têtes :

Horodatages

Tous les horodatages dans l'API suivent le format ISO 8601 en UTC :

2024-03-20T10:30:00.000Z

Lors de l'envoi de dates dans les requêtes :

• Le format ISO 8601 est préféré : 2024-03-20T10:30:00Z
• Le format date seule est accepté où applicable : 2024-03-20

Valeurs Null

• Les champs null peuvent être omis des réponses pour réduire la taille du payload
• Lors de la mise à jour de ressources, envoyer null explicitement effacera le champ
• Les tableaux seront toujours présents comme [] vide plutôt que null

Étapes Suivantes

• Erreurs - Liste complète des codes d'erreur
• Limites de taux - Limites d'utilisation de l'API et en-têtes
• Mise en route - Effectuez votre premier appel API