Suppliers API

Supplier relationship management endpoints.

Suppliers API

The Suppliers API provides endpoints for managing supplier relationships, contact information, performance tracking, and procurement processes.

Endpoints

GET /api/suppliers

Retrieve suppliers.

Query Parameters:

  • is_active (boolean): Filter by active status
  • search (string): Search by name or email
  • page (number): Page number
  • limit (number): Items per page

Response:

{
  "data": [
    {
      "id": "sup_789",
      "name": "Supplier ABC",
      "email": "orders@supplierabc.com",
      "phone": "+1-555-0123",
      "website": "https://supplierabc.com",
      "address": {
        "line1": "789 Supplier St",
        "line2": "Suite 100",
        "city": "Supplier City",
        "state": "CA",
        "postal_code": "90210",
        "country": "US"
      },
      "payment_terms": "net_30",
      "credit_limit": 50000.00,
      "current_balance": 12500.00,
      "performance_rating": 4.5,
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

GET /api/suppliers/:id

Retrieve a specific supplier by ID.

Response:

{
  "data": {
    "id": "sup_789",
    "name": "Supplier ABC",
    "email": "orders@supplierabc.com",
    "phone": "+1-555-0123",
    "fax": "+1-555-0124",
    "website": "https://supplierabc.com",
    "tax_id": "12-3456789",
    "address": {
      "line1": "789 Supplier St",
      "line2": "Suite 100",
      "city": "Supplier City",
      "state": "CA",
      "postal_code": "90210",
      "country": "US"
    },
    "contacts": [
      {
        "id": "cont_001",
        "name": "John Smith",
        "title": "Sales Manager",
        "email": "john.smith@supplierabc.com",
        "phone": "+1-555-0125",
        "is_primary": true
      }
    ],
    "payment_terms": "net_30",
    "currency": "USD",
    "credit_limit": 50000.00,
    "current_balance": 12500.00,
    "performance_rating": 4.5,
    "lead_time_days": 7,
    "minimum_order_amount": 1000.00,
    "shipping_terms": "FOB_ORIGIN",
    "is_active": true,
    "notes": "Reliable supplier with good quality products",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

POST /api/suppliers

Create a new supplier.

Request Body:

{
  "name": "New Supplier Inc",
  "email": "orders@newsupplier.com",
  "phone": "+1-555-0199",
  "website": "https://newsupplier.com",
  "tax_id": "98-7654321",
  "address": {
    "line1": "999 New Supplier Ave",
    "city": "New City",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "contacts": [
    {
      "name": "Jane Smith",
      "title": "Account Manager",
      "email": "jane.smith@newsupplier.com",
      "phone": "+1-555-0200",
      "is_primary": true
    }
  ],
  "payment_terms": "net_30",
  "currency": "USD",
  "credit_limit": 25000.00,
  "lead_time_days": 5,
  "minimum_order_amount": 500.00,
  "shipping_terms": "FOB_DESTINATION"
}

Response:

{
  "data": {
    "id": "sup_790",
    "name": "New Supplier Inc",
    "email": "orders@newsupplier.com",
    "phone": "+1-555-0199",
    "address": {
      "line1": "999 New Supplier Ave",
      "city": "New City",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "contacts": [
      {
        "id": "cont_002",
        "name": "Jane Smith",
        "title": "Account Manager",
        "email": "jane.smith@newsupplier.com",
        "phone": "+1-555-0200",
        "is_primary": true
      }
    ],
    "payment_terms": "net_30",
    "currency": "USD",
    "credit_limit": 25000.00,
    "current_balance": 0.00,
    "performance_rating": null,
    "lead_time_days": 5,
    "minimum_order_amount": 500.00,
    "is_active": true,
    "created_at": "2024-01-15T20:00:00Z",
    "updated_at": "2024-01-15T20:00:00Z"
  }
}

PUT /api/suppliers/:id

Update an existing supplier.

Request Body:

{
  "name": "Updated Supplier Name",
  "email": "new.orders@supplier.com",
  "credit_limit": 75000.00,
  "lead_time_days": 10,
  "is_active": true
}

Response:

{
  "data": {
    "id": "sup_789",
    "name": "Updated Supplier Name",
    "email": "new.orders@supplier.com",
    "credit_limit": 75000.00,
    "lead_time_days": 10,
    "updated_at": "2024-01-15T20:30:00Z"
  }
}

GET /api/suppliers/:id/performance

Get supplier performance metrics.

Query Parameters:

  • period (string): Time period (30d, 90d, 1y)

Response:

{
  "data": {
    "supplier": {
      "id": "sup_789",
      "name": "Supplier ABC"
    },
    "overview": {
      "performance_rating": 4.5,
      "total_orders": 25,
      "total_value": 125000.00,
      "avg_order_value": 5000.00
    },
    "delivery_performance": {
      "on_time_delivery_rate": 95.8,
      "avg_lead_time": 6.5,
      "lead_time_variance": 1.2,
      "early_deliveries": 12,
      "on_time_deliveries": 23,
      "late_deliveries": 2
    },
    "quality_metrics": {
      "quality_rating": 4.8,
      "defect_rate": 0.5,
      "return_rate": 0.2,
      "quality_incidents": 1
    },
    "financial_metrics": {
      "payment_terms_compliance": 100.0,
      "avg_payment_days": 28,
      "cost_variance": -2.5,
      "current_balance": 12500.00
    },
    "monthly_performance": [
      {
        "month": "2024-01",
        "orders": 8,
        "value": 40000.00,
        "on_time_rate": 100.0,
        "quality_rating": 5.0
      }
    ]
  }
}

GET /api/suppliers/:id/orders

Get purchase orders for a specific supplier.

Query Parameters:

  • status (string): Filter by order status
  • date_from (string): Start date
  • date_to (string): End date
  • page (number): Page number
  • limit (number): Items per page

Response:

{
  "data": [
    {
      "id": "po_456",
      "po_number": "PO-2024-001",
      "status": "received",
      "order_date": "2024-01-15T00:00:00Z",
      "expected_date": "2024-01-25T00:00:00Z",
      "received_date": "2024-01-24T00:00:00Z",
      "total_amount": 5000.00,
      "items_count": 3,
      "delivery_performance": "on_time"
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

POST /api/suppliers/:id/contacts

Add a contact to a supplier.

Request Body:

{
  "name": "Mike Johnson",
  "title": "Technical Support",
  "email": "mike.johnson@supplier.com",
  "phone": "+1-555-0300",
  "is_primary": false
}

Response:

{
  "data": {
    "id": "cont_003",
    "name": "Mike Johnson",
    "title": "Technical Support",
    "email": "mike.johnson@supplier.com",
    "phone": "+1-555-0300",
    "is_primary": false,
    "supplier_id": "sup_789",
    "created_at": "2024-01-15T21:00:00Z"
  }
}

PUT /api/suppliers/:id/contacts/:contact_id

Update a supplier contact.

Request Body:

{
  "title": "Senior Technical Support",
  "phone": "+1-555-0301",
  "is_primary": true
}

DELETE /api/suppliers/:id/contacts/:contact_id

Remove a contact from a supplier.

Response:

{
  "data": {
    "message": "Contact successfully removed"
  }
}