Proveedores API

The Proveedores (Suppliers) API provides complete CRUD operations for managing supplier information in the POS system. Suppliers are registered with their business details, contact information, and are linked to cities for geographical organization.

Endpoints Overview

Method	Endpoint	Authentication	Description
POST	`/api/pos/proveedor`	Required	Create a new supplier
GET	`/api/pos/proveedor`	Required	Get all suppliers with pagination
GET	`/api/pos/proveedor/search`	Required	Search suppliers by name or RUC
GET	`/api/pos/proveedor/:id`	Required	Get supplier by ID
PUT	`/api/pos/proveedor/:id`	Required	Update supplier information
DELETE	`/api/pos/proveedor/:id`	Required	Soft delete supplier (marks as inactive)

POST /api/pos/proveedor

Create a new supplier in the system. All fields are validated using the proveedor DTO schema before insertion.

All authenticated requests must include a valid JWT token in the Authorization header.

Request

prv_razonsocial

string

required

Company business name. Must be between 7 and 120 characters.

prv_ruc

string

required

Tax identification number (RUC). Must be exactly 13 numeric digits. Must be unique across all suppliers.

prv_telefono

string

required

Landline phone number. Maximum 10 numeric digits.

prv_celular

string

required

Mobile phone number. Maximum 9 numeric digits.

prv_mail

string

required

Email address. Must be valid email format, maximum 60 characters.

prv_direccion

string

required

Physical address. Between 5 and 60 characters.

ct_codigo

string

required

City code (foreign key). Must reference a valid city in the database.

prv_estado

string

required

Supplier status. Valid values: ACT (Active), INA (Inactive). Defaults to ACT.

prv_fecha_alta

date

Registration date. Defaults to current date if not provided.

Response

prv_codigo

string

Auto-generated unique supplier code

prv_razonsocial

string

Company business name

prv_ruc

string

Tax identification number

prv_telefono

string

Landline phone number

prv_celular

string

Mobile phone number

prv_mail

string

Email address

prv_direccion

string

Physical address

ct_codigo

string

City code

prv_estado

string

Supplier status (ACT/INA)

prv_fecha_alta

date

Registration date

Example Request

curl -X POST http://localhost:3000/api/pos/proveedor \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "prv_razonsocial": "DISTRIBUIDORA ALIMENTICIA GARCIA S.A.",
    "prv_ruc": "1234567890001",
    "prv_telefono": "0987654321",
    "prv_celular": "098765432",
    "prv_mail": "[email protected]",
    "prv_direccion": "Av. Principal 123 y Secundaria",
    "ct_codigo": "CT001",
    "prv_estado": "ACT",
    "prv_fecha_alta": "2024-03-04"
  }'

Response Examples

Success Response (201 Created)

{
  "prv_codigo": "PRV000123",
  "prv_razonsocial": "DISTRIBUIDORA ALIMENTICIA GARCIA S.A.",
  "prv_ruc": "1234567890001",
  "prv_telefono": "0987654321",
  "prv_celular": "098765432",
  "prv_mail": "[email protected]",
  "prv_direccion": "Av. Principal 123 y Secundaria",
  "ct_codigo": "CT001",
  "prv_estado": "ACT",
  "prv_fecha_alta": "2024-03-04T00:00:00.000Z"
}

Validation Error (400)

{
  "errors": [
    "El RUC debe tener exactamente 13 dígitos",
    "El correo es obligatorio"
  ]
}

Validation errors are returned as an array when the request body doesn’t meet DTO validation requirements.

Duplicate RUC (400)

{
  "message": "Ese RUC o Razón Social ya se encuentra registrado.",
  "detail": "duplicate key value violates unique constraint",
  "code": "23505"
}

This error occurs when attempting to create a supplier with a RUC or business name that already exists in the database.

Invalid City (400)

{
  "message": "La ciudad seleccionada no es válida.",
  "detail": "insert or update on table violates foreign key constraint",
  "code": "23503"
}

GET /api/pos/proveedor

Retrieve a paginated list of all active suppliers. Supports search functionality by business name or RUC.

Query Parameters

page

integer

default:"1"

Page number for pagination

limit

integer

default:"10"

Number of records per page

string

Search term to filter by business name or RUC (case-insensitive)

Response

data

array

Array of supplier objects

Show supplier object

prv_codigo

string

Supplier code

prv_razonsocial

string

Company business name

prv_ruc

string

Tax identification number

prv_telefono

string

Landline phone

prv_celular

string

Mobile phone

prv_mail

string

Email address

prv_direccion

string

Physical address

prv_estado

string

Status (ACT/INA)

ct_codigo

string

City code

ciudad_nombre

string

City name (joined from ciudad table)

total

integer

Total number of suppliers matching the search criteria

page

integer

Current page number

totalPages

integer

Total number of pages

limit

integer

Number of records per page

Example Request

curl -X GET "http://localhost:3000/api/pos/proveedor?page=1&limit=10&search=garcia" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response Example

Success Response (200 OK)

{
  "data": [
    {
      "prv_codigo": "PRV000123",
      "prv_razonsocial": "DISTRIBUIDORA ALIMENTICIA GARCIA S.A.",
      "prv_ruc": "1234567890001",
      "prv_telefono": "0987654321",
      "prv_celular": "098765432",
      "prv_mail": "[email protected]",
      "prv_direccion": "Av. Principal 123 y Secundaria",
      "prv_estado": "ACT",
      "ct_codigo": "CT001",
      "ciudad_nombre": "Quito"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1,
  "limit": 10
}

GET /api/pos/proveedor/search

Fast search endpoint for finding suppliers by business name or RUC. Returns a simplified list limited to 20 results for autocomplete functionality.

This endpoint is designed for quick searches and autocomplete features. It returns only basic supplier information and is limited to 20 results.

Query Parameters

string

required

Search term to match against business name or RUC (case-insensitive)

Response

Returns an array of supplier objects with basic information:

prv_codigo

string

Supplier code

prv_razonsocial

string

Company business name

prv_ruc

string

Tax identification number

prv_estado

string

Status (ACT/INA)

Example Request

curl -X GET "http://localhost:3000/api/pos/proveedor/search?q=garcia" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response Examples

Success Response (200 OK)

[
  {
    "prv_codigo": "PRV000123",
    "prv_razonsocial": "DISTRIBUIDORA ALIMENTICIA GARCIA S.A.",
    "prv_ruc": "1234567890001",
    "prv_estado": "ACT"
  },
  {
    "prv_codigo": "PRV000456",
    "prv_razonsocial": "GARCIA HERMANOS CIA. LTDA.",
    "prv_ruc": "1234567890002",
    "prv_estado": "ACT"
  }
]

Missing Parameter (400)

{
  "message": "Parámetro q es requerido"
}

GET /api/pos/proveedor/:id

Retrieve detailed information for a specific supplier by their unique code.

Path Parameters

string

required

The unique supplier code (e.g., PRV000123)

Response

Returns the complete supplier object with all fields.

Example Request

curl -X GET http://localhost:3000/api/pos/proveedor/PRV000123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response Examples

Success Response (200 OK)

{
  "prv_codigo": "PRV000123",
  "prv_razonsocial": "DISTRIBUIDORA ALIMENTICIA GARCIA S.A.",
  "prv_ruc": "1234567890001",
  "prv_telefono": "0987654321",
  "prv_celular": "098765432",
  "prv_mail": "[email protected]",
  "prv_direccion": "Av. Principal 123 y Secundaria",
  "ct_codigo": "CT001",
  "prv_estado": "ACT",
  "prv_fecha_alta": "2024-03-04T00:00:00.000Z"
}

Not Found (404)

{
  "message": "Proveedor no encontrado"
}

PUT /api/pos/proveedor/:id

Update supplier information. All fields are optional; only provided fields will be updated using COALESCE in the SQL query.

Path Parameters

string

required

The unique supplier code to update

Request

prv_razonsocial

string

Company business name (min 7 characters)

prv_ruc

string

Tax identification number (13 digits)

prv_telefono

string

Landline phone number (max 10 digits)

prv_celular

string

Mobile phone number (max 9 digits)

prv_mail

string

Email address

prv_direccion

string

Physical address

ct_codigo

string

City code

prv_estado

string

Supplier status (ACT/INA)

Response

Returns the complete updated supplier object.

Example Request

curl -X PUT http://localhost:3000/api/pos/proveedor/PRV000123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "prv_telefono": "0987654322",
    "prv_mail": "[email protected]"
  }'

Response Example

Success Response (200 OK)

{
  "prv_codigo": "PRV000123",
  "prv_razonsocial": "DISTRIBUIDORA ALIMENTICIA GARCIA S.A.",
  "prv_ruc": "1234567890001",
  "prv_telefono": "0987654322",
  "prv_celular": "098765432",
  "prv_mail": "[email protected]",
  "prv_direccion": "Av. Principal 123 y Secundaria",
  "ct_codigo": "CT001",
  "prv_estado": "ACT",
  "prv_fecha_alta": "2024-03-04T00:00:00.000Z"
}

DELETE /api/pos/proveedor/:id

Soft delete a supplier by marking it as inactive (prv_estado = ‘INA’). The supplier record is not physically removed from the database.

This is a soft delete operation. The supplier record remains in the database but is marked as inactive and will be filtered out from active supplier lists.

Path Parameters

string

required

The unique supplier code to delete

Response

Returns 204 No Content on successful deletion.

Example Request

curl -X DELETE http://localhost:3000/api/pos/proveedor/PRV000123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Error Codes

Status Code	Description
200	Request successful
201	Resource created successfully
204	Resource deleted successfully (no content)
400	Bad request - validation errors or constraint violations
404	Supplier not found
500	Internal server error

Database Constraints

Key Database Constraints:

prv_ruc and prv_razonsocial must be unique across all suppliers
ct_codigo must reference a valid city in the ciudad table
Only active suppliers (prv_estado = 'ACT') are returned in listing endpoints
Supplier codes are auto-generated by the database

Implementation Notes

The Proveedores API uses connection pooling with user-specific database credentials extracted from the JWT token. Each request:

Extracts credentials from req.user (populated by verifyToken middleware)
Creates a dedicated connection pool using those credentials
Executes the database operation
Closes the connection pool in the finally block

This ensures proper row-level security and audit trailing at the database level.

Authentication

Products & Inventory

Sales & Invoicing

Suppliers & Purchasing

Master Data

​Proveedores API

​Endpoints Overview

​POST /api/pos/proveedor

​Request

​Response

​Example Request

​Response Examples

​GET /api/pos/proveedor

​Query Parameters

​Response

​Example Request

​Response Example

​GET /api/pos/proveedor/search

​Query Parameters

​Response

​Example Request

​Response Examples

​GET /api/pos/proveedor/:id

​Path Parameters

​Response

​Example Request

​Response Examples

​PUT /api/pos/proveedor/:id

​Path Parameters

​Request

​Response

​Example Request

​Response Example

​DELETE /api/pos/proveedor/:id

​Path Parameters

​Response

​Example Request

​Error Codes

​Database Constraints

​Implementation Notes

Build docs developers (and LLMs) love

Proveedores API

Endpoints Overview

POST /api/pos/proveedor

Request

Response

Example Request

Response Examples

GET /api/pos/proveedor

Query Parameters

Response

Example Request

Response Example

GET /api/pos/proveedor/search

Query Parameters

Response

Example Request

Response Examples

GET /api/pos/proveedor/:id

Path Parameters

Response

Example Request

Response Examples

PUT /api/pos/proveedor/:id

Path Parameters

Request

Response

Example Request

Response Example

DELETE /api/pos/proveedor/:id

Path Parameters

Response

Example Request

Error Codes

Database Constraints

Implementation Notes