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 in ServiciosYa is not a simple record — it is a coordinated pair of entities: the request itself (tracking progress toward service delivery) and a linked payment record (tracking the financial proof and its validation). Both entities advance through their own state machines in lockstep, driven by customer actions and administrator reviews. Understanding how these two state machines interact is essential for building correct integrations and troubleshooting stuck requests.

​
Service request states

StateMeaning
SOLICITADORequest created and payment proof uploaded. Awaiting admin payment review.
EN_PROCESOPayment validated by admin. Service is being delivered.
FINALIZADOService delivery complete. Terminal state.
CANCELADO_USUARIOCustomer cancelled the request while it was still in SOLICITADO.
CANCELADO_PAGOAdmin rejected the payment proof. Terminal state.
State transitions are enforced by the UpdateServiceRequestStatus stored procedure in SQL Server. The API layer sends the new status and the procedure validates that the transition is permitted for the current state and the caller’s role before applying it.

​
Payment states

Each service request has exactly one associated ServiceRequestPayments record. Its state mirrors — and often drives — the state of the parent request.
Payment stateMeaning
PENDIENTEProof uploaded, awaiting admin review. Set automatically at request creation.
VALIDADOAdmin approved the proof. The request moves to EN_PROCESO.
RECHAZADOAdmin rejected the proof. The request moves to CANCELADO_PAGO.
PENDIENTE_DEVOLUCIONCustomer cancelled. Refund is pending admin confirmation.
REINTEGRADOAdmin confirmed the refund has been returned to the customer.

​
Standard creation flow

The creation of a service request is a two-step process. The payment proof must be uploaded first to obtain its URL, which is then referenced in the request body.
1

Upload the payment proof

Send the image file as multipart/form-data to the uploads endpoint. The API writes the file to wwwroot/uploads and returns the relative URL.
POST /api/uploads/payment
Authorization: Bearer <token>
Content-Type: multipart/form-data

[image file field]
Response:
{
  "imageUrl": "/uploads/payments/abc123.jpg"
}
Maximum file size is 10 MB.
2

Create the service request

Submit a request body that references the service and the proof URL returned in the previous step.
POST /api/servicerequests
Authorization: Bearer <token>
Content-Type: application/json

{
  "serviceId": 42,
  "paymentImageUrl": "/uploads/payments/abc123.jpg"
}
The API calls CreateServiceRequest (stored procedure), which creates both the ServiceRequests row (state: SOLICITADO) and the ServiceRequestPayments row (state: PENDIENTE). The response includes the new requestId.
3

Admin reviews the payment proof

An admin user (role SUPER_ADMIN, ADMIN_GENERAL, or GESTOR_SUPREMO) reviews the uploaded proof and validates or rejects it.
PUT /api/servicerequests/{id}/payment
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "isValid": true
}
  • If isValid: true → payment moves to VALIDADO, request moves to EN_PROCESO.
  • If isValid: false → payment moves to RECHAZADO, request moves to CANCELADO_PAGO.
4

Admin advances the request to FINALIZADO

Once the service has been delivered, the admin changes the status to FINALIZADO.
PUT /api/servicerequests/{id}/status
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "newStatus": "FINALIZADO"
}

​
Cancellation and refund flow

A customer can cancel a request only while it is in SOLICITADO state. Once the request moves to EN_PROCESO or any terminal state, cancellation is no longer possible.
1

Customer cancels the request

PUT /api/servicerequests/{id}/status
Authorization: Bearer <customer-token>
Content-Type: application/json

{
  "newStatus": "CANCELADO_USUARIO"
}
The request state becomes CANCELADO_USUARIO and the payment state becomes PENDIENTE_DEVOLUCION in the same database transaction.
2

Admin confirms the refund

An admin user (role SUPER_ADMIN, ADMIN_GENERAL, GESTOR_SUPREMO, or GESTOR) confirms that the refund has been issued to the customer.
PUT /api/servicerequests/{id}/refund
Authorization: Bearer <admin-token>
The payment state moves from PENDIENTE_DEVOLUCION to REINTEGRADO. The Angular portal dashboard displays a reminder for all requests in PENDIENTE_DEVOLUCION so that pending refunds are not missed.
Only SUPER_ADMIN can permanently delete a service request record via DELETE /api/servicerequests/{id}. All other roles can only observe or transition states. Deletion is irreversible.

​
Optional attachment flow

Some services are configured with PermiteAdjunto = 1, which allows the customer to attach an additional file to the request (separate from the payment proof) after creation. 
POST /api/servicerequests/{id}/attachment
Authorization: Bearer <token>
Content-Type: multipart/form-data

[attachment file field]
To retrieve the attachment: 
GET /api/servicerequests/{id}/attachment
Authorization: Bearer <token>
Attachment uploads are only accepted for services that have PermiteAdjunto enabled. Attempting to upload an attachment for a service without this flag set will be rejected by the stored procedure.

​
Custom (uncatalogued) service requests

In addition to standard catalogued services, the platform supports custom service requests for needs that do not map to an existing service entry. These follow a separate, simpler state machine managed through ICustomServiceRequestRepository.
StateMeaning
NUEVOCustom request received, no action taken yet.
CONTACTADOStaff has reached out to the customer.
EN_REVISIONThe request is being evaluated internally.
CONVERTIDO_A_SERVICIOA standard service was created from this custom request. Terminal state.
DESCARTADOThe request was reviewed and discarded. Terminal state.
Custom service requests do not have a linked payment record — payment handling only begins once a request is converted to a standard catalogued service.

​
State summary table

EntityStateTerminal?
Service requestSOLICITADO❌
Service requestEN_PROCESO❌
Service requestFINALIZADO✅
Service requestCANCELADO_USUARIO✅
Service requestCANCELADO_PAGO✅
PaymentPENDIENTE❌
PaymentVALIDADO✅
PaymentRECHAZADO✅
PaymentPENDIENTE_DEVOLUCION❌
PaymentREINTEGRADO✅
Custom requestNUEVO❌
Custom requestCONTACTADO❌
Custom requestEN_REVISION❌
Custom requestCONVERTIDO_A_SERVICIO✅
Custom requestDESCARTADO✅

Build docs developers (and LLMs) love

Get started for freeTalk to us