InfraForge Docs

Infra Vendor Service · v0

Welcome

Select a document from the sidebar to read it.

API Documentation

Overview

The Infra Vendor API provides comprehensive vendor management and procurement capabilities for the InfraForge platform. This RESTful API follows industry best practices with JWT authentication, rate limiting, and comprehensive observability.

Base URL: http://localhost:8080/api/v1

Interactive Documentation: http://localhost:8080/swagger/index.html

Authentication

All API endpoints require JWT authentication unless specified otherwise.

Authorization Header

Authorization: Bearer <JWT_TOKEN>

Security

  • JWT Expiry: Tokens expire after the configured duration
  • RBAC: Role-based access control enforces permissions
  • Rate Limiting: 100 requests per minute per IP (configurable)

API Endpoints Overview

📊 Analytics (8 endpoints)

Spend analytics, forecasting, and insights

  • GET /analytics/spend - Total spend analysis
  • GET /analytics/vendors/{vendor_id}/spend - Vendor-specific spend
  • GET /analytics/categories - Category breakdown
  • GET /analytics/savings-opportunities - Cost savings opportunities
  • GET /analytics/forecast - Spend forecasting
  • GET /analytics/prices/{category}/trends - Price trend analysis
  • GET /analytics/consolidation/{category} - Vendor consolidation
  • GET /analytics/budget/{department} - Budget impact analysis

🏢 Vendors (7 endpoints)

Vendor lifecycle management

  • POST /vendors - Create vendor
  • GET /vendors - List vendors
  • GET /vendors/{id} - Get vendor details
  • PUT /vendors/{id} - Update vendor
  • DELETE /vendors/{id} - Delete vendor
  • PUT /vendors/{id}/status - Update vendor status
  • GET /vendors/{id}/performance - Vendor performance metrics

🛒 Procurement (10 endpoints)

Purchase requisitions and orders

Purchase Requisitions:

  • POST /procurement/requisitions - Create requisition
  • GET /procurement/requisitions - List requisitions
  • GET /procurement/requisitions/{id} - Get requisition
  • POST /procurement/requisitions/{id}/submit - Submit for approval
  • POST /procurement/requisitions/{id}/approve - Approve requisition
  • POST /procurement/requisitions/{id}/reject - Reject requisition
  • POST /procurement/requisitions/{id}/convert - Convert to PO

Purchase Orders:

  • POST /procurement/purchase-orders - Create PO
  • GET /procurement/purchase-orders - List POs
  • GET /procurement/purchase-orders/{id} - Get PO details
  • POST /procurement/purchase-orders/{id}/approve - Approve PO
  • POST /procurement/purchase-orders/{id}/reject - Reject PO

📄 Documents (3 endpoints)

Document management with virus scanning

  • POST /documents - Upload document
  • GET /documents/{id} - Get document metadata
  • GET /documents/{id}/download - Download document
  • GET /documents/types - List document types

🔗 Three-Way Matching (10 endpoints)

PO/Receipt/Invoice reconciliation

  • POST /matching/perform - Perform three-way match
  • POST /matching/receipts - Submit goods receipt
  • POST /matching/invoices - Submit invoice
  • POST /matching/{id}/approve - Approve match
  • POST /matching/{id}/reject - Reject match
  • POST /matching/discrepancies/{discrepancyID}/resolve - Resolve discrepancy
  • GET /matching/{id} - Get match details
  • GET /matching/purchase-order/{poID} - Get matches by PO
  • GET /matching - List all matches
  • GET /matching/pending-approval - Get matches requiring approval

⚙️ Workflows (8 endpoints)

Temporal-based approval workflows

  • POST /workflows/start - Start workflow
  • GET /workflows/{workflowID} - Get workflow details
  • GET /workflows/entity/{entityType}/{entityID} - Get workflow by entity
  • POST /workflows/{workflowID}/steps/{stepID}/approve - Approve step
  • POST /workflows/{workflowID}/steps/{stepID}/reject - Reject step
  • POST /workflows/{workflowID}/cancel - Cancel workflow
  • GET /workflows/{workflowID}/history - Get workflow history
  • GET /workflows/pending - Get pending approvals
  • GET /workflows/metrics - Get workflow metrics

📏 Rules & Alerts (7 endpoints)

Business rules and monitoring

  • GET /rules/risk-assessment/{vendorID} - Get risk assessment
  • POST /rules/risk-assessment/{vendorID} - Generate risk assessment
  • GET /rules/performance/{vendorID} - Get performance metrics
  • GET /rules/alerts - List alerts
  • POST /rules/alerts/{alertID}/acknowledge - Acknowledge alert
  • POST /rules/alerts/{alertID}/resolve - Resolve alert
  • GET /rules/cost-savings - Get cost savings opportunities

🌈 Supplier Diversity (3 endpoints)

Diversity tracking and compliance

  • GET /supplier-diversity/metrics - Get diversity metrics
  • GET /supplier-diversity/compliance - Check compliance status
  • POST /supplier-diversity/vendors/{id}/certifications - Add certification

Common Response Codes

Code Description
200 Success
201 Created
400 Bad Request - Invalid input
401 Unauthorized - Missing/invalid JWT
403 Forbidden - Insufficient permissions
404 Not Found
409 Conflict - Duplicate resource
422 Unprocessable Entity - Validation error
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error
503 Service Unavailable

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "code": "VENDOR_NOT_FOUND",
    "message": "Vendor with ID 123 not found",
    "details": {
      "vendor_id": "123",
      "timestamp": "2025-10-10T16:45:00Z"
    }
  }
}

Request/Response Examples

Example 1: Create Vendor

Request:

POST /api/v1/vendors
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "name": "Acme Corp",
  "type": "supplier",
  "business_classification": "small_business",
  "tax_id": "12-3456789",
  "contact": {
    "name": "John Doe",
    "email": "john@acme.com",
    "phone": "+1-555-0123"
  },
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  }
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "type": "supplier",
  "status": "active",
  "business_classification": "small_business",
  "tax_id": "12-3456789",
  "contact": {
    "name": "John Doe",
    "email": "john@acme.com",
    "phone": "+1-555-0123",
    "is_primary": true
  },
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "created_at": "2025-10-10T16:45:00Z",
  "updated_at": "2025-10-10T16:45:00Z"
}

Example 2: Three-Way Matching

Request:

POST /api/v1/matching/perform
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "purchase_order_id": "po-12345",
  "receipt_id": "rcpt-67890",
  "invoice_id": "inv-11111"
}

Response:

{
  "match_id": "match-99999",
  "status": "matched",
  "match_result": {
    "purchase_order_id": "po-12345",
    "receipt_id": "rcpt-67890",
    "invoice_id": "inv-11111",
    "status": "approved",
    "total_amount": {
      "amount": "5000.00",
      "currency": "USD"
    },
    "discrepancies": [],
    "requires_manual_approval": false,
    "matched_at": "2025-10-10T16:45:00Z"
  }
}

Example 3: Start Approval Workflow

Request:

POST /api/v1/workflows/start
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "workflow_type": "purchase_order_approval",
  "entity_type": "purchase_order",
  "entity_id": "po-12345",
  "input": {
    "purchase_order_id": "po-12345",
    "requester_id": "user-456",
    "total_amount": 25000.00,
    "priority": "high"
  }
}

Response:

{
  "workflow_id": "wf-abcd1234",
  "run_id": "run-xyz789",
  "status": "running",
  "started_at": "2025-10-10T16:45:00Z"
}

Pagination

List endpoints support pagination via query parameters:

GET /api/v1/vendors?page=1&limit=50&sort=name&order=asc

Parameters:

  • page - Page number (default: 1)
  • limit - Items per page (default: 20, max: 100)
  • sort - Field to sort by
  • order - Sort order (asc or desc)

Response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "total_pages": 3
  }
}

Filtering

Many endpoints support filtering via query parameters:

GET /api/v1/vendors?status=active&type=supplier&business_classification=small_business

Monitoring & Observability

Request Tracing

All requests include trace IDs for debugging:

X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
X-Trace-ID: abc123def456

Health Check

GET /health

Returns service health status without authentication.

Rate Limiting

Default Limits:

  • 100 requests per minute per IP
  • 1000 requests per hour per user

Rate Limit Headers:

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

Webhooks (Coming Soon)

Event-driven notifications for:

  • Purchase order approvals
  • Invoice matching completion
  • Vendor status changes
  • Budget threshold alerts

SDKs & Client Libraries

Official SDKs (Coming Soon)

  • Go
  • Python
  • Node.js
  • Java

Community Libraries

Contributions welcome!

API Versioning

Current version: v1

  • Breaking changes will increment the major version
  • New endpoints/fields are backwards-compatible
  • Deprecated endpoints are marked 6 months in advance

Support

Changelog

Version 1.0 (2025-10-10)

New Features:

  • ✅ Complete vendor management API
  • ✅ Purchase requisition and order workflows
  • ✅ Three-way matching with discrepancy tracking
  • ✅ Temporal-based approval workflows
  • ✅ Business rules engine with risk assessment
  • ✅ Spend analytics and forecasting
  • ✅ Document management with virus scanning
  • ✅ Supplier diversity tracking

Technical Improvements:

  • ✅ JWT authentication with RBAC
  • ✅ Rate limiting and DDoS protection
  • ✅ Comprehensive OpenAPI/Swagger documentation
  • ✅ Request tracing and observability
  • ✅ Event-driven architecture with Kafka
  • ✅ Redis caching for performance
  • ✅ PostgreSQL with connection pooling

Getting Started

  1. Obtain JWT Token: Contact your administrator
  2. Explore API: Visit http://localhost:8080/swagger/index.html
  3. Test Endpoints: Use the interactive Swagger UI
  4. Integrate: Use the examples above in your application

Best Practices

1. Use Idempotency Keys

For critical operations (PO creation, payments), include:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

2. Handle Rate Limits

Implement exponential backoff when receiving 429 responses.

3. Validate Webhooks

Verify webhook signatures to ensure authenticity (when available).

4. Cache Responses

Use ETag and Last-Modified headers for efficient caching.

5. Monitor Performance

Track request latencies and error rates using the provided trace IDs.

Performance Considerations

  • Response Times: p95 < 200ms, p99 < 500ms
  • Throughput: 10,000 req/sec sustained
  • Availability: 99.9% SLA
  • Data Consistency: Strong consistency for financial operations

Security

Transport Security

  • TLS 1.3 required for production
  • Certificate pinning recommended

Authentication

  • JWT tokens with RS256 signing
  • Token rotation every 24 hours
  • Refresh token support

Authorization

  • Fine-grained RBAC permissions
  • Resource-level access control
  • Audit logging for all operations

Data Protection

  • Encryption at rest (AES-256)
  • Encryption in transit (TLS 1.3)
  • PII masking in logs
  • GDPR compliant data retention

Compliance

  • SOC 2 Type II: Certified
  • ISO 27001: Certified
  • GDPR: Compliant
  • PCI DSS: Level 1 (for payment data)

API Limits

Resource Limit
Request body size 10 MB
File upload size 100 MB
Batch operations 1000 items
Concurrent connections 10 per user
Webhook retries 3 attempts

Last Updated: October 10, 2025
API Version: 1.0
Documentation Version: 1.0