Service catalog endpoints: create, update, toggle, delete

The service catalog endpoints give admin roles complete control over what offerings appear in the ServiciosYa platform. Staff can create new services, update their details, toggle their visibility, and (for SUPER_ADMIN) logically delete them. Customers and admins use separate read endpoints: the admin listing exposes all services including inactive ones, while the customer-facing endpoint returns only active, non-deleted records. All endpoints are tenant-scoped — the companyID is resolved automatically from the authenticated user’s JWT claims.

POST /api/services

Creates a new service in the company’s catalog. Required role: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, or GESTOR

Request body

name

string

required

Display name of the service. Must be a non-empty string.

description

string

Optional free-text description shown to customers and staff.

referenceCode

string

Optional internal reference or SKU code for the service.

price

decimal

required

Customer-facing price in the company’s currency. Use a numeric value (e.g. 1500.00).

cost

decimal

Optional internal cost for margin tracking. Not exposed to customers.

estimatedTimeText

string

Human-readable turnaround estimate (e.g. "2 a 3 días hábiles").

category

string

required

Must be one of the valid category values. The API normalises common variations — see the category normalisation note below.Accepted canonical values: Escribania y legales, Presentacion de documentos, Pago de impuestos, patentes y otros, Traducciones legales, Delivery, Otros.

permiteAdjunto

boolean

When true, service requests for this service may include an optional file attachment beyond the payment voucher. Defaults to false.

Response

Returns 200 OK with the auto-generated service identifier.

{
  "serviceID": 42
}

Example

curl -X POST https://api.serviciosya.com/api/services \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Certificado de antecedentes penales",
    "description": "Gestión y presentación del certificado ante el organismo correspondiente.",
    "referenceCode": "CAP-001",
    "price": 2500.00,
    "cost": 800.00,
    "estimatedTimeText": "3 a 5 días hábiles",
    "category": "Presentacion de documentos",
    "permiteAdjunto": true
  }'

PUT /api/services/{id}

Updates an existing service. All writable fields are replaced with the values supplied in the request body. Required role: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, or GESTOR

Path parameter

integer

required

The serviceID of the service to update.

Request body

The body accepts the same fields as POST /api/services with the addition of serviceID, which must match the path parameter.

serviceID

integer

required

Must equal the {id} path parameter. The API returns 400 Bad Request if there is a mismatch.

name

string

required

Updated display name.

description

string

Updated description.

referenceCode

string

Updated reference code.

price

decimal

required

Updated customer-facing price.

cost

decimal

Updated internal cost.

estimatedTimeText

string

Updated estimated turnaround text.

category

string

Updated category. Subject to the same normalisation rules as creation.

permiteAdjunto

boolean

Updated attachment flag.

Response

Returns 204 No Content on success. Returns 400 Bad Request if serviceID in the body does not match the {id} path parameter.

PATCH /api/services/{id}/toggle

Toggles the isActive flag of a service. An active service becomes inactive, and an inactive service becomes active. Required role: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, or GESTOR

Path parameter

integer

required

The serviceID of the service to toggle.

Response

Returns 204 No Content on success.

Deactivating a service removes it from the customer-facing GET /api/services/available endpoint immediately. It does not affect any existing or in-progress service requests that reference it — those continue to show the service name and details from the time they were created.

DELETE /api/services/{id}

Performs a logical deletion of a service by setting isDeleted = true. The record is retained in the database but is excluded from all listings, including admin views. Required role: SUPER_ADMIN only

Logical deletion is irreversible through the API. Once deleted, a service cannot be restored via any exposed endpoint. Only SUPER_ADMIN can perform this action.

Path parameter

integer

required

The serviceID of the service to delete.

Response

Returns 204 No Content on success.

GET /api/services

Returns a paginated list of services for admin use. Includes inactive services; excludes logically deleted ones. Required role: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, or GESTOR

Query parameters

pageNumber

integer

Page index (1-based). Defaults to 1.

pageSize

integer

Number of records per page. Defaults to 10.

string

Optional free-text search applied against service name, description, and reference code.

onlyActive

boolean

When true, filters the results to active services only. Omit or set to false to include inactive services.

Response

Returns 200 OK with a paginated result object containing an array of ServiceResponse records.

Example

curl "https://api.serviciosya.com/api/services?pageNumber=1&pageSize=20&onlyActive=true&search=certificado" \
  -H "Authorization: Bearer <token>"

GET /api/services/available

Returns a paginated list of active, non-deleted services intended for customer browsing. This is the endpoint used by the Android app catalog screen. Required role: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, or CUSTOMER

Query parameters

pageNumber

integer

Page index (1-based). Defaults to 1.

pageSize

integer

Number of records per page. Defaults to 100.

string

Optional free-text search applied against service name and description.

category

string

Optional category filter. When provided, only services in the specified category are returned.

Response

Returns 200 OK with a paginated result object containing active ServiceResponse records.

The default pageSize for this endpoint is 100 (versus 10 for the admin listing) to allow the mobile app to load the full catalog in a single request for offline browsing.

GET /api/services/{id}

Returns the full detail of a single service. Required role: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, GESTOR, or CUSTOMER

Path parameter

integer

required

The serviceID to retrieve.

Response

Returns 200 OK with a ServiceResponse object. Returns 404 Not Found if the service does not exist or belongs to a different company.

GET /api/services/by-category

Returns all active, non-deleted services belonging to a specific category. Required role: SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, or CUSTOMER

Query parameters

category

string

required

The category to filter by. Must be a non-empty string. Returns 400 Bad Request if omitted or blank.

Response

Returns 200 OK with an array of ServiceResponse objects. Returns 400 Bad Request if category is missing or blank.

ServiceResponse shape

The following fields are returned in service read responses.

serviceID

integer

Unique identifier of the service.

companyID

integer

Tenant identifier.

name

string

Display name of the service.

description

string

Optional description.

referenceCode

string

Optional internal reference code.

price

decimal

Customer-facing price.

cost

decimal

Optional internal cost.

estimatedTimeText

string

Human-readable turnaround estimate.

category

string

Normalised category value.

permiteAdjunto

boolean

Whether requests for this service may include an optional attachment.

isActive

boolean

Whether the service is currently active.

createdAt

string (ISO 8601)

Timestamp of when the service was created.

Category normalisation

The API accepts several common shorthand or variant spellings and normalises them to the canonical category value before persisting. For example, sending "LEGALES" is accepted and stored as "Escribania y legales". The following aliases are recognised:

Alias accepted	Stored as
`LEGALES`	`Escribania y legales`
`DOCUMENTOS`	`Presentacion de documentos`
`COMPRAS`	`Pago de impuestos, patentes y otros`
`TRADUCCIONES LEGALES`	`Traducciones legales`
`DELIVERYS`	`Delivery`
`OTHER`	`Otros`
`OTROS`	`Otros`

Any value that does not match a canonical category or a known alias will result in a validation error from the underlying stored procedure.

Authentication

Services

Service Requests

System

Service catalog endpoints: create, update, toggle, delete

POST /api/services

Request body

Response

Example

PUT /api/services/{id}

Path parameter

Request body

Response

PATCH /api/services/{id}/toggle

Path parameter

Response

DELETE /api/services/{id}

Path parameter

Response

GET /api/services

Query parameters

Response

Example

GET /api/services/available

Query parameters

Response

GET /api/services/{id}

Path parameter

Response

GET /api/services/by-category

Query parameters

Response

ServiceResponse shape

Category normalisation

Build docs developers (and LLMs) love

Authentication

Services

Service Requests

System

Documentation Index

​POST /api/services

​Request body

​Response

​Example

​PUT /api/services/{id}

​Path parameter

​Request body

​Response

​PATCH /api/services/{id}/toggle

​Path parameter

​Response

​DELETE /api/services/{id}

​Path parameter

​Response

​GET /api/services

​Query parameters

​Response

​Example

​GET /api/services/available

​Query parameters

​Response

​GET /api/services/{id}

​Path parameter

​Response

​GET /api/services/by-category

​Query parameters

​Response

​ServiceResponse shape

​Category normalisation

Build docs developers (and LLMs) love

POST /api/services

Request body

Response

Example

PUT /api/services/{id}

Path parameter

Request body

Response

PATCH /api/services/{id}/toggle

Path parameter

Response

DELETE /api/services/{id}

Path parameter

Response

GET /api/services

Query parameters

Response

Example

GET /api/services/available

Query parameters

Response

GET /api/services/{id}

Path parameter

Response

GET /api/services/by-category

Query parameters

Response

ServiceResponse shape

Category normalisation