# .env.development
STATESET_API_KEY=sk_test_your_actual_key_here
STATESET_WEBHOOK_SECRET=whsec_test_...
STATESET_ENVIRONMENT=sandbox

# .env.production  
STATESET_API_KEY=sk_live_your_actual_key_here
STATESET_WEBHOOK_SECRET=whsec_live_...
STATESET_ENVIRONMENT=production

{
  "error": {
    "code": "RATE_LIMITED", 
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60,
    "limit": 1000,
    "remaining": 0,
    "reset_at": "2024-01-15T12:00:00Z"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "field": "email",
      "issue": "Invalid email format",
      "expected": "valid email address",
      "received": "invalid-email"
    },
    "request_id": "req_1NXWPnCo6bFb1KQto6C8OWvE",
    "timestamp": "2024-01-15T10:30:00Z",
    "documentation_url": "https://docs.stateset.com/errors/VALIDATION_ERROR"
  }
}

GET /v1/orders?limit=20&offset=40

GET /v1/orders?limit=20&cursor=eyJpZCI6Im9yZF8xMjM0NSJ9

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6Im9yZF82Nzg5MCJ9",
    "previous_cursor": "eyJpZCI6Im9yZF8wMTIzNCJ9",
    "total_count": 1250,
    "page_count": 63,
    "current_page": 3
  },
  "meta": {
    "request_id": "req_1NXWPnCo6bFb1KQto6C8OWvE",
    "response_time_ms": 142
  }
}

# Exact match
GET /v1/orders?status=shipped

# Multiple values  
GET /v1/orders?status_in=pending,processing,shipped

# Range queries
GET /v1/orders?created_after=2024-01-01T00:00:00Z
GET /v1/orders?total_amount_gte=100.00&total_amount_lte=500.00

# Search
GET /v1/[email protected]

# Complex filtering
GET /v1/orders?status=shipped&created_after=2024-01-01&customer_tier=gold

# Sort by field (default: ascending)
GET /v1/orders?sort=created_at

# Specify direction
GET /v1/orders?sort=total_amount&order=desc

# Multiple sort fields
GET /v1/orders?sort=status,created_at&order=asc,desc

POST https://api.stateset.com/graphql

query GetOrdersWithItems {
  orders(limit: 10, where: {status: {_eq: "shipped"}}) {
    id
    order_number
    status
    total_amount
    customer {
      id
      email
      first_name
      last_name
    }
    line_items {
      id
      sku
      quantity
      price
      product {
        name
        category
      }
    }
  }
}

subscription OrderUpdates {
  orders(where: {status: {_in: ["processing", "shipped"]}}) {
    id
    status
    updated_at
  }
}

{
  "id": "evt_1NXWPnCo6bFb1KQto6C8OWvE",
  "type": "order.created",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "object": { /* Full object data */ }
  },
  "previous_attributes": { /* For update events */ },
  "metadata": {
    "workspace_id": "ws_123",
    "user_id": "usr_456",
    "api_version": "2024-01-01"
  }
}

// Production-ready webhook verification
const crypto = require('crypto');
// Replace with a structured logger (Winston, Pino, etc) in production
const logger = console;

function verifyWebhook(payload, signature, secret) {
  // Extract timestamp and signatures
  const elements = signature.split(' ');
  const timestamp = elements.find(e => e.startsWith('t=')).slice(2);
  const signatures = elements.filter(e => e.startsWith('v1=')).map(e => e.slice(3));
  
  // Verify timestamp is within 5 minutes
  const currentTime = Math.floor(Date.now() / 1000);
  if (currentTime - parseInt(timestamp) > 300) {
    throw new Error('Webhook timestamp too old');
  }
  
  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  // Verify signature matches
  const valid = signatures.some(sig => 
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSignature))
  );
  
  if (!valid) {
    throw new Error('Invalid webhook signature');
  }
  
  return true;
}

// Express.js webhook handler
app.post('/webhooks/stateset', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['stateset-signature'];
  const secret = process.env.STATESET_WEBHOOK_SECRET;
  
  try {
    verifyWebhook(req.body, signature, secret);
    const event = JSON.parse(req.body);
    
    // Process webhook event
    switch(event.type) {
      case 'order.created':
        handleOrderCreated(event.data.object);
        break;
      case 'return.approved':
        handleReturnApproved(event.data.object);
        break;
      // ... handle other events
    }
    
    res.json({received: true});
  } catch (error) {
    logger.error('Webhook error', { message: error.message });
    res.status(400).json({error: 'Webhook verification failed'});
  }
});

# Sandbox endpoints
REST API: https://api.sandbox.stateset.com/v1
GraphQL: https://api.sandbox.stateset.com/graphql
Webhooks: https://webhooks.sandbox.stateset.com

# Test API keys
Authorization: Bearer ${STATESET_API_KEY}

# Using idempotency for safe retries
curl -X POST https://api.stateset.com/v1/orders \
  -H "Idempotency-Key: order-550e8400-e29b-41d4-a716" \
  -H "Authorization: Bearer sk_test_..." \
  -d @order.json

// Node.js with automatic retry and idempotency
const { v4: uuidv4 } = require('uuid');

async function createOrderSafely(orderData) {
  const idempotencyKey = `order-${uuidv4()}`;
  
  return await stateset.orders.create(orderData, {
    idempotencyKey,
    maxRetries: 3,
    retryDelay: 1000
  });
}