Referencia API del Gateway

API Gateway - Referencia API

Descripción General

Este documento proporciona una referencia completa para todos los Endpoints del API Gateway. Todos los Endpoints siguen convenciones RESTful y retornan respuestas JSON estandarizadas con seguimiento de solicitudes.

Información Base:

URL Base (Desarrollo): http://localhost:3000/api
URL Base (Producción): https://api.algesta.com/api
Swagger UI: http://localhost:3000/api/docs
Autenticación: Token JWT Bearer en encabezado Authorization
Content-Type: application/json para todas las solicitudes con cuerpo

Formatos de Respuesta Estándar:

Respuestas exitosas (envueltas por ResponseInterceptor):

{
  "statusCode": 200,
  "message": "Operation successful",
  "timestamp": "2025-01-15T10:30:00Z",
  "path": "/api/orders",
  "method": "GET",
  "data": { ... },
  "traceId": "550e8400-e29b-41d4-a716-446655440000"
}

Nota: Si un handler retorna un objeto que contiene success o statusCode, el interceptor lo pasa sin envolver.

Respuestas de error (desde HttpExceptionFilter usando BaseResponseDto<null>):

{
  "success": false,
  "message": "Error message",
  "data": null,
  "error": {
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Detailed error message",
    "timestamp": "2025-01-15T10:30:00Z",
    "path": "/api/orders",
    "method": "POST",
    "traceId": "uuid",
    "details": ["Validation error 1", "Validation error 2"]
  }
}

Para detalles de autenticación, ver Autenticación del API Gateway.

Para resiliencia y manejo de errores, ver Resiliencia del API Gateway.

Authentication Endpoints

All authentication Endpoints are accessible without prior authentication (except where noted).

POST /api/auth/login

Authenticate user with email and password.

Request:

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

Success Response (200):

{
  "statusCode": 200,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "user-123",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "CLIENT",
      "isEmailVerified": true
    }
  },
  "traceId": "uuid"
}

Error Responses:

400: Validation error (missing email/password)
401: Invalid credentials
403: Email not verified

Example error response (BaseResponseDto):

{
  "success": false,
  "message": "Invalid credentials",
  "data": null,
  "error": {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "Invalid credentials",
    "timestamp": "2025-01-15T10:30:00Z",
    "path": "/api/auth/login",
    "method": "POST",
    "traceId": "uuid"
  }
}

Example:

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/auth.controller.ts

POST /api/auth/register-web

Request:

{
  "email": "newuser@example.com",
  "name": "Jane Smith",
  "identification": "1234567890",
  "phone": "+573001234567",
  "password": "SecurePass123!",
  "isEmployee": false
}

Success Response (201):

{
  "statusCode": 201,
  "message": "User registered successfully. Please verify your email.",
  "data": {
    "userId": "user-456",
    "email": "newuser@example.com"
  },
  "traceId": "uuid"
}

Error Responses:

400: Validation error
409: User already exists

Example:

curl -X POST http://localhost:3000/api/auth/register-web \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "Jane Smith",
    "identification": "1234567890",
    "phone": "+573001234567",
    "password": "SecurePass123!",
    "isEmployee": false
  }'

POST /api/auth/forgot-password/:email

Request password reset OTP.

URL Parameters:

email: User email address

Success Response (200):

{
  "statusCode": 200,
  "message": "Password reset OTP sent to email",
  "data": {
    "email": "user@example.com"
  },
  "traceId": "uuid"
}

Error Responses:

404: User not found

Example:

curl -X POST http://localhost:3000/api/auth/forgot-password/user@example.com

POST /api/auth/validate-forgot-password-otp/:email/:code

Validate password reset OTP and receive reset token.

URL Parameters:

email: User email address
code: 6-digit OTP code

Success Response (200):

{
  "statusCode": 200,
  "message": "OTP validated successfully",
  "data": {
    "resetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "2 hours"
  },
  "traceId": "uuid"
}

Error Responses:

400: Invalid or expired OTP

Example:

curl -X POST http://localhost:3000/api/auth/validate-forgot-password-otp/user@example.com/123456

POST /api/auth/reset-password

Reset password using reset token.

Request:

{
  "resetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "newPassword": "NewSecurePass123!"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Password reset successfully",
  "data": {
    "email": "user@example.com"
  },
  "traceId": "uuid"
}

Error Responses:

400: Invalid/expired token or weak password

Example:

curl -X POST http://localhost:3000/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "resetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "newPassword": "NewSecurePass123!"
  }'

POST /api/auth/otp/send/:email

Send email verification OTP.

URL Parameters:

email: User email address

Success Response (200):

{
  "statusCode": 200,
  "message": "OTP sent to email",
  "data": {
    "email": "user@example.com",
    "expiresIn": "10 minutes"
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/auth/otp/send/user@example.com

POST /api/auth/otp/validate/:email/:code

Validate email verification OTP.

URL Parameters:

email: User email address
code: 6-digit OTP code

Success Response (200):

{
  "statusCode": 200,
  "message": "Email verified successfully",
  "data": {
    "verified": true
  },
  "traceId": "uuid"
}

Error Responses:

400: Invalid or expired OTP

Example:

curl -X POST http://localhost:3000/api/auth/otp/validate/user@example.com/123456

Orders Management Endpoints

POST /api/orders

Create new order.

Authentication: Optional (can be created by unauthenticated users via WhatsApp channel)

Request:

{
  "channel": "WHATSAPP",
  "service": "PLUMBING",
  "address": "123 Main Street, Apt 4B",
  "city": "Bogota",
  "description": "Leaking pipe in bathroom",
  "phoneNumber": "+573001234567",
  "nameContact": "John Doe",
  "emailContact": "john@example.com",
  "scheduledDate": "2025-01-20",
  "scheduledTime": "14:00",
  "priority": "MEDIUM",
  "image1Url": "https://storage.azure.com/...",
  "image2Url": "https://storage.azure.com/...",
  "image3Url": null
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Order created successfully",
  "data": {
    "orderId": "order-789",
    "status": "RECEIVED",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Error Responses:

400: Validation error

Example:

curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "WEB",
    "service": "ELECTRICAL",
    "address": "123 Main St",
    "city": "Bogota",
    "phoneNumber": "+573001234567",
    "nameContact": "Jane Doe",
    "priority": "HIGH"
  }'

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/orders-management.controller.ts

GET /api/orders

List all orders with filters.

Authentication: Not Required* (Endpoint does not have @UseGuards(JwtAuthGuard) decorator in current Implementación)

*Note: This may be intentional for allowing public order tracking.

Query Parameters:

Estado: Filter by Estado (RECEIVED, IN_EVALUATION, PUBLISHED, etc.)
service: Filter by service type
city: Filter by city
Prioridad: Filter by Prioridad (LOW, MEDIUM, HIGH, URGENT)
page: Page number (default: 1)
limit: Results per page (default: 10)
sortBy: Sort field (default: createdAt)
sortOrder: Sort order (ASC, DESC) (default: DESC)

Success Response (200):

{
  "statusCode": 200,
  "message": "Orders retrieved successfully",
  "data": {
    "orders": [
      {
        "orderId": "order-123",
        "status": "IN_PROGRESS",
        "service": "PLUMBING",
        "address": "123 Main St",
        "city": "Bogota",
        "priority": "HIGH",
        "createdAt": "2025-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10,
      "totalPages": 10
    }
  },
  "traceId": "uuid"
}

Example:

curl "http://localhost:3000/api/orders?status=IN_PROGRESS&page=1&limit=20" \
  -H "Authorization: Bearer <token>"

GET /api/orders/:orderId

Get order by ID.

Authentication: Not Required* (Endpoint does not have @UseGuards(JwtAuthGuard) decorator in current Implementación)

*Note: This may be intentional for allowing public order tracking.

URL Parameters:

orderId: Order identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Order retrieved successfully",
  "data": {
    "orderId": "order-123",
    "status": "IN_PROGRESS",
    "service": "PLUMBING",
    "description": "Leaking pipe",
    "address": "123 Main St",
    "city": "Bogota",
    "priority": "HIGH",
    "assignedProvider": {
      "providerId": "provider-456",
      "name": "ABC Plumbing"
    },
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T12:00:00Z"
  },
  "traceId": "uuid"
}

Error Responses:

404: Order not found

Example:

curl http://localhost:3000/api/orders/order-123 \
  -H "Authorization: Bearer <token>"

GET /api/orders/details/:orderId

Get detailed order information including history, Documentos, and provider details.

Authentication: Required

URL Parameters:

orderId: Order identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Order details retrieved successfully",
  "data": {
    "order": { /* order data */ },
    "history": [
      {
        "status": "RECEIVED",
        "timestamp": "2025-01-15T10:30:00Z",
        "changedBy": "system"
      },
      {
        "status": "IN_EVALUATION",
        "timestamp": "2025-01-15T11:00:00Z",
        "changedBy": "agent-123"
      }
    ],
    "documents": [
      {
        "documentId": "doc-789",
        "type": "QUOTE",
        "url": "https://storage.azure.com/...",
        "uploadedAt": "2025-01-15T12:00:00Z"
      }
    ],
    "provider": {
      "providerId": "provider-456",
      "name": "ABC Plumbing",
      "rating": 4.8
    }
  },
  "traceId": "uuid"
}

Example:

curl http://localhost:3000/api/orders/details/order-123 \
  -H "Authorization: Bearer <token>"

GET /api/orders/by-phone/:phoneNumber

Get orders by phone number (for unauthenticated users tracking orders).

Authentication: Not required

URL Parameters:

phoneNumber: Phone number with country code (e.g., +573001234567)

Success Response (200):

{
  "statusCode": 200,
  "message": "Orders retrieved successfully",
  "data": {
    "orders": [
      {
        "orderId": "order-123",
        "status": "IN_PROGRESS",
        "service": "PLUMBING",
        "createdAt": "2025-01-15T10:30:00Z"
      }
    ]
  },
  "traceId": "uuid"
}

Example:

curl http://localhost:3000/api/orders/by-phone/+573001234567

GET /api/orders/history/:orderId

Get order Estado history.

Authentication: Required

URL Parameters:

orderId: Order identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Order history retrieved successfully",
  "data": {
    "history": [
      {
        "status": "RECEIVED",
        "timestamp": "2025-01-15T10:30:00Z",
        "changedBy": "system",
        "notes": "Order received via WhatsApp"
      },
      {
        "status": "IN_EVALUATION",
        "timestamp": "2025-01-15T11:00:00Z",
        "changedBy": "agent-123",
        "notes": "Initial evaluation completed"
      }
    ]
  },
  "traceId": "uuid"
}

Example:

curl http://localhost:3000/api/orders/history/order-123 \
  -H "Authorization: Bearer <token>"

PATCH /api/orders/:orderId

Update order details.

Authentication: Required Roles: ADMIN, AGENT

URL Parameters:

orderId: Order identifier

Request:

{
  "status": "IN_EVALUATION",
  "priority": "HIGH",
  "scheduledDate": "2025-01-20",
  "notes": "Updated priority due to urgency"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Order updated successfully",
  "data": {
    "orderId": "order-123",
    "status": "IN_EVALUATION",
    "priority": "HIGH",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Error Responses:

403: Insufficient permissions
404: Order not found

Example:

curl -X PATCH http://localhost:3000/api/orders/order-123 \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "IN_EVALUATION",
    "priority": "HIGH"
  }'

PATCH /api/orders/additional-evaluation/:orderId

Update evaluation notes for order.

Authentication: Required Roles: ADMIN, AGENT

URL Parameters:

orderId: Order identifier

Request:

{
  "evaluationNotes": "Customer needs urgent service. Requires specialized equipment.",
  "estimatedCost": 500000,
  "estimatedDuration": "2 hours"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Evaluation updated successfully",
  "data": {
    "orderId": "order-123",
    "evaluationNotes": "Customer needs urgent service...",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Example:

curl -X PATCH http://localhost:3000/api/orders/additional-evaluation/order-123 \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "evaluationNotes": "Urgent service required",
    "estimatedCost": 500000
  }'

PATCH /api/orders/publish/:orderId

Publish order to marketplace for provider bidding.

Authentication: Required Roles: ADMIN, AGENT

URL Parameters:

orderId: Order identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Order published successfully",
  "data": {
    "orderId": "order-123",
    "status": "PUBLISHED",
    "auctionId": "auction-456",
    "publishedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Error Responses:

400: Order not ready for publishing (missing evaluation, etc.)
403: Insufficient permissions

Example:

curl -X PATCH http://localhost:3000/api/orders/publish/order-123 \
  -H "Authorization: Bearer <admin-token>"

GET /api/orders/accepted-providers/:orderId

Get list of providers who accepted the order.

Authentication: Required Roles: ADMIN, AGENT

URL Parameters:

orderId: Order identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Accepted providers retrieved successfully",
  "data": {
    "providers": [
      {
        "providerId": "provider-456",
        "name": "ABC Plumbing",
        "rating": 4.8,
        "quotedPrice": 450000,
        "estimatedDuration": "2 hours",
        "acceptedAt": "2025-01-15T11:00:00Z"
      }
    ]
  },
  "traceId": "uuid"
}

Example:

curl http://localhost:3000/api/orders/accepted-providers/order-123 \
  -H "Authorization: Bearer <admin-token>"

POST /api/orders/send-quote/:orderId

Send quote to customer for approval.

Authentication: Required (authenticated providers)

URL Parameters:

orderId: Order identifier

Request:

{
  "quotedPrice": 450000,
  "estimatedDuration": "2 hours",
  "notes": "Includes parts and labor",
  "breakdownItems": [
    {
      "description": "Parts",
      "cost": 200000
    },
    {
      "description": "Labor",
      "cost": 250000
    }
  ]
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Quote sent successfully",
  "data": {
    "quoteId": "quote-789",
    "orderId": "order-123",
    "sentAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/orders/send-quote/order-123 \
  -H "Authorization: Bearer <provider-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "quotedPrice": 450000,
    "estimatedDuration": "2 hours"
  }'

POST /api/orders/asset

Create asset record associated with an order.

Authentication: Required

Request:

{
  "orderId": "order-123",
  "assetType": "EQUIPMENT",
  "brand": "Samsung",
  "model": "Model-X",
  "serialNumber": "SN123456",
  "condition": "FUNCTIONAL",
  "notes": "Customer equipment details"
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Asset created successfully",
  "data": {
    "assetId": "asset-999",
    "orderId": "order-123",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/orders/asset \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "assetType": "EQUIPMENT",
    "brand": "Samsung"
  }'

POST /api/orders/raw-query

Execute raw MongoDB query (DEVELOPMENT ONLY - DANGEROUS).

Authentication: Required Roles: ADMIN

Warning: This Endpoint should be disabled in production environments.

Request:

{
  "query": {
    "status": "IN_PROGRESS"
  }
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Query executed successfully",
  "data": {
    "results": [ /* matching documents */ ],
    "count": 15
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/orders/raw-query \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{ "query": { "status": "IN_PROGRESS" } }'

Provider Endpoints

All provider Endpoints require authentication with PROVIDER role.

GET /api/provider/auctions

List available auctions for provider to bid on.

Authentication: Required Roles: PROVIDER

Success Response (200):

{
  "statusCode": 200,
  "message": "Auctions retrieved successfully",
  "data": {
    "auctions": [
      {
        "auctionId": "auction-456",
        "orderId": "order-123",
        "service": "PLUMBING",
        "city": "Bogota",
        "description": "Leaking pipe repair",
        "publishedAt": "2025-01-15T10:00:00Z",
        "expiresAt": "2025-01-16T10:00:00Z",
        "currentOffers": 3
      }
    ]
  },
  "traceId": "uuid"
}

Example:

curl http://localhost:3000/api/provider/auctions \
  -H "Authorization: Bearer <provider-token>"

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/provider.controller.ts

POST /api/provider/auction-response

Submit offer for auction.

Authentication: Required Roles: PROVIDER

Request:

{
  "auctionId": "auction-456",
  "quotedPrice": 450000,
  "estimatedDuration": "2 hours",
  "proposedStartDate": "2025-01-18",
  "notes": "Available immediately"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Auction offer submitted successfully",
  "data": {
    "offerId": "offer-789",
    "auctionId": "auction-456",
    "submittedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Error Responses:

400: Invalid offer (expired auction, etc.)
409: Provider already submitted offer

Example:

curl -X POST http://localhost:3000/api/provider/auction-response \
  -H "Authorization: Bearer <provider-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "auctionId": "auction-456",
    "quotedPrice": 450000,
    "estimatedDuration": "2 hours"
  }'

GET /api/provider/orders

Get provider’s assigned orders.

Authentication: Required Roles: PROVIDER

Success Response (200):

{
  "statusCode": 200,
  "message": "Provider orders retrieved successfully",
  "data": {
    "orders": [
      {
        "orderId": "order-123",
        "status": "IN_PROGRESS",
        "service": "PLUMBING",
        "address": "123 Main St",
        "scheduledDate": "2025-01-18",
        "assignedAt": "2025-01-15T10:30:00Z"
      }
    ]
  },
  "traceId": "uuid"
}

Example:

curl http://localhost:3000/api/provider/orders \
  -H "Authorization: Bearer <provider-token>"

POST /api/provider/confirm-work-start

Confirm work has started on assigned order.

Authentication: Required Roles: PROVIDER

Request:

{
  "orderId": "order-123",
  "startedAt": "2025-01-18T09:00:00Z",
  "notes": "Arrived on site, starting work"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Work start confirmed",
  "data": {
    "orderId": "order-123",
    "status": "WORK_IN_PROGRESS",
    "startedAt": "2025-01-18T09:00:00Z"
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/provider/confirm-work-start \
  -H "Authorization: Bearer <provider-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "startedAt": "2025-01-18T09:00:00Z"
  }'

POST /api/provider/initial-inspection

Submit initial inspection report.

Authentication: Required Roles: PROVIDER

Request:

{
  "orderId": "order-123",
  "findings": "Found additional damage to adjacent pipes",
  "additionalWorkRequired": true,
  "additionalCost": 150000,
  "photos": [
    "https://storage.azure.com/photo1.jpg",
    "https://storage.azure.com/photo2.jpg"
  ]
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Initial inspection submitted",
  "data": {
    "inspectionId": "inspection-999",
    "orderId": "order-123",
    "submittedAt": "2025-01-18T09:30:00Z",
    "requiresApproval": true
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/provider/initial-inspection \
  -H "Authorization: Bearer <provider-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "findings": "Additional damage found"
  }'

POST /api/provider/work-completion-report

Submit work completion report.

Authentication: Required Roles: PROVIDER

Request:

{
  "orderId": "order-123",
  "workCompleted": "Replaced damaged pipe section, tested for leaks",
  "completedAt": "2025-01-18T12:00:00Z",
  "photos": [
    "https://storage.azure.com/after1.jpg",
    "https://storage.azure.com/after2.jpg"
  ],
  "notes": "All work completed successfully"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Work completion report submitted",
  "data": {
    "reportId": "report-888",
    "orderId": "order-123",
    "status": "PENDING_CLIENT_APPROVAL",
    "submittedAt": "2025-01-18T12:00:00Z"
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/provider/work-completion-report \
  -H "Authorization: Bearer <provider-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "workCompleted": "Pipe replaced successfully",
    "completedAt": "2025-01-18T12:00:00Z"
  }'

POST /api/provider/final-report

Submit final report after client approval.

Authentication: Required Roles: PROVIDER

Request:

{
  "orderId": "order-123",
  "finalNotes": "Client satisfied with work",
  "totalCost": 450000,
  "warranty": "6 months on parts and labor"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Final report submitted",
  "data": {
    "reportId": "final-777",
    "orderId": "order-123",
    "submittedAt": "2025-01-18T13:00:00Z"
  },
  "traceId": "uuid"
}

POST /api/provider/final-delivery

Submit final delivery confirmation.

Authentication: Required Roles: PROVIDER

Request:

{
  "orderId": "order-123",
  "deliveredAt": "2025-01-18T13:30:00Z",
  "clientSignature": "base64-encoded-signature",
  "notes": "Customer satisfied, invoice provided"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Final delivery confirmed",
  "data": {
    "orderId": "order-123",
    "status": "COMPLETED",
    "deliveredAt": "2025-01-18T13:30:00Z"
  },
  "traceId": "uuid"
}

PATCH /api/provider/update

Update provider profile.

Authentication: Required Roles: PROVIDER

Request:

{
  "companyName": "ABC Plumbing Services",
  "phone": "+573009876543",
  "serviceAreas": ["Bogota", "Medellin"],
  "specialties": ["PLUMBING", "ELECTRICAL"]
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Provider profile updated",
  "data": {
    "providerId": "provider-456",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Auction Endpoints

POST /api/auction/publish

Publish new auction.

Authentication: Required Roles: ADMIN, AGENT

Request:

{
  "orderId": "order-123",
  "expiresAt": "2025-01-16T10:00:00Z",
  "targetProviderCategories": ["PLUMBING"],
  "targetCities": ["Bogota"],
  "minProviderRating": 4.0
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Auction published successfully",
  "data": {
    "auctionId": "auction-456",
    "orderId": "order-123",
    "publishedAt": "2025-01-15T10:00:00Z",
    "expiresAt": "2025-01-16T10:00:00Z"
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/auction/publish \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "expiresAt": "2025-01-16T10:00:00Z"
  }'

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/auction.controller.ts

GET /api/auction/list

List all Activo auctions.

Authentication: Required

Success Response (200):

{
  "statusCode": 200,
  "message": "Auctions retrieved successfully",
  "data": {
    "auctions": [
      {
        "auctionId": "auction-456",
        "orderId": "order-123",
        "service": "PLUMBING",
        "status": "ACTIVE",
        "publishedAt": "2025-01-15T10:00:00Z",
        "expiresAt": "2025-01-16T10:00:00Z",
        "offerCount": 3
      }
    ]
  },
  "traceId": "uuid"
}

Example:

curl http://localhost:3000/api/auction/list \
  -H "Authorization: Bearer <token>"

GET /api/auction/list-finished

List finished auctions.

Authentication: Required

Success Response (200):

{
  "statusCode": 200,
  "message": "Finished auctions retrieved successfully",
  "data": {
    "auctions": [
      {
        "auctionId": "auction-123",
        "orderId": "order-456",
        "status": "CLOSED",
        "winningOffer": {
          "providerId": "provider-789",
          "quotedPrice": 450000
        },
        "closedAt": "2025-01-14T15:00:00Z"
      }
    ]
  },
  "traceId": "uuid"
}

GET /api/auction/:auctionId

Get auction details.

Authentication: Required

URL Parameters:

auctionId: Auction identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Auction details retrieved successfully",
  "data": {
    "auctionId": "auction-456",
    "orderId": "order-123",
    "status": "ACTIVE",
    "service": "PLUMBING",
    "publishedAt": "2025-01-15T10:00:00Z",
    "expiresAt": "2025-01-16T10:00:00Z",
    "offerCount": 3,
    "orderDetails": {
      "description": "Leaking pipe repair",
      "address": "123 Main St",
      "city": "Bogota"
    }
  },
  "traceId": "uuid"
}

GET /api/auction/:auctionId/offers

List offers for auction.

Authentication: Required Roles: ADMIN, AGENT

URL Parameters:

auctionId: Auction identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Auction offers retrieved successfully",
  "data": {
    "offers": [
      {
        "offerId": "offer-789",
        "providerId": "provider-456",
        "providerName": "ABC Plumbing",
        "providerRating": 4.8,
        "quotedPrice": 450000,
        "estimatedDuration": "2 hours",
        "submittedAt": "2025-01-15T11:00:00Z"
      }
    ]
  },
  "traceId": "uuid"
}

POST /api/auction/:auctionId/offer

Create auction offer (for providers).

Authentication: Required Roles: PROVIDER

URL Parameters:

auctionId: Auction identifier

Request:

{
  "quotedPrice": 450000,
  "estimatedDuration": "2 hours",
  "proposedStartDate": "2025-01-18",
  "notes": "Experienced with similar repairs"
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Auction offer created successfully",
  "data": {
    "offerId": "offer-789",
    "auctionId": "auction-456",
    "submittedAt": "2025-01-15T11:00:00Z"
  },
  "traceId": "uuid"
}

PATCH /api/auction/:auctionId/offer

Edit existing auction offer.

Authentication: Required Roles: PROVIDER

URL Parameters:

auctionId: Auction identifier

Request:

{
  "quotedPrice": 420000,
  "estimatedDuration": "1.5 hours",
  "notes": "Updated pricing"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Auction offer updated successfully",
  "data": {
    "offerId": "offer-789",
    "updatedAt": "2025-01-15T11:30:00Z"
  },
  "traceId": "uuid"
}

POST /api/auction/:auctionId/assign-provider

Assign provider to auction (select winning bid).

Authentication: Required Roles: ADMIN, AGENT

URL Parameters:

auctionId: Auction identifier

Request:

{
  "offerId": "offer-789",
  "providerId": "provider-456"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Provider assigned successfully",
  "data": {
    "auctionId": "auction-456",
    "orderId": "order-123",
    "assignedProviderId": "provider-456",
    "assignedAt": "2025-01-15T12:00:00Z"
  },
  "traceId": "uuid"
}

POST /api/auction/inflate-offer-Valors

Apply inflation adjustment to offer Valors.

Authentication: Required Roles: ADMIN

Request:

{
  "inflationRate": 3.5,
  "effectiveDate": "2025-02-01"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Inflation applied successfully",
  "data": {
    "updatedOffers": 150,
    "inflationRate": 3.5
  },
  "traceId": "uuid"
}

POST /api/auction/upload-Documento

Upload Documento related to auction.

Authentication: Required

Request (multipart/form-data):

file: <binary-file-data>
auctionId: "auction-456"
documentType: "QUOTE"

Success Response (201):

{
  "statusCode": 201,
  "message": "Document uploaded successfully",
  "data": {
    "documentId": "doc-999",
    "url": "https://storage.azure.com/...",
    "uploadedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Client Endpoints

All client Endpoints require authentication with CLIENT role.

GET /api/client/orders

Get orders for authenticated client.

Authentication: Required Roles: CLIENT

Success Response (200):

{
  "statusCode": 200,
  "message": "Client orders retrieved successfully",
  "data": {
    "orders": [
      {
        "orderId": "order-123",
        "status": "IN_PROGRESS",
        "service": "PLUMBING",
        "createdAt": "2025-01-15T10:00:00Z"
      }
    ]
  },
  "traceId": "uuid"
}

Example:

curl http://localhost:3000/api/client/orders \
  -H "Authorization: Bearer <client-token>"

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/client.controller.ts

POST /api/client/submit-approval

Submit approval for quote or Completod work.

Authentication: Required Roles: CLIENT

Request:

{
  "orderId": "order-123",
  "approvalType": "QUOTE",
  "approved": true,
  "comments": "Pricing is acceptable, proceed with work"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Approval submitted successfully",
  "data": {
    "orderId": "order-123",
    "approvalStatus": "APPROVED",
    "submittedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/client/submit-approval \
  -H "Authorization: Bearer <client-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "approvalType": "QUOTE",
    "approved": true
  }'

POST /api/client/request-changes

Request changes to work or quote.

Authentication: Required Roles: CLIENT

Request:

{
  "orderId": "order-123",
  "requestType": "WORK_REVISION",
  "description": "Please fix leak in adjacent pipe as well",
  "priority": "HIGH"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Change request submitted successfully",
  "data": {
    "requestId": "request-888",
    "orderId": "order-123",
    "submittedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

POST /api/client/rate-provider

Rate provider after service completion.

Authentication: Required Roles: CLIENT

Request:

{
  "orderId": "order-123",
  "providerId": "provider-456",
  "rating": 5,
  "comment": "Excellent service, very professional",
  "categories": {
    "punctuality": 5,
    "quality": 5,
    "communication": 5,
    "cleanliness": 4
  }
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Provider rating submitted successfully",
  "data": {
    "ratingId": "rating-777",
    "providerId": "provider-456",
    "submittedAt": "2025-01-18T14:00:00Z"
  },
  "traceId": "uuid"
}

Documento Management Endpoints

POST /api/Documento/upload

Upload Documento.

Authentication: Required

Request (multipart/form-data):

file: <binary-file-data>
orderId: "order-123"
documentType: "INVOICE"

Success Response (201):

{
  "statusCode": 201,
  "message": "Document uploaded successfully",
  "data": {
    "documentId": "doc-999",
    "url": "https://storage.azure.com/documents/doc-999.pdf",
    "uploadedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Example:

curl -X POST http://localhost:3000/api/document/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@invoice.pdf" \
  -F "orderId=order-123" \
  -F "documentType=INVOICE"

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/Documento.controller.ts

GET /api/Documento/:DocumentoId

Get Documento by ID.

Authentication: Required

URL Parameters:

DocumentoId: Documento identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Document retrieved successfully",
  "data": {
    "documentId": "doc-999",
    "orderId": "order-123",
    "type": "INVOICE",
    "url": "https://storage.azure.com/documents/doc-999.pdf",
    "uploadedBy": "provider-456",
    "uploadedAt": "2025-01-15T10:30:00Z",
    "status": "ACTIVE"
  },
  "traceId": "uuid"
}

GET /api/Documento/order/:orderId

Get all Documentos for an order.

Authentication: Required

URL Parameters:

orderId: Order identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Documents retrieved successfully",
  "data": {
    "documents": [
      {
        "documentId": "doc-999",
        "type": "QUOTE",
        "url": "https://storage.azure.com/...",
        "uploadedAt": "2025-01-15T10:00:00Z"
      },
      {
        "documentId": "doc-998",
        "type": "INVOICE",
        "url": "https://storage.azure.com/...",
        "uploadedAt": "2025-01-18T13:00:00Z"
      }
    ]
  },
  "traceId": "uuid"
}

PATCH /api/Documento/:DocumentoId/Estado

Update Documento Estado.

Authentication: Required Roles: ADMIN, AGENT

URL Parameters:

DocumentoId: Documento identifier

Request:

{
  "status": "ARCHIVED"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Document status updated",
  "data": {
    "documentId": "doc-999",
    "status": "ARCHIVED",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

DELETE /api/Documento/:DocumentoId

Delete Documento.

Authentication: Required Roles: ADMIN

URL Parameters:

DocumentoId: Documento identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Document deleted successfully",
  "data": {
    "documentId": "doc-999",
    "deletedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

POST /api/Documento/generate-order-pdf

Generate PDF Documento for order.

Authentication: Required

Request:

{
  "orderId": "order-123",
  "documentType": "INVOICE",
  "includeDetails": true
}

Success Response (201):

{
  "statusCode": 201,
  "message": "PDF generated successfully",
  "data": {
    "documentId": "doc-888",
    "url": "https://storage.azure.com/pdfs/invoice-order-123.pdf",
    "generatedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

GET /api/Documento/Resumen/:orderId

Get Documentos Resumen for order.

Authentication: Required

URL Parameters:

orderId: Order identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Document summary retrieved successfully",
  "data": {
    "orderId": "order-123",
    "totalDocuments": 5,
    "byType": {
      "QUOTE": 1,
      "INVOICE": 1,
      "PHOTO": 3
    },
    "latestDocument": {
      "documentId": "doc-999",
      "type": "INVOICE",
      "uploadedAt": "2025-01-18T13:00:00Z"
    }
  },
  "traceId": "uuid"
}

Notification Endpoints

POST /api/notification

Create notification.

Authentication: Required

Request:

{
  "userId": "user-123",
  "type": "ORDER_UPDATE",
  "title": "Order Status Updated",
  "message": "Your order is now in progress",
  "data": {
    "orderId": "order-123",
    "newStatus": "IN_PROGRESS"
  }
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Notification created successfully",
  "data": {
    "notificationId": "notif-777",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/notification.controller.ts

GET /api/notification/:notificationId

Get notification by ID.

Authentication: Required

URL Parameters:

notificationId: Notification identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Notification retrieved successfully",
  "data": {
    "notificationId": "notif-777",
    "type": "ORDER_UPDATE",
    "title": "Order Status Updated",
    "message": "Your order is now in progress",
    "read": false,
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

GET /api/notification/user/:userId

Get notifications for user.

Authentication: Required

URL Parameters:

userId: User identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Notifications retrieved successfully",
  "data": {
    "notifications": [
      {
        "notificationId": "notif-777",
        "type": "ORDER_UPDATE",
        "title": "Order Status Updated",
        "read": false,
        "createdAt": "2025-01-15T10:30:00Z"
      }
    ],
    "unreadCount": 3
  },
  "traceId": "uuid"
}

PATCH /api/notification/:notificationId/read

Mark notification as read.

Authentication: Required

URL Parameters:

notificationId: Notification identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Notification marked as read",
  "data": {
    "notificationId": "notif-777",
    "read": true,
    "readAt": "2025-01-15T10:35:00Z"
  },
  "traceId": "uuid"
}

Asset Management Endpoints

POST /api/assets

Create asset.

Authentication: Required

Request:

{
  "companyId": "company-123",
  "assetType": "VEHICLE",
  "brand": "Toyota",
  "model": "Corolla 2020",
  "serialNumber": "VIN123456789",
  "condition": "EXCELLENT",
  "purchaseDate": "2020-01-15",
  "purchasePrice": 80000000,
  "notes": "Company vehicle for field operations"
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Asset created successfully",
  "data": {
    "assetId": "asset-999",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/assets.controller.ts

GET /api/assets/:assetId

Get asset by ID.

Authentication: Required

URL Parameters:

assetId: Asset identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Asset retrieved successfully",
  "data": {
    "assetId": "asset-999",
    "companyId": "company-123",
    "assetType": "VEHICLE",
    "brand": "Toyota",
    "model": "Corolla 2020",
    "condition": "EXCELLENT",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

PATCH /api/assets/:assetId

Update asset.

Authentication: Required

URL Parameters:

assetId: Asset identifier

Request:

{
  "condition": "GOOD",
  "notes": "Minor wear and tear from regular use"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Asset updated successfully",
  "data": {
    "assetId": "asset-999",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

DELETE /api/assets/:assetId

Delete asset.

Authentication: Required Roles: ADMIN

URL Parameters:

assetId: Asset identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Asset deleted successfully",
  "data": {
    "assetId": "asset-999",
    "deletedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

GET /api/assets/company/:companyId

Get assets for company.

Authentication: Required

URL Parameters:

companyId: Company identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Company assets retrieved successfully",
  "data": {
    "assets": [
      {
        "assetId": "asset-999",
        "assetType": "VEHICLE",
        "brand": "Toyota",
        "model": "Corolla 2020",
        "condition": "EXCELLENT"
      }
    ],
    "totalValue": 80000000
  },
  "traceId": "uuid"
}

POST /api/assets/generate-cv

Generate asset CV (curriculum vitae).

Authentication: Required

Request:

{
  "assetId": "asset-999",
  "includeMaintenanceHistory": true,
  "includeFinancialInfo": false
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Asset CV generated successfully",
  "data": {
    "cvUrl": "https://storage.azure.com/cvs/asset-999-cv.pdf",
    "generatedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

POST /api/assets/find-by-details

Find asset by details.

Authentication: Required

Request:

{
  "brand": "Toyota",
  "model": "Corolla",
  "serialNumber": "VIN123"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Assets found",
  "data": {
    "assets": [
      {
        "assetId": "asset-999",
        "brand": "Toyota",
        "model": "Corolla 2020",
        "serialNumber": "VIN123456789"
      }
    ],
    "matchCount": 1
  },
  "traceId": "uuid"
}

Company and Employee Endpoints

POST /api/company/register

Authentication: Not required

Request:

{
  "nit": "900123456-7",
  "name": "ABC Company S.A.S.",
  "address": "Calle 123 #45-67",
  "city": "Bogota",
  "phone": "+573001234567",
  "email": "contact@abccompany.com",
  "legalRepresentative": "John Doe"
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Company registered successfully",
  "data": {
    "companyId": "company-123",
    "nit": "900123456-7",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/company.controller.ts

GET /api/company/:nit

Get company by NIT.

Authentication: Required

URL Parameters:

nit: Company NIT (Tax ID)

Success Response (200):

{
  "statusCode": 200,
  "message": "Company retrieved successfully",
  "data": {
    "companyId": "company-123",
    "nit": "900123456-7",
    "name": "ABC Company S.A.S.",
    "address": "Calle 123 #45-67",
    "city": "Bogota",
    "employeeCount": 25,
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

GET /api/company/list

List all companies.

Authentication: Required Roles: ADMIN, AGENT

Success Response (200):

{
  "statusCode": 200,
  "message": "Companies retrieved successfully",
  "data": {
    "companies": [
      {
        "companyId": "company-123",
        "nit": "900123456-7",
        "name": "ABC Company S.A.S.",
        "employeeCount": 25
      }
    ]
  },
  "traceId": "uuid"
}

POST /api/employee/register

Authentication: Not required

Request:

{
  "email": "employee@company.com",
  "name": "Jane Smith",
  "identification": "9876543210",
  "phone": "+573009876543",
  "password": "SecurePass123!",
  "companyNit": "900123456-7"
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Employee registered successfully",
  "data": {
    "userId": "user-789",
    "companyId": "company-123",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/employee.controller.ts

POST /api/employee/send-otp

Send OTP to employee.

Authentication: Not required

Request:

{
  "email": "employee@company.com"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "OTP sent successfully",
  "data": {
    "email": "employee@company.com"
  },
  "traceId": "uuid"
}

POST /api/employee/validate-otp

Validate employee OTP.

Authentication: Not required

Request:

{
  "email": "employee@company.com",
  "code": "123456"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "OTP validated successfully",
  "data": {
    "verified": true
  },
  "traceId": "uuid"
}

GET /api/employee/by-nit/:nit

Get employees by company NIT.

Authentication: Required

URL Parameters:

nit: Company NIT

Success Response (200):

{
  "statusCode": 200,
  "message": "Employees retrieved successfully",
  "data": {
    "employees": [
      {
        "userId": "user-789",
        "name": "Jane Smith",
        "email": "employee@company.com",
        "role": "EMPLOYEE",
        "createdAt": "2025-01-15T10:30:00Z"
      }
    ],
    "totalEmployees": 25
  },
  "traceId": "uuid"
}

Service and Technician Endpoints

GET /api/service/list

List all services.

Authentication: Required

Success Response (200):

{
  "statusCode": 200,
  "message": "Services retrieved successfully",
  "data": {
    "services": [
      {
        "serviceId": "service-123",
        "name": "PLUMBING",
        "description": "Plumbing services",
        "category": "HOME_REPAIR"
      },
      {
        "serviceId": "service-456",
        "name": "ELECTRICAL",
        "description": "Electrical services",
        "category": "HOME_REPAIR"
      }
    ]
  },
  "traceId": "uuid"
}

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/service.controller.ts

POST /api/service/associate-provider

Associate service with provider.

Authentication: Required Roles: ADMIN, AGENT

Request:

{
  "serviceId": "service-123",
  "providerId": "provider-456"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Service associated with provider successfully",
  "data": {
    "serviceId": "service-123",
    "providerId": "provider-456",
    "associatedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

GET /api/technician/list

List all technicians.

Authentication: Required Roles: ADMIN, AGENT

Success Response (200):

{
  "statusCode": 200,
  "message": "Technicians retrieved successfully",
  "data": {
    "technicians": [
      {
        "technicianId": "tech-123",
        "name": "Carlos Rodriguez",
        "specialties": ["PLUMBING", "ELECTRICAL"],
        "rating": 4.9,
        "availableNow": true
      }
    ]
  },
  "traceId": "uuid"
}

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/technician.controller.ts

POST /api/technician/assign-order

Assign order to technician.

Authentication: Required Roles: ADMIN, AGENT

Request:

{
  "orderId": "order-123",
  "technicianId": "tech-123"
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Order assigned to technician successfully",
  "data": {
    "orderId": "order-123",
    "technicianId": "tech-123",
    "assignedAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Messages and Chat Endpoints

POST /api/messages

Create message.

Authentication: Required

Request:

{
  "conversationId": "conv-123",
  "senderId": "user-123",
  "content": "When will the work be completed?",
  "type": "TEXT"
}

Success Response (201):

{
  "statusCode": 201,
  "message": "Message created successfully",
  "data": {
    "messageId": "msg-777",
    "conversationId": "conv-123",
    "sentAt": "2025-01-15T10:30:00Z"
  },
  "traceId": "uuid"
}

Reference: algesta-api-gateway-nestjs/src/infrastructure/controllers/messages.controller.ts

GET /api/messages/:messageId

Get message by ID.

Authentication: Required

URL Parameters:

messageId: Message identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Message retrieved successfully",
  "data": {
    "messageId": "msg-777",
    "conversationId": "conv-123",
    "senderId": "user-123",
    "content": "When will the work be completed?",
    "type": "TEXT",
    "sentAt": "2025-01-15T10:30:00Z",
    "read": false
  },
  "traceId": "uuid"
}

GET /api/messages/conversation/:conversationId

Get messages for conversation.

Authentication: Required

URL Parameters:

conversationId: Conversation identifier

Success Response (200):

{
  "statusCode": 200,
  "message": "Messages retrieved successfully",
  "data": {
    "messages": [
      {
        "messageId": "msg-777",
        "senderId": "user-123",
        "content": "When will the work be completed?",
        "sentAt": "2025-01-15T10:30:00Z"
      },
      {
        "messageId": "msg-776",
        "senderId": "provider-456",
        "content": "Work will be completed by tomorrow",
        "sentAt": "2025-01-15T10:32:00Z"
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1
    }
  },
  "traceId": "uuid"
}

PATCH /api/messages/:messageId

Update message.

Authentication: Required

URL Parameters:

messageId: Message identifier

Request:

{
  "content": "When will the work be completed? (Updated)",
  "edited": true
}

Success Response (200):

{
  "statusCode": 200,
  "message": "Message updated successfully",
  "data": {
    "messageId": "msg-777",
    "updatedAt": "2025-01-15T10:35:00Z"
  },
  "traceId": "uuid"
}

Health Check Endpoints

GET /health

Gateway health check (no authentication required).

Success Response (200):

{
  "status": "healthy",
  "service": "api-gateway",
  "timestamp": "2025-01-15T10:30:00Z",
  "uptime": 3600,
  "version": "1.0.0",
  "environment": "production"
}

Example:

curl http://localhost:3000/health

Reference: algesta-api-gateway-nestjs/src/main.ts

GET /api/health/services

Check all Microservicios health (authentication required).

Authentication: Required

Success Response (200):

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "services": [
    {
      "service": "ms-auth",
      "status": "healthy",
      "responseTime": 45,
      "url": "http://ms-auth:3001/health"
    },
    {
      "service": "ms-orders",
      "status": "healthy",
      "responseTime": 32,
      "url": "http://ms-orders:3004/health"
    }
  ],
  "summary": {
    "total": 5,
    "healthy": 5,
    "degraded": 0,
    "unhealthy": 0
  }
}

Example:

curl http://localhost:3000/api/health/services \
  -H "Authorization: Bearer <token>"

Common Response Formats

Success Response

All successful responses follow this structure:

{
  "statusCode": 200,
  "message": "Operation successful",
  "timestamp": "2025-01-15T10:30:00Z",
  "path": "/api/orders",
  "method": "GET",
  "data": {
    /* Response data */
  },
  "traceId": "550e8400-e29b-41d4-a716-446655440000"
}

Error Response

All error responses follow this structure:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "BadRequestException",
  "timestamp": "2025-01-15T10:30:00Z",
  "path": "/api/orders",
  "traceId": "550e8400-e29b-41d4-a716-446655440000"
}

Pagination Format

Paginated responses include pagination metadata:

{
  "statusCode": 200,
  "message": "Results retrieved successfully",
  "data": {
    "results": [ /* Array of items */ ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10,
      "totalPages": 10
    }
  },
  "traceId": "uuid"
}

HTTP Estado Codes

The API uses standard HTTP Estado codes:

Estado Code	Meaning	Usage
200 OK	Success	Successful GET, PATCH, DELETE
201 Created	Resource created	Successful POST
400 Bad Request	Invalid request	Validation error, malformed JSON
401 Unauthorized	Authentication failed	Missing/invalid/expired token
403 Forbidden	Insufficient permissions	User lacks required role, email not verified
404 Not Found	Resource not found	Requested resource doesn’t exist
409 Conflict	Resource conflict	Resource already exists
422 Unprocessable Entity	Business logic error	Valid request but business rules prevent operation
500 Internal Server Error	Server error	Unexpected error
503 Service Unavailable	Service unavailable	Microservicio down, circuit breaker open
504 Gateway Timeout	Timeout	Microservicio timeout

Request Examples

Completo Workflow: Create Order, Publish Auction, Assign Provider

Step 1: Register and Login

# Register user
curl -X POST http://localhost:3000/api/auth/register-web \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "name": "Client User",
    "identification": "1234567890",
    "phone": "+573001234567",
    "password": "ClientPass123!",
    "isEmployee": false
  }'

# Login
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client@example.com",
    "password": "ClientPass123!"
  }'

# Save token
export TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Step 2: Create Order

curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "channel": "WEB",
    "service": "PLUMBING",
    "address": "123 Main Street",
    "city": "Bogota",
    "description": "Leaking kitchen pipe",
    "phoneNumber": "+573001234567",
    "nameContact": "Client User",
    "emailContact": "client@example.com",
    "priority": "HIGH"
  }'

# Response: { "data": { "orderId": "order-123", ... } }
export ORDER_ID="order-123"

Step 3: Agent Updates Order (ADMIN/AGENT token)

curl -X PATCH http://localhost:3000/api/orders/$ORDER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "IN_EVALUATION",
    "notes": "Evaluated, ready for auction"
  }'

Step 4: Publish Auction

curl -X PATCH http://localhost:3000/api/orders/publish/$ORDER_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Response: { "data": { "auctionId": "auction-456", ... } }
export AUCTION_ID="auction-456"

Step 5: Provider Submits Offer (PROVIDER token)

curl -X POST http://localhost:3000/api/provider/auction-response \
  -H "Authorization: Bearer $PROVIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auctionId": "'"$AUCTION_ID"'",
    "quotedPrice": 450000,
    "estimatedDuration": "2 hours"
  }'

# Response: { "data": { "offerId": "offer-789", ... } }
export OFFER_ID="offer-789"

Step 6: Assign Provider to Order

curl -X POST http://localhost:3000/api/auction/$AUCTION_ID/assign-provider \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": "'"$OFFER_ID"'",
    "providerId": "provider-456"
  }'

Step 7: Provider Confirms Work Start

curl -X POST http://localhost:3000/api/provider/confirm-work-start \
  -H "Authorization: Bearer $PROVIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "'"$ORDER_ID"'",
    "startedAt": "2025-01-18T09:00:00Z"
  }'

Step 8: Client Approves Work

curl -X POST http://localhost:3000/api/client/submit-approval \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "'"$ORDER_ID"'",
    "approvalType": "WORK_COMPLETION",
    "approved": true
  }'

Step 9: Client Rates Provider

curl -X POST http://localhost:3000/api/client/rate-provider \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "'"$ORDER_ID"'",
    "providerId": "provider-456",
    "rating": 5,
    "comment": "Excellent service!"
  }'

Rate Limiting and Quotas

Current Estado: Not implemented

Recommendation: Implement rate limiting per user/IP address

Suggested Limits:

Authenticated users: 100 requests per minute
Unauthenticated Endpoints: 20 requests per minute
Authentication Endpoints: 5 requests per 15 minutes (login, password reset)

API Versioning

Current Estado: Not implemented (all Endpoints implicitly v1)

Recommendation: Implement versioning strategy

Options:

URL-based: /api/v1/orders, /api/v2/orders
Header-based: Accept: application/vnd.algesta.v1+json

Deprecation Policy

Current Estado: No formal policy

Recommendation:

Announce deprecations 6 months in advance
Include deprecation warnings in response headers
Maintain deprecated Endpoints for minimum 12 months
Provide migration Guías

Referencias Cruzadas

Main Gateway Documentoation: API Gateway Arquitectura
Authentication Details: API Gateway Authentication
Resilience Patterns: API Gateway Resilience
Inter-Service Communication: Inter-Service Communication
Backend Microservicios: Backend Microservicios Descripción General

Swagger/OpenAPI

For interActivo API Documentoation and Pruebas:

Development: http://localhost:3000/api/docs
Production: https://api.algesta.com/api/docs

Resumen

This API reference provides comprehensive Documentoation for all API Gateway Endpoints. Each Endpoint includes authentication Requisitos, request/response formats, Estado codes, and executable examples.

Key Funcionalidades:

RESTful design with standard HTTP Métodos
Consistent response format with traceId
Role-based access control
Comprehensive error handling
InterActivo Swagger Documentoation

Quick Start:

Register user: POST /api/auth/register-web
Login: POST /api/auth/login
Use returned JWT token in Authorization: Bearer <token> header
Access protected Endpoints

For detailed authentication flows, see API Gateway Authentication.

For error handling and resilience patterns, see API Gateway Resilience.