{ "openapi": "3.0.0", "info": { "title": "API de Volao", "version": "1.0.0", "description": "La API REST de Volao conecta tu tienda o sistema con la plataforma de envíos de Volao. Con ella puedes cotizar envíos entre varias mensajerías, crear y cancelar órdenes, obtener la guía de cada envío y seguir su recorrido, además de administrar las direcciones de recolecta y los clientes de tu comercio.\n\n## Qué puedes hacer\n\n| Área | Para qué sirve |\n| --- | --- |\n| **Autenticación** | Obtener el token de acceso con tus credenciales. |\n| **Órdenes** | Crear órdenes de envío, cancelarlas, obtener la guía, consultar el seguimiento y sus incidencias. |\n| **Mensajerías** | Cotizar un envío, y consultar las mensajerías disponibles, sus modalidades de servicio, promesas de entrega, cobertura, agencias y tarifas. |\n| **Sucursales** | Administrar las direcciones de recolecta y los clientes (destinatarios) de tu comercio. |\n| **Historial** | Consultar el historial de órdenes, de transacciones y movimientos de saldo, de liquidaciones y de beneficios del comercio. |\n| **Operaciones masivas** | Crear órdenes y generar guías por lote a partir de un archivo Excel. |\n| **Catálogos y datos públicos** | Departamentos, municipios, tipos de dirección, bancos, tipos de documento, motivos de movimiento y seguimiento público de órdenes. |\n\n## URL base\n\nTodas las rutas empiezan con `/api` y se concatenan a la URL del servidor. Por ejemplo: `{servidor}/api/orders`. En el panel **Petición** de cada endpoint puedes ver y elegir el servidor.\n\n## Autenticación\n\n1. Solicita tus credenciales (`client_id` y `client_secret`) al equipo de Volao.\n2. Obtén un token con `POST /api/auth/client/login`.\n3. Envía el token en el header de cada petición: `Authorization: Bearer `.\n\nEl token dura **15 minutos** y no se puede renovar: cuando vence, repite el login. Los endpoints bajo `/api/open/` son públicos y no requieren token.\n\n## Formato de las peticiones\n\n- Los parámetros de los endpoints `GET` se envían en la URL (query string).\n- El cuerpo de las peticiones `POST`, `PUT`, `PATCH` y `DELETE` se envía en JSON, con el header `Content-Type: application/json`.\n- La excepción es la carga masiva de órdenes, que recibe el archivo Excel como `multipart/form-data`.\n\n## Formato de las respuestas\n\nTodas las respuestas comparten la misma estructura:\n\n```json\n{\n \"response_code\": 200,\n \"response_status\": \"Success\",\n \"response_message\": \"Operación exitosa\",\n \"data\": {}\n}\n```\n\n`response_code` repite el código HTTP y `data` contiene el resultado. `response_status` puede llegar como `Success`/`Error` o `success`/`error`, así que compáralo sin distinguir mayúsculas o usa `response_code`.\n\n## Códigos de estado\n\n| Código | Significado |\n| --- | --- |\n| `200` | La operación se realizó correctamente. |\n| `201` | El recurso se creó correctamente (por ejemplo, una orden, una dirección o un cliente). |\n| `400` | La petición tiene datos inválidos o le faltan parámetros. |\n| `401` | Las credenciales son inválidas, o el token falta, venció o no es válido. |\n| `403` | El cliente API está desactivado. |\n| `404` | El recurso solicitado no existe. |\n| `409` | La operación no se puede realizar por una regla de negocio (por ejemplo, saldo insuficiente o un nombre repetido). El motivo viene en `response_message`. |\n| `500` | Error interno del servidor. |\n\n## Flujo para crear un envío\n\n1. **Autentícate** con `POST /api/auth/client/login`.\n2. **Consulta los catálogos** de departamentos y municipios (`/api/open/...`) para obtener los códigos de ubicación.\n3. **Elige o registra la dirección de recolecta** en `/api/branchs/branchsAddresses`.\n4. **Elige o registra al cliente** (destinatario) en `/api/branchs/branchsClient`.\n5. **Cotiza el envío** con `POST /api/courier` para ver las mensajerías disponibles y su precio.\n6. **Crea la orden** con `POST /api/orders`.\n7. **Obtén la guía** con `GET /api/orders` y **sigue el envío** con `GET /api/orders/tracking`.\n\n## Probar desde esta documentación\n\nCada endpoint incluye un panel para enviar peticiones reales:\n\n1. Abre **Login de cliente API**, escribe tus credenciales y presiona **Enviar petición**.\n2. Copia el `access_token` de la respuesta.\n3. En cualquier otro endpoint, pégalo en el campo **Autenticación** del panel. Se mantiene mientras no cierres la pestaña.\n\n## Más información\n\n- [Primeros pasos](/docs/guides/gettingStarted): credenciales y primera petición.\n- [Autenticación](/docs/guides/authentication): vigencia del token y errores.\n- [Formato de respuesta](/docs/guides/responseEnvelope): estructura común de las respuestas.", "contact": { "name": "Equipo Volao", "url": "https://volao.app" } }, "tags": [ { "name": "Autenticación API", "description": "Obtención del token de acceso con las credenciales del cliente API (`client_id` y `client_secret`). El token se envía en el header `Authorization` del resto de endpoints." }, { "name": "Órdenes", "description": "Creación y cancelación de órdenes de envío, consulta de la guía y seguimiento de cada orden." }, { "name": "Mensajerías (Couriers)", "description": "Cotización de envíos y consulta de las mensajerías disponibles: modalidades de servicio, cobertura, agencias y tarifas." }, { "name": "Direcciones de Sucursales (Branch Addresses)", "description": "Administración de las direcciones de recolecta del comercio. Cada orden sale de una de estas direcciones." }, { "name": "Clientes de Sucursales (Branch Clients)", "description": "Administración de los clientes (destinatarios) del comercio. La orden se entrega en la dirección registrada del cliente." }, { "name": "Historial de Sucursales (Branch History)", "description": "Historial del comercio: órdenes, transacciones y movimientos de saldo, liquidaciones y beneficios." }, { "name": "Operaciones Masivas (Batch Operations)", "description": "Creación de órdenes en lote mediante un archivo Excel y generación de guías de varias órdenes a la vez." }, { "name": "Datos Públicos (Open Data)", "description": "Catálogos de acceso público (no requieren token). Se usan para llenar formularios de direcciones, clientes y datos del comercio." }, { "name": "Estados y Catálogos", "description": "Catálogos de estados y subestados de las órdenes y de motivos de movimiento de saldo. Sirven para interpretar el seguimiento y para filtrar los historiales." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "Unauthorized": { "description": "Falta el token, venció (dura 15 minutos) o no es válido. Repite el login para obtener uno nuevo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "tokenInvalido": { "summary": "Token vencido o inválido", "value": { "response_code": 401, "response_status": "Error", "response_message": "Token inválido o expirado" } }, "sinToken": { "summary": "No se envió el header Authorization", "value": { "response_code": 401, "response_status": "Error", "response_message": "Autenticación requerida" } } } } } } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Formato común de las respuestas de error.", "properties": { "response_code": { "type": "integer", "description": "Código HTTP del error (igual al status de la respuesta)." }, "response_status": { "type": "string", "description": "Siempre indica error. Puede llegar como `Error` o `error`.", "example": "Error" }, "response_message": { "type": "string", "description": "Motivo del error, legible para personas." } } }, "ApiClientLoginRequest": { "type": "object", "required": [ "client_id", "client_secret" ], "properties": { "client_id": { "type": "string", "example": "client_demo" }, "client_secret": { "type": "string", "example": "secret_demo" } } }, "OrderStatus": { "type": "object", "description": "Estado principal de una orden.", "properties": { "statusMainId": { "type": "string", "format": "uuid", "description": "ID del estado. Se usa como `statusMainId` en `GET /api/subStatusMain`." }, "statusCode": { "type": "string", "description": "Código del estado (por ejemplo `DELIVERED`). Identifica el estado de la orden en el seguimiento.", "example": "DELIVERED" }, "descriptionStatus": { "type": "string", "description": "Nombre del estado, en español, para mostrarlo al usuario.", "example": "Entregado" }, "flowGroup": { "type": "string", "description": "Flujo al que pertenece el estado (por ejemplo, `delivery` para la entrega o `return` para la devolución). Es el valor que acepta el filtro `flowGroups`.", "example": "delivery" } } }, "OrderSubStatus": { "type": "object", "description": "Subestado de una orden; detalla el estado principal.", "properties": { "subStatusMainId": { "type": "string", "format": "uuid", "description": "ID del subestado." }, "subStatusDescription": { "type": "string", "description": "Nombre del subestado, en español.", "example": "En ruta de entrega" } } }, "OrderTrackingSummary": { "type": "object", "description": "Resumen de una orden con su historial de movimientos.", "properties": { "commerce": { "type": "object", "description": "Comercio que creó la orden y su dirección de recolecta.", "properties": { "branchsId": { "type": "string", "format": "uuid" }, "branchsName": { "type": "string" }, "branchsAddress": { "type": "string" }, "branchDepartment": { "type": "string" }, "branchsMunicipality": { "type": "string" } } }, "recipient": { "type": "object", "description": "Destinatario y dirección de entrega.", "properties": { "recipientName": { "type": "string" }, "recipientAddress": { "type": "string" }, "recipientDepartment": { "type": "string" }, "recipientMunicipality": { "type": "string" }, "comments": { "type": "string", "nullable": true, "description": "Comentarios de la orden para la entrega." } } }, "order": { "type": "object", "description": "Datos de la orden.", "properties": { "orderId": { "type": "string", "format": "uuid" }, "comprobante": { "type": "string", "nullable": true, "description": "Número de comprobante de la guía." }, "courierName": { "type": "string" }, "createdAt": { "type": "string", "description": "Fecha de creación (`YYYY-MM-DD HH:mm:ss`)." }, "onDelivery": { "type": "boolean", "description": "`true` si el cobro es contra entrega." }, "consignmentValue": { "type": "number", "description": "Monto a cobrar al destinatario." }, "deliveryCost": { "type": "number", "description": "Costo del envío." }, "totalWeight": { "type": "number" }, "cantPackages": { "type": "integer" }, "productDescription": { "type": "string" } } }, "trackingMovement": { "type": "array", "description": "Movimientos de la orden, del más antiguo al más reciente. El último es el estado actual.", "items": { "type": "object", "properties": { "statusMainCode": { "type": "string", "description": "Código del estado (catálogo `GET /api/statusMain`)." }, "statusMainDescription": { "type": "string" }, "subStatusCode": { "type": "string" }, "subStatusDescription": { "type": "string" }, "statusColor": { "type": "string", "description": "Color del estado, en hexadecimal." }, "statusIcon": { "type": "string", "description": "Clase del ícono del estado (Font Awesome)." }, "dateMovement": { "type": "string", "description": "Fecha del movimiento (`YYYY-MM-DD HH:mm:ss`)." }, "datetimeMovementFormatted": { "type": "string", "description": "Fecha del movimiento con formato legible." } } } }, "guide": { "type": "object", "properties": { "URLguide": { "type": "string", "description": "URL de la guía de envío. Vacía si la orden no tiene guía." } } }, "tracking": { "type": "object", "properties": { "URLtracking": { "type": "string", "description": "URL de la página pública de seguimiento, para compartir con el destinatario. Vacía si la orden no tiene guía." } } } } }, "OrderIncidentsDetail": { "type": "object", "description": "Estado actual de una orden y todas sus incidencias.", "properties": { "order": { "type": "object", "description": "Datos de la orden y su estado actual.", "properties": { "orderId": { "type": "string", "format": "uuid" }, "comprobante": { "type": "string", "nullable": true, "description": "Número de comprobante de la guía." }, "integrationOrderRef": { "type": "string", "nullable": true, "description": "Número de la orden en el sistema del comercio, si se envió al crearla." }, "isCurrentlyInIncident": { "type": "boolean", "description": "Indica si la orden sigue en incidencia." }, "currentStatus": { "type": "object", "description": "Estado actual de la orden.", "properties": { "statusMainId": { "type": "string", "format": "uuid", "description": "ID del estado (catálogo `GET /api/statusMain`)." }, "description": { "type": "string", "description": "Nombre del estado, en español." }, "flowGroup": { "type": "string", "description": "Flujo al que pertenece el estado (por ejemplo, `delivery` o `incident`)." }, "color": { "type": "string", "description": "Color del estado, en hexadecimal." }, "icon": { "type": "string", "description": "Nombre del ícono del estado (Font Awesome)." } } } } }, "summary": { "type": "object", "properties": { "totalIncidents": { "type": "integer", "description": "Cantidad de incidencias de la orden." } } }, "incidents": { "type": "array", "description": "Incidencias de la orden, de la más reciente a la más antigua.", "items": { "type": "object", "properties": { "incidentId": { "type": "string", "format": "uuid" }, "trackingId": { "type": "string", "format": "uuid", "description": "ID del movimiento de seguimiento asociado a la incidencia." }, "statusMainId": { "type": "string", "format": "uuid", "description": "ID del estado (catálogo `GET /api/statusMain`)." }, "statusDescription": { "type": "string", "description": "Nombre del estado, en español." }, "statusColor": { "type": "string", "description": "Color del estado, en hexadecimal." }, "statusIcon": { "type": "string", "description": "Nombre del ícono del estado (Font Awesome)." }, "subStatusId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del subestado (catálogo `GET /api/subStatusMain`)." }, "subStatusDescription": { "type": "string", "nullable": true, "description": "Nombre del subestado, en español." }, "comment": { "type": "string", "nullable": true, "description": "Comentario registrado con la incidencia." }, "source": { "type": "string", "description": "Origen de la incidencia (por ejemplo, `tracking`)." }, "reportedAt": { "type": "string", "description": "Fecha en que se reportó la incidencia (`YYYY-MM-DD HH:mm:ss`)." } } } } } }, "CourierQuoteOption": { "type": "object", "description": "Opción de envío de la cotización, un servicio de un courier con su costo y fechas estimadas.", "properties": { "courierId": { "type": "string", "format": "uuid", "description": "Courier. Se usa como `courierId` en `GET /api/courier/agencies`." }, "courierServiceId": { "type": "string", "format": "uuid", "description": "Servicio de envío. Se envía como `courier.courierServiceId` al crear la orden (`POST /api/orders`)." }, "courierName": { "type": "string", "description": "Nombre del courier." }, "serviceName": { "type": "string", "description": "Nombre del servicio." }, "serviceTypeName": { "type": "string", "description": "Nombre del tipo de servicio." }, "path_logo": { "type": "string", "description": "URL del logo del courier." }, "isSameDay": { "type": "boolean", "description": "El servicio entrega el mismo día." }, "enableGeoreference": { "type": "boolean", "description": "El courier trabaja con la georreferencia de la dirección." }, "deliveryCost": { "type": "number", "description": "Costo del envío." }, "hasDeliveryPromotion": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` si el costo del envío tiene una promoción." }, "previousDeliveryCost": { "type": "number", "nullable": true, "description": "Costo del envío sin la promoción; `null` si no hay promoción." }, "ComCCE": { "type": "number", "description": "Comisión del servicio." }, "hasCommissionPromotion": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` si la comisión tiene una promoción." }, "previousComCCE": { "type": "number", "nullable": true, "description": "Comisión sin la promoción; `null` si no hay promoción." }, "enablePromotionLabel": { "type": "boolean", "description": "Indica si se muestra la etiqueta de promoción." }, "enableRecommended": { "type": "boolean", "description": "Servicio recomendado." }, "courierDates": { "type": "object", "description": "Fechas y horarios estimados de recolección y entrega.", "properties": { "collectionDate": { "type": "string", "format": "date" }, "collectionDay": { "type": "string", "description": "Día de la semana de la recolección." }, "pickupStartTime": { "type": "string", "description": "Inicio del horario de recolección." }, "pickupEndTime": { "type": "string", "description": "Fin del horario de recolección." }, "deliveryDate": { "type": "string", "format": "date" }, "deliveryDay": { "type": "string", "description": "Día de la semana de la entrega." }, "collectionDate_byCoverage": { "type": "string", "description": "Fecha de recolección según los días de cobertura." }, "deliveryDate_byCoverage": { "type": "string", "description": "Fecha de entrega según los días de cobertura." }, "collectionMessage": { "type": "string", "description": "Texto de la recolección para mostrar al usuario." }, "deliveryMessage": { "type": "string", "description": "Texto de la entrega para mostrar al usuario." }, "alertColor_collection": { "type": "string", "description": "Color (hexadecimal) para mostrar el texto de la recolección." }, "alertColor_delivery": { "type": "string", "description": "Color (hexadecimal) para mostrar el texto de la entrega." }, "collectionAlert": { "type": "integer" } } }, "courierInfo": { "type": "object", "description": "Condiciones del courier para el servicio.", "properties": { "weightLimit": { "type": "number", "description": "Peso máximo por envío." }, "sizeLimit": { "type": "string", "description": "Dimensiones máximas por envío." }, "additionalPoundCost": { "type": "number", "description": "Costo por libra adicional." }, "insuranceCoverage": { "type": "number", "description": "Cobertura del seguro por envío." }, "returnCost": { "type": "number", "description": "Costo de la devolución." }, "returnTimeEstimate": { "type": "number", "description": "Tiempo estimado de la devolución, en días." }, "maximumEffectiveLimit": { "type": "number", "description": "Monto máximo a cobrar al destinatario." }, "minimumConsignmentRequired": { "type": "number" }, "baseCommissionTotal": { "type": "number" }, "maximumCollectionTime": { "type": "string", "description": "Hora límite de recolección." }, "collectionTime": { "type": "string", "nullable": true }, "deliveryTime": { "type": "string", "nullable": true }, "text_coverage": { "type": "string", "description": "Texto de la cobertura del servicio." }, "phoneNumber": { "type": "string", "description": "Teléfono de contacto del courier." }, "averageRating": { "type": "string", "description": "Calificación promedio del courier, como texto numérico." } } }, "courierLabels": { "type": "object", "description": "Etiquetas para mostrar junto al servicio.", "properties": { "labels": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "label_color": { "type": "string", "description": "Color de la etiqueta (hexadecimal)." }, "icon": { "type": "string", "nullable": true }, "iconVariant": { "type": "string", "nullable": true } } } }, "customLabels": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "label_color": { "type": "string", "description": "Color de la etiqueta (hexadecimal)." }, "icon": { "type": "string", "nullable": true }, "iconVariant": { "type": "string", "nullable": true } } } } } }, "agencies": { "type": "array", "description": "Agencias del courier, en los servicios que entregan o recolectan en agencia. Vacío en los demás servicios.", "items": { "type": "object", "properties": { "agencyId": { "type": "string", "format": "uuid" }, "agencyName": { "type": "string" }, "agencyAddress": { "type": "string" } } } } } }, "CourierServiceItem": { "type": "object", "description": "Servicio de un courier con sus límites, precios y condiciones de entrega.", "properties": { "courierServiceId": { "type": "string", "format": "uuid", "description": "Servicio de envío." }, "courier": { "type": "object", "properties": { "courierId": { "type": "string", "format": "uuid" }, "courierName": { "type": "string" }, "courierLogo": { "type": "string", "nullable": true, "description": "URL del logo del courier." }, "courierLabelText": { "type": "string", "nullable": true, "description": "Etiqueta del courier para mostrar." }, "courierEnableGeoreference": { "type": "boolean", "description": "El courier trabaja con la georreferencia de la dirección." }, "courierAverageRating": { "type": "number", "nullable": true, "description": "Calificación promedio del courier." } } }, "service": { "type": "object", "properties": { "serviceCode": { "type": "string" }, "serviceName": { "type": "string" }, "serviceType": { "type": "object", "properties": { "serviceTypeCode": { "type": "string" }, "serviceTypeName": { "type": "string" }, "serviceTypeRequiresCoverageValidation": { "type": "boolean", "description": "El tipo de servicio valida la cobertura del destino." } } } } }, "limits": { "type": "object", "properties": { "limitMaximumWeight": { "type": "number", "nullable": true, "description": "Peso máximo por envío." }, "limitWeightUnit": { "type": "string", "nullable": true, "description": "Unidad del peso (por ejemplo, `lb`)." }, "limitMaximumDimensions": { "type": "string", "nullable": true, "description": "Dimensiones máximas por envío." }, "limitMaximumCashAmount": { "type": "number", "nullable": true, "description": "Monto máximo a cobrar al destinatario." }, "limitMaximumPickupTime": { "type": "string", "nullable": true, "description": "Hora límite de recolección." } } }, "pricing": { "type": "object", "properties": { "pricingRateRange": { "type": "string", "nullable": true, "description": "Tarifa o rango de tarifas, como texto." }, "pricingAdditionalWeightUnitCost": { "type": "number", "nullable": true, "description": "Costo por unidad de peso adicional." }, "pricingInsurancePerShipment": { "type": "number", "nullable": true, "description": "Seguro por envío." }, "pricingReturnCost": { "type": "number", "nullable": true, "description": "Costo de la devolución." }, "pricingComCCE": { "type": "number", "description": "Comisión del servicio; `0` si no tiene." } } }, "delivery": { "type": "object", "properties": { "deliverySameDayService": { "type": "boolean", "description": "El servicio entrega el mismo día." }, "deliveryFreeAttempts": { "type": "integer", "nullable": true, "description": "Intentos de entrega sin costo." }, "deliveryReturnTimeEstimateDays": { "type": "integer", "nullable": true, "description": "Días estimados para la devolución." }, "deliveryCoverageText": { "type": "string", "nullable": true, "description": "Texto de la cobertura del servicio." }, "deliveryPromotionLabelEnabled": { "type": "boolean", "description": "Indica si se muestra la etiqueta de promoción." } } }, "agencies": { "type": "object", "properties": { "agenciesHasAgencies": { "type": "boolean", "description": "El servicio trabaja con agencias (`GET /api/courier/agencies`)." }, "agenciesCount": { "type": "integer", "description": "Cantidad de agencias del courier." } } } } }, "CourierAgency": { "type": "object", "description": "Agencia de un courier.", "properties": { "agencyId": { "type": "string", "format": "uuid", "description": "Se envía en `courier.agencias` (`idAgenciaEntrega` o `idAgenciaRecolecta`) al crear la orden." }, "agencyName": { "type": "string" }, "agencyAddress": { "type": "string" }, "scheduleDescription": { "type": "string", "nullable": true, "description": "Horario de atención." }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "location": { "type": "object", "description": "Ubicación de la agencia.", "properties": { "district": { "type": "object", "properties": { "districtId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "municipality": { "type": "object", "properties": { "municipalityId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "department": { "type": "object", "properties": { "departmentId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" } } } } } } }, "BranchClientBody": { "type": "object", "required": [ "recipientName", "recipientPhone", "recipientAddress", "municipalityCode" ], "properties": { "recipientName": { "type": "string", "minLength": 1, "maxLength": 350, "example": "Cliente Prueba" }, "recipientEmail": { "type": "string", "format": "email", "maxLength": 100, "description": "Opcional.", "example": "cliente.prueba@example.com" }, "recipientPhone": { "type": "string", "minLength": 7, "maxLength": 150, "description": "Solo números, espacios, `+`, `-` y paréntesis.", "example": "70000000" }, "recipientAddress": { "type": "string", "minLength": 5, "maxLength": 500, "example": "Calle Ficticia #456, Colonia Prueba, San Salvador" }, "municipalityCode": { "type": "string", "format": "uuid", "description": "UUID del municipio de entrega (`municipalityId` de `POST /api/open/municipality`).", "example": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005" } } }, "BranchClient": { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "Se usa como `branchInfo.branchsClientId` al crear una orden." }, "recipientName": { "type": "string" }, "recipientEmail": { "type": "string", "nullable": true }, "recipientPhone": { "type": "string" }, "recipientAddress": { "type": "string" }, "districtId": { "type": "string", "format": "uuid" }, "districtName": { "type": "string" }, "municipalityId": { "type": "string", "format": "uuid" }, "municipalityName": { "type": "string" }, "departmentId": { "type": "string", "format": "uuid" }, "departmentName": { "type": "string" }, "postalCode": { "type": "string" }, "favorite": { "type": "boolean" }, "recipientCreateAt": { "type": "string", "description": "Fecha de creación en formato legible." } } }, "BranchClientListResponse": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BranchClient" } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Clientes obtenidos correctamente", "data": [ { "branchsClientId": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003", "recipientName": "Cliente Prueba", "recipientEmail": "cliente.prueba@example.com", "recipientPhone": "70000000", "recipientAddress": "Calle Ficticia #456, Colonia Prueba, San Salvador", "districtId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0006", "districtName": "SAN SALVADOR", "municipalityId": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005", "municipalityName": "SAN SALVADOR CENTRO", "departmentId": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004", "departmentName": "SAN SALVADOR", "postalCode": "1101", "favorite": true, "recipientCreateAt": "lunes 2 de junio a las 12:30" } ] } }, "BranchAddressBody": { "type": "object", "required": [ "branchAddressName", "collectionAddress", "contactName", "phoneNumber", "emailContact", "latitude", "longitude", "municipalityCodigo", "typeBranchAddressId" ], "properties": { "branchAddressName": { "type": "string", "minLength": 3, "maxLength": 120, "description": "Nombre único de la dirección dentro del comercio.", "example": "Bodega Prueba" }, "collectionAddress": { "type": "string", "minLength": 5, "maxLength": 500, "description": "Dirección física completa de recolecta.", "example": "Calle Ficticia #123, Colonia Prueba, San Salvador" }, "contactName": { "type": "string", "minLength": 3, "maxLength": 120, "example": "Cliente Prueba" }, "phoneNumber": { "type": "string", "minLength": 7, "maxLength": 15, "description": "Solo números, espacios, `+`, `-` y paréntesis.", "example": "70000000" }, "emailContact": { "type": "string", "format": "email", "maxLength": 100, "example": "cliente.prueba@example.com" }, "latitude": { "type": "string", "pattern": "^-?\\d{1,3}\\.\\d{1,10}$", "description": "Latitud con punto decimal (de 1 a 10 decimales), enviada como texto.", "example": "13.692940" }, "longitude": { "type": "string", "pattern": "^-?\\d{1,3}\\.\\d{1,10}$", "description": "Longitud con punto decimal (de 1 a 10 decimales), enviada como texto.", "example": "-89.218191" }, "municipalityCodigo": { "type": "string", "description": "Código del municipio de la dirección (`municipalityCode` de `POST /api/open/municipality`), no su UUID.", "example": "0102" }, "typeBranchAddressId": { "type": "string", "format": "uuid", "description": "Tipo de dirección (catálogo `GET /api/open/typeBranchAddress`). Se envía como texto.", "example": "0199a1b2-1111-7e5f-8a6b-1c2d3e4f0002" } } }, "BranchSuccessResponse": { "type": "object", "description": "Campos comunes de las respuestas exitosas.", "properties": { "response_code": { "type": "integer", "description": "Código HTTP de la respuesta (igual al status)." }, "response_status": { "type": "string", "description": "Indica éxito. Puede llegar como `Success` o `success`." }, "response_message": { "type": "string", "description": "Resultado de la operación, legible para personas." } } }, "BranchAddress": { "type": "object", "description": "Dirección de recolecta del comercio.", "properties": { "branchAddressId": { "type": "string", "format": "uuid", "description": "ID de la dirección. Se usa como `branchInfo.branchAddressId` al crear una orden." }, "branchAddressName": { "type": "string", "description": "Nombre de la dirección para mostrar." }, "defaultAddress": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` si es la dirección predeterminada del comercio." }, "branchsId": { "type": "string", "format": "uuid", "description": "ID del comercio." }, "typeBranchAddress": { "type": "string", "format": "uuid", "description": "Tipo de dirección (`TypeBranchAddressId` de `GET /api/open/typeBranchAddress`)." }, "typeBranchAddressIcon": { "type": "string", "nullable": true, "description": "Ícono del tipo de dirección (clase de Font Awesome)." }, "nameBranchAddress": { "type": "string", "description": "Nombre del tipo de dirección." }, "collectionAddress": { "type": "string", "description": "Dirección de recolecta." }, "contactName": { "type": "string", "description": "Nombre del contacto en la dirección." }, "principalPhone": { "type": "string", "description": "Teléfono del contacto." }, "emailContact": { "type": "string", "nullable": true, "description": "Correo del contacto." }, "georeference": { "type": "string", "description": "Latitud y longitud separadas por coma." }, "municipalityCode": { "type": "string", "description": "Código del municipio." }, "municipalitiesName": { "type": "string", "description": "Nombre del municipio." }, "departmentsCodigo": { "type": "string", "description": "Código del departamento." }, "departmentsName": { "type": "string", "description": "Nombre del departamento." } } }, "HistoryPagination": { "type": "object", "description": "Paginación de los resultados.", "properties": { "page": { "type": "integer", "description": "Página actual." }, "limit": { "type": "integer", "description": "Resultados por página." }, "max_limit": { "type": "integer", "description": "Valor máximo permitido para `limit`." }, "total": { "type": "integer", "description": "Total de resultados con los filtros aplicados." }, "total_pages": { "type": "integer", "description": "Total de páginas." }, "has_next": { "type": "boolean", "description": "Hay una página siguiente." }, "has_prev": { "type": "boolean", "description": "Hay una página anterior." }, "from": { "type": "integer", "description": "Posición del primer resultado de la página (`0` si no hay resultados)." }, "to": { "type": "integer", "description": "Posición del último resultado de la página." } } }, "HistoryExport": { "type": "object", "description": "Exportación a Excel.", "properties": { "URLDataExcel": { "type": "string", "description": "URL del Excel con todos los resultados. Cadena vacía si no se envió `export` con `1` o no hay resultados." } } }, "HistoryMetric": { "type": "object", "description": "Métrica del periodo consultado.", "properties": { "value": { "type": "number", "description": "Valor del periodo." }, "changePercentage": { "type": "number", "description": "Variación porcentual respecto al periodo anterior. No viene en todas las métricas." } } }, "HistoryOrderItem": { "type": "object", "description": "Orden del historial con su estado actual, courier y destinatario.", "properties": { "ordersId": { "type": "string", "format": "uuid", "description": "ID de la orden." }, "order": { "type": "object", "description": "Datos de la orden.", "properties": { "comprobante": { "type": "string", "description": "Número de comprobante de la orden." }, "createdAt": { "type": "string", "description": "Fecha y hora de creación (`YYYY-MM-DD HH:mm:ss`)." }, "platform": { "type": "string", "description": "Canal por el que se creó la orden (por ejemplo, `API`)." }, "productDescription": { "type": "string", "description": "Descripción del contenido del paquete." }, "totalWeight": { "type": "number", "description": "Peso total del envío." }, "packageCount": { "type": "integer", "description": "Cantidad de paquetes." }, "onDelivery": { "type": "boolean", "description": "La orden tiene cobro contra entrega." }, "paidShipping": { "type": "boolean", "description": "El envío ya está pagado." }, "consignmentValue": { "type": "number", "description": "Monto a cobrar al destinatario." }, "deliveryCost": { "type": "number", "description": "Costo del envío." }, "baseCommissionAmount": { "type": "number", "description": "Comisión base de la orden." }, "pcme": { "type": "number", "description": "Porcentaje de comisión de la orden (de 0 a 100)." }, "branchDepartmentName": { "type": "string", "description": "Departamento de la dirección de recolecta." }, "branchMunicipalityName": { "type": "string", "description": "Municipio de la dirección de recolecta." } } }, "status": { "type": "object", "description": "Estado actual de la orden.", "properties": { "statusMainId": { "type": "string", "format": "uuid", "description": "Estado principal (`statusMainId` de `GET /api/statusMain`)." }, "statusDescription": { "type": "string", "description": "Nombre del estado." }, "subStatusMainId": { "type": "string", "format": "uuid", "description": "Subestado (`GET /api/subStatusMain`)." }, "subStatusDescription": { "type": "string", "description": "Nombre del subestado." }, "flowGroup": { "type": "string", "description": "Grupo de flujo del estado (por ejemplo, `delivery` o `return`)." }, "statusColor": { "type": "string", "description": "Color del estado (hexadecimal)." }, "lastMovementDate": { "type": "string", "description": "Fecha y hora del último movimiento de la orden." } } }, "courier": { "type": "object", "description": "Courier de la orden.", "properties": { "courierId": { "type": "string", "format": "uuid", "description": "ID del courier." }, "courierName": { "type": "string", "description": "Nombre del courier." }, "courierLogo": { "type": "string", "description": "URL del logo del courier." }, "courierPhone": { "type": "string", "nullable": true, "description": "Teléfono del courier." } } }, "recipient": { "type": "object", "description": "Destinatario de la orden.", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "Cliente destinatario (`GET /api/branchs/branchsClient`)." }, "recipientName": { "type": "string", "description": "Nombre del destinatario." }, "recipientPhone": { "type": "string", "description": "Teléfono del destinatario." }, "recipientAddress": { "type": "string", "description": "Dirección de entrega." }, "departmentCode": { "type": "string", "description": "Código del departamento de entrega." }, "departmentName": { "type": "string", "description": "Nombre del departamento de entrega." }, "municipalityCode": { "type": "string", "description": "Código del municipio de entrega." }, "municipalityName": { "type": "string", "description": "Nombre del municipio de entrega." }, "favoriteClient": { "type": "boolean", "description": "El cliente está marcado como favorito." }, "branchsClientStatus": { "type": "boolean", "description": "El cliente está activo." } } }, "tracking": { "type": "object", "description": "Seguimiento de la orden.", "properties": { "URLtracking": { "type": "string", "description": "URL del seguimiento público de la orden." } } } } }, "TransactionHistoryItem": { "type": "object", "description": "Transacción del comercio con su método de pago, resumen del monedero y movimientos de saldo.", "properties": { "transaction": { "type": "object", "description": "Datos de la transacción.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "ID de la transacción." }, "createdAt": { "type": "string", "description": "Fecha y hora de la transacción (`YYYY-MM-DD HH:mm:ss`)." }, "transactionAmount": { "type": "number", "description": "Monto de la transacción." }, "transactionGatewayId": { "type": "string", "format": "uuid", "description": "Pasarela de pago de la transacción." }, "transactionGatewayCode": { "type": "string", "description": "Código de la pasarela de pago." }, "transactionGatewayLabel": { "type": "string", "description": "Nombre de la pasarela de pago para mostrar." }, "gatewayTransactionReference": { "type": "string", "nullable": true, "description": "Referencia de la transacción en la pasarela de pago." }, "internalTransactionReference": { "type": "string", "description": "Referencia interna de la transacción." } } }, "paymentMethod": { "type": "object", "description": "Tarjeta con la que se pagó. Sus campos son `null` si la transacción no se pagó con tarjeta.", "properties": { "paymentCardId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID de la tarjeta." }, "cardBin": { "type": "string", "nullable": true, "description": "Primeros 6 dígitos de la tarjeta." }, "cardLast4": { "type": "string", "nullable": true, "description": "Últimos 4 dígitos de la tarjeta." }, "cardMasked": { "type": "string", "nullable": true, "description": "Número de la tarjeta enmascarado." }, "typeCard": { "type": "string", "nullable": true, "description": "Tipo de tarjeta (por ejemplo, `VISA`)." }, "cardOwner": { "type": "string", "nullable": true, "description": "Titular de la tarjeta." } } }, "wallet": { "type": "object", "description": "Resumen del monedero (saldo) del comercio en la transacción.", "properties": { "rechargeAmount": { "type": "number", "description": "Monto recargado." }, "previousWalletBalance": { "type": "number", "description": "Saldo antes de la transacción." }, "walletMovementAmount": { "type": "number", "description": "Monto usado por los movimientos de la transacción." }, "walletNetAmount": { "type": "number", "description": "Monto neto de la transacción en el monedero." }, "walletUsedPreviousBalanceAmount": { "type": "number", "description": "Monto tomado del saldo anterior." }, "residualWalletBalance": { "type": "number", "description": "Saldo restante después de los movimientos." }, "benefitAmount": { "type": "number", "description": "Monto de beneficios de la transacción." } } }, "summary": { "type": "object", "description": "Totales de los movimientos de la transacción.", "properties": { "movementsCount": { "type": "integer", "description": "Cantidad de movimientos." }, "movementDeliveryCostAmount": { "type": "number", "description": "Suma de los costos de envío." }, "movementCourierCostAmount": { "type": "number", "description": "Suma de los costos del courier." }, "movementFeeVolaoAmount": { "type": "number", "description": "Suma de las comisiones de Volao." }, "movementBenefitAmount": { "type": "number", "description": "Suma de los beneficios." } } }, "movements": { "type": "array", "description": "Movimientos de saldo de la transacción.", "items": { "type": "object", "properties": { "transactionMovementId": { "type": "string", "format": "uuid", "description": "ID del movimiento." }, "movementReasonId": { "type": "string", "format": "uuid", "description": "Motivo del movimiento (`GET /api/movementReason`)." }, "movementReasonCode": { "type": "string", "description": "Código del motivo del movimiento." }, "movementDescription": { "type": "string", "description": "Descripción del movimiento." }, "movementIsCredit": { "type": "boolean", "description": "`true` si el movimiento suma al saldo; `false` si lo descuenta." }, "movementIsBenefit": { "type": "boolean", "description": "`true` si el movimiento es un beneficio (detalle en `benefit`)." }, "movementDate": { "type": "string", "nullable": true, "description": "Fecha y hora del movimiento." }, "order": { "type": "object", "description": "Orden del movimiento. Sus campos son `null` si el movimiento no corresponde a una orden.", "properties": { "orderId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID de la orden." }, "comprobanteAf": { "type": "string", "nullable": true, "description": "Número de comprobante de la orden." }, "deliveryCost": { "type": "number", "nullable": true, "description": "Costo del envío." }, "courierCost": { "type": "number", "nullable": true, "description": "Costo del courier." }, "feeVolao": { "type": "number", "nullable": true, "description": "Comisión de Volao." } } }, "courier": { "type": "object", "description": "Courier del movimiento.", "properties": { "courierId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del courier." }, "courierName": { "type": "string", "nullable": true, "description": "Nombre del courier." }, "courierLogo": { "type": "string", "nullable": true, "description": "URL del logo del courier." } } }, "service": { "type": "object", "description": "Servicio de envío del movimiento.", "properties": { "courierServiceId": { "type": "string", "format": "uuid", "nullable": true, "description": "Servicio de envío (`courierServiceId` de `POST /api/courier`)." }, "serviceId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del servicio." }, "serviceName": { "type": "string", "nullable": true, "description": "Nombre del servicio." }, "serviceTypeId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del tipo de servicio." }, "serviceTypeName": { "type": "string", "nullable": true, "description": "Nombre del tipo de servicio." } } }, "balances": { "type": "object", "description": "Saldo del comercio en el movimiento.", "properties": { "previousBalance": { "type": "number", "description": "Saldo antes del movimiento." }, "transactionBalance": { "type": "number", "description": "Monto del movimiento (negativo si descuenta del saldo)." }, "newBalance": { "type": "number", "description": "Saldo después del movimiento." } } }, "benefit": { "type": "object", "nullable": true, "description": "Detalle del beneficio. Es `null` si el movimiento no es un beneficio.", "properties": { "benefitId": { "type": "string", "format": "uuid", "description": "ID del beneficio." }, "tierCode": { "type": "string", "description": "Código del plan de suscripción." }, "tierName": { "type": "string", "description": "Nombre del plan de suscripción." }, "baseAmount": { "type": "number", "description": "Monto sobre el que se calculó el beneficio." }, "rate": { "type": "number", "description": "Tasa aplicada, como decimal (`0.05` = 5 %)." }, "amount": { "type": "number", "description": "Monto del beneficio." }, "status": { "type": "string", "enum": [ "APPLIED", "REVERSED" ], "description": "Estado del beneficio, aplicado o revertido." }, "detail": { "type": "string", "description": "Detalle del beneficio." } } } } } } } }, "BenefitHistoryItem": { "type": "object", "description": "Beneficio del comercio con su plan de suscripción, orden, courier y movimiento de saldo.", "properties": { "benefit": { "type": "object", "description": "Datos del beneficio.", "properties": { "benefitId": { "type": "string", "format": "uuid", "description": "ID del beneficio." }, "movementCode": { "type": "string", "description": "Código del tipo de beneficio (por ejemplo, `CBE`)." }, "movementName": { "type": "string", "description": "Nombre del tipo de beneficio." }, "movementColor": { "type": "string", "nullable": true, "description": "Color con el que se muestra el tipo de beneficio." }, "status": { "type": "string", "enum": [ "APPLIED", "REVERSED" ], "description": "Estado del beneficio, aplicado o revertido." }, "amount": { "type": "number", "description": "Monto del beneficio." }, "baseAmount": { "type": "number", "nullable": true, "description": "Monto sobre el que se calculó el beneficio (por ejemplo, el costo de envío)." }, "rate": { "type": "number", "nullable": true, "description": "Tasa aplicada, como decimal (`0.05` = 5 %)." }, "detail": { "type": "string", "nullable": true, "description": "Detalle del beneficio." }, "metadata": { "type": "object", "nullable": true, "description": "Datos adicionales del beneficio. Puede incluir otros campos según el tipo de beneficio.", "properties": { "tierCode": { "type": "string", "description": "Código del plan de suscripción al otorgarse el beneficio." }, "deliveredAt": { "type": "string", "description": "Fecha y hora de entrega de la orden." }, "orderSubStatusId": { "type": "string", "format": "uuid", "description": "Subestado de la orden que generó el beneficio." }, "orderMovements": { "type": "array", "description": "Movimientos de saldo de la orden.", "items": { "type": "object", "properties": { "balanceTransactionId": { "type": "string", "format": "uuid", "description": "ID del movimiento de saldo." }, "movementCode": { "type": "string", "description": "Código del movimiento." }, "direction": { "type": "string", "description": "Sentido del movimiento (abono o cargo)." }, "amount": { "type": "number", "description": "Monto del movimiento." }, "createdAt": { "type": "string", "description": "Fecha y hora del movimiento." } } } } } }, "createdAt": { "type": "string", "description": "Fecha y hora en que se aplicó el beneficio." }, "reversedAt": { "type": "string", "nullable": true, "description": "Fecha y hora en que se revirtió. Es `null` si no se revirtió." } } }, "subscription": { "type": "object", "description": "Plan de suscripción con el que se otorgó el beneficio.", "properties": { "subscriptionTierId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del plan de suscripción." }, "tierCode": { "type": "string", "nullable": true, "description": "Código del plan de suscripción." }, "tierName": { "type": "string", "nullable": true, "description": "Nombre del plan de suscripción." } } }, "order": { "type": "object", "description": "Orden que generó el beneficio.", "properties": { "orderId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID de la orden." }, "comprobanteAf": { "type": "string", "nullable": true, "description": "Número de comprobante de la orden." }, "deliveryCost": { "type": "number", "nullable": true, "description": "Costo del envío." }, "deliveredAt": { "type": "string", "nullable": true, "description": "Fecha y hora de entrega de la orden." } } }, "courier": { "type": "object", "description": "Courier de la orden.", "properties": { "courierId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del courier." }, "courierName": { "type": "string", "nullable": true, "description": "Nombre del courier." }, "courierLogo": { "type": "string", "nullable": true, "description": "URL del logo del courier." } } }, "movement": { "type": "object", "description": "Movimiento de saldo que generó el beneficio.", "properties": { "balanceTransactionId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del movimiento de saldo del beneficio." }, "paymentTransactionId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID de la transacción asociada al movimiento." }, "previousBalance": { "type": "number", "nullable": true, "description": "Saldo antes del beneficio." }, "newBalance": { "type": "number", "nullable": true, "description": "Saldo después del beneficio." }, "reversedBalanceTransactionId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del movimiento de saldo de la reversión. Es `null` si no se revirtió." } } } } }, "SettlementHistoryItem": { "type": "object", "description": "Acta de liquidación con su cuenta bancaria, totales y órdenes.", "properties": { "acta": { "type": "object", "description": "Datos del acta.", "properties": { "codActa": { "type": "integer", "description": "Número del acta de liquidación." }, "settlementDate": { "type": "string", "format": "date", "description": "Fecha de la liquidación." }, "totalOrders": { "type": "integer", "description": "Cantidad de órdenes del acta." } } }, "bankAccount": { "type": "object", "description": "Cuenta bancaria donde se depositó la liquidación.", "properties": { "titular": { "type": "string", "description": "Titular de la cuenta." }, "bankId": { "type": "string", "format": "uuid", "description": "Banco (`banks[].banksId` de `GET /api/open/banks`)." }, "bankName": { "type": "string", "description": "Nombre del banco." }, "typeAccountId": { "type": "string", "format": "uuid", "description": "Tipo de cuenta (`typeAccount[].typeAccountId` de `GET /api/open/banks`)." }, "typeAccountName": { "type": "string", "description": "Nombre del tipo de cuenta." }, "accountNumber": { "type": "string", "description": "Número de la cuenta." } } }, "totals": { "type": "object", "description": "Totales del acta.", "properties": { "totalConsignmentValue": { "type": "number", "description": "Total cobrado a los destinatarios." }, "totalDeliveryCost": { "type": "number", "description": "Total de costos de envío." }, "totalCommission": { "type": "number", "description": "Total de comisiones." }, "totalSettledAmount": { "type": "number", "description": "Total liquidado al comercio." } } }, "orders": { "type": "array", "description": "Órdenes que liquida el acta.", "items": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid", "description": "ID de la orden." }, "comprobante": { "type": "string", "description": "Número de comprobante de la orden." }, "deliveryDate": { "type": "string", "format": "date", "description": "Fecha de entrega de la orden." }, "consignmentValue": { "type": "number", "description": "Monto cobrado al destinatario." }, "deliveryCost": { "type": "number", "description": "Costo del envío." }, "commission": { "type": "number", "description": "Comisión cobrada." }, "settledAmount": { "type": "number", "description": "Monto liquidado al comercio." } } } } } }, "SettlementDetail": { "type": "object", "description": "Detalle de un acta de liquidación.", "properties": { "accountData": { "type": "object", "description": "Datos del acta, del comercio y de la cuenta bancaria.", "properties": { "codActa": { "type": "integer", "description": "Número del acta de liquidación." }, "actaFecha": { "type": "string", "format": "date", "description": "Fecha del acta." }, "branchId": { "type": "string", "format": "uuid", "description": "ID del comercio." }, "branchName": { "type": "string", "description": "Nombre del comercio." }, "branchEmail": { "type": "string", "description": "Correo del comercio." }, "titular": { "type": "string", "description": "Titular de la cuenta bancaria." }, "bankName": { "type": "string", "description": "Nombre del banco." }, "typeAccount": { "type": "string", "description": "Tipo de cuenta bancaria." }, "accountNumber": { "type": "string", "description": "Número de la cuenta bancaria." } } }, "orders": { "type": "array", "description": "Órdenes que incluye el acta.", "items": { "type": "object", "properties": { "ordersId": { "type": "string", "format": "uuid", "description": "ID de la orden." }, "montoEnvio": { "type": "number", "description": "Monto cobrado al destinatario." }, "costoEnvio": { "type": "number", "description": "Costo del envío." }, "cme": { "type": "number", "description": "Comisión cobrada." }, "montoLiquidado": { "type": "number", "description": "Monto liquidado al comercio." } } } }, "totals": { "type": "object", "description": "Totales del acta.", "properties": { "totalMontoEnvio": { "type": "number", "description": "Total cobrado a los destinatarios." }, "totalCostoEnvio": { "type": "number", "description": "Total de costos de envío." }, "totalCme": { "type": "number", "description": "Total de comisiones." }, "totalLiquidado": { "type": "number", "description": "Total liquidado al comercio." } } } } } } }, "servers": [ { "url": "https://api.volao.app", "description": "Producción" }, { "url": "https://api.dev.volao.app", "description": "Desarrollo" } ], "paths": { "/api/auth/client/login": { "post": { "summary": "Login de cliente API", "operationId": "loginApiClient", "description": "Autentica un cliente de integración mediante `client_id` y `client_secret` y retorna un `access_token` JWT que deberá enviarse en el header `Authorization: Bearer {token}` en las siguientes peticiones.\n", "tags": [ "Autenticación API" ], "security": [], "requestBody": { "required": true, "description": "Credenciales del cliente API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientLoginRequest" } } } }, "responses": { "200": { "description": "Autenticación exitosa", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer", "example": 200 }, "response_status": { "type": "string", "example": "success" }, "response_message": { "type": "string", "example": "Autenticación API exitosa" }, "token": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Token JWT para autenticación", "example": "eyJhbGciOiJIUzI1NiJ9..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "description": "Tiempo de expiración en segundos", "example": 900 } } } } } } } }, "400": { "description": "Faltan `client_id` o `client_secret`, no son texto o están vacíos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noEnviados": { "summary": "Falta un campo o no es texto", "value": { "response_code": 400, "response_status": "Error", "response_message": "client_id y client_secret deben ser válidos." } }, "vacios": { "summary": "Un campo se envió como texto vacío", "value": { "response_code": 400, "response_status": "Error", "response_message": "Debe enviar client_id y client_secret para continuar." } }, "soloEspacios": { "summary": "Un campo contiene solo espacios", "value": { "response_code": 400, "response_status": "Error", "response_message": "client_id no puede estar vacío." } } } } } }, "401": { "description": "Credenciales inválidas (el `client_id` no existe o el `client_secret` no coincide)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 401, "response_status": "error", "response_message": "Credenciales inválidas" } } } }, "403": { "description": "API client desactivado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 403, "response_status": "error", "response_message": "API client desactivado" } } } }, "500": { "description": "Error interno, o el cuerpo no es un JSON válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "error", "response_message": "Error interno al autenticar API client" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Autenticación" } }, "/api/orders": { "post": { "summary": "Crear una nueva orden", "operationId": "createOrder", "description": "Crea una orden de envío, genera la guía de despacho y descuenta el costo del saldo prepago.\n\n**Antes de crear la orden, obtén estos IDs:**\n\n| Campo de la orden | De dónde sale | Campo de la respuesta |\n| --- | --- | --- |\n| `branchInfo.branchAddressId` (dirección de recolecta) | `GET /api/branchs/branchsAddresses`, o el que devuelve `POST /api/branchs/branchsAddresses` al crearla | `branchAddressId` |\n| `branchInfo.branchsClientId` (cliente y dirección de entrega) | `GET /api/branchs/branchsClient` o `GET /api/branchs/branchsClient/search`, o el que devuelve `POST /api/branchs/branchsClient` al registrarlo | `branchsClientId` |\n| `courier.courierServiceId` (mensajería y servicio) | `POST /api/courier` (cotizar), enviando la dirección de recolecta y el municipio del cliente | `courierServiceId` |\n| `courier.agencias` (opcional) | `GET /api/courier/agencies`, solo si la mensajería trabaja con agencias | ID de la agencia |\n\nLa dirección de entrega no se envía aparte: es la que tiene registrada el cliente.\n\nLa validación se hace por secciones (`branchInfo`, `courier`, `location`, `product`, `order`) y se informa el primer error encontrado.\n", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "branchInfo", "courier", "location", "product", "order" ], "properties": { "branchInfo": { "type": "object", "required": [ "branchAddressId", "branchsClientId" ], "properties": { "branchAddressId": { "type": "string", "format": "uuid", "description": "Dirección de recolecta. Copia el campo `branchAddressId` de `GET /api/branchs/branchsAddresses`.", "example": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" }, "branchsClientId": { "type": "string", "format": "uuid", "description": "Cliente destinatario; la orden se entrega en la dirección registrada del cliente. Copia el campo `branchsClientId` de `GET /api/branchs/branchsClient` o de `GET /api/branchs/branchsClient/search`.", "example": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003" } } }, "courier": { "type": "object", "required": [ "courierServiceId", "agencias" ], "properties": { "courierServiceId": { "type": "string", "format": "uuid", "description": "Mensajería y servicio elegidos. Copia el campo `courierServiceId` de la opción elegida en la cotización (`POST /api/courier`).", "example": "019f88a7-40d5-75b5-add9-87e652d9ba69" }, "agencias": { "type": "object", "description": "Obligatorio. Puede enviarse vacío (`{}`); las agencias solo aplican a couriers que las usan.", "properties": { "idAgenciaRecolecta": { "type": "string", "format": "uuid", "description": "Opcional. Agencia de recolecta, obtenida de `GET /api/courier/agencies`." }, "idAgenciaEntrega": { "type": "string", "format": "uuid", "description": "Opcional. Agencia de entrega, obtenida de `GET /api/courier/agencies`." } }, "example": {} } } }, "location": { "type": "object", "required": [ "latitude", "longitude" ], "description": "Coordenadas del punto de entrega, como texto. Las usan las mensajerías con `enableGeoreference` en `true` en la cotización; para las demás puede enviarse `\"0\"`.", "properties": { "latitude": { "type": "string", "maxLength": 20, "example": "13.692940" }, "longitude": { "type": "string", "maxLength": 20, "example": "-89.218191" } } }, "product": { "type": "object", "required": [ "productDescription", "totalWeight", "cantPackages" ], "properties": { "productDescription": { "type": "string", "maxLength": 150, "example": "Ropa" }, "totalWeight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Peso total, mayor que 0.", "example": 4 }, "cantPackages": { "type": "integer", "minimum": 1, "maximum": 50, "example": 1 }, "inventoryItems": { "type": "array", "description": "Opcional. Productos del inventario del comercio incluidos en el envío.", "items": { "type": "object", "required": [ "productId", "quantity", "price" ], "properties": { "productId": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 }, "price": { "type": "number", "minimum": 0 } } } } } }, "order": { "type": "object", "required": [ "shippingAmount", "onDelivery", "paymentOrderCollection", "comments" ], "properties": { "shippingAmount": { "type": "number", "description": "Monto que la mensajería cobra al destinatario cuando `onDelivery` es 1. Sin cobro contra entrega, se envía el valor declarado de la mercancía.", "example": 10 }, "onDelivery": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = el cobro se realiza contra entrega; 0 = sin cobro. También acepta `true` / `false`.", "example": 1 }, "paymentOrderCollection": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de recaudo (1 = aplica, 0 = no aplica). Envía 0 salvo que el equipo de Volao te indique otra cosa. También acepta `true` / `false`.", "example": 0 }, "integrationOrderRef": { "type": "string", "description": "Opcional. Número de la orden en el sistema del comercio (texto, no numérico)." }, "comments": { "type": "string", "description": "Obligatorio; puede enviarse vacío.", "example": "" } } } } } } } }, "responses": { "201": { "description": "Orden creada correctamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "properties": { "ordersId": { "type": "string", "format": "uuid", "description": "ID de la orden. Se usa para obtener la guía, el seguimiento y las incidencias, y para cancelarla." }, "clientName": { "type": "string", "description": "Nombre del cliente destinatario." }, "clientEmail": { "type": "string", "description": "Correo del cliente destinatario." }, "comprobante": { "type": "string", "description": "Número de comprobante de la guía, asignado por la mensajería." }, "courierName": { "type": "string" }, "requestDate": { "type": "string", "description": "Fecha de creación de la orden." }, "availableBalance": { "type": "number", "description": "Saldo prepago disponible después de crear la orden." }, "consignmentValue": { "type": "number", "description": "Monto a cobrar al destinatario." }, "isFirstOrderOfDay": { "type": "integer", "enum": [ 0, 1 ], "description": "1 si es la primera orden del comercio en el día." } } }, "guide": { "type": "object", "properties": { "URLguide": { "type": "string", "description": "URL de la guía de envío (para visualizar o imprimir). Vacía si no se pudo obtener; puedes consultarla después con `GET /api/orders`." } } }, "tracking": { "type": "object", "description": "Puede no venir en la respuesta, según la configuración del comercio.", "properties": { "URLtracking": { "type": "string", "description": "URL de la página pública de seguimiento, para compartir con el destinatario. Vacía si la orden no tiene guía." } } } } }, "example": { "response_code": 201, "response_status": "Success", "response_message": "Orden creada correctamente", "data": { "ordersId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "clientName": "Cliente Prueba", "clientEmail": "cliente.prueba@example.com", "comprobante": "29137811", "courierName": "Mensajería Ejemplo", "requestDate": "2026-10-07 01:49:25.000000", "availableBalance": 42.22, "consignmentValue": 10, "isFirstOrderOfDay": 1 }, "guide": { "URLguide": "https://mensajeria.example.com/guias/GUIA-PRUEBA.pdf" }, "tracking": { "URLtracking": "https://tracking.example.com/?orderId=0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008&identifier=abc123" } } } } }, "400": { "description": "Datos de la solicitud inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "branchInfo": { "summary": "Falta una sección completa (aplica igual a courier, location, product y order).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"branchInfo\": Falta la sección completa" } }, "branchAddressId": { "summary": "Falta la dirección de recolecta (branchInfo.branchAddressId).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"branchInfo\": branchAddressId es requerido" } }, "branchsClientId": { "summary": "Falta el cliente destinatario (branchInfo.branchsClientId).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"branchInfo\": branchsClientId es requerido" } }, "courierServiceId": { "summary": "Falta el servicio de envío elegido al cotizar (courier.courierServiceId).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"courier\": courierServiceId es requerido" } }, "agencias": { "summary": "Falta el objeto de agencias (courier.agencias); puede enviarse vacío.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"courier\": El campo agencias es requerido y debe ser un objeto." } }, "latitude": { "summary": "Falta la latitud (location.latitude).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"location\": latitud es requerido" } }, "longitude": { "summary": "Falta la longitud (location.longitude).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"location\": longitud es requerido" } }, "productDescription": { "summary": "Falta la descripción del producto (product.productDescription).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": productDescription es requerido" } }, "totalWeight": { "summary": "Falta el peso total (product.totalWeight).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": totalWeight es requerido" } }, "cantPackages": { "summary": "Falta la cantidad de paquetes (product.cantPackages).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": cantPackages es requerido" } }, "shippingAmount": { "summary": "Falta el monto a cobrar (order.shippingAmount).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": shippingAmount es requerido" } }, "onDelivery": { "summary": "Falta indicar si el cobro es contra entrega (order.onDelivery).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": onDelivery es requerido" } }, "paymentOrderCollection": { "summary": "Falta paymentOrderCollection (order.paymentOrderCollection).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": paymentOrderCollection es requerido" } }, "comments": { "summary": "Faltan los comentarios (order.comments); pueden enviarse vacíos.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": comments es requerido" } }, "branchAddressIdType": { "summary": "branchAddressId no es texto (aplica igual a branchsClientId y courierServiceId).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"branchInfo\": branchAddressId debe ser una cadena (UUID)" } }, "agencyFormat": { "summary": "Una agencia no es un UUID válido (aplica igual a idAgenciaEntrega).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"courier\": El campo idAgenciaRecolecta debe ser un UUID válido." } }, "latitudeFormat": { "summary": "La latitud no es texto o supera 20 caracteres (aplica igual a la longitud).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"location\": latitud debe ser una cadena de máximo 20 caracteres" } }, "productDescriptionFormat": { "summary": "La descripción no es texto o supera 150 caracteres.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": productDescription debe ser una cadena de máximo 150 caracteres" } }, "totalWeightValue": { "summary": "El peso no es un número o no es mayor que 0.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": totalWeight debe ser un número decimal mayor que 0" } }, "cantPackagesRange": { "summary": "La cantidad de paquetes no es un entero entre 1 y 50.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": cantPackages debe ser un entero entre 1 y 50" } }, "inventoryItems": { "summary": "Un producto de inventoryItems no tiene un productId válido (también se validan quantity y price).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": Cada inventoryItem debe tener un productId (UUID) válido" } }, "shippingAmountType": { "summary": "El monto no es un número.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": shippingAmount debe ser un número decimal" } }, "onDeliveryValue": { "summary": "onDelivery no es 0, 1, true ni false.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": onDelivery debe ser booleano o 0/1" } }, "integrationOrderRef": { "summary": "integrationOrderRef se envió como número.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": integrationOrderRef debe ser una cadena de texto, no un valor numérico" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Regla de negocio (monto insuficiente, dirección que no pertenece al comercio, saldo)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 409, "response_status": "Error", "response_message": "El monto a cobrar ($1.00) no cubre el costo del envío ($3.39) más las comisiones ($0.50). El monto mínimo requerido es $3.89" } } } }, "422": { "description": "La mensajería no pudo generar el comprobante de la guía. Intenta nuevamente o elige otro servicio en la cotización.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 422, "response_status": "Error", "response_message": "Tuvimos un inconveniente al generar el comprobante con el courier. Intenta nuevamente o selecciona otro courier." } } } }, "500": { "description": "Error interno al crear la orden. El mensaje puede variar e incluir el detalle del error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "general": { "summary": "Error interno, o el body no es un JSON válido.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al crear la orden" } }, "mensajeria": { "summary": "Error al registrar la orden con la mensajería.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error al ejecutar el flujo de orden" } }, "actualizacion": { "summary": "Error al actualizar la orden después de generar la guía.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar la orden" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Órdenes" }, "patch": { "summary": "Cancelar órdenes", "operationId": "cancelOrders", "description": "Cancela una o varias órdenes (máximo 50) en una sola petición.\nLa respuesta general retorna 200 si la solicitud se procesó; el resultado de **cada orden** se valida dentro de `data[]`.\n\nCódigos posibles en cada elemento de `data[]`: `200` (cancelada), un código de error con el motivo si la orden no se puede cancelar (por ejemplo, por su estado actual), `422` si la mensajería no confirmó la cancelación y `500` por un error interno.\n", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "orderIds": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "format": "uuid" }, "description": "IDs de las órdenes a cancelar. También acepta un solo ID como texto. Obligatorio si no se envía `orderId`.", "example": [ "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "0199a1b2-8888-7e5f-8a6b-1c2d3e4f0009" ] }, "orderId": { "type": "string", "format": "uuid", "description": "Alternativa a `orderIds` para cancelar una sola orden. Se ignora si se envía `orderIds`." }, "reason": { "type": "string", "maxLength": 255, "description": "Motivo de la cancelación. No puede estar vacío.", "example": "Cliente solicitó cancelación" } } } } } }, "responses": { "200": { "description": "Cancelación procesada; revisar el resultado de cada orden en `data[]`", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "description": "Resultado de cada orden, en el mismo orden en que se enviaron.", "items": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "response_code": { "type": "integer", "description": "Resultado de la cancelación de esta orden (200 si se canceló)." }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "requestDate": { "type": "string", "nullable": true, "description": "Fecha de la cancelación, con formato legible (hora de El Salvador). Solo viene si la orden se canceló." } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Cancelación procesada", "data": [ { "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "response_code": 409, "response_status": "Error", "response_message": "La orden no puede ser cancelada en su estado actual (CANCELADO)." }, { "orderId": "0199a1b2-8888-7e5f-8a6b-1c2d3e4f0009", "response_code": 200, "response_status": "Success", "response_message": "La orden fue cancelada exitosamente.", "requestDate": "07/10/2026, 07:52 p. m." }, { "orderId": "0199a1b2-9999-7e5f-8a6b-1c2d3e4f0010", "response_code": 422, "response_status": "Error", "response_message": "No se logró cancelar la orden del lado del courier MENSAJERÍA EJEMPLO" } ] } } } }, "400": { "description": "Parámetros inválidos. Mensajes posibles: `orderIds debe ser un UUID o un arreglo de UUIDs`, `orderIds no puede estar vacío`,\n`Máximo 50 órdenes por operación`, `Todos los orderIds deben ser UUIDs válidos`, `reason es requerido y debe ser una cadena válida`,\n`reason no puede exceder 255 caracteres`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sinOrdenes": { "summary": "No se envió `orderIds` ni `orderId`, o no es texto ni arreglo.", "value": { "response_code": 400, "response_status": "Error", "response_message": "orderIds debe ser un UUID o un arreglo de UUIDs" } }, "maximo": { "summary": "Se enviaron más de 50 órdenes.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Máximo 50 órdenes por operación" } }, "uuidInvalido": { "summary": "Algún ID no es un UUID válido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Todos los orderIds deben ser UUIDs válidos" } }, "sinMotivo": { "summary": "Falta `reason`, no es texto o está vacío.", "value": { "response_code": 400, "response_status": "Error", "response_message": "reason es requerido y debe ser una cadena válida" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno al procesar la cancelación, o el body no es un JSON válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al procesar cancelación de órdenes" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Órdenes" }, "get": { "summary": "Obtener URL de la guía de envío", "operationId": "getOrderGuideUrl", "description": "Retorna la URL de la guía de envío (para visualizar o imprimir) de una orden del comercio.", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "OrderId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de la orden (`data.ordersId` al crearla).", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } ], "responses": { "200": { "description": "Guía obtenida correctamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "properties": { "guideUrl": { "type": "string", "description": "URL de la guía de envío, para visualizar o imprimir. Según el servicio, la genera la mensajería o Volao." } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Guía obtenida correctamente", "data": { "guideUrl": "https://mensajeria.example.com/guias/GUIA-PRUEBA.pdf" } } } } }, "400": { "description": "Falta el parámetro OrderId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "OrderId es requerido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No se encontró la guía de la orden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 404, "response_status": "Error", "response_message": "No se ha encontrado la guía correspondiente a este número de orden. Verifique que la orden haya sido procesada correctamente o intente más tarde." } } } }, "500": { "description": "Error interno al obtener la guía", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "general": { "summary": "Error interno al obtener la guía.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener la guía del número de orden" } }, "validacion": { "summary": "Error al validar la orden antes de obtener la guía.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al validar datos para captura de guía" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Órdenes" } }, "/api/orders/tracking": { "get": { "summary": "Obtener el resumen de seguimiento de una orden", "operationId": "getOrderTracking", "description": "Retorna el resumen de una orden del comercio: datos del comercio, del destinatario y de la orden, sus movimientos (el último es el estado actual) y las URLs de la guía y del seguimiento público. Los códigos de estado se interpretan con `GET /api/statusMain`.", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "OrderId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de la orden a rastrear.", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } ], "responses": { "200": { "description": "Resumen de la orden encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "$ref": "#/components/schemas/OrderTrackingSummary" } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Resumen de la orden obtenido correctamente", "data": { "commerce": { "branchsId": "0199a1b2-0000-7e5f-8a6b-1c2d3e4f0001", "branchsName": "Comercio Prueba", "branchsAddress": "Calle Principal 123, Colonia Prueba", "branchDepartment": "SAN SALVADOR", "branchsMunicipality": "SAN SALVADOR CENTRO" }, "recipient": { "recipientName": "Cliente Prueba", "recipientAddress": "Calle Ficticia #123", "recipientDepartment": "LA LIBERTAD", "recipientMunicipality": "LA LIBERTAD SUR", "comments": "Entregar en horario de oficina" }, "order": { "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "comprobante": "VOL-000123", "courierName": "Mensajería Ejemplo", "createdAt": "2026-10-07 10:15:00", "onDelivery": true, "consignmentValue": 25, "deliveryCost": 3.5, "totalWeight": 1.5, "cantPackages": 1, "productDescription": "Ropa" }, "trackingMovement": [ { "statusMainCode": "CONFIRMED", "statusMainDescription": "Pedido confirmado", "subStatusCode": "CONFIRMED", "subStatusDescription": "Pedido confirmado", "statusColor": "#2E7D32", "statusIcon": "fa-solid fa-check", "dateMovement": "2026-10-07 10:15:00", "datetimeMovementFormatted": "07/10/2026 10:15 a. m." }, { "statusMainCode": "IN_ROUTE", "statusMainDescription": "En ruta de entrega", "subStatusCode": "IN_ROUTE", "subStatusDescription": "En ruta de entrega", "statusColor": "#1565C0", "statusIcon": "fa-solid fa-truck", "dateMovement": "2026-10-07 14:30:00", "datetimeMovementFormatted": "07/10/2026 2:30 p. m." } ], "guide": { "URLguide": "https://mensajeria.example.com/guias/GUIA-PRUEBA.pdf" }, "tracking": { "URLtracking": "https://tracking.example.com/?orderId=0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008&identifier=abc123" } } } } } }, "400": { "description": "Falta el parámetro OrderId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "Debe enviar un orderId válido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno al obtener el resumen de la orden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error inesperado al obtener el resumen de la orden" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Órdenes" } }, "/api/orders/incidents": { "post": { "summary": "Obtener órdenes con incidencias", "operationId": "getCurrentIncidents", "description": "Retorna las órdenes del comercio que están actualmente en incidencia (por ejemplo, destinatario ausente o dirección incorrecta), con su última incidencia y el courier.\nIncluye un resumen: total de órdenes en incidencia, couriers y tipos de incidencia distintos, y la fecha de la incidencia más reciente.\n\nEs una consulta: no registra incidencias. El body es obligatorio, pero sus campos son opcionales: con `{}` retorna la primera página (10 órdenes).\nPara ver el detalle de todas las incidencias de una orden, usa `GET /api/orders/incidents/{ordersId}`.\n", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "search": { "type": "string", "maxLength": 250, "description": "Busca por ID de la orden, comprobante, referencia de integración (`integrationOrderRef`) o nombre del courier." } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "minimum": 1, "default": 10 } } } } }, "example": { "filters": { "search": "29137811" }, "pagination": { "page": 1, "limit": 10 } } } } }, "responses": { "200": { "description": "Órdenes en incidencia obtenidas", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "properties": { "pagination": { "type": "object", "description": "Paginación de las órdenes.", "properties": { "page": { "type": "integer", "description": "Página actual." }, "limit": { "type": "integer", "description": "Cantidad de órdenes por página." }, "total": { "type": "integer", "description": "Total de órdenes en incidencia que coinciden con la búsqueda." }, "totalPages": { "type": "integer", "description": "Total de páginas." }, "hasNext": { "type": "integer", "enum": [ 0, 1 ], "description": "1 si hay una página siguiente." }, "hasPrev": { "type": "integer", "enum": [ 0, 1 ], "description": "1 si hay una página anterior." } } }, "summary": { "type": "object", "description": "Resumen de las órdenes en incidencia del comercio.", "properties": { "totalOrdersInIncident": { "type": "integer", "description": "Total de órdenes en incidencia." }, "totalDistinctCouriers": { "type": "integer", "description": "Cantidad de mensajerías distintas con órdenes en incidencia." }, "totalDistinctIncidentStatuses": { "type": "integer", "description": "Cantidad de tipos de incidencia distintos." }, "latestIncidentAt": { "type": "string", "nullable": true, "description": "Fecha de la incidencia más reciente (`YYYY-MM-DD HH:mm:ss`)." } } }, "orders": { "type": "array", "description": "Órdenes en incidencia de la página actual, con su última incidencia.", "items": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "comprobante": { "type": "string", "nullable": true, "description": "Número de comprobante de la guía." }, "integrationOrderRef": { "type": "string", "nullable": true, "description": "Número de la orden en el sistema del comercio, si se envió al crearla." }, "courier": { "type": "object", "description": "Mensajería de la orden.", "properties": { "courierId": { "type": "string", "format": "uuid" }, "courierName": { "type": "string" }, "courierLogo": { "type": "string", "nullable": true, "description": "URL del logo de la mensajería." } } }, "latestIncident": { "type": "object", "description": "Última incidencia reportada de la orden.", "properties": { "incidentId": { "type": "string", "format": "uuid" }, "statusMainId": { "type": "string", "format": "uuid", "description": "ID del estado (catálogo `GET /api/statusMain`)." }, "statusDescription": { "type": "string", "description": "Nombre del estado, en español." }, "subStatusId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del subestado (catálogo `GET /api/subStatusMain`)." }, "subStatusDescription": { "type": "string", "nullable": true, "description": "Nombre del subestado, en español." }, "comment": { "type": "string", "nullable": true, "description": "Comentario registrado con la incidencia." }, "reportedAt": { "type": "string", "description": "Fecha en que se reportó la incidencia (`YYYY-MM-DD HH:mm:ss`)." } } } } } } } } } }, "example": { "response_code": 200, "response_status": "success", "response_message": "Incidencias actuales obtenidas correctamente.", "data": { "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1, "hasNext": 0, "hasPrev": 0 }, "summary": { "totalOrdersInIncident": 1, "totalDistinctCouriers": 1, "totalDistinctIncidentStatuses": 1, "latestIncidentAt": "2026-10-08 09:30:00" }, "orders": [ { "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "comprobante": "29137811", "integrationOrderRef": null, "courier": { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierName": "Mensajería Ejemplo", "courierLogo": "https://storage.example.com/logos/mensajeria-ejemplo.png" }, "latestIncident": { "incidentId": "0199a1b2-1717-7e5f-8a6b-1c2d3e4f0071", "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0025", "statusDescription": "Incidencia", "subStatusId": "0199a1b2-6666-7e5f-8a6b-1c2d3e4f0035", "subStatusDescription": "Incidencia reportada", "comment": "No se encontró al destinatario en la dirección.", "reportedAt": "2026-10-08 09:30:00" } } ] } } } } }, "400": { "description": "Filtro o paginación inválidos. Formato del mensaje: `Error en campo \"\": `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "search": { "summary": "search no es texto o supera 250 caracteres.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.search\": debe ser texto válido (máx. 250 caracteres)" } }, "page": { "summary": "page no es un entero positivo.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"pagination.page\": debe ser un entero positivo" } }, "limit": { "summary": "limit no es un entero positivo.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"pagination.limit\": debe ser un entero positivo" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener las incidencias actuales" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Órdenes" }, "get": { "summary": "Obtener las incidencias de una orden (por parámetro)", "operationId": "getOrderIncidentsByQuery", "description": "Igual que `GET /api/orders/incidents/{ordersId}`, pero recibe el ID de la orden como parámetro `OrderId` en la URL.\n", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "OrderId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de la orden (`data.ordersId` al crearla).", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } ], "responses": { "200": { "description": "Incidencias de la orden obtenidas. Misma respuesta que `GET /api/orders/incidents/{ordersId}`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "$ref": "#/components/schemas/OrderIncidentsDetail" } } }, "example": { "response_code": 200, "response_status": "success", "response_message": "Incidencias de la orden obtenidas correctamente.", "data": { "order": { "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "comprobante": "29137811", "integrationOrderRef": null, "isCurrentlyInIncident": true, "currentStatus": { "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0025", "description": "Incidencia", "flowGroup": "incident", "color": "#e67e22", "icon": "triangle-exclamation" } }, "summary": { "totalIncidents": 1 }, "incidents": [ { "incidentId": "0199a1b2-1717-7e5f-8a6b-1c2d3e4f0071", "trackingId": "0199a1b2-1818-7e5f-8a6b-1c2d3e4f0072", "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0025", "statusDescription": "Incidencia", "statusColor": "#e67e22", "statusIcon": "triangle-exclamation", "subStatusId": "0199a1b2-6666-7e5f-8a6b-1c2d3e4f0035", "subStatusDescription": "Incidencia reportada", "comment": "No se encontró al destinatario en la dirección.", "source": "tracking", "reportedAt": "2026-10-08 09:30:00" } ] } } } } }, "400": { "description": "Falta el parámetro OrderId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "OrderId es requerido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener las incidencias de la orden" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Órdenes" } }, "/api/orders/incidents/{ordersId}": { "get": { "summary": "Obtener las incidencias de una orden", "operationId": "getOrderIncidents", "description": "Retorna el estado actual de una orden del comercio y todas sus incidencias, de la más reciente a la más antigua.\n`order.isCurrentlyInIncident` indica si la orden sigue en incidencia.\n", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "ordersId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de la orden (`data.ordersId` al crearla).", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } ], "responses": { "200": { "description": "Incidencias de la orden obtenidas", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "$ref": "#/components/schemas/OrderIncidentsDetail" } } }, "example": { "response_code": 200, "response_status": "success", "response_message": "Incidencias de la orden obtenidas correctamente.", "data": { "order": { "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "comprobante": "29137811", "integrationOrderRef": null, "isCurrentlyInIncident": true, "currentStatus": { "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0025", "description": "Incidencia", "flowGroup": "incident", "color": "#e67e22", "icon": "triangle-exclamation" } }, "summary": { "totalIncidents": 1 }, "incidents": [ { "incidentId": "0199a1b2-1717-7e5f-8a6b-1c2d3e4f0071", "trackingId": "0199a1b2-1818-7e5f-8a6b-1c2d3e4f0072", "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0025", "statusDescription": "Incidencia", "statusColor": "#e67e22", "statusIcon": "triangle-exclamation", "subStatusId": "0199a1b2-6666-7e5f-8a6b-1c2d3e4f0035", "subStatusDescription": "Incidencia reportada", "comment": "No se encontró al destinatario en la dirección.", "source": "tracking", "reportedAt": "2026-10-08 09:30:00" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener las incidencias de la orden" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Órdenes" } }, "/api/courier/serviceMode": { "get": { "summary": "Obtener modalidades de servicio", "operationId": "getServiceModes", "description": "Retorna las modalidades de servicio disponibles. El `serviceModeCode` se envía como `typeService` al cotizar (`POST /api/courier`).", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Modalidades obtenidas", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "serviceModeId": { "type": "string", "format": "uuid", "description": "ID de la modalidad. Se puede enviar como `serviceTypeId` en `GET /api/courier/services`." }, "serviceModeCode": { "type": "string", "description": "Código de la modalidad. Se envía como `typeService` al cotizar." }, "serviceModeName": { "type": "string" }, "serviceModeDescription": { "type": "string" }, "requiresCoverageValidation": { "type": "boolean", "description": "La modalidad valida la cobertura del destino." } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Modos de servicio obtenidos correctamente", "data": [ { "serviceModeId": "0199a1b2-eeee-7e5f-8a6b-1c2d3e4f000f", "serviceModeCode": "NORMAL", "serviceModeName": "Entrega estándar", "serviceModeDescription": "Entrega en los días hábiles indicados por el courier.", "requiresCoverageValidation": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar las modalidades.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error inesperado al obtener modos de servicio", "data": [] } }, "general": { "summary": "Error general del servidor.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener modos de servicio", "data": [] } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" } }, "/api/courier": { "post": { "summary": "Cotizar envío (couriers disponibles)", "operationId": "quoteShipment", "description": "Retorna los servicios de envío disponibles para una dirección de recolecta y un destino, con su costo, comisión, fechas estimadas y agencias.\nDel servicio elegido se toma el `courierServiceId` para crear la orden (`POST /api/orders`).\n", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "branchAddressId", "shippingAmount", "weight", "municipalityCode", "courierName", "typeService" ], "properties": { "branchAddressId": { "type": "string", "format": "uuid", "description": "Dirección de recolecta (`GET /api/branchs/branchsAddresses`).", "example": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" }, "municipalityCode": { "type": "string", "format": "uuid", "description": "Municipio de destino. Se envía el `municipalityId` del cliente destinatario (`GET /api/branchs/branchsClient`) o de `POST /api/open/municipality`.", "example": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005" }, "shippingAmount": { "type": "number", "minimum": 0, "description": "Monto a cobrar al destinatario, como número (no texto), sin signo y con máximo 2 decimales. Puede ser 0.", "example": 10 }, "weight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Peso total, como número mayor que 0.", "example": 4 }, "cantPackages": { "type": "integer", "minimum": 1, "description": "Opcional. Cantidad de paquetes, entero mayor que 0.", "example": 1 }, "courierName": { "type": "string", "maxLength": 100, "description": "Filtra por nombre de courier. Envíe `\"\"` para ver todos.", "example": "" }, "typeService": { "type": "string", "description": "Modalidad de servicio (`serviceModeCode` de `GET /api/courier/serviceMode`).", "example": "NORMAL" } } } } } }, "responses": { "200": { "description": "Servicios disponibles con su costo", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CourierQuoteOption" } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Consulta ejecutada correctamente", "data": [ { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierServiceId": "019f88a7-40d5-75b5-add9-87e652d9ba69", "courierName": "Mensajería Ejemplo", "serviceName": "Entrega a domicilio", "serviceTypeName": "Servicio Normal", "path_logo": "https://example.com/logos/mensajeria-ejemplo.png", "isSameDay": false, "enableGeoreference": false, "deliveryCost": 3.39, "hasDeliveryPromotion": 0, "previousDeliveryCost": null, "ComCCE": 0.5, "hasCommissionPromotion": 0, "previousComCCE": null, "enablePromotionLabel": false, "enableRecommended": true, "courierDates": { "collectionDate": "2026-10-08", "collectionDay": "Jueves", "pickupStartTime": "08:00", "pickupEndTime": "17:00", "deliveryDate": "2026-10-09", "deliveryDay": "Viernes", "collectionDate_byCoverage": "2026-10-08", "deliveryDate_byCoverage": "2026-10-09", "collectionMessage": "Recolección hoy", "deliveryMessage": "Entrega mañana", "alertColor_collection": "#2E7D32", "alertColor_delivery": "#2E7D32", "collectionAlert": 0 }, "courierInfo": { "weightLimit": 50, "sizeLimit": "60x60x60 cm", "additionalPoundCost": 0.25, "insuranceCoverage": 100, "returnCost": 2.5, "returnTimeEstimate": 3, "maximumEffectiveLimit": 500, "minimumConsignmentRequired": 0, "baseCommissionTotal": 0.5, "maximumCollectionTime": "13:00", "collectionTime": null, "deliveryTime": null, "text_coverage": "Cobertura nacional", "phoneNumber": "70000000", "averageRating": "4.5" }, "courierLabels": { "labels": [ { "label": "Recomendado", "label_color": "#2E7D32", "icon": null, "iconVariant": null } ], "customLabels": [] }, "agencies": [] } ] } } } }, "400": { "description": "Datos inválidos. Formato del mensaje: `Error en campo \"\": `.\nPrimero se revisa que vengan todos los campos obligatorios (`es requerido y no fue enviado`) y después el formato de cada campo; se reporta el primer error.\n\nMotivos por campo:\n- `branchAddressId`, `municipalityCode`: `debe ser un UUID válido`\n- `shippingAmount`: `debe ser un número válido con hasta dos decimales`\n- `weight`: `debe ser un número válido mayor a 0`\n- `cantPackages`: `debe ser un número entero válido mayor a 0`\n- `courierName`: `es texto, puede ir vacío, no debe exceder 100 caracteres`\n- `typeService`: `debe ser un string válido`\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "faltante": { "summary": "Campo obligatorio no enviado", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"typeService\": es requerido y no fue enviado" } }, "invalido": { "summary": "Destino con formato inválido", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"municipalityCode\": debe ser un UUID válido" } }, "monto": { "summary": "Monto negativo, enviado como texto o con más de 2 decimales", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"shippingAmount\": debe ser un número válido con hasta dos decimales" } }, "peso": { "summary": "Peso igual a 0, negativo o enviado como texto", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"weight\": debe ser un número válido mayor a 0" } }, "paquetes": { "summary": "Cantidad de paquetes que no es un entero mayor que 0", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"cantPackages\": debe ser un número entero válido mayor a 0" } }, "nombreCourier": { "summary": "courierName no es texto o pasa de 100 caracteres", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"courierName\": es texto, puede ir vacío, no debe exceder 100 caracteres" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno. También se responde 500 si el cuerpo no es un JSON válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar los servicios.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener couriers", "data": [] } }, "general": { "summary": "Error general, por ejemplo un cuerpo que no es JSON válido.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los couriers: " } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" }, "get": { "summary": "Obtener mensajerías por servicio", "operationId": "getCouriersByService", "description": "Retorna los servicios de todos los couriers activos, agrupados por código de servicio, con sus límites, precios y condiciones de entrega.\nLos grupos vienen en orden alfabético, con los servicios de agencia al final.\n", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Servicios agrupados por código de servicio. Cada clave de `data` es un código de servicio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/CourierServiceItem" } } } } }, "example": { "response_code": 200, "response_status": "success", "response_message": "Couriers obtenidos correctamente", "data": { "DOMICILIO": [ { "courierServiceId": "019f88a7-40d5-75b5-add9-87e652d9ba69", "courier": { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierName": "Mensajería Ejemplo", "courierLogo": "https://example.com/logos/mensajeria-ejemplo.png", "courierLabelText": null, "courierEnableGeoreference": false, "courierAverageRating": 4.5 }, "service": { "serviceCode": "DOMICILIO", "serviceName": "Entrega a domicilio", "serviceType": { "serviceTypeCode": "NORMAL", "serviceTypeName": "Servicio Normal", "serviceTypeRequiresCoverageValidation": true } }, "limits": { "limitMaximumWeight": 50, "limitWeightUnit": "lb", "limitMaximumDimensions": "60x60x60 cm", "limitMaximumCashAmount": 500, "limitMaximumPickupTime": "17:00" }, "pricing": { "pricingRateRange": "$2.50 - $5.00", "pricingAdditionalWeightUnitCost": 0.25, "pricingInsurancePerShipment": null, "pricingReturnCost": 2.5, "pricingComCCE": 0.5 }, "delivery": { "deliverySameDayService": false, "deliveryFreeAttempts": 2, "deliveryReturnTimeEstimateDays": 3, "deliveryCoverageText": "Cobertura nacional", "deliveryPromotionLabelEnabled": false }, "agencies": { "agenciesHasAgencies": false, "agenciesCount": 0 } } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar los servicios.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error inesperado al obtener los couriers por servicio", "data": {} } }, "general": { "summary": "Error general del servidor.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los couriers" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" } }, "/api/courier/coverage": { "get": { "summary": "Obtener la cobertura de un servicio de courier", "operationId": "getCourierCoverage", "description": "Retorna los departamentos, municipios y distritos que cubre un servicio de courier, con los días de cobertura de cada distrito.", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "courierServiceId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Servicio de courier (`courierServiceId` de la cotización o de `GET /api/courier`).", "example": "019f88a7-40d5-75b5-add9-87e652d9ba69" } ], "responses": { "200": { "description": "Cobertura obtenida", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "courierId": { "type": "string", "format": "uuid" }, "serviceId": { "type": "string", "format": "uuid" }, "courierName": { "type": "string" }, "departments": { "type": "array", "items": { "type": "object", "properties": { "departmentId": { "type": "string", "format": "uuid" }, "departmentName": { "type": "string" }, "municipalities": { "type": "array", "items": { "type": "object", "properties": { "municipalityId": { "type": "string", "format": "uuid" }, "municipalityName": { "type": "string" }, "districts": { "type": "array", "items": { "type": "object", "properties": { "districtId": { "type": "string", "format": "uuid" }, "districtName": { "type": "string" }, "daysCoverage": { "type": "string", "description": "Días de la semana en que el servicio cubre el distrito." } } } } } } } } } } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Cobertura obtenida correctamente", "data": [ { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "serviceId": "0199a1b2-ffff-7e5f-8a6b-1c2d3e4f0010", "courierName": "Mensajería Ejemplo", "departments": [ { "departmentId": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004", "departmentName": "SAN SALVADOR", "municipalities": [ { "municipalityId": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005", "municipalityName": "SAN SALVADOR CENTRO", "districts": [ { "districtId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0006", "districtName": "SAN SALVADOR", "daysCoverage": "Lunes a sábado" } ] } ] } ] } ] } } } }, "400": { "description": "Falta el courierServiceId o no es un UUID válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "courierServiceId es requerido y debe ser un UUID válido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar la cobertura.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener la cobertura del courier.", "data": [] } }, "general": { "summary": "Error general del servidor.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener cobertura del courier" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" } }, "/api/courier/agencies": { "get": { "summary": "Obtener agencias de un courier", "operationId": "getCourierAgencies", "description": "Retorna las agencias de un courier, para los servicios que entregan o recolectan en agencia. El `agencyId` se envía en `courier.agencias` al crear la orden.", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "courierId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Courier (`courierId` de la cotización o de `GET /api/courier`).", "example": "019f81b1-a481-77d5-be76-6c74b42c1e59" }, { "in": "query", "name": "searchText", "schema": { "type": "string" }, "description": "Opcional. Filtra las agencias por texto." } ], "responses": { "200": { "description": "Agencias obtenidas", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "properties": { "agencies": { "type": "array", "items": { "$ref": "#/components/schemas/CourierAgency" } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Agencias obtenidas correctamente", "data": { "agencies": [ { "agencyId": "0199a1b2-abcd-7e5f-8a6b-1c2d3e4f0011", "agencyName": "Agencia Centro", "agencyAddress": "Calle Ficticia #123, San Salvador", "scheduleDescription": "Lunes a viernes de 8:00 a 17:00", "isActive": true, "createdAt": "2026-01-15T10:00:00Z", "location": { "district": { "districtId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0006", "code": "060101", "name": "SAN SALVADOR" }, "municipality": { "municipalityId": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005", "code": "0601", "name": "SAN SALVADOR CENTRO" }, "department": { "departmentId": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004", "code": "06", "name": "SAN SALVADOR" } } } ] } } } } }, "400": { "description": "Falta el courierId o no es un UUID válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "El parámetro courierId es requerido y debe ser un UUID válido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar las agencias.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener agencias del courier" } }, "general": { "summary": "Error general del servidor.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error interno del servidor al obtener agencias del courier" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" } }, "/api/courier/generalRates": { "get": { "summary": "Obtener tarifas generales de los couriers", "operationId": "getCourierGeneralRates", "description": "Retorna las tarifas generales de los couriers disponibles para el comercio autenticado, por servicio.", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Tarifas obtenidas", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "courierId": { "type": "string", "format": "uuid" }, "courierLogo": { "type": "string", "nullable": true, "description": "URL del logo del courier." }, "courierName": { "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "format": "uuid" }, "serviceName": { "type": "string" }, "serviceTypes": { "type": "array", "items": { "type": "object", "properties": { "courierServiceId": { "type": "string", "format": "uuid", "description": "Servicio de envío." }, "serviceTypeId": { "type": "string", "format": "uuid" }, "serviceTypeName": { "type": "string" }, "rate": { "type": "number", "description": "Tarifa general del servicio." } } } } } } } } } } } }, "example": { "response_code": 200, "response_status": "success", "response_message": "Tarifas obtenidas correctamente", "data": [ { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierLogo": "https://example.com/logos/mensajeria-ejemplo.png", "courierName": "Mensajería Ejemplo", "services": [ { "serviceId": "0199a1b2-aaaa-7e5f-8a6b-1c2d3e4f0041", "serviceName": "DEPARTAMENTAL / NEXT DAY", "serviceTypes": [ { "courierServiceId": "019f88a7-40d5-75b5-add9-87e652d9ba69", "serviceTypeId": "0199a1b2-bbbb-7e5f-8a6b-1c2d3e4f0042", "serviceTypeName": "Servicio Normal", "rate": 3.1 } ] } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar las tarifas.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error al obtener tarifas generales de couriers", "data": [] } }, "general": { "summary": "Error general del servidor.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener tarifas generales del courier" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" } }, "/api/courier/services": { "get": { "summary": "Obtener couriers por tipo de servicio", "operationId": "getCouriersByServiceType", "description": "Retorna los servicios de los couriers activos agrupados por tipo de servicio (por ejemplo, `NORMAL` o `PRIORITY`).\nPor cada servicio: el courier, sus límites (peso, dimensiones, monto máximo a cobrar, hora límite de recolección), precios, condiciones de entrega y si trabaja con agencias.\n\nSirve para mostrar las opciones de envío y sus condiciones. Para el precio exacto de un envío, cotiza con `POST /api/courier`.\n", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "serviceTypeId", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Opcional. Retorna solo los servicios de este tipo de servicio (`serviceModeId` de `GET /api/courier/serviceMode`). Si se envía vacío, se ignora." } ], "responses": { "200": { "description": "Couriers agrupados por tipo de servicio. Cada clave de `data` es el código del tipo de servicio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/CourierServiceItem" }, { "type": "object", "properties": { "flags": { "type": "object", "properties": { "isNextDay": { "type": "boolean", "description": "El servicio entrega al día siguiente." }, "isSameDay": { "type": "boolean", "description": "El servicio entrega el mismo día." } } } } } ] } } } } }, "example": { "response_code": 200, "response_status": "success", "response_message": "Couriers agrupados por tipo de servicio obtenidos correctamente", "data": { "NORMAL": [ { "courierServiceId": "019f88a7-40d5-75b5-add9-87e652d9ba69", "flags": { "isNextDay": true, "isSameDay": false }, "courier": { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierName": "Mensajería Ejemplo", "courierLogo": "https://example.com/logos/mensajeria-ejemplo.png", "courierLabelText": null, "courierEnableGeoreference": false, "courierAverageRating": 4.5 }, "service": { "serviceCode": "NEXT_DAY", "serviceName": "DEPARTAMENTAL / NEXT DAY", "serviceType": { "serviceTypeCode": "NORMAL", "serviceTypeName": "Servicio Normal", "serviceTypeRequiresCoverageValidation": true } }, "limits": { "limitMaximumWeight": 50, "limitWeightUnit": "lb", "limitMaximumDimensions": "50x50x50", "limitMaximumCashAmount": 1000, "limitMaximumPickupTime": "13:00:00" }, "pricing": { "pricingRateRange": "$3.10", "pricingAdditionalWeightUnitCost": 0.13, "pricingInsurancePerShipment": 100, "pricingReturnCost": 0, "pricingComCCE": 2 }, "delivery": { "deliverySameDayService": false, "deliveryFreeAttempts": 2, "deliveryReturnTimeEstimateDays": 3, "deliveryCoverageText": null, "deliveryPromotionLabelEnabled": false }, "agencies": { "agenciesHasAgencies": false, "agenciesCount": 0 } } ] } } } } }, "400": { "description": "serviceTypeId no es un UUID válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "El parámetro \"serviceTypeId\" debe ser un UUID válido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Ningún courier activo ofrece el tipo de servicio indicado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar los servicios.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error inesperado al obtener los couriers por tipo de servicio", "data": {} } }, "general": { "summary": "Error general del servidor.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los couriers por tipo de servicio" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" } }, "/api/courier/deliveryPromise": { "get": { "summary": "Obtener promesas de entrega", "operationId": "getDeliveryPromises", "description": "Retorna el catálogo de promesas de entrega: el tiempo en que se compromete a entregar cada tipo de servicio (por ejemplo, entrega al día siguiente).\n", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Promesas de entrega obtenidas", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "deliveryPromiseId": { "type": "string", "format": "uuid" }, "deliveryPromiseCode": { "type": "string" }, "deliveryPromiseName": { "type": "string" }, "deliveryPromiseDescription": { "type": "string" } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Promesas de entrega obtenidas correctamente", "data": [ { "deliveryPromiseId": "01970000-0000-7000-8000-000000000048", "deliveryPromiseCode": "NEXT_DAY", "deliveryPromiseName": "DEPARTAMENTAL / NEXT DAY", "deliveryPromiseDescription": "Entrega al día siguiente" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar las promesas de entrega.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error inesperado al obtener promesas de entrega", "data": [] } }, "general": { "summary": "Error general del servidor.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener promesas de entrega", "data": [] } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" } }, "/api/courier/coverage/operational": { "get": { "summary": "Obtener la cobertura operativa de un servicio", "operationId": "getOperationalCoverage", "description": "Retorna, por departamento y municipio, dónde opera un servicio de envío: si tiene cobertura de recolección y de entrega, los días en que opera y el horario de recolección.\nSirve para saber antes de cotizar si un servicio llega al municipio del cliente.\n", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "courierServiceId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Servicio de envío (`courierServiceId` de `POST /api/courier` o de `GET /api/courier/services`).", "example": "019f88a7-40d5-75b5-add9-87e652d9ba69" }, { "in": "query", "name": "coverageType", "required": false, "schema": { "type": "string", "enum": [ "ALL", "PICKUP", "DELIVERY" ], "default": "ALL" }, "description": "Tipo de cobertura, de recolección, de entrega o ambas. No distingue mayúsculas de minúsculas." }, { "in": "query", "name": "departmentsJson", "required": false, "schema": { "type": "string" }, "description": "Opcional. Arreglo JSON con los UUID de los departamentos a consultar (`departmentId` de `GET /api/open/departments`).", "example": "[\"0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004\"]" }, { "in": "query", "name": "searchText", "required": false, "schema": { "type": "string" }, "description": "Opcional. Texto a buscar en los nombres de departamentos y municipios." } ], "responses": { "200": { "description": "Cobertura operativa obtenida", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "courierServiceId": { "type": "string", "format": "uuid" }, "courierId": { "type": "string", "format": "uuid" }, "courierName": { "type": "string" }, "coverageType": { "type": "string", "enum": [ "ALL", "PICKUP", "DELIVERY" ], "description": "Tipo de cobertura consultado." }, "coverage": { "type": "object", "properties": { "label": { "type": "string" }, "departments": { "type": "array", "items": { "type": "object", "properties": { "departmentId": { "type": "string", "format": "uuid" }, "departmentName": { "type": "string" }, "municipalities": { "type": "array", "items": { "type": "object", "properties": { "municipalityId": { "type": "string", "format": "uuid" }, "municipalityName": { "type": "string" }, "hasPickupCoverage": { "type": "boolean", "description": "El servicio recolecta en el municipio." }, "hasDeliveryCoverage": { "type": "boolean", "description": "El servicio entrega en el municipio." }, "daysCoverage": { "type": "string", "description": "Días en que opera, separados por coma (`L`, `M`, `Mi`, `J`, `V`, `S`, `D`)." }, "pickupStartTime": { "type": "string", "nullable": true, "description": "Inicio del horario de recolección." }, "pickupEndTime": { "type": "string", "nullable": true, "description": "Fin del horario de recolección." } } } } } } } } } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Coberturas operativas del courier obtenidas correctamente", "data": [ { "courierServiceId": "019f88a7-40d5-75b5-add9-87e652d9ba69", "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierName": "Mensajería Ejemplo", "coverageType": "ALL", "coverage": { "label": "Coberturas operativas", "departments": [ { "departmentId": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004", "departmentName": "Ahuachapán", "municipalities": [ { "municipalityId": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005", "municipalityName": "Ahuachapán", "hasPickupCoverage": true, "hasDeliveryCoverage": true, "daysCoverage": "L,M,Mi,J,V,S", "pickupStartTime": "08:00:00", "pickupEndTime": "14:00:00" } ] } ] } } ] } } } }, "400": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "courierServiceId": { "summary": "Falta courierServiceId o no es un UUID válido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "El parámetro courierServiceId es requerido y debe ser un UUID válido" } }, "coverageType": { "summary": "coverageType no es ALL, PICKUP ni DELIVERY.", "value": { "response_code": 400, "response_status": "Error", "response_message": "El parámetro coverageType es inválido. Los valores permitidos son: ALL, PICKUP, DELIVERY" } }, "departmentsJson": { "summary": "departmentsJson no es un arreglo JSON de textos.", "value": { "response_code": 400, "response_status": "Error", "response_message": "El parámetro departmentsJson debe ser un arreglo de strings válido" } }, "departmentsJsonFormato": { "summary": "departmentsJson no es un JSON válido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "El parámetro departmentsJson no es un JSON válido" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "El servicio no existe o no está activo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 404, "response_status": "Error", "response_message": "El courierServiceId (019f88a7-40d5-75b5-add9-87e652d9ba69) no existe o no está activo" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar la cobertura operativa.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener las coberturas operativas del courier.", "data": [] } }, "general": { "summary": "Error general del servidor.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener las coberturas operativas del courier" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Couriers" } }, "/api/branchs/branchsAddresses": { "get": { "summary": "Obtener direcciones de sucursal", "operationId": "getBranchAddresses", "description": "Retorna las direcciones de recolecta del comercio. Envíe `-1` para obtener todas, o el UUID de una dirección para obtener solo esa.", "tags": [ "Direcciones de Sucursales (Branch Addresses)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "branchAddressId", "required": true, "schema": { "type": "string" }, "description": "`-1` para todas las direcciones, o el UUID de una dirección.", "example": "-1" } ], "responses": { "200": { "description": "Direcciones obtenidas correctamente", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "description": "Direcciones del comercio (una sola si se envió el UUID de una dirección).", "items": { "$ref": "#/components/schemas/BranchAddress" } } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Direcciones procesadas correctamente", "data": [ { "branchAddressId": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b", "branchAddressName": "Casa / Domicilio · Bodega Prueba", "defaultAddress": 1, "branchsId": "0199a1b2-0000-7e5f-8a6b-1c2d3e4f0001", "typeBranchAddress": "0199a1b2-1111-7e5f-8a6b-1c2d3e4f0002", "typeBranchAddressIcon": "fa-solid fa-house", "nameBranchAddress": "Casa / Domicilio", "collectionAddress": "Bodega Prueba", "contactName": "Cliente Prueba", "principalPhone": "70000000", "emailContact": "cliente.prueba@example.com", "georeference": "13.692940,-89.218191", "municipalityCode": "0102", "municipalitiesName": "APANECA", "departmentsCodigo": "01", "departmentsName": "AHUACHAPÁN" } ] } } } }, "400": { "description": "Falta el parámetro branchAddressId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "branchAddressId es requerido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "El comercio no tiene direcciones o la dirección no existe. El mensaje incluye el valor enviado en `branchAddressId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "direccion": { "summary": "La dirección no existe o no pertenece al comercio.", "value": { "response_code": 404, "response_status": "Error", "response_message": "No se encontró dirección con branchAddressId 0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b", "data": [] } }, "sinDirecciones": { "summary": "Se envió `-1` y el comercio no tiene direcciones.", "value": { "response_code": 404, "response_status": "Error", "response_message": "No se encontró dirección con branchAddressId -1", "data": [] } } } } } }, "500": { "description": "Error interno (por ejemplo, un `branchAddressId` que no es `-1` ni un UUID válido).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al capturar las direcciones: ", "data": [] } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Direcciones de recolecta" }, "post": { "summary": "Crear nueva dirección de sucursal", "operationId": "createBranchAddress", "description": "Registra una nueva dirección de recolecta para el comercio. El tipo de dirección sale de `GET /api/open/typeBranchAddress` y el municipio de `POST /api/open/municipality`.", "tags": [ "Direcciones de Sucursales (Branch Addresses)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchAddressBody" } } } }, "responses": { "201": { "description": "Dirección registrada", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchAddressId": { "type": "string", "format": "uuid", "description": "ID de la dirección creada. Se usa como `branchInfo.branchAddressId` al crear una orden." } } } ] }, "example": { "response_code": 201, "response_status": "success", "response_message": "Dirección registrada correctamente.", "branchAddressId": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" } } } }, "400": { "description": "Errores de validación. La API reúne todos los errores en un solo mensaje, separados por `;`.\nMensajes posibles por campo: `es requerido`, `debe ser una cadena`, `debe tener al menos N caracteres`, `no debe exceder los N caracteres`, `tiene un formato inválido`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "Errores de validación en los campos: \"phoneNumber\": tiene un formato inválido; \"typeBranchAddressId\": debe ser una cadena" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Ya existe una dirección activa con el mismo nombre", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 409, "response_status": "Error", "response_message": "Ya existe otra dirección activa con el mismo nombre en tu comercio." } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "registro": { "summary": "Error al guardar la dirección.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al crear dirección de recolecta: " } }, "general": { "summary": "Error general (por ejemplo, el body no es un JSON válido).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al capturar las direcciones de la sucursal" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Direcciones de recolecta" }, "put": { "summary": "Actualizar dirección de sucursal", "operationId": "updateBranchAddress", "description": "Actualiza una dirección de recolecta existente. Se envían todos los campos de la creación más el `branchAddressId`.", "tags": [ "Direcciones de Sucursales (Branch Addresses)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "branchAddressId" ], "properties": { "branchAddressId": { "type": "string", "format": "uuid", "example": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" } } }, { "$ref": "#/components/schemas/BranchAddressBody" } ] } } } }, "responses": { "200": { "description": "Dirección actualizada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSuccessResponse" }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Dirección actualizada correctamente" } } } }, "400": { "description": "Errores de validación (mismo formato que en la creación; incluye `branchAddressId`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "Errores de validación en los campos: \"branchAddressId\": es requerido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Regla de negocio (por ejemplo, nombre duplicado)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 409, "response_status": "Error", "response_message": "" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "actualizacion": { "summary": "Error al guardar los cambios.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar dirección de recolecta: " } }, "general": { "summary": "Error general (por ejemplo, el body no es un JSON válido).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar la dirección de recolecta" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Direcciones de recolecta" }, "delete": { "summary": "Eliminar dirección de sucursal", "operationId": "deleteBranchAddress", "description": "Elimina una dirección de recolecta del comercio. El id se envía en el body.", "tags": [ "Direcciones de Sucursales (Branch Addresses)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "branchAddressId" ], "properties": { "branchAddressId": { "type": "string", "format": "uuid", "example": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" } } } } } }, "responses": { "200": { "description": "Dirección eliminada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSuccessResponse" }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Dirección eliminada correctamente" } } } }, "400": { "description": "Falta el branchAddressId o no es texto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "El campo \"branchAddressId\" es requerido y debe ser una cadena (UUID)." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "eliminacion": { "summary": "Error al eliminar la dirección.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al eliminar la dirección de recolecta: " } }, "general": { "summary": "Error general (por ejemplo, el body no es un JSON válido).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al eliminar la dirección de recolección." } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Direcciones de recolecta" }, "patch": { "summary": "Establecer dirección predeterminada", "operationId": "setDefaultBranchAddress", "description": "Marca una dirección como la predeterminada del comercio (`defaultAddress = 1`).", "tags": [ "Direcciones de Sucursales (Branch Addresses)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "branchAddressId" ], "properties": { "branchAddressId": { "type": "string", "format": "uuid", "example": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" } } } } } }, "responses": { "200": { "description": "Dirección predeterminada actualizada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSuccessResponse" }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Dirección predeterminada establecida correctamente" } } } }, "400": { "description": "Falta el branchAddressId o no es texto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "El campo \"branchAddressId\" es requerido y debe ser una cadena (UUID)." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "predeterminada": { "summary": "Error al guardar la dirección predeterminada.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al establecer la dirección predeterminada: " } }, "general": { "summary": "Error general (por ejemplo, el body no es un JSON válido).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al establecer la dirección predeterminada." } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Direcciones de recolecta" } }, "/api/branchs/branchsClient": { "get": { "summary": "Obtener clientes de la sucursal", "operationId": "getBranchClients", "description": "Retorna los clientes/destinatarios del comercio, ordenados con los favoritos primero. Permite obtener un solo cliente o filtrar por favoritos.", "tags": [ "Clientes de Sucursales (Branch Clients)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "branchsClientId", "schema": { "type": "string", "format": "uuid" }, "description": "Opcional. UUID de un cliente para obtener solo ese registro. Sin este parámetro, o si no es un UUID válido, se ignora y retorna todos." }, { "in": "query", "name": "favorite", "schema": { "type": "string", "enum": [ "-1", "0", "1", "true" ], "default": "0" }, "description": "`-1` = todos, `1` o `true` = solo favoritos, `0` = solo no favoritos. Si se omite o tiene otro valor se usa `0`: envíe `-1` para obtener todos.", "example": "-1" } ], "responses": { "200": { "description": "Clientes obtenidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchClientListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar los clientes.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener clientes de la sucursal", "data": [] } }, "general": { "summary": "Error general.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener clientes" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Clientes y direcciones de entrega" }, "post": { "summary": "Registrar nuevo cliente", "operationId": "createBranchClient", "description": "Crea un nuevo cliente/destinatario asociado al comercio.", "tags": [ "Clientes de Sucursales (Branch Clients)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchClientBody" }, { "type": "object", "properties": { "saveClient": { "type": "boolean", "description": "Opcional. `true` guarda el cliente en la libreta del comercio. Por defecto `false`. También acepta `1` y `0`; otro valor responde 400 (`solo puede ser 0 o 1`).", "example": true } } } ] } } } }, "responses": { "201": { "description": "Cliente registrado", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "ID del cliente registrado. Se usa como `branchInfo.branchsClientId` al crear una orden." } } } ] }, "example": { "response_code": 201, "response_status": "Success", "response_message": "Cliente procesado correctamente", "branchsClientId": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003" } } } }, "400": { "description": "Errores de validación. La API reúne todos los errores en un solo mensaje, separados por `;`.\nMensajes posibles por campo: `es requerido`, `debe ser una cadena`, `debe tener al menos N caracteres`, `no debe exceder los N caracteres`, `tiene un formato inválido`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "Errores de validación en los campos: \"recipientPhone\": es requerido; \"municipalityCode\": tiene un formato inválido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno al crear el cliente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al crear el cliente: " } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Clientes y direcciones de entrega" }, "put": { "summary": "Actualizar datos de cliente", "operationId": "updateBranchClient", "description": "Actualiza la información de un cliente existente. Se envían todos los campos más el `branchsClientId`.", "tags": [ "Clientes de Sucursales (Branch Clients)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "branchsClientId" ], "properties": { "branchsClientId": { "type": "string", "format": "uuid", "example": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003" } } }, { "$ref": "#/components/schemas/BranchClientBody" } ] } } } }, "responses": { "200": { "description": "Cliente actualizado", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "ID del cliente actualizado. Puede no venir en la respuesta." } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Cliente actualizado correctamente" } } } }, "400": { "description": "Errores de validación (mismo formato que en la creación; incluye `branchsClientId`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "Errores de validación en los campos: \"branchsClientId\": es requerido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno al actualizar el cliente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar el cliente: " } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Clientes y direcciones de entrega" }, "delete": { "summary": "Eliminar cliente", "operationId": "deleteBranchClient", "description": "Elimina un cliente del comercio. El id se envía en el body.", "tags": [ "Clientes de Sucursales (Branch Clients)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "branchsClientId" ], "properties": { "branchsClientId": { "type": "string", "format": "uuid", "example": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003" } } } } } }, "responses": { "200": { "description": "Cliente eliminado", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "ID del cliente eliminado. Puede no venir en la respuesta." } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Cliente eliminado correctamente" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Falta el branchsClientId o no es un UUID válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 409, "response_status": "Error", "response_message": "branchsClientId es obligatorio y debe ser un UUID válido" } } } }, "500": { "description": "Error interno al eliminar el cliente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al eliminar el cliente: " } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Clientes y direcciones de entrega" }, "patch": { "summary": "Marcar o quitar cliente favorito", "operationId": "toggleBranchClientFavorite", "description": "Marca un cliente como favorito o le quita esa marca.", "tags": [ "Clientes de Sucursales (Branch Clients)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "branchsClientId", "favoriteStatus" ], "properties": { "branchsClientId": { "type": "string", "format": "uuid", "example": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003" }, "favoriteStatus": { "oneOf": [ { "type": "integer", "enum": [ 0, 1 ] }, { "type": "boolean" } ], "description": "`1` o `true` para marcarlo como favorito; `0` o `false` para quitarlo.", "example": 1 } } } } } }, "responses": { "200": { "description": "Estado de favorito actualizado", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "ID del cliente." }, "favorite": { "type": "boolean", "description": "`true` si el cliente quedó marcado como favorito; `false` si se le quitó la marca." } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Cliente marcado como favorito", "branchsClientId": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003", "favorite": true } } } }, "400": { "description": "Falta un parámetro o tiene un valor inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "branchsClientId (UUID) y favoriteStatus (0, 1, true o false) son obligatorios" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno al actualizar el favorito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar favorito del cliente: " } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Clientes y direcciones de entrega" } }, "/api/branchs/branchsClient/search": { "get": { "summary": "Buscar clientes de la sucursal", "operationId": "searchBranchClients", "description": "Busca clientes del comercio por texto (nombre, teléfono, correo…), con filtro opcional de favoritos. Retorna los favoritos primero.", "tags": [ "Clientes de Sucursales (Branch Clients)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Opcional. Texto a buscar.", "example": "Cliente Prueba" }, { "in": "query", "name": "favorite", "schema": { "type": "string", "enum": [ "-1", "0", "1", "true" ], "default": "0" }, "description": "`-1` = todos, `1` o `true` = solo favoritos, `0` = solo no favoritos. Si se omite o tiene otro valor se usa `0`: envíe `-1` para buscar entre todos.", "example": "-1" } ], "responses": { "200": { "description": "Búsqueda realizada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchClientListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar los clientes.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al buscar clientes de la sucursal", "data": [] } }, "general": { "summary": "Error general.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error al buscar clientes" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Sucursales/Clientes y direcciones de entrega" } }, "/api/branchs/history/orders": { "post": { "summary": "Obtener historial de órdenes", "operationId": "getOrdersHistory", "description": "Retorna las órdenes del comercio con su estado actual, courier y destinatario, más los totales del periodo (órdenes, en ruta, completadas y canceladas).\nCada orden incluye la URL de su seguimiento público en `tracking.URLtracking`.\n\nEl body es obligatorio (sin body responde 500), pero todos sus campos son opcionales: con `{}` retorna la primera página (20 órdenes), de la más reciente a la más antigua.\nCon `export: 1` también genera un Excel con todos los resultados y retorna su URL en `export.URLDataExcel`.\n", "tags": [ "Historial de Sucursales (Branch History)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "description": "Todos los filtros son opcionales y se pueden combinar.", "properties": { "dateFrom": { "type": "string", "format": "date", "example": "2026-10-01" }, "dateTo": { "type": "string", "format": "date", "description": "No puede ser anterior a `dateFrom`.", "example": "2026-10-31" }, "ordersId": { "type": "string", "format": "uuid", "description": "ID de la orden (`data.ordersId` al crearla)." }, "comprobante": { "type": "string", "maxLength": 120, "description": "Número de comprobante de la orden." }, "statusMainId": { "type": "string", "format": "uuid", "description": "Estado actual de la orden (`statusMainId` de `GET /api/statusMain`)." }, "courierServiceId": { "type": "string", "format": "uuid", "description": "Servicio de envío (`courierServiceId` de `POST /api/courier`)." }, "branchsClientId": { "type": "string", "format": "uuid", "description": "Cliente destinatario (`GET /api/branchs/branchsClient`)." }, "nomDestinatario": { "type": "string", "maxLength": 250, "description": "Nombre del destinatario." }, "departmentId": { "type": "string", "format": "uuid", "description": "Departamento de entrega (`GET /api/open/departments`)." }, "municipalityId": { "type": "string", "format": "uuid", "description": "Municipio de entrega (`POST /api/open/municipality`)." }, "onDelivery": { "type": "boolean", "description": "Órdenes con cobro contra entrega (acepta también 0 y 1)." }, "paidShipping": { "type": "boolean", "description": "Órdenes con el envío ya pagado (acepta también 0 y 1)." }, "favoriteClient": { "type": "boolean", "description": "Órdenes de clientes marcados como favoritos (acepta también 0 y 1)." }, "branchsClientStatus": { "type": "boolean", "description": "Órdenes de clientes activos (acepta también 0 y 1)." }, "consignmentValue": { "type": "number", "minimum": 0, "description": "Monto cobrado al destinatario, con máximo 2 decimales." }, "deliveryCost": { "type": "number", "minimum": 0, "description": "Costo del envío, con máximo 2 decimales." } } }, "order": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "createdAt", "lastMovementDate" ], "default": "createdAt" }, "direction": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } }, "export": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` genera además un Excel con todos los resultados (sin paginar)." } } }, "example": { "filters": { "dateFrom": "2026-10-01", "dateTo": "2026-10-31", "onDelivery": true }, "order": { "by": "createdAt", "direction": "DESC" }, "pagination": { "page": 1, "limit": 20 }, "export": 0 } } } }, "responses": { "200": { "description": "Historial de órdenes obtenido. Las órdenes están en `data.data` y la paginación en `data.pagination`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Resultado del historial.", "properties": { "pagination": { "$ref": "#/components/schemas/HistoryPagination" }, "totals": { "type": "object", "description": "Totales del periodo consultado.", "properties": { "totalOrders": { "description": "Órdenes del periodo.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "inRoute": { "description": "Órdenes en ruta.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "completed": { "description": "Órdenes completadas.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "cancelled": { "description": "Órdenes canceladas.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] } } }, "data": { "type": "array", "description": "Órdenes de la página.", "items": { "$ref": "#/components/schemas/HistoryOrderItem" } } } }, "export": { "$ref": "#/components/schemas/HistoryExport" } } } ] }, "example": { "response_code": 200, "response_status": "success", "response_message": "Historial obtenido correctamente", "data": { "pagination": { "page": 1, "limit": 20, "max_limit": 50, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false, "from": 1, "to": 1 }, "totals": { "totalOrders": { "value": 1, "changePercentage": 0 }, "inRoute": { "value": 1, "changePercentage": 0 }, "completed": { "value": 0 }, "cancelled": { "value": 0 } }, "data": [ { "ordersId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "order": { "comprobante": "29137811", "createdAt": "2026-10-07 10:15:00", "platform": "API", "productDescription": "Ropa", "totalWeight": 4, "packageCount": 1, "onDelivery": true, "paidShipping": false, "consignmentValue": 10, "deliveryCost": 3.39, "baseCommissionAmount": 0.5, "pcme": 0, "branchDepartmentName": "SAN SALVADOR", "branchMunicipalityName": "SAN SALVADOR CENTRO" }, "status": { "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0022", "statusDescription": "En ruta de entrega", "subStatusMainId": "0199a1b2-6666-7e5f-8a6b-1c2d3e4f0031", "subStatusDescription": "En ruta de entrega", "flowGroup": "delivery", "statusColor": "#1565C0", "lastMovementDate": "2026-10-07 14:30:00" }, "courier": { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierName": "Mensajería Ejemplo", "courierLogo": "https://...", "courierPhone": null }, "recipient": { "branchsClientId": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003", "recipientName": "Cliente Prueba", "recipientPhone": "70000000", "recipientAddress": "Calle Ficticia #456, Colonia Prueba, San Salvador", "departmentCode": "06", "departmentName": "SAN SALVADOR", "municipalityCode": "0614", "municipalityName": "SAN SALVADOR CENTRO", "favoriteClient": true, "branchsClientStatus": true }, "tracking": { "URLtracking": "https://..." } } ] }, "export": { "URLDataExcel": "" } } } } }, "400": { "description": "Filtro, ordenamiento o paginación inválidos. Se reporta el primer error encontrado, con el formato `Error en campo \"\": `; el campo va sin el prefijo `filters.`.\nMotivos posibles: `debe ser 0 o 1` (`export`), `debe ser formato YYYY-MM-DD válido`, `dateFrom no puede ser mayor a dateTo` (campo `dateRange`), `debe ser un UUID válido`, `debe ser 0, 1, true o false`, `decimal inválido (máx 2 decimales)`, `texto inválido` (`comprobante`, `nomDestinatario`), `valor inválido` (`pagination.page`, `pagination.limit`), `campo inválido` (`order.by`) y `debe ser ASC o DESC` (`order.direction`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "fecha": { "summary": "Fecha con formato inválido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"dateFrom\": debe ser formato YYYY-MM-DD válido" } }, "booleano": { "summary": "Un filtro de sí/no tiene un valor no permitido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"onDelivery\": debe ser 0, 1, true o false" } }, "monto": { "summary": "Monto con más de 2 decimales o negativo.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"deliveryCost\": decimal inválido (máx 2 decimales)" } }, "paginacion": { "summary": "page o limit no es un entero mayor a 0.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"pagination.limit\": valor inválido" } }, "rango": { "summary": "dateFrom es posterior a dateTo.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"dateRange\": dateFrom no puede ser mayor a dateTo" } }, "uuid": { "summary": "Un filtro de ID no es un UUID válido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"statusMainId\": debe ser un UUID válido" } }, "orden": { "summary": "Campo de ordenamiento no permitido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"order.by\": campo inválido" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error al consultar el historial.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener historial órdenes: ", "data": { "pagination": { "page": 1, "limit": 20, "max_limit": 50, "total": 0, "total_pages": 0, "has_next": false, "has_prev": false, "from": 0, "to": 0 }, "data": [] }, "export": { "URLDataExcel": "" } } }, "general": { "summary": "Error general (por ejemplo, sin body o con un body que no es JSON válido).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener historial de órdenes" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Historial" } }, "/api/branchs/history/transactionsAndMovements": { "post": { "summary": "Obtener historial de transacciones y movimientos", "operationId": "getTransactionsAndMovementsHistory", "description": "Retorna las transacciones del comercio (recargas y pagos) con sus movimientos de saldo asociados: cobros de envío, comisiones, devoluciones y beneficios.\nCada transacción incluye el método de pago, el resumen del monedero (saldo anterior, monto usado y saldo restante) y la lista de movimientos con su orden, courier y servicio.\nLos movimientos de beneficio (`movementIsBenefit: true`) traen su detalle en `benefit`; en los demás movimientos `benefit` es `null`.\n\nTodos los campos del body son opcionales: sin body retorna la primera página (20 transacciones), de la más reciente a la más antigua.\nCon `export: 1` también genera un Excel con todos los resultados y retorna su URL en `export.URLDataExcel`.\n", "tags": [ "Historial de Sucursales (Branch History)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "description": "Todos los filtros son opcionales y se pueden combinar.", "properties": { "dateFrom": { "type": "string", "format": "date", "example": "2026-10-01" }, "dateTo": { "type": "string", "format": "date", "description": "No puede ser anterior a `dateFrom`.", "example": "2026-10-31" }, "transactionId": { "type": "string", "format": "uuid", "description": "ID de la transacción." }, "transactionAmount": { "type": "number", "minimum": 0, "description": "Monto de la transacción." }, "transactionGatewayId": { "type": "string", "format": "uuid", "description": "Pasarela de pago de la transacción." }, "gatewayTransactionReference": { "type": "string", "maxLength": 150, "description": "Referencia de la transacción en la pasarela de pago." }, "internalTransactionReference": { "type": "string", "maxLength": 150, "description": "Referencia interna de la transacción." }, "typeCard": { "type": "string", "maxLength": 20, "description": "Tipo de tarjeta (por ejemplo, `VISA`)." }, "cardOwner": { "type": "string", "maxLength": 120, "description": "Titular de la tarjeta." }, "cardLast4": { "type": "string", "pattern": "^\\d{4}$", "description": "Últimos 4 dígitos de la tarjeta.", "example": "4242" }, "movementReasonId": { "type": "string", "format": "uuid", "description": "Motivo del movimiento (`GET /api/movementReason`)." }, "courierServiceId": { "type": "string", "format": "uuid", "description": "Servicio de envío del movimiento." }, "ordersId": { "type": "string", "format": "uuid", "description": "Orden del movimiento (`data.ordersId` al crearla)." }, "comprobante": { "type": "string", "maxLength": 100, "description": "Número de comprobante de la orden." }, "deliveryCost": { "type": "number", "minimum": 0, "description": "Costo del envío del movimiento." }, "onlyFilteredMovements": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "Con `1`, cada transacción muestra solo los movimientos que cumplen los filtros; con `0`, todos sus movimientos." } } }, "order": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } }, "export": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` genera además un Excel con todos los resultados (sin paginar)." } } }, "example": { "filters": { "dateFrom": "2026-10-01", "dateTo": "2026-10-31", "onlyFilteredMovements": 0 }, "order": { "direction": "DESC" }, "pagination": { "page": 1, "limit": 20 }, "export": 0 } } } }, "responses": { "200": { "description": "Transacciones y movimientos obtenidos", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/HistoryPagination" }, "totals": { "type": "object", "description": "Totales del periodo consultado.", "properties": { "totalTransactions": { "description": "Cantidad de transacciones del periodo.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "totalVolume": { "description": "Monto total de las transacciones del periodo.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "totalBenefits": { "type": "object", "description": "Beneficios del periodo.", "properties": { "value": { "type": "number", "description": "Valor del periodo." } } } } }, "data": { "type": "array", "description": "Transacciones de la página.", "items": { "$ref": "#/components/schemas/TransactionHistoryItem" } }, "export": { "$ref": "#/components/schemas/HistoryExport" } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Movimientos del comercio obtenidos correctamente.", "pagination": { "page": 1, "limit": 20, "max_limit": 50, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false, "from": 1, "to": 1 }, "totals": { "totalTransactions": { "value": 1, "changePercentage": 0 }, "totalVolume": { "value": 25, "changePercentage": 0 }, "totalBenefits": { "value": 0 } }, "data": [ { "transaction": { "transactionId": "0199a1b2-cccc-7e5f-8a6b-1c2d3e4f0051", "createdAt": "2026-10-05 09:00:00", "transactionAmount": 25, "transactionGatewayId": "0199a1b2-dddd-7e5f-8a6b-1c2d3e4f0052", "transactionGatewayCode": "PASARELA_EJEMPLO", "transactionGatewayLabel": "Pago con tarjeta (Pasarela Ejemplo)", "gatewayTransactionReference": "REF-000001", "internalTransactionReference": "INT-000001" }, "paymentMethod": { "paymentCardId": "0199a1b2-eeee-7e5f-8a6b-1c2d3e4f0053", "cardBin": "424242", "cardLast4": "4242", "cardMasked": "4242 42** **** 4242", "typeCard": "VISA", "cardOwner": "Cliente Prueba" }, "wallet": { "rechargeAmount": 25, "previousWalletBalance": 20.61, "walletMovementAmount": 3.89, "walletNetAmount": 21.11, "walletUsedPreviousBalanceAmount": 0, "residualWalletBalance": 41.72, "benefitAmount": 0 }, "summary": { "movementsCount": 1, "movementDeliveryCostAmount": 3.39, "movementCourierCostAmount": 2.8, "movementFeeVolaoAmount": 0.5, "movementBenefitAmount": 0 }, "movements": [ { "transactionMovementId": "0199a1b2-ffff-7e5f-8a6b-1c2d3e4f0054", "movementReasonId": "0199a1b2-1212-7e5f-8a6b-1c2d3e4f0055", "movementReasonCode": "ORDER_PAYMENT", "movementDescription": "Shipping Payment", "movementIsCredit": false, "movementIsBenefit": false, "movementDate": "2026-10-07 10:15:00", "order": { "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "comprobanteAf": "29137811", "deliveryCost": 3.39, "courierCost": 2.8, "feeVolao": 0.5 }, "courier": { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierName": "Mensajería Ejemplo", "courierLogo": "https://..." }, "service": { "courierServiceId": "019f88a7-40d5-75b5-add9-87e652d9ba69", "serviceId": "0199a1b2-aaaa-7e5f-8a6b-1c2d3e4f0041", "serviceName": "Entrega a domicilio", "serviceTypeId": "0199a1b2-bbbb-7e5f-8a6b-1c2d3e4f0042", "serviceTypeName": "Estándar" }, "balances": { "previousBalance": 45.61, "transactionBalance": -3.89, "newBalance": 41.72 }, "benefit": null } ] } ], "export": { "URLDataExcel": "" } } } } }, "400": { "description": "Filtro, ordenamiento o paginación inválidos. Se reporta el primer error encontrado, con el formato `Error en campo \"\": `.\nMotivos posibles: `debe ser 0 o 1` (`export` y `filters.onlyFilteredMovements`, como número), `debe ser un UUID válido`, `número inválido` (montos negativos o que no son número), `texto inválido (máx N caracteres)`, `debe contener exactamente 4 dígitos`, `debe ser una fecha válida (YYYY-MM-DD)`, `dateFrom no puede ser mayor a dateTo`, `debe ser un entero mayor a 0` (`pagination.page`), `debe ser un entero entre 1 y 50` (`pagination.limit`) y `debe ser ASC o DESC` (`order.direction`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "uuid": { "summary": "Un filtro de ID no es un UUID válido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.ordersId\": debe ser un UUID válido" } }, "monto": { "summary": "Un monto es negativo o no es un número.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.transactionAmount\": número inválido" } }, "tarjeta": { "summary": "cardLast4 no tiene 4 dígitos.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.cardLast4\": debe contener exactamente 4 dígitos" } }, "rango": { "summary": "dateFrom es posterior a dateTo.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.dateFrom\": dateFrom no puede ser mayor a dateTo" } }, "limit": { "summary": "limit fuera del rango permitido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"pagination.limit\": debe ser un entero entre 1 y 50" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los movimientos del comercio" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Historial" } }, "/api/branchs/history/benefits": { "post": { "summary": "Obtener historial de beneficios", "operationId": "getBenefitsHistory", "description": "Retorna los beneficios que recibió el comercio, con su orden, courier y el movimiento de saldo que generaron. Por ejemplo, el cashback por envío (`CBE`): un porcentaje del costo de envío que se devuelve al saldo al entregarse la orden, según el nivel de suscripción del comercio.\nIncluye totales del periodo: cantidad y monto de beneficios, monto del mes actual y del anterior, monto revertido y desglose por tipo.\n\nTodos los campos del body son opcionales: sin body retorna la primera página (20 beneficios), del más reciente al más antiguo.\nCon `export: 1` también genera un Excel con todos los resultados y retorna su URL en `export.URLDataExcel`.\n", "tags": [ "Historial de Sucursales (Branch History)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "description": "Todos los filtros son opcionales y se pueden combinar.", "properties": { "dateFrom": { "type": "string", "format": "date", "example": "2026-10-01" }, "dateTo": { "type": "string", "format": "date", "description": "No puede ser anterior a `dateFrom`.", "example": "2026-10-31" }, "movementCode": { "type": "string", "maxLength": 20, "description": "Tipo de beneficio (`benefit.movementCode` de la respuesta)." }, "status": { "type": "string", "enum": [ "APPLIED", "REVERSED" ], "description": "Estado del beneficio, aplicado o revertido." }, "subscriptionTierId": { "type": "string", "format": "uuid", "description": "Plan de suscripción con el que se otorgó el beneficio." }, "ordersId": { "type": "string", "format": "uuid", "description": "Orden que generó el beneficio (`data.ordersId` al crearla)." }, "comprobante": { "type": "string", "maxLength": 100, "description": "Número de comprobante de la orden." } } }, "order": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } }, "export": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` genera además un Excel con todos los resultados (sin paginar)." } } }, "example": { "filters": { "dateFrom": "2026-10-01", "dateTo": "2026-10-31", "status": "APPLIED" }, "order": { "direction": "DESC" }, "pagination": { "page": 1, "limit": 20 }, "export": 0 } } } }, "responses": { "200": { "description": "Beneficios obtenidos", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/HistoryPagination" }, "totals": { "type": "object", "description": "Totales del periodo consultado.", "properties": { "totalBenefits": { "description": "Cantidad de beneficios del periodo.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "totalAmount": { "description": "Monto total de beneficios del periodo.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "currentMonthAmount": { "type": "number", "description": "Monto de beneficios del mes actual." }, "previousMonthAmount": { "type": "number", "description": "Monto de beneficios del mes anterior." }, "reversedAmount": { "type": "number", "description": "Monto de beneficios revertidos." }, "byType": { "type": "array", "description": "Desglose por tipo de beneficio.", "items": { "type": "object", "properties": { "movementCode": { "type": "string", "description": "Código del tipo de beneficio." }, "movementName": { "type": "string", "description": "Nombre del tipo de beneficio." }, "count": { "type": "integer", "description": "Cantidad de beneficios de este tipo." }, "amount": { "type": "number", "description": "Monto total de este tipo." } } } } } }, "data": { "type": "array", "description": "Beneficios de la página.", "items": { "$ref": "#/components/schemas/BenefitHistoryItem" } }, "export": { "$ref": "#/components/schemas/HistoryExport" } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Beneficios del comercio obtenidos correctamente.", "pagination": { "page": 1, "limit": 20, "max_limit": 50, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false, "from": 1, "to": 1 }, "totals": { "totalBenefits": { "value": 1, "changePercentage": 0 }, "totalAmount": { "value": 0.17, "changePercentage": 0 }, "currentMonthAmount": 0.17, "previousMonthAmount": 0, "reversedAmount": 0, "byType": [ { "movementCode": "CBE", "movementName": "CASHBACK POR ENVÍO", "count": 1, "amount": 0.17 } ] }, "data": [ { "benefit": { "benefitId": "0199a1b2-1313-7e5f-8a6b-1c2d3e4f0061", "movementCode": "CBE", "movementName": "CASHBACK POR ENVÍO", "movementColor": "rgb(235 243 237)", "status": "APPLIED", "amount": 0.17, "baseAmount": 3.39, "rate": 0.05, "detail": "Beneficio aplicado a la orden 29137811", "metadata": { "tierCode": "TIER1", "deliveredAt": "2026-10-08 11:00:00" }, "createdAt": "2026-10-08 11:00:05", "reversedAt": null }, "subscription": { "subscriptionTierId": "0199a1b2-1414-7e5f-8a6b-1c2d3e4f0062", "tierCode": "TIER1", "tierName": "Tier 1 - Basic Extensions" }, "order": { "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "comprobanteAf": "29137811", "deliveryCost": 3.39, "deliveredAt": null }, "courier": { "courierId": "019f81b1-a481-77d5-be76-6c74b42c1e59", "courierName": "Mensajería Ejemplo", "courierLogo": "https://..." }, "movement": { "balanceTransactionId": "0199a1b2-1515-7e5f-8a6b-1c2d3e4f0063", "paymentTransactionId": "0199a1b2-1616-7e5f-8a6b-1c2d3e4f0064", "previousBalance": 41.72, "newBalance": 41.89, "reversedBalanceTransactionId": null } } ], "export": { "URLDataExcel": "" } } } } }, "400": { "description": "Filtro, ordenamiento o paginación inválidos. Se reporta el primer error encontrado, con el formato `Error en campo \"\": `.\nMotivos posibles: `debe ser 0 o 1` (`export`, como número), `debe ser un código de texto válido (máx 20 caracteres)` (`filters.movementCode`), `debe ser un UUID válido`, `texto inválido (máx N caracteres)` (`filters.comprobante`, `filters.status`), `debe ser una fecha válida (YYYY-MM-DD)`, `dateFrom no puede ser mayor a dateTo`, `debe ser un entero mayor a 0` (`pagination.page`), `debe ser un entero entre 1 y 50` (`pagination.limit`) y `debe ser ASC o DESC` (`order.direction`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "uuid": { "summary": "Un filtro de ID no es un UUID válido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.ordersId\": debe ser un UUID válido" } }, "codigo": { "summary": "movementCode vacío o con más de 20 caracteres.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.movementCode\": debe ser un código de texto válido (máx 20 caracteres)" } }, "rango": { "summary": "dateFrom es posterior a dateTo.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.dateFrom\": dateFrom no puede ser mayor a dateTo" } }, "limit": { "summary": "limit fuera del rango permitido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"pagination.limit\": debe ser un entero entre 1 y 50" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los beneficios del comercio" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Historial" } }, "/api/branchs/history/settlements": { "post": { "summary": "Obtener historial de liquidaciones", "operationId": "getSettlementsHistory", "description": "Retorna las liquidaciones (actas) del comercio: el pago al comercio de lo cobrado contra entrega, descontando el costo de envío y la comisión.\nCada acta incluye la cuenta bancaria donde se depositó, sus totales y las órdenes que liquida.\n\nTodos los campos del body son opcionales: sin body retorna la primera página (20 actas), de la más reciente a la más antigua.\nCon `export: 1` también genera un Excel con todos los resultados y retorna su URL en `export.URLDataExcel`.\n", "tags": [ "Historial de Sucursales (Branch History)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "description": "Todos los filtros son opcionales y se pueden combinar.", "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Liquidación que incluye esta orden (`data.ordersId` al crearla).", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" }, "comprobante": { "type": "string", "description": "Liquidación que incluye la orden con este comprobante.", "example": "29137811" }, "expandActaByOrderSearch": { "type": "boolean", "description": "Al buscar por `orderId` o `comprobante`, `true` retorna el acta con todas sus órdenes, no solo la buscada. Acepta también `1` y `0`.", "example": true }, "dateType": { "type": "string", "enum": [ "deliveryDate", "settlementDate" ], "description": "Fecha a la que se aplica el rango `dateFrom`–`dateTo`, la de entrega de la orden o la de la liquidación.", "example": "settlementDate" }, "dateFrom": { "type": "string", "format": "date", "description": "Se envía junto con `dateTo`.", "example": "2026-10-01" }, "dateTo": { "type": "string", "format": "date", "description": "Se envía junto con `dateFrom`.", "example": "2026-10-31" }, "codActa": { "type": "integer", "description": "Número del acta de liquidación.", "example": 1024 }, "titular": { "type": "string", "description": "Titular de la cuenta bancaria.", "example": "Comercio Prueba" }, "bankId": { "type": "string", "format": "uuid", "description": "Banco de la cuenta (`banks[].banksId` de `GET /api/open/banks`)." }, "typeAccountId": { "type": "string", "format": "uuid", "description": "Tipo de cuenta bancaria (`typeAccount[].typeAccountId` de `GET /api/open/banks`)." }, "accountNumber": { "type": "string", "description": "Número de la cuenta bancaria.", "example": "0000000000" }, "consignmentValue": { "type": "number", "description": "Monto cobrado al destinatario." }, "deliveryCost": { "type": "number", "description": "Costo del envío." }, "commission": { "type": "number", "description": "Comisión cobrada." }, "settledAmount": { "type": "number", "description": "Monto liquidado al comercio." } } }, "order": { "type": "object", "properties": { "orderBy": { "type": "string", "enum": [ "orderId", "comprobante", "deliveryDate", "codActa", "settlementDate", "titular", "bankId", "bankName", "typeAccountId", "typeAccountName", "accountNumber", "consignmentValue", "deliveryCost", "commission", "settledAmount" ], "default": "settlementDate" }, "orderDirection": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 150, "default": 20 } } }, "export": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` genera además un Excel con todos los resultados (sin paginar)." } } }, "example": { "filters": { "dateType": "settlementDate", "dateFrom": "2026-10-01", "dateTo": "2026-10-31" }, "order": { "orderBy": "settlementDate", "orderDirection": "DESC" }, "pagination": { "page": 1, "limit": 20 }, "export": 0 } } } }, "responses": { "200": { "description": "Historial de liquidaciones obtenido", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/HistoryPagination" }, "data": { "type": "array", "description": "Actas de liquidación de la página.", "items": { "$ref": "#/components/schemas/SettlementHistoryItem" } }, "export": { "$ref": "#/components/schemas/HistoryExport" } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Historial de liquidaciones obtenido correctamente", "pagination": { "page": 1, "limit": 20, "max_limit": 150, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false, "from": 1, "to": 1 }, "data": [ { "acta": { "codActa": 1024, "settlementDate": "2026-10-15", "totalOrders": 1 }, "bankAccount": { "titular": "Comercio Prueba", "bankId": "0199a1b2-8888-7e5f-8a6b-1c2d3e4f0009", "bankName": "Banco Prueba", "typeAccountId": "0199a1b2-9999-7e5f-8a6b-1c2d3e4f0010", "typeAccountName": "Ahorro", "accountNumber": "0000000000" }, "totals": { "totalConsignmentValue": 10, "totalDeliveryCost": 3.39, "totalCommission": 0.5, "totalSettledAmount": 6.11 }, "orders": [ { "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "comprobante": "29137811", "deliveryDate": "2026-10-10", "consignmentValue": 10, "deliveryCost": 3.39, "commission": 0.5, "settledAmount": 6.11 } ] } ], "export": { "URLDataExcel": "" } } } } }, "400": { "description": "Filtros, ordenamiento o paginación inválidos. Se reporta el primer error encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "orderBy": { "summary": "Campo de ordenamiento no permitido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "orderBy inválido. Valores permitidos: orderId, comprobante, deliveryDate, codActa, settlementDate, titular, bankId, bankName, typeAccountId, typeAccountName, accountNumber, consignmentValue, deliveryCost, commission, settledAmount" } }, "orderDirection": { "summary": "Dirección de ordenamiento no permitida.", "value": { "response_code": 400, "response_status": "Error", "response_message": "orderDirection debe ser ASC o DESC" } }, "page": { "summary": "page no es un entero mayor a 0.", "value": { "response_code": 400, "response_status": "Error", "response_message": "page debe ser un entero mayor a 0" } }, "fechas": { "summary": "dateFrom y dateTo deben enviarse juntos.", "value": { "response_code": 400, "response_status": "Error", "response_message": "dateFrom y dateTo deben enviarse juntos" } }, "dateType": { "summary": "Valor de dateType no permitido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "dateType inválido. Valores permitidos: deliveryDate, settlementDate" } }, "uuid": { "summary": "orderId, bankId o typeAccountId no es un UUID válido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "orderId debe ser un UUID válido" } }, "limit": { "summary": "limit fuera del rango permitido.", "value": { "response_code": 400, "response_status": "Error", "response_message": "limit debe ser un entero entre 1 y 150" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener el historial de liquidaciones" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Historial" } }, "/api/branchs/settlements/liquidationActs": { "post": { "summary": "Obtener el detalle de una liquidación", "operationId": "getSettlementDetail", "description": "Retorna el detalle de un acta de liquidación del comercio: la cuenta bancaria donde se depositó, las órdenes que incluye con sus montos y los totales.\nPor cada orden: el monto cobrado (`montoEnvio`), el costo del envío (`costoEnvio`), la comisión (`cme`) y el monto liquidado al comercio (`montoLiquidado`).\n", "tags": [ "Historial de Sucursales (Branch History)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "codActa" ], "properties": { "codActa": { "type": "string", "format": "uuid", "description": "UUID del acta de liquidación. No es el número de acta (`acta.codActa`) que retorna el historial de liquidaciones.", "example": "0199a1b2-1919-7e5f-8a6b-1c2d3e4f0081" } } } } } }, "responses": { "200": { "description": "Detalle de la liquidación obtenido", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SettlementDetail" } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Datos de liquidación obtenidos correctamente", "data": { "accountData": { "codActa": 1024, "actaFecha": "2026-10-15", "branchId": "0199a1b2-0000-7e5f-8a6b-1c2d3e4f0001", "branchName": "Comercio Prueba", "branchEmail": "comercio.prueba@example.com", "titular": "Comercio Prueba", "bankName": "Banco Prueba", "typeAccount": "Ahorro", "accountNumber": "0000000000" }, "orders": [ { "ordersId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "montoEnvio": 10, "costoEnvio": 3.39, "cme": 0.5, "montoLiquidado": 6.11 } ], "totals": { "totalMontoEnvio": 10, "totalCostoEnvio": 3.39, "totalCme": 0.5, "totalLiquidado": 6.11 } } } } } }, "400": { "description": "codActa falta o no es un UUID válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "codActa es requerido y debe ser un UUID válido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los datos del acta de liquidación" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Historial" } }, "/api/batchShipping": { "get": { "summary": "Generar plantilla Excel para envíos masivos", "operationId": "getBatchShippingTemplate", "description": "Genera la plantilla Excel (.xlsx) configurada para el comercio y retorna una URL temporal para descargarla. Se llena una fila por orden y se carga con `POST /api/batchShipping`.\n\nLa plantilla trae listas desplegables con las direcciones de recolecta del comercio, los couriers con sus servicios y tipos de servicio, y los departamentos y municipios. Tiene espacio para 499 órdenes (filas 2 a 500).\n\nLa URL es pública (no requiere token) y el archivo es temporal: descárguelo en cuanto lo reciba.\n", "tags": [ "Operaciones Masivas (Batch Operations)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Plantilla generada", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL temporal del archivo .xlsx." } } } } }, "example": { "response_code": 200, "response_status": "success", "response_message": "Plantilla Excel generada correctamente", "data": { "url": "https://api.volao.app/api/tmp/shipping-template-0199a1b2-0000-7000-8000-000000000001-1759900000000.xlsx" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error al generar la plantilla", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "error", "response_message": "Error al generar la plantilla Excel" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Operaciones masivas" }, "post": { "summary": "Crear órdenes masivas (carga de Excel)", "operationId": "createBatchOrders", "description": "Crea varias órdenes a partir de la plantilla Excel llena (`GET /api/batchShipping`). Cada fila se valida y se procesa por separado.\n**La respuesta es 200 aunque algunas filas fallen:** revise `isValid` y `response_message` de cada fila en `data[]`.\n`codeExcel` es el número de fila del Excel, para ubicar los errores.\n\n**Cómo enviar el archivo**\n\n- Se envía como `multipart/form-data` en el campo `file`, con el tipo de contenido de Excel\n (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`). Si el archivo llega con otro tipo\n (por ejemplo `application/octet-stream`), se rechaza. Con curl: `-F \"file=@plantilla.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\"`.\n- Solo se lee el formato .xlsx. Un .xls (formato antiguo) se rechaza con `El archivo no pudo ser leído como Excel`.\n- Se lee la primera hoja; la fila 1 son los encabezados y las filas vacías se omiten.\n- Llene la plantilla en Excel u otra hoja de cálculo que guarde el resultado de las fórmulas: las columnas ocultas\n calculan los IDs (dirección, municipio, servicio) a partir de lo elegido en las listas. Si el archivo se genera\n con una librería que no calcula fórmulas, las filas fallan.\n\n**Columnas y validaciones por fila**\n\nCada fila se valida en este orden y se reporta solo el primer error:\n\n| Columna | Dato | Regla | Mensaje si falla |\n| --- | --- | --- | --- |\n| B | Nombre de cliente | Obligatorio, de 2 a 150 caracteres | `El nombre del cliente es obligatorio y no puede estar vacío`, `El nombre del cliente debe contener al menos 2 caracteres`, `El nombre del cliente es demasiado largo. No puede superar los 150 caracteres` |\n| C | Teléfono de cliente | Obligatorio, de 7 a 9 caracteres: números y, opcionalmente, guion | `El número de teléfono del cliente es obligatorio`, `El número de teléfono del cliente no puede tener más de 9 caracteres. Puede ingresarse con o sin guion`, `El número de teléfono del cliente solo puede contener números y, opcionalmente, un guion` |\n| D | Dirección de envío | Obligatoria, de 5 a 250 caracteres | `La dirección del cliente es obligatoria y no puede estar vacía`, `La dirección del cliente es demasiado corta. Debe contener al menos 5 caracteres`, `La dirección del cliente es demasiado larga. No puede superar los 250 caracteres` |\n| E, F | Departamento y municipio | Elegidos de la lista | `No se pudo identificar el municipio del cliente. Verifica que el municipio exista y esté correctamente seleccionado` |\n| A | Dirección de recolección | Elegida de la lista | `Seleccione una dirección de recolección válida` |\n| I | Courier | Obligatorio | `Seleccione un courier válido` |\n| J | Servicio | Obligatorio | `Seleccione un servicio` |\n| K | Tipo de servicio | Obligatorio; la combinación de courier, servicio y tipo debe existir en la lista | `Seleccione un tipo de servicio`, `La combinación de courier, servicio y tipo de servicio no es válida` |\n| L | Tipo de entrega | `Entrega Normal (Sin Cobro)` o `Cobro Contra Entrega` | `Seleccione un tipo de entrega válido` |\n| N | Descripción del producto | Obligatoria, máximo 150 caracteres | `Ingrese una descripción del producto`, `La descripción del producto es demasiado larga` |\n| H | Peso (lb) | Número mayor que 0 | `Ingrese un peso válido` |\n| G | Cantidad de paquetes | Entero de 1 a 50 | `Ingrese una cantidad de paquetes válida` |\n| M | Monto a cobrar | Mayor que 0 con `Cobro Contra Entrega`; sin cobro, vacío o mayor o igual a 0 | `Ingrese un monto a cobrar válido, por ejemplo 15.50`, `El monto a cobrar no puede ser negativo` |\n| O | Comentarios | Opcional, máximo 300 caracteres | `Los comentarios son demasiado largos` |\n\n**Qué hace cada fila válida**\n\nGuarda o actualiza el destinatario en los clientes del comercio y crea la orden igual que `POST /api/orders`:\ngenera la guía y descuenta el costo del saldo. Si la creación falla (por ejemplo, por saldo o por un error del courier),\nla fila llega con `isValid: false` y el mensaje de ese error. Las demás filas se procesan igual.\n", "tags": [ "Operaciones Masivas (Batch Operations)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Plantilla Excel (.xlsx) de `GET /api/batchShipping` con al menos una fila de datos. El cuerpo de la petición admite hasta 30 MB." } } }, "encoding": { "file": { "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" } } } } }, "responses": { "200": { "description": "Archivo procesado; revisar el resultado de cada fila", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "description": "Una entrada por fila con datos, en el orden del Excel.", "items": { "type": "object", "description": "Los datos de envío (dirección, peso, paquetes, montos) solo son confiables cuando `isValid` es `true`; en las filas con error pueden llegar vacíos o en `0`.", "properties": { "codeExcel": { "type": "integer", "description": "Número de fila en el Excel." }, "ordersId": { "description": "ID (UUID) de la orden creada. Llega como el número `0` si la fila no creó orden.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ] }, "courierName": { "type": "string" }, "comprobante": { "type": "string", "description": "Número de comprobante de la orden; vacío si no se creó. Se usa en `POST /api/batchShipping/guides`." }, "recipientName": { "type": "string" }, "departmentName": { "type": "string" }, "municipalityName": { "type": "string" }, "recipientAddress": { "type": "string" }, "totalWeight": { "type": "number" }, "cantPackages": { "type": "integer" }, "shippingAmount": { "type": "number" }, "onDelivery": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = cobro contra entrega." }, "isValid": { "type": "boolean", "description": "`true` si la orden se creó." }, "response_message": { "type": "string", "description": "`Orden creada correctamente` o el motivo por el que la fila falló." }, "guide": { "type": "object", "properties": { "URLguide": { "type": "string", "description": "URL de la guía; vacía si no se creó la orden." } } }, "tracking": { "type": "object", "properties": { "URLtracking": { "type": "string", "description": "URL del seguimiento público; vacía si no se creó la orden o si no aplica al comercio." } } } } } } } }, "examples": { "mixto": { "summary": "Una fila creada y una con error", "value": { "response_code": 200, "response_status": "success", "response_message": "Archivo procesado", "data": [ { "codeExcel": 2, "ordersId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "courierName": "Mensajería Ejemplo", "comprobante": "29137811", "recipientName": "Cliente Prueba", "departmentName": "SAN SALVADOR", "municipalityName": "SAN SALVADOR CENTRO", "recipientAddress": "Calle Ficticia #123, Colonia Prueba", "totalWeight": 4, "cantPackages": 1, "shippingAmount": 10, "onDelivery": 1, "isValid": true, "response_message": "Orden creada correctamente", "guide": { "URLguide": "https://mensajeria.example.com/guias/GUIA-PRUEBA.pdf" }, "tracking": { "URLtracking": "https://tracking.example.com/?orderId=0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } }, { "codeExcel": 3, "ordersId": 0, "courierName": "Mensajería Ejemplo", "comprobante": "", "recipientName": "Cliente Prueba", "departmentName": "SANTA ANA", "municipalityName": "SANTA ANA CENTRO", "recipientAddress": "", "totalWeight": 0, "cantPackages": 0, "shippingAmount": 0, "onDelivery": 0, "isValid": false, "response_message": "El número de teléfono del cliente solo puede contener números y, opcionalmente, un guion", "guide": { "URLguide": "" }, "tracking": { "URLtracking": "" } } ] } }, "ningunaValida": { "summary": "Ninguna fila pasó la validación (no se creó ninguna orden)", "value": { "response_code": 200, "response_status": "success", "response_message": "Archivo procesado", "data": [ { "codeExcel": 2, "ordersId": 0, "courierName": "Mensajería Ejemplo", "comprobante": "", "recipientName": "Cliente Prueba", "departmentName": "SAN SALVADOR", "municipalityName": "SAN SALVADOR CENTRO", "recipientAddress": "Calle Ficticia #123", "totalWeight": 0, "cantPackages": 1, "shippingAmount": 0, "onDelivery": 0, "isValid": false, "response_message": "Ingrese un peso válido", "guide": { "URLguide": "" }, "tracking": { "URLtracking": "" } } ] } } } } } }, "400": { "description": "El archivo no es válido. Mensajes posibles: `No se envió ningún archivo`, `El archivo enviado no es válido`,\n`El archivo enviado no es un archivo Excel válido`, `El archivo no pudo ser leído como Excel`,\n`El archivo Excel no contiene hojas`, `El archivo Excel no contiene registros`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sinArchivo": { "summary": "No se envió el campo file, o se envió como texto", "value": { "response_code": 400, "response_status": "error", "response_message": "No se envió ningún archivo" } }, "tipoInvalido": { "summary": "El archivo no tiene el tipo de contenido de Excel, o el cuerpo no es multipart/form-data", "value": { "response_code": 400, "response_status": "error", "response_message": "El archivo enviado no es un archivo Excel válido" } }, "noLegible": { "summary": "Archivo dañado o en formato .xls", "value": { "response_code": 400, "response_status": "error", "response_message": "El archivo no pudo ser leído como Excel" } }, "sinRegistros": { "summary": "La plantilla no tiene filas con datos", "value": { "response_code": 400, "response_status": "error", "response_message": "El archivo Excel no contiene registros" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno al procesar el archivo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "error", "response_message": "Error al procesar el archivo Excel" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Operaciones masivas" } }, "/api/batchShipping/guides": { "post": { "summary": "Generar guías masivas", "operationId": "generateBatchGuides", "description": "Genera un solo documento PDF con las guías de varias órdenes de un mismo courier y retorna su URL.\nSolo está disponible para los couriers que admiten guía masiva; con los demás responde 500 `No se pudo generar la guía masiva`.\n", "tags": [ "Operaciones Masivas (Batch Operations)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "courierId", "comprobantes" ], "properties": { "courierId": { "type": "string", "format": "uuid", "description": "Courier de las órdenes (`courierId` de la cotización).", "example": "019f81b1-a481-77d5-be76-6c74b42c1e59" }, "comprobantes": { "type": "array", "minItems": 1, "description": "Números de comprobante de las órdenes (`data.comprobante` al crearlas). También se acepta el nombre `orders`; si se envían los dos, se usa `orders`.", "items": { "type": "string", "example": "29137811" }, "example": [ "29137811", "29137812" ] } } } } } }, "responses": { "200": { "description": "Guías generadas", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "properties": { "guideUrl": { "type": "string", "format": "uri", "description": "URL del PDF con las guías. Puede ser un archivo temporal de Volao o una URL del courier; descárguelo en cuanto lo reciba." } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Guías generadas exitosamente", "data": { "guideUrl": "https://api.volao.app/api/tmp/GUIAS-POR-LOTE-1759900000000.pdf" } } } } }, "400": { "description": "Faltan parámetros (`courierId` o una lista de comprobantes no vacía), o los comprobantes no son válidos para el courier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "Los parámetros courierId y orders (o comprobantes) son requeridos" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "No se pudo generar el documento de guías", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sinGuia": { "summary": "El courier no admite guía masiva o no devolvió el documento", "value": { "response_code": 500, "response_status": "Error", "response_message": "No se pudo generar la guía masiva" } }, "validacion": { "summary": "No se pudieron validar los comprobantes (por ejemplo, courierId no es un UUID válido)", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error validando guías masivas del courier" } }, "cuerpoInvalido": { "summary": "El cuerpo no es un JSON válido", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al procesar guías masivas" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Operaciones masivas" } }, "/api/open/departments": { "get": { "summary": "Obtener todos los departamentos", "operationId": "getDepartments", "description": "Retorna el catálogo de departamentos. El `departmentId` es el valor que se envía para consultar municipios.", "tags": [ "Datos Públicos (Open Data)" ], "responses": { "200": { "description": "Departamentos obtenidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "departmentId": { "type": "string", "format": "uuid", "description": "ID del departamento. Se envía como `departmentId` para consultar municipios (`POST /api/open/municipality`)." }, "departmentsCode": { "type": "string", "description": "Código del departamento." }, "departmentName": { "type": "string", "description": "Nombre del departamento." } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Departamentos procesados correctamente", "data": [ { "departmentId": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004", "departmentsCode": "01", "departmentName": "AHUACHAPÁN" }, { "departmentId": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0014", "departmentsCode": "02", "departmentName": "SANTA ANA" } ] } } } }, "404": { "description": "No hay departamentos registrados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 404, "response_status": "Error", "response_message": "No se encontraron departamentos", "data": null } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error inesperado al obtener los departamentos.", "data": null } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Datos públicos" } }, "/api/open/municipality": { "post": { "summary": "Obtener municipios por departamento", "operationId": "getMunicipalities", "description": "Retorna los municipios de un departamento. El `municipalityId` se usa al crear clientes y al cotizar envíos.", "tags": [ "Datos Públicos (Open Data)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "departmentId" ], "properties": { "departmentId": { "type": "string", "format": "uuid", "description": "UUID del departamento (`GET /api/open/departments`).", "example": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004" } } } } } }, "responses": { "200": { "description": "Municipios obtenidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "municipalityId": { "type": "string", "format": "uuid", "description": "ID del municipio. Se usa al crear clientes y al cotizar envíos." }, "municipalityCode": { "type": "string", "description": "Código del municipio." }, "municipalityName": { "type": "string", "description": "Nombre del municipio." } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Municipios procesados correctamente", "data": [ { "municipalityId": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005", "municipalityCode": "0101", "municipalityName": "AHUACHAPÁN" }, { "municipalityId": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0015", "municipalityCode": "0102", "municipalityName": "APANECA" } ] } } } }, "400": { "description": "Falta el departmentId o no es un UUID válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "El campo departmentId es requerido y debe ser un UUID válido" } } } }, "404": { "description": "El departamento no existe", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 404, "response_status": "Error", "response_message": "El departamento \"0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004\" no corresponde a ningún departamento válido registrado en el sistema." } } } }, "500": { "description": "Error interno, o el cuerpo no es un JSON válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "errorConsulta": { "summary": "Error al consultar los municipios", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error inesperado al obtener los municipios.", "data": null } }, "cuerpoInvalido": { "summary": "El cuerpo no es un JSON válido", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al capturar los municipios" } } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Datos públicos" } }, "/api/open/typeBranchAddress": { "get": { "summary": "Obtener tipos de direcciones de sucursal", "operationId": "getBranchAddressTypes", "description": "Retorna los tipos de dirección (casa, tienda, bodega…). El `TypeBranchAddressId` se envía como `typeBranchAddressId` al crear o actualizar una dirección de recolecta.", "tags": [ "Datos Públicos (Open Data)" ], "responses": { "200": { "description": "Tipos de dirección obtenidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "TypeBranchAddressId": { "type": "string", "format": "uuid", "description": "ID del tipo de dirección. Se envía como `typeBranchAddressId` al crear o actualizar una dirección de recolecta." }, "codeBranchAddress": { "type": "string", "description": "Código del tipo de dirección." }, "icon": { "type": "string", "description": "Clase del ícono del tipo de dirección (Font Awesome)." } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Tipos de dirección obtenidos correctamente", "data": [ { "TypeBranchAddressId": "0199a1b2-1111-7e5f-8a6b-1c2d3e4f0002", "codeBranchAddress": "CASA", "icon": "fa-solid fa-house" }, { "TypeBranchAddressId": "0199a1b2-1111-7e5f-8a6b-1c2d3e4f0012", "codeBranchAddress": "TIENDA", "icon": "fa-solid fa-store" } ] } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los tipos de direcciones", "data": [] } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Datos públicos" } }, "/api/open/banks": { "get": { "summary": "Obtener listado de bancos", "operationId": "getBanks", "description": "Retorna los bancos habilitados y los tipos de cuenta, para registrar la cuenta bancaria del comercio.", "tags": [ "Datos Públicos (Open Data)" ], "responses": { "200": { "description": "Bancos y tipos de cuenta obtenidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "properties": { "banks": { "type": "array", "description": "Bancos habilitados.", "items": { "type": "object", "properties": { "banksId": { "type": "string", "format": "uuid", "description": "ID del banco." }, "banksName": { "type": "string", "description": "Nombre del banco." }, "swiftCode": { "type": "string", "description": "Código SWIFT del banco." }, "localBankCode": { "type": "string", "description": "Código local del banco." } } } }, "typeAccount": { "type": "array", "description": "Tipos de cuenta bancaria.", "items": { "type": "object", "properties": { "typeAccountId": { "type": "string", "format": "uuid", "description": "ID del tipo de cuenta." }, "accountCode": { "type": "string", "description": "Código del tipo de cuenta." }, "accountName": { "type": "string", "description": "Nombre del tipo de cuenta." } } } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Bancos obtenidos correctamente", "data": { "banks": [ { "banksId": "0199a1b2-cccc-7e5f-8a6b-1c2d3e4f000d", "banksName": "Banco Prueba", "swiftCode": "BPRUSVSS", "localBankCode": "001" } ], "typeAccount": [ { "typeAccountId": "0199a1b2-dddd-7e5f-8a6b-1c2d3e4f000e", "accountCode": "AHORRO", "accountName": "Cuenta de ahorro" } ] } } } } }, "500": { "description": "Error interno; el mensaje incluye el detalle del error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener bancos: ", "data": { "banks": [], "typeAccount": [] } } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Datos públicos" } }, "/api/open/typePersonDocument": { "get": { "summary": "Obtener tipos de documentos de persona", "operationId": "getPersonDocumentTypes", "description": "Retorna los tipos de persona (natural, jurídica…) con los documentos que cada uno debe presentar (DUI, NIT, etc.).", "tags": [ "Datos Públicos (Open Data)" ], "responses": { "200": { "description": "Tipos de persona y documentos obtenidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "TypePersonId": { "type": "integer", "description": "ID del tipo de persona." }, "namePerson": { "type": "string", "description": "Nombre del tipo de persona." }, "documents": { "type": "array", "description": "Documentos que debe presentar este tipo de persona.", "items": { "type": "object", "properties": { "documentId": { "type": "integer", "description": "ID del documento." }, "documentName": { "type": "string", "description": "Nombre del documento." }, "isRequired": { "type": "boolean", "description": "Indica si el documento es obligatorio." } } } } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Tipos de documentos obtenidos correctamente", "data": [ { "TypePersonId": 1, "namePerson": "Persona natural", "documents": [ { "documentId": 1, "documentName": "DUI", "isRequired": true } ] } ] } } } }, "500": { "description": "Error interno; el mensaje incluye el detalle del error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener tipos de documentos: ", "data": [] } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Datos públicos" } }, "/api/open/trackingComp": { "get": { "summary": "Seguimiento público de órdenes", "operationId": "getPublicTracking", "description": "Retorna el estado y el historial de movimientos de una orden, sin token.\nEs el endpoint que usa la página pública de seguimiento que se comparte con el destinatario.\n", "tags": [ "Datos Públicos (Open Data)" ], "parameters": [ { "in": "query", "name": "OrderId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID de la orden.", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" }, { "in": "query", "name": "identifier", "schema": { "type": "string" }, "description": "Opcional. Identificador cifrado del comercio, incluido en los enlaces de seguimiento que genera Volao. No cambia la respuesta; no es necesario enviarlo." } ], "responses": { "200": { "description": "Seguimiento obtenido", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "object", "properties": { "generalData": { "type": "object", "description": "Datos generales de la orden, tomados del movimiento más reciente.", "properties": { "comment": { "type": "string", "nullable": true, "description": "Comentario del movimiento más reciente." }, "creationDate": { "type": "string", "nullable": true, "description": "Fecha de creación de la orden (`YYYY-MM-DD HH:mm:ss`)." }, "branchName": { "type": "string", "nullable": true, "description": "Nombre del comercio que envía la orden." }, "cantPackages": { "type": "integer", "description": "Cantidad de paquetes." }, "courierName": { "type": "string", "nullable": true, "description": "Nombre de la mensajería." }, "statusMainDescription": { "type": "string", "nullable": true, "description": "Estado actual de la orden, en español." }, "subStatusDescription": { "type": "string", "nullable": true, "description": "Subestado actual de la orden, en español." }, "colorMovement": { "type": "string", "nullable": true, "description": "Color del estado actual, en hexadecimal." }, "flowGroup": { "type": "string", "nullable": true, "description": "Reservado; actualmente siempre es `null`." }, "publicNotice": { "type": "object", "description": "Aviso público de la orden. Actualmente no se usa: `hasNotice` siempre es `false`.", "properties": { "hasNotice": { "type": "boolean" }, "type": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } } }, "recipientName": { "type": "string", "nullable": true, "description": "Nombre del destinatario." }, "collectionDate": { "type": "string", "nullable": true, "description": "Fecha de recolección." }, "deliveryDate": { "type": "string", "nullable": true, "description": "Fecha de entrega; `null` si aún no se entrega." }, "deliveryMessage": { "type": "string", "nullable": true, "description": "Mensaje sobre la entrega, si lo hay." }, "alertColor_delivery": { "type": "string", "nullable": true, "description": "Color de alerta de la entrega, en hexadecimal." } } }, "geolocation": { "type": "object", "description": "Coordenadas del movimiento más reciente, como texto. Son `null` si el movimiento no tiene georreferencia.", "properties": { "latitude": { "type": "string", "nullable": true }, "longitude": { "type": "string", "nullable": true } } }, "resources": { "type": "object", "description": "Recursos del movimiento más reciente.", "properties": { "imgURL": { "type": "string", "nullable": true, "description": "URL de la imagen del movimiento (por ejemplo, la foto de la entrega)." }, "markedMap": { "type": "string", "nullable": true, "description": "Mapa con la ubicación marcada, si existe." } } }, "trackingMovement": { "type": "array", "description": "Movimientos de la orden, del más antiguo al más reciente. El último es el estado actual.", "items": { "type": "object", "properties": { "iconMovement": { "type": "string", "nullable": true, "description": "Clase del ícono del estado (Font Awesome)." }, "colorMovement": { "type": "string", "nullable": true, "description": "Color del estado, en hexadecimal." }, "statusMainDescription": { "type": "string", "nullable": true, "description": "Nombre del estado, en español." }, "flowGroup": { "type": "string", "nullable": true, "description": "Reservado; actualmente siempre es `null`." }, "dateMovement": { "type": "string", "nullable": true, "description": "Fecha del movimiento (`YYYY-MM-DD HH:mm:ss`)." } } } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Tracking obtenido correctamente", "data": { "generalData": { "comment": null, "creationDate": "2026-10-07 10:15:00", "branchName": "Comercio Prueba", "cantPackages": 1, "courierName": "Mensajería Ejemplo", "statusMainDescription": "EN RUTA", "subStatusDescription": "En ruta de entrega", "colorMovement": "#1565C0", "flowGroup": null, "publicNotice": { "hasNotice": false, "type": null, "message": null }, "recipientName": "Cliente Prueba", "collectionDate": "2026-10-07", "deliveryDate": null, "deliveryMessage": null, "alertColor_delivery": null }, "geolocation": { "latitude": "13.692940", "longitude": "-89.218191" }, "resources": { "imgURL": null, "markedMap": null }, "trackingMovement": [ { "iconMovement": "fa-solid fa-truck", "colorMovement": "#1565C0", "statusMainDescription": "EN RUTA", "flowGroup": null, "dateMovement": "2026-10-07 14:30:00" } ] } } } } }, "400": { "description": "Falta el OrderId o no es un UUID válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "faltante": { "summary": "OrderId no enviado", "value": { "response_code": 400, "response_status": "Error", "response_message": "OrderId es requerido" } }, "invalido": { "summary": "OrderId con formato inválido", "value": { "response_code": 400, "response_status": "Error", "response_message": "OrderId debe ser un UUID válido" } } } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al capturar tracking de envío" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Datos públicos" } }, "/api/statusMain": { "get": { "summary": "Obtener estados de orden", "operationId": "getOrderStatuses", "description": "Retorna el catálogo de estados principales de una orden (`CONFIRMED`, `IN_WAREHOUSE`, `IN_ROUTE`, `INCIDENT`, `DELIVERED`, `CANCELLED`…).\n\nSirve para:\n- Interpretar el estado de una orden en el seguimiento (`GET /api/orders/tracking`).\n- Obtener el `statusMainId` para consultar los subestados (`GET /api/subStatusMain`).\n", "tags": [ "Estados y Catálogos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "flowGroups", "required": false, "schema": { "type": "string" }, "description": "Opcional. Grupos de flujo a incluir, separados por coma y sin repetidos. Sin este parámetro retorna todos los estados.", "example": "delivery,return" } ], "responses": { "200": { "description": "Estados obtenidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderStatus" } } } }, "example": { "response_code": 200, "response_status": "success", "response_message": "Estados principales obtenidos correctamente.", "data": [ { "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0021", "statusCode": "CONFIRMED", "descriptionStatus": "Pedido confirmado", "flowGroup": "delivery" }, { "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0022", "statusCode": "IN_ROUTE", "descriptionStatus": "En ruta de entrega", "flowGroup": "delivery" }, { "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0023", "statusCode": "DELIVERED", "descriptionStatus": "Entregado", "flowGroup": "delivery" }, { "statusMainId": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0024", "statusCode": "REFUNDED", "descriptionStatus": "Devuelto y reembolsado", "flowGroup": "return" } ] } } } }, "400": { "description": "flowGroups contiene valores repetidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "flowGroups no puede contener valores repetidos" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "error", "response_message": "Error al obtener status main", "data": [] } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Estados" } }, "/api/subStatusMain": { "get": { "summary": "Obtener subestados de un estado", "operationId": "getOrderSubStatuses", "description": "Retorna los subestados de un estado principal. El subestado detalla el estado de la orden en el seguimiento\n(por ejemplo, dentro de `INCIDENT`: dirección incorrecta, destinatario ausente…).\nEl `statusMainId` se obtiene de `GET /api/statusMain`.\n", "tags": [ "Estados y Catálogos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "statusMainId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID del estado principal (`statusMainId` de `GET /api/statusMain`).", "example": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0022" } ], "responses": { "200": { "description": "Subestados obtenidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSubStatus" } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Subestados obtenidos correctamente", "data": [ { "subStatusMainId": "0199a1b2-6666-7e5f-8a6b-1c2d3e4f0031", "subStatusDescription": "En ruta de entrega" }, { "subStatusMainId": "0199a1b2-6666-7e5f-8a6b-1c2d3e4f0032", "subStatusDescription": "Reprogramado para el siguiente día" } ] } } } }, "400": { "description": "statusMainId no enviado o no es un UUID válido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 400, "response_status": "Error", "response_message": "El parámetro \"statusMainId\" es requerido y debe ser un UUID válido" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los subestados" } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Estados" } }, "/api/movementReason": { "get": { "summary": "Obtener motivos de movimiento", "operationId": "getMovementReasons", "description": "Retorna el catálogo de motivos de movimiento de saldo (recarga, cobro de envío, devolución, beneficio…). El `movementTypeId` se usa como filtro `filters.movementReasonId` en `POST /api/branchs/history/transactionsAndMovements`.", "tags": [ "Estados y Catálogos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Motivos obtenidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "movementTypeId": { "type": "string", "format": "uuid", "description": "ID del motivo. Es el valor que acepta el filtro `filters.movementReasonId` del historial de transacciones y movimientos." }, "movementCode": { "type": "string", "description": "Código del motivo." }, "movementDescription": { "type": "string", "description": "Nombre del motivo, en español." }, "movementDirection": { "type": "string", "description": "Sentido del movimiento sobre el saldo (por ejemplo, `credit` para un abono)." }, "affectsBalance": { "type": "boolean", "description": "Indica si el movimiento modifica el saldo del comercio." } } } } } }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Motivos de movimiento procesados correctamente", "data": [ { "movementTypeId": "0199a1b2-1234-7e5f-8a6b-1c2d3e4f0013", "movementCode": "RECHARGE", "movementDescription": "Recarga de Saldo", "movementDirection": "credit", "affectsBalance": true }, { "movementTypeId": "0199a1b2-1238-7e5f-8a6b-1c2d3e4f0017", "movementCode": "PACKAGE_CHANGE_CREDIT", "movementDescription": "Reintegro por reducción de paquetes", "movementDirection": "credit", "affectsBalance": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No hay motivos registrados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 404, "response_status": "Error", "response_message": "No se encontraron motivos de movimiento", "data": null } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error inesperado al obtener los motivos de movimiento", "data": null } } } } }, "x-apidog-status": "released", "x-apidog-folder": "Catálogos/Estados" } } } }