Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CodexaCP/SERVICIOS-BACK/llms.txt

Use this file to discover all available pages before exploring further.

A service request is the core transactional unit in ServiciosYa. It links a user, a catalog service, and a payment proof image. When you create a request the API calls the CreateServiceRequest stored procedure, which writes a ServiceRequests row and a matching ServiceRequestPayments row in PENDIENTE state in a single atomic operation. Status management, payment validation, and file attachments all operate on top of this record.
Before creating a request you must upload a payment proof image via POST /api/uploads/payment. That call returns an imageUrl which you pass to the create endpoint below. Without a valid imageUrl the create call returns 400 Bad Request.

​
POST /api/servicerequests — Create a service request

Any authenticated user can create a service request. The caller’s CompanyID and UserID are resolved automatically from the JWT claims — you do not need to supply them in the body. Authentication: Bearer token (any role)

​
Request body

​
serviceID
integer
required
The ID of the catalog service being requested. Must be an active, non-deleted service belonging to the caller’s company.
​
imageUrl
string
required
The absolute URL of the payment proof image returned by POST /api/uploads/payment. The request is rejected with 400 Bad Request if this field is absent or blank.
​
requiresInvoice
boolean
Set to true if the customer needs a fiscal invoice for this request. Defaults to false.
​
razonSocial
string
Company name to print on the invoice. Required by your business process when requiresInvoice is true.
​
ruc
string
Tax identification number (RUC) for the invoice. Required by your business process when requiresInvoice is true.

​
Response

​
requestId
integer
The auto-generated ID of the newly created service request. Store this value — you will need it for status updates, payment validation, and file uploads.
{ "requestId": 123 }
When requiresInvoice is true, staff must later upload the invoice document via POST /api/servicerequests/{id}/invoice once the payment is approved and the service is in progress. See the Attachments page for details.

​
GET /api/servicerequests/my — Get my requests

Returns a paginated list of service requests belonging to the authenticated caller. Customers use this endpoint to track their own history; internal staff can also call it to see only the requests they personally submitted. Authentication: Bearer token (any role)

​
Query parameters

​
pageNumber
integer
Page to return. Defaults to 1.
​
pageSize
integer
Number of records per page. Defaults to 20.
​
search
string
Free-text filter applied against service name, request ID, and customer fields.
​
status
string
Filter by request status. Accepted values: SOLICITADO, EN_PROCESO, FINALIZADO, CANCELADO_USUARIO, CANCELADO_PAGO.
​
paymentStatus
string
Filter by payment status. Accepted values: PENDIENTE, VALIDADO, RECHAZADO, PENDIENTE_DEVOLUCION, REINTEGRADO.

​
Response

Returns a paginated wrapper containing an array of ServiceRequestDto objects.

​
GET /api/servicerequests — Admin: all requests

Returns a paginated list of all service requests for the caller’s company. This endpoint is restricted to administrative roles. Authentication: Bearer token — SUPER_ADMIN, ADMIN_GENERAL, or GESTOR_SUPREMO

​
Query parameters

​
pageNumber
integer
Page to return. Defaults to 1.
​
pageSize
integer
Number of records per page. Defaults to 10.
​
search
string
Free-text filter applied against service name, request ID, and customer fields.
​
status
string
Filter by request status. Accepted values: SOLICITADO, EN_PROCESO, FINALIZADO, CANCELADO_USUARIO, CANCELADO_PAGO.
​
paymentStatus
string
Filter by payment status. Accepted values: PENDIENTE, VALIDADO, RECHAZADO, PENDIENTE_DEVOLUCION, REINTEGRADO.

​
Response

Returns a paginated wrapper containing an array of ServiceRequestDto objects.

​
GET /api/servicerequests/ — Get single request

Returns the full detail of a single service request, including customer info, service info, and payment state. Authentication: Bearer token (any role)

​
Path parameters

​
id
integer
required
The requestId returned when the request was created.

​
ServiceRequestDto fields

​
requestID
integer
Unique identifier of the service request.
​
status
string
Current request status: SOLICITADO, EN_PROCESO, FINALIZADO, CANCELADO_USUARIO, or CANCELADO_PAGO.
​
createdAt
string (ISO 8601)
Timestamp when the request was created.
​
updatedAt
string (ISO 8601)
Timestamp of the last status update, if any.
​
userID
integer
ID of the customer who submitted the request.
​
firstName
string
Customer’s first name.
​
lastName
string
Customer’s last name.
​
phone
string
Customer’s phone number.
​
email
string
Customer’s email address.
​
serviceID
integer
ID of the requested service.
​
serviceName
string
Display name of the service.
​
price
number
Unit price of the service at request time.
​
quantity
integer
Quantity recorded by the payment validator (default 1).
​
totalPaid
number
Total amount paid, calculated as price × quantity.
​
estimatedTimeText
string
Human-readable estimated delivery time from the service definition.
​
category
string
Category of the service.
​
permiteAdjunto
boolean
Whether the service allows an optional additional attachment.
​
imageUrl
string
URL of the payment proof image.
​
paymentStatus
string
Current payment status: PENDIENTE, VALIDADO, RECHAZADO, PENDIENTE_DEVOLUCION, or REINTEGRADO.
​
validatedAt
string (ISO 8601)
Timestamp when the payment was validated or rejected.
​
validatedBy
integer
UserID of the staff member who reviewed the payment.
​
attachmentUrl
string
Relative path of the optional additional attachment, if uploaded.
​
requiresInvoice
boolean
Whether an invoice was requested at creation time.
​
razonSocial
string
Company name for the invoice, if provided.
​
ruc
string
Tax ID for the invoice, if provided.
​
invoiceAttachmentUrl
string
Relative path of the uploaded invoice document, if any.
​
deliveryAttachmentUrl
string
Relative path of the delivery confirmation document, if any.

​
DELETE /api/servicerequests/ — Delete request

Performs a logical (soft) deletion of a service request. This operation is irreversible from the API layer. All historical data is preserved in the database and remains visible in audit logs. Authentication: Bearer token — SUPER_ADMIN only

​
Path parameters

​
id
integer
required
The requestId of the request to delete.

​
Response

Returns 204 No Content on success.

​
Two-step create flow

The following example shows the complete flow: uploading a payment proof and then creating the service request. Step 1 — Upload payment proof 
curl -X POST https://your-api/api/uploads/payment \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/receipt.jpg"

{
  "imageUrl": "https://your-api/uploads/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg"
}
Step 2 — Create the service request 
curl -X POST https://your-api/api/servicerequests \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceID": 7,
    "imageUrl": "https://your-api/uploads/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
    "requiresInvoice": true,
    "razonSocial": "Distribuidora XYZ S.A.",
    "ruc": "1234567890001"
  }'

{ "requestId": 123 }
Retrieve the request 
curl https://your-api/api/servicerequests/123 \
  -H "Authorization: Bearer <token>"
List my requests with filters 
curl "https://your-api/api/servicerequests/my?pageNumber=1&pageSize=20&status=SOLICITADO" \
  -H "Authorization: Bearer <token>"
Admin list — all requests 
curl "https://your-api/api/servicerequests?pageNumber=1&pageSize=10&paymentStatus=PENDIENTE" \
  -H "Authorization: Bearer <token>"
Delete a request (SUPER_ADMIN only) 
curl -X DELETE https://your-api/api/servicerequests/123 \
  -H "Authorization: Bearer <token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us