API Reference

Documentation complète de l'API REST de la plateforme 2Krika.

Base URL

Production: https://api.2krikaservices.cloud
Staging:    https://api-staging.2krikaservices.cloud
Local:      http://localhost:8000

Authentication

L'API utilise JWT (JSON Web Tokens) pour l'authentification.

Obtenir un Token

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Réponse:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "user_123",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "client"
    }
  }
}

Utiliser le Token

Incluez le token dans le header de chaque requête:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Rafraîchir le Token

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Endpoints

Authentication

Register

POST /auth/register
Content-Type: application/json

{
  "email": "newuser@example.com",
  "password": "password123",
  "name": "New User"
}

Logout

POST /auth/logout
Authorization: Bearer {token}

Forgot Password

POST /auth/forgot-password
Content-Type: application/json

{
  "email": "user@example.com"
}

Reset Password

POST /auth/reset-password
Content-Type: application/json

{
  "token": "reset_token_here",
  "password": "newpassword123"
}

Users

Get Current User

GET /users/me
Authorization: Bearer {token}

Update User Profile

PUT /users/me
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Updated Name",
  "bio": "Updated bio",
  "phone": "+1234567890"
}

Get User by ID

GET /users/{userId}

Upload Avatar

POST /users/me/avatar
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: [image file]

Services

Get All Services

GET /services?page=1&limit=20&category={categoryId}&search={query}

Query Parameters:

page: Page number (default: 1)
limit: Items per page (default: 20)
category: Filter by category ID
search: Search query
minPrice: Minimum price
maxPrice: Maximum price
sortBy: Sort field (price, rating, createdAt)
sortOrder: asc or desc

Réponse:

{
  "success": true,
  "data": {
    "services": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

Get Service by ID

GET /services/{serviceId}

Create Service

POST /services
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Service Title",
  "description": "Detailed description",
  "shortDescription": "Short description",
  "categoryId": "cat_123",
  "tags": ["tag1", "tag2"],
  "packages": [
    {
      "name": "Basic",
      "description": "Basic package",
      "price": 50,
      "deliveryDays": 3,
      "revisions": 1,
      "features": ["Feature 1", "Feature 2"]
    }
  ]
}

Update Service

PUT /services/{serviceId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Updated Title",
  ...
}

Delete Service

DELETE /services/{serviceId}
Authorization: Bearer {token}

Upload Service Images

POST /services/{serviceId}/images
Authorization: Bearer {token}
Content-Type: multipart/form-data

files: [image files]

Orders

Get My Orders (as Buyer)

GET /orders/purchases?status={status}
Authorization: Bearer {token}

Get My Orders (as Seller)

GET /orders/sales?status={status}
Authorization: Bearer {token}

Get Order by ID

GET /orders/{orderId}
Authorization: Bearer {token}

Create Order

POST /orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "serviceId": "service_123",
  "packageId": "package_123",
  "requirements": "Project requirements here",
  "extras": ["extra_id_1", "extra_id_2"]
}

Update Order Status

PUT /orders/{orderId}/status
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "in_progress"
}

Statuts disponibles:

pending: En attente
in_progress: En cours
delivered: Livré
completed: Terminé
cancelled: Annulé
disputed: En litige

Deliver Order (Seller)

POST /orders/{orderId}/deliver
Authorization: Bearer {token}
Content-Type: multipart/form-data

message: "Delivery message"
files: [delivery files]

Reviews

Get Service Reviews

GET /services/{serviceId}/reviews?page=1&limit=10

Create Review

POST /reviews
Authorization: Bearer {token}
Content-Type: application/json

{
  "orderId": "order_123",
  "rating": 5,
  "comment": "Great service!",
  "criteria": {
    "communication": 5,
    "quality": 5,
    "delivery": 5
  }
}

Messages (Chat)

Get Conversations

GET /messages/conversations
Authorization: Bearer {token}

Get Messages in Conversation

GET /messages/conversations/{conversationId}?page=1&limit=50
Authorization: Bearer {token}

Send Message

POST /messages
Authorization: Bearer {token}
Content-Type: application/json

{
  "conversationId": "conv_123",
  "content": "Hello, I have a question..."
}

Upload File in Chat

POST /messages/files
Authorization: Bearer {token}
Content-Type: multipart/form-data

conversationId: conv_123
file: [file]

Wallet

Get Wallet Balance

GET /wallet
Authorization: Bearer {token}

Get Transactions

GET /wallet/transactions?page=1&limit=20
Authorization: Bearer {token}

Request Payout

POST /wallet/payout
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 1000,
  "method": "bank_transfer",
  "details": {
    "accountNumber": "123456789",
    "bankName": "Bank Name"
  }
}

Seller (KYC)

Submit KYC Step 1

POST /seller/kyc/step1
Authorization: Bearer {token}
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-01-01",
  "country": "US",
  "phone": "+1234567890"
}

Submit KYC Step 2

POST /seller/kyc/step2
Authorization: Bearer {token}
Content-Type: multipart/form-data

documentType: "passport"
documentFront: [file]
documentBack: [file]
selfie: [file]

Get KYC Status

GET /seller/kyc/status
Authorization: Bearer {token}

Admin (Protected)

Get Admin Stats

GET /admin/stats
Authorization: Bearer {admin_token}

Get All Users (Admin)

GET /admin/users?page=1&limit=20&role={role}&status={status}
Authorization: Bearer {admin_token}

Suspend User

POST /admin/users/{userId}/suspend
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "reason": "Violation of terms"
}

Approve Service

POST /admin/services/{serviceId}/approve
Authorization: Bearer {admin_token}

Reject Service

POST /admin/services/{serviceId}/reject
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "reason": "Description not clear enough"
}

Error Responses

L'API utilise des codes HTTP standards pour indiquer le succès ou l'échec d'une requête.

Codes de Statut

200 OK: Succès
201 Created: Ressource créée
400 Bad Request: Requête invalide
401 Unauthorized: Non authentifié
403 Forbidden: Non autorisé
404 Not Found: Ressource non trouvée
422 Unprocessable Entity: Validation échouée
429 Too Many Requests: Rate limit dépassé
500 Internal Server Error: Erreur serveur

Format d'Erreur

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Email is required"
      }
    ]
  }
}

Rate Limiting

L'API implémente un rate limiting pour prévenir les abus:

Authentification: 5 requêtes par minute
API générale: 100 requêtes par minute
Upload de fichiers: 10 uploads par minute

Headers de réponse:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1635789600

Webhooks

L'API peut envoyer des webhooks pour certains événements (configuration requise).

Événements Disponibles

order.created: Nouvelle commande
order.completed: Commande terminée
service.approved: Service approuvé
payout.processed: Payout traité

Format du Webhook

{
  "event": "order.created",
  "timestamp": "2025-12-01T10:00:00Z",
  "data": {
    "orderId": "order_123",
    ...
  }
}

Pagination

Les endpoints qui retournent des listes utilisent la pagination:

GET /services?page=1&limit=20

Réponse:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Filtrage et Tri

Les endpoints de liste supportent le filtrage et le tri:

GET /services?
  category=design&
  minPrice=50&
  maxPrice=200&
  sortBy=rating&
  sortOrder=desc

API Reference

Déploiement

Configuration

On this page