Orders API

Endpoints pour gérer les commandes clients.

Lister les commandes

GET /v1/public-api/orders

Scope requis: read:orders

Paramètres de requête

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/orders?dateFrom=2024-01-01&dateTo=2024-01-31" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "data": [
    {
      "id": "ord_abc123",
      "orderNumber": "ORD-2024-001234",
      "status": "COMPLETED",
      "customerId": "cust_001",
      "customerName": "Jean Dupont",
      "subtotal": 1998.00,
      "taxAmount": 359.64,
      "discountAmount": 100.00,
      "total": 2257.64,
      "itemCount": 2,
      "items": [
        {
          "productId": "prod_001",
          "productName": "iPhone 15 Pro",
          "sku": "IPHONE-15-PRO-128",
          "quantity": 1,
          "unitPrice": 999.00,
          "totalPrice": 999.00
        },
        {
          "productId": "prod_002",
          "productName": "AirPods Pro",
          "sku": "AIRPODS-PRO-2",
          "quantity": 1,
          "unitPrice": 999.00,
          "totalPrice": 999.00
        }
      ],
      "createdAt": "2024-01-25T10:30:00Z"
    }
  ],
  "total": 1523,
  "page": 1,
  "limit": 20,
  "totalPages": 77
}

---

Obtenir une commande

GET /v1/public-api/orders/:id

Scope requis: read:orders

Paramètres de chemin

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/orders/ord_abc123" \
  -H "X-API-Key: sk_live_xxx"

Réponse

Même format que dans la liste, mais pour une seule commande.

---

Créer une commande

POST /v1/public-api/orders

Scope requis: write:orders

Corps de la requête

Exemple de requête

curl -X POST "https://api.nerpsuite.com/v1/public-api/orders" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_001",
    "warehouseId": "wh_001",
    "items": [
      {
        "productId": "prod_001",
        "quantity": 2,
        "unitPrice": 999.00
      },
      {
        "productId": "prod_003",
        "quantity": 1
      }
    ],
    "discountAmount": 50.00,
    "notes": "Commande web #12345"
  }'

Réponse

{
  "id": "ord_xyz789",
  "orderNumber": "ORD-2024-001235",
  "status": "PENDING",
  "customerId": "cust_001",
  "customerName": "Jean Dupont",
  "subtotal": 2048.00,
  "taxAmount": 368.64,
  "discountAmount": 50.00,
  "total": 2366.64,
  "itemCount": 3,
  "items": [
    {
      "productId": "prod_001",
      "productName": "iPhone 15 Pro",
      "sku": "IPHONE-15-PRO-128",
      "quantity": 2,
      "unitPrice": 999.00,
      "totalPrice": 1998.00
    },
    {
      "productId": "prod_003",
      "productName": "Coque iPhone 15",
      "sku": "CASE-IPHONE-15-BLK",
      "quantity": 1,
      "unitPrice": 50.00,
      "totalPrice": 50.00
    }
  ],
  "createdAt": "2024-01-25T14:45:00Z"
}

Statuts de commande

Champs de réponse

Commande

Article

Erreurs courantes

// Stock insuffisant
{
  "statusCode": 422,
  "message": "Insufficient stock for product IPHONE-15-PRO-128. Available: 5, Requested: 10",
  "error": "Unprocessable Entity"
}

// Produit non trouvé
{
  "statusCode": 404,
  "message": "Product prod_invalid not found",
  "error": "Not Found"
}

// Client non trouvé
{
  "statusCode": 404,
  "message": "Customer cust_invalid not found",
  "error": "Not Found"
}

Cas d'usage

Intégration e-commerce

Synchronisez les commandes de votre boutique en ligne :

async function syncOrderToNerpsuite(shopifyOrder) {
  const items = shopifyOrder.line_items.map(item => ({
    productId: item.nerpsuite_product_id,
    quantity: item.quantity,
    unitPrice: parseFloat(item.price)
  }));

  const response = await fetch('/v1/public-api/orders', {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      customerId: shopifyOrder.nerpsuite_customer_id,
      warehouseId: 'wh_main',
      items,
      notes: `Shopify Order #${shopifyOrder.order_number}`
    })
  });

  return response.json();
}