{ "openapi": "3.0.0", "info": { "title": "Volao API", "version": "1.0.0", "description": "The Volao REST API connects your store or system to Volao's shipping platform. With it you can quote shipments across several couriers, create and cancel orders, get each shipment's shipping label and track its journey, and manage your merchant's pickup addresses and clients.\n\n## What you can do\n\n| Area | What it is for |\n| --- | --- |\n| **Authentication** | Get an access token with your credentials. |\n| **Orders** | Create shipping orders, cancel them, get the shipping label, and check the tracking and incidents. |\n| **Couriers** | Quote a shipment and check the available couriers, their service modes, delivery promises, coverage, agencies and rates. |\n| **Branches** | Manage your merchant's pickup addresses and clients (recipients). |\n| **History** | Check the merchant's order, transaction and balance movement, settlement and benefit history. |\n| **Batch operations** | Create orders and generate shipping labels in bulk from an Excel file. |\n| **Catalogs and public data** | Departments, municipalities, address types, banks, document types, movement reasons and public order tracking. |\n\n## Base URL\n\nEvery path starts with `/api` and is appended to the server URL. For example: `{server}/api/orders`. You can see and choose the server in each endpoint's **Request** panel.\n\n## Authentication\n\n1. Request your credentials (`client_id` and `client_secret`) from the Volao team.\n2. Get a token with `POST /api/auth/client/login`.\n3. Send the token in the header of every request: `Authorization: Bearer `.\n\nThe token lasts **15 minutes** and cannot be refreshed: when it expires, log in again. The endpoints under `/api/open/` are public and do not require a token.\n\n## Request format\n\n- Parameters of `GET` endpoints are sent in the URL (query string).\n- The body of `POST`, `PUT`, `PATCH` and `DELETE` requests is sent as JSON, with the header `Content-Type: application/json`.\n- The exception is the batch order upload, which receives the Excel file as `multipart/form-data`.\n\n## Response format\n\nEvery response shares the same structure:\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` repeats the HTTP status code and `data` contains the result. `response_status` may arrive as `Success`/`Error` or `success`/`error`, so compare it case-insensitively or use `response_code`.\n\nThe API responds in Spanish: `response_message` texts are shown in Spanish throughout this documentation.\n\n## Status codes\n\n| Code | Meaning |\n| --- | --- |\n| `200` | The operation was completed successfully. |\n| `201` | The resource was created successfully (for example, an order, an address or a client). |\n| `400` | The request has invalid data or is missing parameters. |\n| `401` | The credentials are invalid, or the token is missing, expired or invalid. |\n| `403` | The API client is disabled. |\n| `404` | The requested resource does not exist. |\n| `409` | The operation cannot be performed because of a business rule (for example, insufficient balance or a duplicate name). The reason comes in `response_message`. |\n| `500` | Internal server error. |\n\n## Flow to create a shipment\n\n1. **Authenticate** with `POST /api/auth/client/login`.\n2. **Check the catalogs** of departments and municipalities (`/api/open/...`) to get the location IDs.\n3. **Choose or register the pickup address** at `/api/branchs/branchsAddresses`.\n4. **Choose or register the client** (recipient) at `/api/branchs/branchsClient`.\n5. **Quote the shipment** with `POST /api/courier` to see the available couriers and their price.\n6. **Create the order** with `POST /api/orders`.\n7. **Get the shipping label** with `GET /api/orders` and **track the shipment** with `GET /api/orders/tracking`.\n\n## Try it from this documentation\n\nEach endpoint includes a panel to send real requests:\n\n1. Open **API client login**, enter your credentials and press **Send API Request**.\n2. Copy the `access_token` from the response.\n3. In any other endpoint, paste it in the panel's **Auth** field. It is kept until you close the tab.\n\n## More information\n\n- [Getting started](/docs/guides/gettingStarted): credentials and first request.\n- [Authentication](/docs/guides/authentication): token lifetime and errors.\n- [Response format](/docs/guides/responseEnvelope): common structure of the responses.", "contact": { "name": "Volao Team", "url": "https://volao.app" } }, "tags": [ { "name": "Autenticación API", "description": "Getting the access token with the API client credentials (`client_id` and `client_secret`). The token is sent in the `Authorization` header of every other endpoint." }, { "name": "Órdenes", "description": "Creating and cancelling shipping orders, getting the shipping label and tracking each order." }, { "name": "Mensajerías (Couriers)", "description": "Shipment quotes and the available couriers: service modes, coverage, agencies and rates." }, { "name": "Direcciones de Sucursales (Branch Addresses)", "description": "Managing the merchant's pickup addresses. Every order is picked up at one of these addresses." }, { "name": "Clientes de Sucursales (Branch Clients)", "description": "Managing the merchant's clients (recipients). The order is delivered to the client's registered address." }, { "name": "Historial de Sucursales (Branch History)", "description": "The merchant's history: orders, transactions and balance movements, settlements and benefits." }, { "name": "Operaciones Masivas (Batch Operations)", "description": "Batch order creation from an Excel file and generation of shipping labels for several orders at once." }, { "name": "Datos Públicos (Open Data)", "description": "Publicly accessible catalogs (no token required). Used to fill in address, client and merchant forms." }, { "name": "Estados y Catálogos", "description": "Catalogs of order statuses and sub-statuses and of balance movement reasons. Used to interpret tracking and to filter the histories." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "Unauthorized": { "description": "The token is missing, expired (it lasts 15 minutes) or invalid. Log in again to get a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "tokenInvalido": { "summary": "Expired or invalid token", "value": { "response_code": 401, "response_status": "Error", "response_message": "Token inválido o expirado" } }, "sinToken": { "summary": "The Authorization header was not sent", "value": { "response_code": 401, "response_status": "Error", "response_message": "Autenticación requerida" } } } } } } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Common format of error responses.", "properties": { "response_code": { "type": "integer", "description": "HTTP status code of the error (same as the response status)." }, "response_status": { "type": "string", "description": "Always indicates an error. May arrive as `Error` or `error`.", "example": "Error" }, "response_message": { "type": "string", "description": "Human-readable reason for the error (in Spanish)." } } }, "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": "Main status of an order.", "properties": { "statusMainId": { "type": "string", "format": "uuid", "description": "Status ID. Used as `statusMainId` in `GET /api/subStatusMain`." }, "statusCode": { "type": "string", "description": "Status code (for example `DELIVERED`). Identifies the order's status in its tracking.", "example": "DELIVERED" }, "descriptionStatus": { "type": "string", "description": "Status name, in Spanish, to show to the user.", "example": "Entregado" }, "flowGroup": { "type": "string", "description": "Flow the status belongs to (for example, `delivery` for delivery or `return` for returns). It is the value accepted by the `flowGroups` filter.", "example": "delivery" } } }, "OrderSubStatus": { "type": "object", "description": "Sub-status of an order; it details the main status.", "properties": { "subStatusMainId": { "type": "string", "format": "uuid", "description": "Sub-status ID." }, "subStatusDescription": { "type": "string", "description": "Sub-status name, in Spanish.", "example": "En ruta de entrega" } } }, "OrderTrackingSummary": { "type": "object", "description": "Summary of an order with its movement history.", "properties": { "commerce": { "type": "object", "description": "Merchant that created the order and its pickup address.", "properties": { "branchsId": { "type": "string", "format": "uuid" }, "branchsName": { "type": "string" }, "branchsAddress": { "type": "string" }, "branchDepartment": { "type": "string" }, "branchsMunicipality": { "type": "string" } } }, "recipient": { "type": "object", "description": "Recipient and delivery address.", "properties": { "recipientName": { "type": "string" }, "recipientAddress": { "type": "string" }, "recipientDepartment": { "type": "string" }, "recipientMunicipality": { "type": "string" }, "comments": { "type": "string", "nullable": true, "description": "Order comments for the delivery." } } }, "order": { "type": "object", "description": "Order data.", "properties": { "orderId": { "type": "string", "format": "uuid" }, "comprobante": { "type": "string", "nullable": true, "description": "Receipt number of the shipping label." }, "courierName": { "type": "string" }, "createdAt": { "type": "string", "description": "Creation date (`YYYY-MM-DD HH:mm:ss`)." }, "onDelivery": { "type": "boolean", "description": "`true` if payment is collected on delivery." }, "consignmentValue": { "type": "number", "description": "Amount to collect from the recipient." }, "deliveryCost": { "type": "number", "description": "Shipping cost." }, "totalWeight": { "type": "number" }, "cantPackages": { "type": "integer" }, "productDescription": { "type": "string" } } }, "trackingMovement": { "type": "array", "description": "Order movements, from oldest to newest. The last one is the current status.", "items": { "type": "object", "properties": { "statusMainCode": { "type": "string", "description": "Status code (catalog `GET /api/statusMain`)." }, "statusMainDescription": { "type": "string" }, "subStatusCode": { "type": "string" }, "subStatusDescription": { "type": "string" }, "statusColor": { "type": "string", "description": "Status color, in hexadecimal." }, "statusIcon": { "type": "string", "description": "Status icon class (Font Awesome)." }, "dateMovement": { "type": "string", "description": "Movement date (`YYYY-MM-DD HH:mm:ss`)." }, "datetimeMovementFormatted": { "type": "string", "description": "Movement date in a readable format." } } } }, "guide": { "type": "object", "properties": { "URLguide": { "type": "string", "description": "URL of the shipping label. Empty if the order has no shipping label." } } }, "tracking": { "type": "object", "properties": { "URLtracking": { "type": "string", "description": "URL of the public tracking page, to share with the recipient. Empty if the order has no shipping label." } } } } }, "OrderIncidentsDetail": { "type": "object", "description": "Current status of an order and all its incidents.", "properties": { "order": { "type": "object", "description": "Order data and its current status.", "properties": { "orderId": { "type": "string", "format": "uuid" }, "comprobante": { "type": "string", "nullable": true, "description": "Receipt number of the shipping label." }, "integrationOrderRef": { "type": "string", "nullable": true, "description": "Order number in the merchant's system, if it was sent when creating the order." }, "isCurrentlyInIncident": { "type": "boolean", "description": "Indicates whether the order is still in an incident." }, "currentStatus": { "type": "object", "description": "Current status of the order.", "properties": { "statusMainId": { "type": "string", "format": "uuid", "description": "Status ID (catalog `GET /api/statusMain`)." }, "description": { "type": "string", "description": "Status name, in Spanish." }, "flowGroup": { "type": "string", "description": "Flow the status belongs to (for example, `delivery` or `incident`)." }, "color": { "type": "string", "description": "Status color, in hexadecimal." }, "icon": { "type": "string", "description": "Status icon name (Font Awesome)." } } } } }, "summary": { "type": "object", "properties": { "totalIncidents": { "type": "integer", "description": "Number of incidents of the order." } } }, "incidents": { "type": "array", "description": "Incidents of the order, from the most recent to the oldest.", "items": { "type": "object", "properties": { "incidentId": { "type": "string", "format": "uuid" }, "trackingId": { "type": "string", "format": "uuid", "description": "ID of the tracking movement linked to the incident." }, "statusMainId": { "type": "string", "format": "uuid", "description": "Status ID (catalog `GET /api/statusMain`)." }, "statusDescription": { "type": "string", "description": "Status name, in Spanish." }, "statusColor": { "type": "string", "description": "Status color, in hexadecimal." }, "statusIcon": { "type": "string", "description": "Status icon name (Font Awesome)." }, "subStatusId": { "type": "string", "format": "uuid", "nullable": true, "description": "Sub-status ID (catalog `GET /api/subStatusMain`)." }, "subStatusDescription": { "type": "string", "nullable": true, "description": "Sub-status name, in Spanish." }, "comment": { "type": "string", "nullable": true, "description": "Comment registered with the incident." }, "source": { "type": "string", "description": "Source of the incident (for example, `tracking`)." }, "reportedAt": { "type": "string", "description": "Date the incident was reported (`YYYY-MM-DD HH:mm:ss`)." } } } } } }, "CourierQuoteOption": { "type": "object", "description": "Shipping option of the quote: a courier service with its cost and estimated dates.", "properties": { "courierId": { "type": "string", "format": "uuid", "description": "Courier. Used as `courierId` in `GET /api/courier/agencies`." }, "courierServiceId": { "type": "string", "format": "uuid", "description": "Shipping service. Sent as `courier.courierServiceId` when creating the order (`POST /api/orders`)." }, "courierName": { "type": "string", "description": "Courier name." }, "serviceName": { "type": "string", "description": "Service name." }, "serviceTypeName": { "type": "string", "description": "Service type name." }, "path_logo": { "type": "string", "description": "URL of the courier's logo." }, "isSameDay": { "type": "boolean", "description": "The service delivers on the same day." }, "enableGeoreference": { "type": "boolean", "description": "The courier works with the address's georeference." }, "deliveryCost": { "type": "number", "description": "Shipping cost." }, "hasDeliveryPromotion": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` if the shipping cost has a promotion." }, "previousDeliveryCost": { "type": "number", "nullable": true, "description": "Shipping cost without the promotion; `null` if there is no promotion." }, "ComCCE": { "type": "number", "description": "Service commission." }, "hasCommissionPromotion": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` if the commission has a promotion." }, "previousComCCE": { "type": "number", "nullable": true, "description": "Commission without the promotion; `null` if there is no promotion." }, "enablePromotionLabel": { "type": "boolean", "description": "Whether the promotion label is shown." }, "enableRecommended": { "type": "boolean", "description": "Recommended service." }, "courierDates": { "type": "object", "description": "Estimated pickup and delivery dates and times.", "properties": { "collectionDate": { "type": "string", "format": "date" }, "collectionDay": { "type": "string", "description": "Day of the week of the pickup." }, "pickupStartTime": { "type": "string", "description": "Start of the pickup time window." }, "pickupEndTime": { "type": "string", "description": "End of the pickup time window." }, "deliveryDate": { "type": "string", "format": "date" }, "deliveryDay": { "type": "string", "description": "Day of the week of the delivery." }, "collectionDate_byCoverage": { "type": "string", "description": "Pickup date according to the coverage days." }, "deliveryDate_byCoverage": { "type": "string", "description": "Delivery date according to the coverage days." }, "collectionMessage": { "type": "string", "description": "Pickup text to show to the user." }, "deliveryMessage": { "type": "string", "description": "Delivery text to show to the user." }, "alertColor_collection": { "type": "string", "description": "Color (hexadecimal) in which to show the pickup text." }, "alertColor_delivery": { "type": "string", "description": "Color (hexadecimal) in which to show the delivery text." }, "collectionAlert": { "type": "integer" } } }, "courierInfo": { "type": "object", "description": "Courier's conditions for the service.", "properties": { "weightLimit": { "type": "number", "description": "Maximum weight per shipment." }, "sizeLimit": { "type": "string", "description": "Maximum dimensions per shipment." }, "additionalPoundCost": { "type": "number", "description": "Cost per additional pound." }, "insuranceCoverage": { "type": "number", "description": "Insurance coverage per shipment." }, "returnCost": { "type": "number", "description": "Return cost." }, "returnTimeEstimate": { "type": "number", "description": "Estimated return time, in days." }, "maximumEffectiveLimit": { "type": "number", "description": "Maximum amount to collect from the recipient." }, "minimumConsignmentRequired": { "type": "number" }, "baseCommissionTotal": { "type": "number" }, "maximumCollectionTime": { "type": "string", "description": "Pickup cut-off time." }, "collectionTime": { "type": "string", "nullable": true }, "deliveryTime": { "type": "string", "nullable": true }, "text_coverage": { "type": "string", "description": "Service coverage text." }, "phoneNumber": { "type": "string", "description": "Courier's contact phone number." }, "averageRating": { "type": "string", "description": "Courier's average rating, as a numeric string." } } }, "courierLabels": { "type": "object", "description": "Labels to show next to the service.", "properties": { "labels": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "label_color": { "type": "string", "description": "Label color (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": "Label color (hexadecimal)." }, "icon": { "type": "string", "nullable": true }, "iconVariant": { "type": "string", "nullable": true } } } } } }, "agencies": { "type": "array", "description": "The courier's agencies, for services that deliver or pick up at an agency. Empty for the other services.", "items": { "type": "object", "properties": { "agencyId": { "type": "string", "format": "uuid" }, "agencyName": { "type": "string" }, "agencyAddress": { "type": "string" } } } } } }, "CourierServiceItem": { "type": "object", "description": "A courier service with its limits, prices and delivery conditions.", "properties": { "courierServiceId": { "type": "string", "format": "uuid", "description": "Shipping service." }, "courier": { "type": "object", "properties": { "courierId": { "type": "string", "format": "uuid" }, "courierName": { "type": "string" }, "courierLogo": { "type": "string", "nullable": true, "description": "URL of the courier's logo." }, "courierLabelText": { "type": "string", "nullable": true, "description": "Courier label to show." }, "courierEnableGeoreference": { "type": "boolean", "description": "The courier works with the address's georeference." }, "courierAverageRating": { "type": "number", "nullable": true, "description": "Courier's average rating." } } }, "service": { "type": "object", "properties": { "serviceCode": { "type": "string" }, "serviceName": { "type": "string" }, "serviceType": { "type": "object", "properties": { "serviceTypeCode": { "type": "string" }, "serviceTypeName": { "type": "string" }, "serviceTypeRequiresCoverageValidation": { "type": "boolean", "description": "The service type validates the destination's coverage." } } } } }, "limits": { "type": "object", "properties": { "limitMaximumWeight": { "type": "number", "nullable": true, "description": "Maximum weight per shipment." }, "limitWeightUnit": { "type": "string", "nullable": true, "description": "Weight unit (for example, `lb`)." }, "limitMaximumDimensions": { "type": "string", "nullable": true, "description": "Maximum dimensions per shipment." }, "limitMaximumCashAmount": { "type": "number", "nullable": true, "description": "Maximum amount to collect from the recipient." }, "limitMaximumPickupTime": { "type": "string", "nullable": true, "description": "Pickup cut-off time." } } }, "pricing": { "type": "object", "properties": { "pricingRateRange": { "type": "string", "nullable": true, "description": "Rate or rate range, as text." }, "pricingAdditionalWeightUnitCost": { "type": "number", "nullable": true, "description": "Cost per additional weight unit." }, "pricingInsurancePerShipment": { "type": "number", "nullable": true, "description": "Insurance per shipment." }, "pricingReturnCost": { "type": "number", "nullable": true, "description": "Return cost." }, "pricingComCCE": { "type": "number", "description": "Service commission; `0` if there is none." } } }, "delivery": { "type": "object", "properties": { "deliverySameDayService": { "type": "boolean", "description": "The service delivers on the same day." }, "deliveryFreeAttempts": { "type": "integer", "nullable": true, "description": "Free delivery attempts." }, "deliveryReturnTimeEstimateDays": { "type": "integer", "nullable": true, "description": "Estimated days for the return." }, "deliveryCoverageText": { "type": "string", "nullable": true, "description": "Service coverage text." }, "deliveryPromotionLabelEnabled": { "type": "boolean", "description": "Whether the promotion label is shown." } } }, "agencies": { "type": "object", "properties": { "agenciesHasAgencies": { "type": "boolean", "description": "The service works with agencies (`GET /api/courier/agencies`)." }, "agenciesCount": { "type": "integer", "description": "Number of the courier's agencies." } } } } }, "CourierAgency": { "type": "object", "description": "A courier's agency.", "properties": { "agencyId": { "type": "string", "format": "uuid", "description": "Sent in `courier.agencias` (`idAgenciaEntrega` or `idAgenciaRecolecta`) when creating the order." }, "agencyName": { "type": "string" }, "agencyAddress": { "type": "string" }, "scheduleDescription": { "type": "string", "nullable": true, "description": "Opening hours." }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "location": { "type": "object", "description": "Agency location.", "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": "Optional.", "example": "cliente.prueba@example.com" }, "recipientPhone": { "type": "string", "minLength": 7, "maxLength": 150, "description": "Digits, spaces, `+`, `-` and parentheses only.", "example": "70000000" }, "recipientAddress": { "type": "string", "minLength": 5, "maxLength": 500, "example": "Calle Ficticia #456, Colonia Prueba, San Salvador" }, "municipalityCode": { "type": "string", "format": "uuid", "description": "UUID of the delivery municipality (`municipalityId` from `POST /api/open/municipality`).", "example": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005" } } }, "BranchClient": { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "Used as `branchInfo.branchsClientId` when creating an order." }, "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": "Creation date in a readable format." } } }, "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": "Unique name of the address within the merchant.", "example": "Bodega Prueba" }, "collectionAddress": { "type": "string", "minLength": 5, "maxLength": 500, "description": "Full physical pickup address.", "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": "Digits, spaces, `+`, `-` and parentheses only.", "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": "Latitude with a decimal point (1 to 10 decimals), sent as a string.", "example": "13.692940" }, "longitude": { "type": "string", "pattern": "^-?\\d{1,3}\\.\\d{1,10}$", "description": "Longitude with a decimal point (1 to 10 decimals), sent as a string.", "example": "-89.218191" }, "municipalityCodigo": { "type": "string", "description": "Code of the address's municipality (`municipalityCode` from `POST /api/open/municipality`), not its UUID.", "example": "0102" }, "typeBranchAddressId": { "type": "string", "format": "uuid", "description": "Address type (catalog `GET /api/open/typeBranchAddress`). Sent as a string.", "example": "0199a1b2-1111-7e5f-8a6b-1c2d3e4f0002" } } }, "BranchSuccessResponse": { "type": "object", "description": "Common fields of successful responses.", "properties": { "response_code": { "type": "integer", "description": "HTTP status code of the response (same as the status)." }, "response_status": { "type": "string", "description": "Indicates success. May arrive as `Success` or `success`." }, "response_message": { "type": "string", "description": "Human-readable result of the operation (in Spanish)." } } }, "BranchAddress": { "type": "object", "description": "The merchant's pickup address.", "properties": { "branchAddressId": { "type": "string", "format": "uuid", "description": "Address ID. Used as `branchInfo.branchAddressId` when creating an order." }, "branchAddressName": { "type": "string", "description": "Address name to display." }, "defaultAddress": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` if it is the merchant's default address." }, "branchsId": { "type": "string", "format": "uuid", "description": "Merchant ID." }, "typeBranchAddress": { "type": "string", "format": "uuid", "description": "Address type (`TypeBranchAddressId` from `GET /api/open/typeBranchAddress`)." }, "typeBranchAddressIcon": { "type": "string", "nullable": true, "description": "Address type icon (Font Awesome class)." }, "nameBranchAddress": { "type": "string", "description": "Address type name." }, "collectionAddress": { "type": "string", "description": "Pickup address." }, "contactName": { "type": "string", "description": "Name of the contact at the address." }, "principalPhone": { "type": "string", "description": "Contact's phone number." }, "emailContact": { "type": "string", "nullable": true, "description": "Contact's email." }, "georeference": { "type": "string", "description": "Latitude and longitude separated by a comma." }, "municipalityCode": { "type": "string", "description": "Municipality code." }, "municipalitiesName": { "type": "string", "description": "Municipality name." }, "departmentsCodigo": { "type": "string", "description": "Department code." }, "departmentsName": { "type": "string", "description": "Department name." } } }, "HistoryPagination": { "type": "object", "description": "Pagination of the results.", "properties": { "page": { "type": "integer", "description": "Current page." }, "limit": { "type": "integer", "description": "Results per page." }, "max_limit": { "type": "integer", "description": "Maximum value allowed for `limit`." }, "total": { "type": "integer", "description": "Total results with the applied filters." }, "total_pages": { "type": "integer", "description": "Total pages." }, "has_next": { "type": "boolean", "description": "There is a next page." }, "has_prev": { "type": "boolean", "description": "There is a previous page." }, "from": { "type": "integer", "description": "Position of the first result on the page (`0` if there are no results)." }, "to": { "type": "integer", "description": "Position of the last result on the page." } } }, "HistoryExport": { "type": "object", "description": "Excel export.", "properties": { "URLDataExcel": { "type": "string", "description": "URL of the Excel file with all the results. Empty string if `export` was not sent as `1` or there are no results." } } }, "HistoryMetric": { "type": "object", "description": "Metric for the queried period.", "properties": { "value": { "type": "number", "description": "Value for the period." }, "changePercentage": { "type": "number", "description": "Percentage change compared with the previous period. Not included in every metric." } } }, "HistoryOrderItem": { "type": "object", "description": "History order with its current status, courier and recipient.", "properties": { "ordersId": { "type": "string", "format": "uuid", "description": "Order ID." }, "order": { "type": "object", "description": "Order data.", "properties": { "comprobante": { "type": "string", "description": "Order's receipt number." }, "createdAt": { "type": "string", "description": "Creation date and time (`YYYY-MM-DD HH:mm:ss`)." }, "platform": { "type": "string", "description": "Channel through which the order was created (for example, `API`)." }, "productDescription": { "type": "string", "description": "Description of the package contents." }, "totalWeight": { "type": "number", "description": "Total shipment weight." }, "packageCount": { "type": "integer", "description": "Number of packages." }, "onDelivery": { "type": "boolean", "description": "The order has cash on delivery." }, "paidShipping": { "type": "boolean", "description": "The shipping is already paid." }, "consignmentValue": { "type": "number", "description": "Amount to collect from the recipient." }, "deliveryCost": { "type": "number", "description": "Shipping cost." }, "baseCommissionAmount": { "type": "number", "description": "Order's base commission." }, "pcme": { "type": "number", "description": "Order's commission percentage (0 to 100)." }, "branchDepartmentName": { "type": "string", "description": "Pickup address's department." }, "branchMunicipalityName": { "type": "string", "description": "Pickup address's municipality." } } }, "status": { "type": "object", "description": "Order's current status.", "properties": { "statusMainId": { "type": "string", "format": "uuid", "description": "Main status (`statusMainId` from `GET /api/statusMain`)." }, "statusDescription": { "type": "string", "description": "Status name." }, "subStatusMainId": { "type": "string", "format": "uuid", "description": "Sub-status (`GET /api/subStatusMain`)." }, "subStatusDescription": { "type": "string", "description": "Sub-status name." }, "flowGroup": { "type": "string", "description": "Status flow group (for example, `delivery` or `return`)." }, "statusColor": { "type": "string", "description": "Status color (hexadecimal)." }, "lastMovementDate": { "type": "string", "description": "Date and time of the order's last movement." } } }, "courier": { "type": "object", "description": "The order's courier.", "properties": { "courierId": { "type": "string", "format": "uuid", "description": "Courier ID." }, "courierName": { "type": "string", "description": "Courier name." }, "courierLogo": { "type": "string", "description": "URL of the courier's logo." }, "courierPhone": { "type": "string", "nullable": true, "description": "Courier's phone number." } } }, "recipient": { "type": "object", "description": "The order's recipient.", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "Recipient client (`GET /api/branchs/branchsClient`)." }, "recipientName": { "type": "string", "description": "Recipient name." }, "recipientPhone": { "type": "string", "description": "Recipient's phone number." }, "recipientAddress": { "type": "string", "description": "Delivery address." }, "departmentCode": { "type": "string", "description": "Delivery department code." }, "departmentName": { "type": "string", "description": "Delivery department name." }, "municipalityCode": { "type": "string", "description": "Delivery municipality code." }, "municipalityName": { "type": "string", "description": "Delivery municipality name." }, "favoriteClient": { "type": "boolean", "description": "The client is marked as a favorite." }, "branchsClientStatus": { "type": "boolean", "description": "The client is active." } } }, "tracking": { "type": "object", "description": "The order's tracking.", "properties": { "URLtracking": { "type": "string", "description": "URL of the order's public tracking page." } } } } }, "TransactionHistoryItem": { "type": "object", "description": "Merchant transaction with its payment method, wallet summary and balance movements.", "properties": { "transaction": { "type": "object", "description": "Transaction data.", "properties": { "transactionId": { "type": "string", "format": "uuid", "description": "Transaction ID." }, "createdAt": { "type": "string", "description": "Transaction date and time (`YYYY-MM-DD HH:mm:ss`)." }, "transactionAmount": { "type": "number", "description": "Transaction amount." }, "transactionGatewayId": { "type": "string", "format": "uuid", "description": "Transaction's payment gateway." }, "transactionGatewayCode": { "type": "string", "description": "Payment gateway code." }, "transactionGatewayLabel": { "type": "string", "description": "Payment gateway name to display." }, "gatewayTransactionReference": { "type": "string", "nullable": true, "description": "Transaction reference in the payment gateway." }, "internalTransactionReference": { "type": "string", "description": "Internal transaction reference." } } }, "paymentMethod": { "type": "object", "description": "Card used for the payment. Its fields are `null` if the transaction was not paid by card.", "properties": { "paymentCardId": { "type": "string", "format": "uuid", "nullable": true, "description": "Card ID." }, "cardBin": { "type": "string", "nullable": true, "description": "First 6 digits of the card." }, "cardLast4": { "type": "string", "nullable": true, "description": "Last 4 digits of the card." }, "cardMasked": { "type": "string", "nullable": true, "description": "Masked card number." }, "typeCard": { "type": "string", "nullable": true, "description": "Card type (for example, `VISA`)." }, "cardOwner": { "type": "string", "nullable": true, "description": "Cardholder." } } }, "wallet": { "type": "object", "description": "Summary of the merchant's wallet (balance) in the transaction.", "properties": { "rechargeAmount": { "type": "number", "description": "Top-up amount." }, "previousWalletBalance": { "type": "number", "description": "Balance before the transaction." }, "walletMovementAmount": { "type": "number", "description": "Amount used by the transaction's movements." }, "walletNetAmount": { "type": "number", "description": "Net amount of the transaction in the wallet." }, "walletUsedPreviousBalanceAmount": { "type": "number", "description": "Amount taken from the previous balance." }, "residualWalletBalance": { "type": "number", "description": "Remaining balance after the movements." }, "benefitAmount": { "type": "number", "description": "Amount of the transaction's benefits." } } }, "summary": { "type": "object", "description": "Totals of the transaction's movements.", "properties": { "movementsCount": { "type": "integer", "description": "Number of movements." }, "movementDeliveryCostAmount": { "type": "number", "description": "Sum of the shipping costs." }, "movementCourierCostAmount": { "type": "number", "description": "Sum of the courier costs." }, "movementFeeVolaoAmount": { "type": "number", "description": "Sum of Volao's commissions." }, "movementBenefitAmount": { "type": "number", "description": "Sum of the benefits." } } }, "movements": { "type": "array", "description": "The transaction's balance movements.", "items": { "type": "object", "properties": { "transactionMovementId": { "type": "string", "format": "uuid", "description": "Movement ID." }, "movementReasonId": { "type": "string", "format": "uuid", "description": "Movement reason (`GET /api/movementReason`)." }, "movementReasonCode": { "type": "string", "description": "Movement reason code." }, "movementDescription": { "type": "string", "description": "Movement description." }, "movementIsCredit": { "type": "boolean", "description": "`true` if the movement adds to the balance; `false` if it deducts from it." }, "movementIsBenefit": { "type": "boolean", "description": "`true` if the movement is a benefit (details in `benefit`)." }, "movementDate": { "type": "string", "nullable": true, "description": "Movement date and time." }, "order": { "type": "object", "description": "Movement's order. Its fields are `null` if the movement is not linked to an order.", "properties": { "orderId": { "type": "string", "format": "uuid", "nullable": true, "description": "Order ID." }, "comprobanteAf": { "type": "string", "nullable": true, "description": "Order's receipt number." }, "deliveryCost": { "type": "number", "nullable": true, "description": "Shipping cost." }, "courierCost": { "type": "number", "nullable": true, "description": "Courier cost." }, "feeVolao": { "type": "number", "nullable": true, "description": "Volao's commission." } } }, "courier": { "type": "object", "description": "Movement's courier.", "properties": { "courierId": { "type": "string", "format": "uuid", "nullable": true, "description": "Courier ID." }, "courierName": { "type": "string", "nullable": true, "description": "Courier name." }, "courierLogo": { "type": "string", "nullable": true, "description": "URL of the courier's logo." } } }, "service": { "type": "object", "description": "Movement's shipping service.", "properties": { "courierServiceId": { "type": "string", "format": "uuid", "nullable": true, "description": "Shipping service (`courierServiceId` from `POST /api/courier`)." }, "serviceId": { "type": "string", "format": "uuid", "nullable": true, "description": "Service ID." }, "serviceName": { "type": "string", "nullable": true, "description": "Service name." }, "serviceTypeId": { "type": "string", "format": "uuid", "nullable": true, "description": "Service type ID." }, "serviceTypeName": { "type": "string", "nullable": true, "description": "Service type name." } } }, "balances": { "type": "object", "description": "Merchant's balance in the movement.", "properties": { "previousBalance": { "type": "number", "description": "Balance before the movement." }, "transactionBalance": { "type": "number", "description": "Movement amount (negative if it deducts from the balance)." }, "newBalance": { "type": "number", "description": "Balance after the movement." } } }, "benefit": { "type": "object", "nullable": true, "description": "Benefit detail. `null` if the movement is not a benefit.", "properties": { "benefitId": { "type": "string", "format": "uuid", "description": "Benefit ID." }, "tierCode": { "type": "string", "description": "Subscription tier code." }, "tierName": { "type": "string", "description": "Subscription tier name." }, "baseAmount": { "type": "number", "description": "Amount on which the benefit was calculated." }, "rate": { "type": "number", "description": "Rate applied, as a decimal (`0.05` = 5%)." }, "amount": { "type": "number", "description": "Benefit amount." }, "status": { "type": "string", "enum": [ "APPLIED", "REVERSED" ], "description": "Benefit status, applied or reversed." }, "detail": { "type": "string", "description": "Benefit detail." } } } } } } } }, "BenefitHistoryItem": { "type": "object", "description": "A merchant benefit with its subscription tier, order, courier and balance movement.", "properties": { "benefit": { "type": "object", "description": "Benefit data.", "properties": { "benefitId": { "type": "string", "format": "uuid", "description": "Benefit ID." }, "movementCode": { "type": "string", "description": "Benefit type code (for example, `CBE`)." }, "movementName": { "type": "string", "description": "Benefit type name." }, "movementColor": { "type": "string", "nullable": true, "description": "Color in which the benefit type is shown." }, "status": { "type": "string", "enum": [ "APPLIED", "REVERSED" ], "description": "Benefit status, applied or reversed." }, "amount": { "type": "number", "description": "Benefit amount." }, "baseAmount": { "type": "number", "nullable": true, "description": "Amount on which the benefit was calculated (for example, the shipping cost)." }, "rate": { "type": "number", "nullable": true, "description": "Rate applied, as a decimal (`0.05` = 5%)." }, "detail": { "type": "string", "nullable": true, "description": "Benefit detail." }, "metadata": { "type": "object", "nullable": true, "description": "Additional benefit data. It may include other fields depending on the benefit type.", "properties": { "tierCode": { "type": "string", "description": "Subscription tier code when the benefit was granted." }, "deliveredAt": { "type": "string", "description": "Date and time the order was delivered." }, "orderSubStatusId": { "type": "string", "format": "uuid", "description": "Sub-status of the order that generated the benefit." }, "orderMovements": { "type": "array", "description": "The order's balance movements.", "items": { "type": "object", "properties": { "balanceTransactionId": { "type": "string", "format": "uuid", "description": "Balance movement ID." }, "movementCode": { "type": "string", "description": "Movement code." }, "direction": { "type": "string", "description": "Movement direction (credit or debit)." }, "amount": { "type": "number", "description": "Movement amount." }, "createdAt": { "type": "string", "description": "Movement date and time." } } } } } }, "createdAt": { "type": "string", "description": "Date and time the benefit was applied." }, "reversedAt": { "type": "string", "nullable": true, "description": "Date and time it was reversed. `null` if it was not reversed." } } }, "subscription": { "type": "object", "description": "Subscription tier under which the benefit was granted.", "properties": { "subscriptionTierId": { "type": "string", "format": "uuid", "nullable": true, "description": "Subscription tier ID." }, "tierCode": { "type": "string", "nullable": true, "description": "Subscription tier code." }, "tierName": { "type": "string", "nullable": true, "description": "Subscription tier name." } } }, "order": { "type": "object", "description": "Order that generated the benefit.", "properties": { "orderId": { "type": "string", "format": "uuid", "nullable": true, "description": "Order ID." }, "comprobanteAf": { "type": "string", "nullable": true, "description": "Order's receipt number." }, "deliveryCost": { "type": "number", "nullable": true, "description": "Shipping cost." }, "deliveredAt": { "type": "string", "nullable": true, "description": "Date and time the order was delivered." } } }, "courier": { "type": "object", "description": "The order's courier.", "properties": { "courierId": { "type": "string", "format": "uuid", "nullable": true, "description": "Courier ID." }, "courierName": { "type": "string", "nullable": true, "description": "Courier name." }, "courierLogo": { "type": "string", "nullable": true, "description": "URL of the courier's logo." } } }, "movement": { "type": "object", "description": "Balance movement generated by the benefit.", "properties": { "balanceTransactionId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the benefit's balance movement." }, "paymentTransactionId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the transaction linked to the movement." }, "previousBalance": { "type": "number", "nullable": true, "description": "Balance before the benefit." }, "newBalance": { "type": "number", "nullable": true, "description": "Balance after the benefit." }, "reversedBalanceTransactionId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the reversal's balance movement. `null` if it was not reversed." } } } } }, "SettlementHistoryItem": { "type": "object", "description": "Settlement statement with its bank account, totals and orders.", "properties": { "acta": { "type": "object", "description": "Statement data.", "properties": { "codActa": { "type": "integer", "description": "Settlement statement number." }, "settlementDate": { "type": "string", "format": "date", "description": "Settlement date." }, "totalOrders": { "type": "integer", "description": "Number of orders in the statement." } } }, "bankAccount": { "type": "object", "description": "Bank account where the settlement was deposited.", "properties": { "titular": { "type": "string", "description": "Account holder." }, "bankId": { "type": "string", "format": "uuid", "description": "Bank (`banks[].banksId` from `GET /api/open/banks`)." }, "bankName": { "type": "string", "description": "Bank name." }, "typeAccountId": { "type": "string", "format": "uuid", "description": "Account type (`typeAccount[].typeAccountId` from `GET /api/open/banks`)." }, "typeAccountName": { "type": "string", "description": "Account type name." }, "accountNumber": { "type": "string", "description": "Account number." } } }, "totals": { "type": "object", "description": "Statement totals.", "properties": { "totalConsignmentValue": { "type": "number", "description": "Total collected from recipients." }, "totalDeliveryCost": { "type": "number", "description": "Total shipping costs." }, "totalCommission": { "type": "number", "description": "Total commissions." }, "totalSettledAmount": { "type": "number", "description": "Total settled to the merchant." } } }, "orders": { "type": "array", "description": "Orders settled by the statement.", "items": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Order ID." }, "comprobante": { "type": "string", "description": "Order's receipt number." }, "deliveryDate": { "type": "string", "format": "date", "description": "Order delivery date." }, "consignmentValue": { "type": "number", "description": "Amount collected from the recipient." }, "deliveryCost": { "type": "number", "description": "Shipping cost." }, "commission": { "type": "number", "description": "Commission charged." }, "settledAmount": { "type": "number", "description": "Amount settled to the merchant." } } } } } }, "SettlementDetail": { "type": "object", "description": "Detail of a settlement statement.", "properties": { "accountData": { "type": "object", "description": "Statement, merchant and bank account data.", "properties": { "codActa": { "type": "integer", "description": "Settlement statement number." }, "actaFecha": { "type": "string", "format": "date", "description": "Statement date." }, "branchId": { "type": "string", "format": "uuid", "description": "Merchant ID." }, "branchName": { "type": "string", "description": "Merchant name." }, "branchEmail": { "type": "string", "description": "Merchant's email." }, "titular": { "type": "string", "description": "Bank account holder." }, "bankName": { "type": "string", "description": "Bank name." }, "typeAccount": { "type": "string", "description": "Bank account type." }, "accountNumber": { "type": "string", "description": "Bank account number." } } }, "orders": { "type": "array", "description": "Orders included in the statement.", "items": { "type": "object", "properties": { "ordersId": { "type": "string", "format": "uuid", "description": "Order ID." }, "montoEnvio": { "type": "number", "description": "Amount collected from the recipient." }, "costoEnvio": { "type": "number", "description": "Shipping cost." }, "cme": { "type": "number", "description": "Commission charged." }, "montoLiquidado": { "type": "number", "description": "Amount settled to the merchant." } } } }, "totals": { "type": "object", "description": "Statement totals.", "properties": { "totalMontoEnvio": { "type": "number", "description": "Total collected from recipients." }, "totalCostoEnvio": { "type": "number", "description": "Total shipping costs." }, "totalCme": { "type": "number", "description": "Total commissions." }, "totalLiquidado": { "type": "number", "description": "Total settled to the merchant." } } } } } } }, "servers": [ { "url": "https://api.volao.app", "description": "Production" }, { "url": "https://api.dev.volao.app", "description": "Development" } ], "paths": { "/api/statusMain": { "get": { "summary": "Get order statuses", "operationId": "getOrderStatuses", "description": "Returns the catalog of main order statuses (`CONFIRMED`, `IN_WAREHOUSE`, `IN_ROUTE`, `INCIDENT`, `DELIVERED`, `CANCELLED`…).\n\nUse it to:\n- Interpret the status of an order in its tracking (`GET /api/orders/tracking`).\n- Get the `statusMainId` to look up the sub-statuses (`GET /api/subStatusMain`).\n", "tags": [ "Estados y Catálogos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "flowGroups", "required": false, "schema": { "type": "string" }, "description": "Optional. Flow groups to include, separated by commas and without duplicates. Without this parameter, all statuses are returned.", "example": "delivery,return" } ], "responses": { "200": { "description": "Statuses retrieved", "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 contains duplicate values", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "error", "response_message": "Error al obtener status main", "data": [] } } } } } } }, "/api/subStatusMain": { "get": { "summary": "Get the sub-statuses of a status", "operationId": "getOrderSubStatuses", "description": "Returns the sub-statuses of a main status. The sub-status details the order's status in its tracking\n(for example, within `INCIDENT`: wrong address, recipient not available…).\nThe `statusMainId` is obtained from `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 of the main status (`statusMainId` from `GET /api/statusMain`).", "example": "0199a1b2-5555-7e5f-8a6b-1c2d3e4f0022" } ], "responses": { "200": { "description": "Sub-statuses retrieved", "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 was not sent or is not a valid UUID", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los subestados" } } } } } } }, "/api/movementReason": { "get": { "summary": "Get movement reasons", "operationId": "getMovementReasons", "description": "Returns the catalog of balance movement reasons (top-up, shipping charge, refund, benefit…). The `movementTypeId` is used as the `filters.movementReasonId` filter in `POST /api/branchs/history/transactionsAndMovements`.", "tags": [ "Estados y Catálogos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Reasons retrieved", "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": "Reason ID. It is the value accepted by the `filters.movementReasonId` filter of the transaction and movement history." }, "movementCode": { "type": "string", "description": "Reason code." }, "movementDescription": { "type": "string", "description": "Reason name, in Spanish." }, "movementDirection": { "type": "string", "description": "Direction of the movement on the balance (for example, `credit` for a credit)." }, "affectsBalance": { "type": "boolean", "description": "Indicates whether the movement changes the merchant's balance." } } } } } }, "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": "There are no registered reasons", "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": "Internal error", "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 } } } } } } }, "/api/orders": { "post": { "summary": "Create a new order", "operationId": "createOrder", "description": "Creates a shipping order, generates the shipping label and deducts the cost from the prepaid balance.\n\n**Before creating the order, get these IDs:**\n\n| Order field | Where it comes from | Response field |\n| --- | --- | --- |\n| `branchInfo.branchAddressId` (pickup address) | `GET /api/branchs/branchsAddresses`, or the one returned by `POST /api/branchs/branchsAddresses` when creating it | `branchAddressId` |\n| `branchInfo.branchsClientId` (client and delivery address) | `GET /api/branchs/branchsClient` or `GET /api/branchs/branchsClient/search`, or the one returned by `POST /api/branchs/branchsClient` when registering it | `branchsClientId` |\n| `courier.courierServiceId` (courier and service) | `POST /api/courier` (quote), sending the pickup address and the client's municipality | `courierServiceId` |\n| `courier.agencias` (optional) | `GET /api/courier/agencies`, only if the courier works with agencies | Agency ID |\n\nThe delivery address is not sent separately: it is the one registered for the client.\n\nValidation is done by section (`branchInfo`, `courier`, `location`, `product`, `order`) and the first error found is reported.\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": "Pickup address. Copy the `branchAddressId` field from `GET /api/branchs/branchsAddresses`.", "example": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" }, "branchsClientId": { "type": "string", "format": "uuid", "description": "Recipient client; the order is delivered to the client's registered address. Copy the `branchsClientId` field from `GET /api/branchs/branchsClient` or `GET /api/branchs/branchsClient/search`.", "example": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003" } } }, "courier": { "type": "object", "required": [ "courierServiceId", "agencias" ], "properties": { "courierServiceId": { "type": "string", "format": "uuid", "description": "Chosen courier and service. Copy the `courierServiceId` field of the option chosen in the quote (`POST /api/courier`).", "example": "019f88a7-40d5-75b5-add9-87e652d9ba69" }, "agencias": { "type": "object", "description": "Required. May be sent empty (`{}`); agencies only apply to couriers that use them.", "properties": { "idAgenciaRecolecta": { "type": "string", "format": "uuid", "description": "Optional. Pickup agency, obtained from `GET /api/courier/agencies`." }, "idAgenciaEntrega": { "type": "string", "format": "uuid", "description": "Optional. Delivery agency, obtained from `GET /api/courier/agencies`." } }, "example": {} } } }, "location": { "type": "object", "required": [ "latitude", "longitude" ], "description": "Coordinates of the delivery point, as strings. Used by couriers with `enableGeoreference` set to `true` in the quote; for the others, `\"0\"` may be sent.", "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": "Total weight, greater than 0.", "example": 4 }, "cantPackages": { "type": "integer", "minimum": 1, "maximum": 50, "example": 1 }, "inventoryItems": { "type": "array", "description": "Optional. Products from the merchant's inventory included in the shipment.", "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": "Amount the courier collects from the recipient when `onDelivery` is 1. Without cash on delivery, send the declared value of the goods.", "example": 10 }, "onDelivery": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = payment is collected on delivery; 0 = no collection. `true` / `false` are also accepted.", "example": 1 }, "paymentOrderCollection": { "type": "integer", "enum": [ 0, 1 ], "description": "Payment collection flag (1 = applies, 0 = does not apply). Send 0 unless the Volao team tells you otherwise. `true` / `false` are also accepted.", "example": 0 }, "integrationOrderRef": { "type": "string", "description": "Optional. Order number in the merchant's system (string, not numeric)." }, "comments": { "type": "string", "description": "Required; may be sent empty.", "example": "" } } } } } } } }, "responses": { "201": { "description": "Order created successfully", "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": "Order ID. Use it to get the shipping label, the tracking and the incidents, and to cancel the order." }, "clientName": { "type": "string", "description": "Name of the recipient client." }, "clientEmail": { "type": "string", "description": "Email of the recipient client." }, "comprobante": { "type": "string", "description": "Receipt number of the shipping label, assigned by the courier." }, "courierName": { "type": "string" }, "requestDate": { "type": "string", "description": "Order creation date." }, "availableBalance": { "type": "number", "description": "Prepaid balance available after creating the order." }, "consignmentValue": { "type": "number", "description": "Amount to collect from the recipient." }, "isFirstOrderOfDay": { "type": "integer", "enum": [ 0, 1 ], "description": "1 if it is the merchant's first order of the day." } } }, "guide": { "type": "object", "properties": { "URLguide": { "type": "string", "description": "URL of the shipping label (to view or print). Empty if it could not be retrieved; you can get it later with `GET /api/orders`." } } }, "tracking": { "type": "object", "description": "May be missing from the response, depending on the merchant's configuration.", "properties": { "URLtracking": { "type": "string", "description": "URL of the public tracking page, to share with the recipient. Empty if the order has no shipping label." } } } } }, "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": "Invalid request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "branchInfo": { "summary": "A whole section is missing (the same applies to courier, location, product and order).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"branchInfo\": Falta la sección completa" } }, "branchAddressId": { "summary": "The pickup address is missing (branchInfo.branchAddressId).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"branchInfo\": branchAddressId es requerido" } }, "branchsClientId": { "summary": "The recipient client is missing (branchInfo.branchsClientId).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"branchInfo\": branchsClientId es requerido" } }, "courierServiceId": { "summary": "The shipping service chosen when quoting is missing (courier.courierServiceId).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"courier\": courierServiceId es requerido" } }, "agencias": { "summary": "The agencies object is missing (courier.agencias); it may be sent empty.", "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": "The latitude is missing (location.latitude).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"location\": latitud es requerido" } }, "longitude": { "summary": "The longitude is missing (location.longitude).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"location\": longitud es requerido" } }, "productDescription": { "summary": "The product description is missing (product.productDescription).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": productDescription es requerido" } }, "totalWeight": { "summary": "The total weight is missing (product.totalWeight).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": totalWeight es requerido" } }, "cantPackages": { "summary": "The number of packages is missing (product.cantPackages).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"product\": cantPackages es requerido" } }, "shippingAmount": { "summary": "The amount to collect is missing (order.shippingAmount).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": shippingAmount es requerido" } }, "onDelivery": { "summary": "Whether payment is collected on delivery is missing (order.onDelivery).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": onDelivery es requerido" } }, "paymentOrderCollection": { "summary": "paymentOrderCollection is missing (order.paymentOrderCollection).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": paymentOrderCollection es requerido" } }, "comments": { "summary": "The comments are missing (order.comments); they may be sent empty.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": comments es requerido" } }, "branchAddressIdType": { "summary": "branchAddressId is not a string (the same applies to branchsClientId and courierServiceId).", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"branchInfo\": branchAddressId debe ser una cadena (UUID)" } }, "agencyFormat": { "summary": "An agency is not a valid UUID (the same applies to 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": "The latitude is not a string or exceeds 20 characters (the same applies to the longitude).", "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": "The description is not a string or exceeds 150 characters.", "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": "The weight is not a number or is not greater than 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": "The number of packages is not an integer between 1 and 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": "A product in inventoryItems does not have a valid productId (quantity and price are also validated).", "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": "The amount is not a number.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en sección \"order\": shippingAmount debe ser un número decimal" } }, "onDeliveryValue": { "summary": "onDelivery is not 0, 1, true or 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 was sent as a number.", "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": "Business rule (insufficient amount, address that does not belong to the merchant, balance)", "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": "The courier could not generate the shipping label receipt. Try again or choose another service from the quote.", "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": "Internal error while creating the order. The message may vary and include the error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "general": { "summary": "Internal error, or the body is not valid JSON.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al crear la orden" } }, "mensajeria": { "summary": "Error while registering the order with the courier.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error al ejecutar el flujo de orden" } }, "actualizacion": { "summary": "Error while updating the order after generating the shipping label.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar la orden" } } } } } } } }, "patch": { "summary": "Cancel orders", "operationId": "cancelOrders", "description": "Cancels one or more orders (up to 50) in a single request.\nThe overall response returns 200 if the request was processed; the result of **each order** must be checked in `data[]`.\n\nPossible codes in each `data[]` item: `200` (cancelled), an error code with the reason if the order cannot be cancelled (for example, because of its current status), `422` if the courier did not confirm the cancellation, and `500` for an internal error.\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 of the orders to cancel. A single ID as a string is also accepted. Required if `orderId` is not sent.", "example": [ "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008", "0199a1b2-8888-7e5f-8a6b-1c2d3e4f0009" ] }, "orderId": { "type": "string", "format": "uuid", "description": "Alternative to `orderIds` to cancel a single order. Ignored if `orderIds` is sent." }, "reason": { "type": "string", "maxLength": 255, "description": "Cancellation reason. It cannot be empty.", "example": "Cliente solicitó cancelación" } } } } } }, "responses": { "200": { "description": "Cancellation processed; check the result of each order in `data[]`", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "description": "Result for each order, in the same order in which they were sent.", "items": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "response_code": { "type": "integer", "description": "Cancellation result for this order (200 if it was cancelled)." }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "requestDate": { "type": "string", "nullable": true, "description": "Cancellation date in a readable format (El Salvador time). Only present if the order was cancelled." } } } } } }, "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": "Invalid parameters. Possible messages: `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": "Neither `orderIds` nor `orderId` was sent, or it is neither a string nor an array.", "value": { "response_code": 400, "response_status": "Error", "response_message": "orderIds debe ser un UUID o un arreglo de UUIDs" } }, "maximo": { "summary": "More than 50 orders were sent.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Máximo 50 órdenes por operación" } }, "uuidInvalido": { "summary": "One of the IDs is not a valid UUID.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Todos los orderIds deben ser UUIDs válidos" } }, "sinMotivo": { "summary": "`reason` is missing, is not a string or is empty.", "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": "Internal error while processing the cancellation, or the body is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al procesar cancelación de órdenes" } } } } } }, "get": { "summary": "Get the shipping label URL", "operationId": "getOrderGuideUrl", "description": "Returns the URL of the shipping label (to view or print) of one of the merchant's orders.", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "OrderId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order ID (`data.ordersId` when it was created).", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } ], "responses": { "200": { "description": "Shipping label retrieved successfully", "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 of the shipping label, to view or print. Depending on the service, it is generated by the courier or by 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": "The OrderId parameter is missing", "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": "The order's shipping label was not found", "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": "Internal error while getting the shipping label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "general": { "summary": "Internal error while getting the shipping label.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener la guía del número de orden" } }, "validacion": { "summary": "Error while validating the order before getting the shipping label.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al validar datos para captura de guía" } } } } } } } } }, "/api/orders/tracking": { "get": { "summary": "Get an order's tracking summary", "operationId": "getOrderTracking", "description": "Returns the summary of one of the merchant's orders: merchant, recipient and order data, its movements (the last one is the current status) and the URLs of the shipping label and the public tracking page. Status codes are interpreted with `GET /api/statusMain`.", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "OrderId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID of the order to track.", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } ], "responses": { "200": { "description": "Order summary found", "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": "The OrderId parameter is missing", "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": "Internal error while getting the order summary", "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" } } } } } } }, "/api/orders/incidents": { "post": { "summary": "Get orders with incidents", "operationId": "getCurrentIncidents", "description": "Returns the merchant's orders that are currently in an incident (for example, recipient not available or wrong address), with their latest incident and the courier.\nIncludes a summary: total orders in incident, distinct couriers and incident types, and the date of the most recent incident.\n\nIt is a query: it does not register incidents. The body is required, but its fields are optional: with `{}` it returns the first page (10 orders).\nTo see every incident of an order, use `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": "Searches by order ID, receipt number, integration reference (`integrationOrderRef`) or courier name." } } }, "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": "Orders in incident retrieved", "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": "Pagination of the orders.", "properties": { "page": { "type": "integer", "description": "Current page." }, "limit": { "type": "integer", "description": "Number of orders per page." }, "total": { "type": "integer", "description": "Total orders in incident that match the search." }, "totalPages": { "type": "integer", "description": "Total pages." }, "hasNext": { "type": "integer", "enum": [ 0, 1 ], "description": "1 if there is a next page." }, "hasPrev": { "type": "integer", "enum": [ 0, 1 ], "description": "1 if there is a previous page." } } }, "summary": { "type": "object", "description": "Summary of the merchant's orders in incident.", "properties": { "totalOrdersInIncident": { "type": "integer", "description": "Total orders in incident." }, "totalDistinctCouriers": { "type": "integer", "description": "Number of distinct couriers with orders in incident." }, "totalDistinctIncidentStatuses": { "type": "integer", "description": "Number of distinct incident types." }, "latestIncidentAt": { "type": "string", "nullable": true, "description": "Date of the most recent incident (`YYYY-MM-DD HH:mm:ss`)." } } }, "orders": { "type": "array", "description": "Orders in incident on the current page, with their latest incident.", "items": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "comprobante": { "type": "string", "nullable": true, "description": "Receipt number of the shipping label." }, "integrationOrderRef": { "type": "string", "nullable": true, "description": "Order number in the merchant's system, if it was sent when creating the order." }, "courier": { "type": "object", "description": "The order's courier.", "properties": { "courierId": { "type": "string", "format": "uuid" }, "courierName": { "type": "string" }, "courierLogo": { "type": "string", "nullable": true, "description": "URL of the courier's logo." } } }, "latestIncident": { "type": "object", "description": "Latest incident reported for the order.", "properties": { "incidentId": { "type": "string", "format": "uuid" }, "statusMainId": { "type": "string", "format": "uuid", "description": "Status ID (catalog `GET /api/statusMain`)." }, "statusDescription": { "type": "string", "description": "Status name, in Spanish." }, "subStatusId": { "type": "string", "format": "uuid", "nullable": true, "description": "Sub-status ID (catalog `GET /api/subStatusMain`)." }, "subStatusDescription": { "type": "string", "nullable": true, "description": "Sub-status name, in Spanish." }, "comment": { "type": "string", "nullable": true, "description": "Comment registered with the incident." }, "reportedAt": { "type": "string", "description": "Date the incident was reported (`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": "Invalid filter or pagination. Message format: `Error en campo \"\": ` (error in field \"\": ).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "search": { "summary": "search is not text or exceeds 250 characters.", "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 is not a positive integer.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"pagination.page\": debe ser un entero positivo" } }, "limit": { "summary": "limit is not a positive integer.", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener las incidencias actuales" } } } } } }, "get": { "summary": "Get an order's incidents (by parameter)", "operationId": "getOrderIncidentsByQuery", "description": "Same as `GET /api/orders/incidents/{ordersId}`, but receives the order ID as the `OrderId` URL parameter.\n", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "OrderId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order ID (`data.ordersId` when creating it).", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } ], "responses": { "200": { "description": "Order's incidents retrieved. Same response as `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": "The OrderId parameter is missing", "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": "Internal error", "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" } } } } } } }, "/api/orders/incidents/{ordersId}": { "get": { "summary": "Get an order's incidents", "operationId": "getOrderIncidents", "description": "Returns the current status of one of the merchant's orders and all its incidents, from the most recent to the oldest.\n`order.isCurrentlyInIncident` indicates whether the order is still in an incident.\n", "tags": [ "Órdenes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "ordersId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Order ID (`data.ordersId` when creating it).", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" } ], "responses": { "200": { "description": "Order's incidents retrieved", "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": "Internal error", "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" } } } } } } }, "/api/open/departments": { "get": { "summary": "Get all departments", "operationId": "getDepartments", "description": "Returns the catalog of departments. The `departmentId` is the value sent to look up municipalities.", "tags": [ "Datos Públicos (Open Data)" ], "responses": { "200": { "description": "Departments retrieved", "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": "Department ID. It is sent as `departmentId` to look up municipalities (`POST /api/open/municipality`)." }, "departmentsCode": { "type": "string", "description": "Department code." }, "departmentName": { "type": "string", "description": "Department name." } } } } } }, "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": "There are no registered departments", "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": "Internal error", "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 } } } } } } }, "/api/open/municipality": { "post": { "summary": "Get municipalities by department", "operationId": "getMunicipalities", "description": "Returns the municipalities of a department. The `municipalityId` is used when creating clients and quoting shipments.", "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 of the department (`GET /api/open/departments`).", "example": "0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004" } } } } } }, "responses": { "200": { "description": "Municipalities retrieved", "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": "Municipality ID. It is used when creating clients and quoting shipments." }, "municipalityCode": { "type": "string", "description": "Municipality code." }, "municipalityName": { "type": "string", "description": "Municipality name." } } } } } }, "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": "The departmentId is missing or is not a valid UUID", "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": "The department does not exist", "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": "Internal error, or the body is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "errorConsulta": { "summary": "Error while querying the municipalities", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error inesperado al obtener los municipios.", "data": null } }, "cuerpoInvalido": { "summary": "The body is not valid JSON", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al capturar los municipios" } } } } } } } } }, "/api/open/typeBranchAddress": { "get": { "summary": "Get branch address types", "operationId": "getBranchAddressTypes", "description": "Returns the address types (house, store, warehouse…). The `TypeBranchAddressId` is sent as `typeBranchAddressId` when creating or updating a pickup address.", "tags": [ "Datos Públicos (Open Data)" ], "responses": { "200": { "description": "Address types retrieved", "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": "Address type ID. It is sent as `typeBranchAddressId` when creating or updating a pickup address." }, "codeBranchAddress": { "type": "string", "description": "Address type code." }, "icon": { "type": "string", "description": "Icon class of the address type (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": "Internal error", "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": [] } } } } } } }, "/api/open/banks": { "get": { "summary": "Get the list of banks", "operationId": "getBanks", "description": "Returns the enabled banks and account types, to register the merchant's bank account.", "tags": [ "Datos Públicos (Open Data)" ], "responses": { "200": { "description": "Banks and account types retrieved", "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": "Enabled banks.", "items": { "type": "object", "properties": { "banksId": { "type": "string", "format": "uuid", "description": "Bank ID." }, "banksName": { "type": "string", "description": "Bank name." }, "swiftCode": { "type": "string", "description": "SWIFT code of the bank." }, "localBankCode": { "type": "string", "description": "Local bank code." } } } }, "typeAccount": { "type": "array", "description": "Bank account types.", "items": { "type": "object", "properties": { "typeAccountId": { "type": "string", "format": "uuid", "description": "Account type ID." }, "accountCode": { "type": "string", "description": "Account type code." }, "accountName": { "type": "string", "description": "Account type name." } } } } } } } }, "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": "Internal error; the message includes the error details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener bancos: ", "data": { "banks": [], "typeAccount": [] } } } } } } } }, "/api/open/typePersonDocument": { "get": { "summary": "Get person document types", "operationId": "getPersonDocumentTypes", "description": "Returns the person types (individual, legal entity…) with the documents each one must provide (DUI, NIT, etc.).", "tags": [ "Datos Públicos (Open Data)" ], "responses": { "200": { "description": "Person types and documents retrieved", "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": "Person type ID." }, "namePerson": { "type": "string", "description": "Person type name." }, "documents": { "type": "array", "description": "Documents this person type must provide.", "items": { "type": "object", "properties": { "documentId": { "type": "integer", "description": "Document ID." }, "documentName": { "type": "string", "description": "Document name." }, "isRequired": { "type": "boolean", "description": "Indicates whether the document is required." } } } } } } } } }, "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": "Internal error; the message includes the error details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener tipos de documentos: ", "data": [] } } } } } } }, "/api/open/trackingComp": { "get": { "summary": "Public order tracking", "operationId": "getPublicTracking", "description": "Returns the status and movement history of an order, without a token.\nIt is the endpoint used by the public tracking page shared with the recipient.\n", "tags": [ "Datos Públicos (Open Data)" ], "parameters": [ { "in": "query", "name": "OrderId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the order.", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" }, { "in": "query", "name": "identifier", "schema": { "type": "string" }, "description": "Optional. Encrypted merchant identifier, included in the tracking links generated by Volao. It does not change the response; you do not need to send it." } ], "responses": { "200": { "description": "Tracking retrieved", "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": "General order data, taken from the most recent movement.", "properties": { "comment": { "type": "string", "nullable": true, "description": "Comment of the most recent movement." }, "creationDate": { "type": "string", "nullable": true, "description": "Order creation date (`YYYY-MM-DD HH:mm:ss`)." }, "branchName": { "type": "string", "nullable": true, "description": "Name of the merchant sending the order." }, "cantPackages": { "type": "integer", "description": "Number of packages." }, "courierName": { "type": "string", "nullable": true, "description": "Courier name." }, "statusMainDescription": { "type": "string", "nullable": true, "description": "Current status of the order, in Spanish." }, "subStatusDescription": { "type": "string", "nullable": true, "description": "Current sub-status of the order, in Spanish." }, "colorMovement": { "type": "string", "nullable": true, "description": "Color of the current status, in hexadecimal." }, "flowGroup": { "type": "string", "nullable": true, "description": "Reserved; currently always `null`." }, "publicNotice": { "type": "object", "description": "Public notice for the order. Currently not used: `hasNotice` is always `false`.", "properties": { "hasNotice": { "type": "boolean" }, "type": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } } }, "recipientName": { "type": "string", "nullable": true, "description": "Recipient name." }, "collectionDate": { "type": "string", "nullable": true, "description": "Pickup date." }, "deliveryDate": { "type": "string", "nullable": true, "description": "Delivery date; `null` if it has not been delivered yet." }, "deliveryMessage": { "type": "string", "nullable": true, "description": "Message about the delivery, if any." }, "alertColor_delivery": { "type": "string", "nullable": true, "description": "Delivery alert color, in hexadecimal." } } }, "geolocation": { "type": "object", "description": "Coordinates of the most recent movement, as text. They are `null` if the movement has no georeference.", "properties": { "latitude": { "type": "string", "nullable": true }, "longitude": { "type": "string", "nullable": true } } }, "resources": { "type": "object", "description": "Resources of the most recent movement.", "properties": { "imgURL": { "type": "string", "nullable": true, "description": "URL of the movement image (for example, the delivery photo)." }, "markedMap": { "type": "string", "nullable": true, "description": "Map with the marked location, if any." } } }, "trackingMovement": { "type": "array", "description": "Order movements, from oldest to newest. The last one is the current status.", "items": { "type": "object", "properties": { "iconMovement": { "type": "string", "nullable": true, "description": "Status icon class (Font Awesome)." }, "colorMovement": { "type": "string", "nullable": true, "description": "Status color, in hexadecimal." }, "statusMainDescription": { "type": "string", "nullable": true, "description": "Status name, in Spanish." }, "flowGroup": { "type": "string", "nullable": true, "description": "Reserved; currently always `null`." }, "dateMovement": { "type": "string", "nullable": true, "description": "Movement date (`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": "The OrderId is missing or is not a valid UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "faltante": { "summary": "OrderId not sent", "value": { "response_code": 400, "response_status": "Error", "response_message": "OrderId es requerido" } }, "invalido": { "summary": "OrderId with an invalid format", "value": { "response_code": 400, "response_status": "Error", "response_message": "OrderId debe ser un UUID válido" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al capturar tracking de envío" } } } } } } }, "/api/courier/serviceMode": { "get": { "summary": "Get service modes", "operationId": "getServiceModes", "description": "Returns the available service modes. The `serviceModeCode` is sent as `typeService` when quoting (`POST /api/courier`).", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Service modes retrieved", "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": "Service mode ID. It can be sent as `serviceTypeId` in `GET /api/courier/services`." }, "serviceModeCode": { "type": "string", "description": "Service mode code. Sent as `typeService` when quoting." }, "serviceModeName": { "type": "string" }, "serviceModeDescription": { "type": "string" }, "requiresCoverageValidation": { "type": "boolean", "description": "The service mode validates the destination's coverage." } } } } } }, "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the service modes.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error inesperado al obtener modos de servicio", "data": [] } }, "general": { "summary": "General server error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener modos de servicio", "data": [] } } } } } } } } }, "/api/courier": { "post": { "summary": "Quote a shipment (available couriers)", "operationId": "quoteShipment", "description": "Returns the shipping services available for a pickup address and a destination, with their cost, commission, estimated dates and agencies.\nTake the `courierServiceId` of the chosen service to create the order (`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": "Pickup address (`GET /api/branchs/branchsAddresses`).", "example": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" }, "municipalityCode": { "type": "string", "format": "uuid", "description": "Destination municipality. Send the `municipalityId` of the recipient client (`GET /api/branchs/branchsClient`) or from `POST /api/open/municipality`.", "example": "0199a1b2-4444-7e5f-8a6b-1c2d3e4f0005" }, "shippingAmount": { "type": "number", "minimum": 0, "description": "Amount to collect from the recipient, as a number (not a string), unsigned and with at most 2 decimals. May be 0.", "example": 10 }, "weight": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Total weight, as a number greater than 0.", "example": 4 }, "cantPackages": { "type": "integer", "minimum": 1, "description": "Optional. Number of packages, an integer greater than 0.", "example": 1 }, "courierName": { "type": "string", "maxLength": 100, "description": "Filters by courier name. Send `\"\"` to see all.", "example": "" }, "typeService": { "type": "string", "description": "Service mode (`serviceModeCode` from `GET /api/courier/serviceMode`).", "example": "NORMAL" } } } } } }, "responses": { "200": { "description": "Available services with their cost", "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": "Invalid data. Message format: `Error en campo \"\": ` (error in field \"\": ).\nFirst it checks that every required field was sent (`es requerido y no fue enviado`, is required and was not sent), then the format of each field; the first error found is reported.\n\nReasons per field (in Spanish):\n- `branchAddressId`, `municipalityCode`: `debe ser un UUID válido` (must be a valid UUID)\n- `shippingAmount`: `debe ser un número válido con hasta dos decimales` (must be a valid number with up to two decimals)\n- `weight`: `debe ser un número válido mayor a 0` (must be a valid number greater than 0)\n- `cantPackages`: `debe ser un número entero válido mayor a 0` (must be a valid integer greater than 0)\n- `courierName`: `es texto, puede ir vacío, no debe exceder 100 caracteres` (is text, may be empty, must not exceed 100 characters)\n- `typeService`: `debe ser un string válido` (must be a valid string)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "faltante": { "summary": "Required field not sent", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"typeService\": es requerido y no fue enviado" } }, "invalido": { "summary": "Destination with an invalid format", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"municipalityCode\": debe ser un UUID válido" } }, "monto": { "summary": "Negative amount, sent as a string or with more than 2 decimals", "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": "Weight equal to 0, negative or sent as a string", "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": "Number of packages that is not an integer greater than 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 is not a string or exceeds 100 characters", "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": "Internal error. A 500 is also returned when the body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the services.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener couriers", "data": [] } }, "general": { "summary": "General error, for example a body that is not valid JSON.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los couriers: " } } } } } } } }, "get": { "summary": "Get couriers by service", "operationId": "getCouriersByService", "description": "Returns the services of all active couriers, grouped by service code, with their limits, prices and delivery conditions.\nThe groups come in alphabetical order, with the agency services last.\n", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Services grouped by service code. Each key of `data` is a service code.", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the services.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error inesperado al obtener los couriers por servicio", "data": {} } }, "general": { "summary": "General server error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los couriers" } } } } } } } } }, "/api/courier/coverage": { "get": { "summary": "Get the coverage of a courier service", "operationId": "getCourierCoverage", "description": "Returns the departments, municipalities and districts covered by a courier service, with the coverage days of each district.", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "courierServiceId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Courier service (`courierServiceId` from the quote or from `GET /api/courier`).", "example": "019f88a7-40d5-75b5-add9-87e652d9ba69" } ], "responses": { "200": { "description": "Coverage retrieved", "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": "Days of the week on which the service covers the district." } } } } } } } } } } } } } } }, "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": "The courierServiceId is missing or is not a valid UUID", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the coverage.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener la cobertura del courier.", "data": [] } }, "general": { "summary": "General server error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener cobertura del courier" } } } } } } } } }, "/api/courier/agencies": { "get": { "summary": "Get a courier's agencies", "operationId": "getCourierAgencies", "description": "Returns the agencies of a courier, for services that deliver or pick up at an agency. The `agencyId` is sent in `courier.agencias` when creating the order.", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "courierId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Courier (`courierId` from the quote or from `GET /api/courier`).", "example": "019f81b1-a481-77d5-be76-6c74b42c1e59" }, { "in": "query", "name": "searchText", "schema": { "type": "string" }, "description": "Optional. Filters the agencies by text." } ], "responses": { "200": { "description": "Agencies retrieved", "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": "The courierId is missing or is not a valid UUID", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the agencies.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener agencias del courier" } }, "general": { "summary": "General server error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error interno del servidor al obtener agencias del courier" } } } } } } } } }, "/api/courier/generalRates": { "get": { "summary": "Get general courier rates", "operationId": "getCourierGeneralRates", "description": "Returns the general rates of the couriers available to the authenticated merchant, per service.", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Rates retrieved", "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 of the courier's logo." }, "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": "Shipping service." }, "serviceTypeId": { "type": "string", "format": "uuid" }, "serviceTypeName": { "type": "string" }, "rate": { "type": "number", "description": "General rate of the service." } } } } } } } } } } } }, "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the rates.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error al obtener tarifas generales de couriers", "data": [] } }, "general": { "summary": "General server error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener tarifas generales del courier" } } } } } } } } }, "/api/courier/services": { "get": { "summary": "Get couriers by service type", "operationId": "getCouriersByServiceType", "description": "Returns the active couriers' services grouped by service type (for example, `NORMAL` or `PRIORITY`).\nFor each service: the courier, its limits (weight, dimensions, maximum cash amount, pickup cut-off time), prices, delivery conditions and whether it works with agencies.\n\nUse it to show the shipping options and their conditions. For the exact price of a shipment, quote with `POST /api/courier`.\n", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "serviceTypeId", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional. Returns only the services of this service type (`serviceModeId` from `GET /api/courier/serviceMode`). Ignored if sent empty." } ], "responses": { "200": { "description": "Couriers grouped by service type. Each key of `data` is the service type code.", "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 is not a valid UUID", "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": "No active courier offers the given service type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the services.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error inesperado al obtener los couriers por tipo de servicio", "data": {} } }, "general": { "summary": "General server error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los couriers por tipo de servicio" } } } } } } } } }, "/api/courier/deliveryPromise": { "get": { "summary": "Get delivery promises", "operationId": "getDeliveryPromises", "description": "Returns the catalog of delivery promises: the time each type of service commits to deliver in (for example, next-day delivery).", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Delivery promises retrieved", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the delivery promises.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error inesperado al obtener promesas de entrega", "data": [] } }, "general": { "summary": "General server error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener promesas de entrega", "data": [] } } } } } } } } }, "/api/courier/coverage/operational": { "get": { "summary": "Get a service's operational coverage", "operationId": "getOperationalCoverage", "description": "Returns, by department and municipality, where a shipping service operates: whether it has pickup and delivery coverage, the days it operates and the pickup hours.\nUse it to know before quoting whether a service reaches the client's municipality.\n", "tags": [ "Mensajerías (Couriers)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "courierServiceId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Shipping service (`courierServiceId` from `POST /api/courier` or from `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": "Coverage type: pickup, delivery or both. Case-insensitive." }, { "in": "query", "name": "departmentsJson", "required": false, "schema": { "type": "string" }, "description": "Optional. JSON array with the UUIDs of the departments to query (`departmentId` from `GET /api/open/departments`).", "example": "[\"0199a1b2-3333-7e5f-8a6b-1c2d3e4f0004\"]" }, { "in": "query", "name": "searchText", "required": false, "schema": { "type": "string" }, "description": "Optional. Text to search in the department and municipality names." } ], "responses": { "200": { "description": "Operational coverage retrieved", "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": "Requested coverage type." }, "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": "The service picks up in the municipality." }, "hasDeliveryCoverage": { "type": "boolean", "description": "The service delivers in the municipality." }, "daysCoverage": { "type": "string", "description": "Days on which it operates, separated by commas (`L`, `M`, `Mi`, `J`, `V`, `S`, `D`: Monday to Sunday, in Spanish)." }, "pickupStartTime": { "type": "string", "nullable": true, "description": "Start of the pickup time window." }, "pickupEndTime": { "type": "string", "nullable": true, "description": "End of the pickup time window." } } } } } } } } } } } } } }, "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": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "courierServiceId": { "summary": "courierServiceId is missing or is not a valid UUID.", "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 is not ALL, PICKUP or 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 is not a JSON array of strings.", "value": { "response_code": 400, "response_status": "Error", "response_message": "El parámetro departmentsJson debe ser un arreglo de strings válido" } }, "departmentsJsonFormato": { "summary": "departmentsJson is not valid JSON.", "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": "The service does not exist or is not active", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the operational coverage.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener las coberturas operativas del courier.", "data": [] } }, "general": { "summary": "General server error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener las coberturas operativas del courier" } } } } } } } } }, "/api/branchs/branchsAddresses": { "get": { "summary": "Get branch addresses", "operationId": "getBranchAddresses", "description": "Returns the merchant's pickup addresses. Send `-1` to get all of them, or the UUID of an address to get only that one.", "tags": [ "Direcciones de Sucursales (Branch Addresses)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "branchAddressId", "required": true, "schema": { "type": "string" }, "description": "`-1` for all addresses, or the UUID of an address.", "example": "-1" } ], "responses": { "200": { "description": "Addresses retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "description": "The merchant's addresses (only one if the UUID of an address was sent).", "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": "The branchAddressId parameter is missing", "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": "The merchant has no addresses or the address does not exist. The message includes the value sent in `branchAddressId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "direccion": { "summary": "The address does not exist or does not belong to the merchant.", "value": { "response_code": 404, "response_status": "Error", "response_message": "No se encontró dirección con branchAddressId 0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b", "data": [] } }, "sinDirecciones": { "summary": "`-1` was sent and the merchant has no addresses.", "value": { "response_code": 404, "response_status": "Error", "response_message": "No se encontró dirección con branchAddressId -1", "data": [] } } } } } }, "500": { "description": "Internal error (for example, a `branchAddressId` that is neither `-1` nor a valid UUID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al capturar las direcciones: ", "data": [] } } } } } }, "post": { "summary": "Create a branch address", "operationId": "createBranchAddress", "description": "Registers a new pickup address for the merchant. The address type comes from `GET /api/open/typeBranchAddress` and the municipality from `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": "Address registered", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchAddressId": { "type": "string", "format": "uuid", "description": "ID of the created address. Used as `branchInfo.branchAddressId` when creating an order." } } } ] }, "example": { "response_code": 201, "response_status": "success", "response_message": "Dirección registrada correctamente.", "branchAddressId": "0199a1b2-3c4d-7e5f-8a6b-1c2d3e4f5a6b" } } } }, "400": { "description": "Validation errors. The API joins all errors into a single message, separated by `;`.\nPossible messages per field (in Spanish): `es requerido` (is required), `debe ser una cadena` (must be a string), `debe tener al menos N caracteres` (must have at least N characters), `no debe exceder los N caracteres` (must not exceed N characters), `tiene un formato inválido` (has an invalid format).\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": "An active address with the same name already exists", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "registro": { "summary": "Error while saving the address.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al crear dirección de recolecta: " } }, "general": { "summary": "General error (for example, the body is not valid JSON).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al capturar las direcciones de la sucursal" } } } } } } } }, "put": { "summary": "Update a branch address", "operationId": "updateBranchAddress", "description": "Updates an existing pickup address. Send all the creation fields plus the `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": "Address updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSuccessResponse" }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Dirección actualizada correctamente" } } } }, "400": { "description": "Validation errors (same format as on creation; includes `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": "Business rule (for example, duplicate name)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 409, "response_status": "Error", "response_message": "" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "actualizacion": { "summary": "Error while saving the changes.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar dirección de recolecta: " } }, "general": { "summary": "General error (for example, the body is not valid JSON).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar la dirección de recolecta" } } } } } } } }, "delete": { "summary": "Delete a branch address", "operationId": "deleteBranchAddress", "description": "Deletes a pickup address of the merchant. The ID is sent in the 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": "Address deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSuccessResponse" }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Dirección eliminada correctamente" } } } }, "400": { "description": "The branchAddressId is missing or is not a string", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "eliminacion": { "summary": "Error while deleting the address.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al eliminar la dirección de recolecta: " } }, "general": { "summary": "General error (for example, the body is not valid JSON).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al eliminar la dirección de recolección." } } } } } } } }, "patch": { "summary": "Set the default address", "operationId": "setDefaultBranchAddress", "description": "Marks an address as the merchant's default (`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": "Default address updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchSuccessResponse" }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Dirección predeterminada establecida correctamente" } } } }, "400": { "description": "The branchAddressId is missing or is not a string", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "predeterminada": { "summary": "Error while saving the default address.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al establecer la dirección predeterminada: " } }, "general": { "summary": "General error (for example, the body is not valid JSON).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al establecer la dirección predeterminada." } } } } } } } } }, "/api/branchs/branchsClient": { "get": { "summary": "Get branch clients", "operationId": "getBranchClients", "description": "Returns the merchant's clients/recipients, with favorites first. Allows getting a single client or filtering by favorites.", "tags": [ "Clientes de Sucursales (Branch Clients)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "branchsClientId", "schema": { "type": "string", "format": "uuid" }, "description": "Optional. UUID of a client to get only that record. If it is missing or is not a valid UUID, it is ignored and all clients are returned." }, { "in": "query", "name": "favorite", "schema": { "type": "string", "enum": [ "-1", "0", "1", "true" ], "default": "0" }, "description": "`-1` = all, `1` or `true` = favorites only, `0` = non-favorites only. If omitted or set to any other value, `0` is used: send `-1` to get all of them.", "example": "-1" } ], "responses": { "200": { "description": "Clients retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchClientListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the clients.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener clientes de la sucursal", "data": [] } }, "general": { "summary": "General error.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener clientes" } } } } } } } }, "post": { "summary": "Register a new client", "operationId": "createBranchClient", "description": "Creates a new client/recipient linked to the merchant.", "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": "Optional. `true` saves the client in the merchant's address book. Defaults to `false`. `1` and `0` are also accepted; any other value returns 400 (`solo puede ser 0 o 1`, can only be 0 or 1).", "example": true } } } ] } } } }, "responses": { "201": { "description": "Client registered", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "ID of the registered client. Used as `branchInfo.branchsClientId` when creating an order." } } } ] }, "example": { "response_code": 201, "response_status": "Success", "response_message": "Cliente procesado correctamente", "branchsClientId": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003" } } } }, "400": { "description": "Validation errors. The API joins all errors into a single message, separated by `;`.\nPossible messages per field (in Spanish): `es requerido` (is required), `debe ser una cadena` (must be a string), `debe tener al menos N caracteres` (must have at least N characters), `no debe exceder los N caracteres` (must not exceed N characters), `tiene un formato inválido` (has an invalid format).\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": "Internal error while creating the client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al crear el cliente: " } } } } } }, "put": { "summary": "Update client data", "operationId": "updateBranchClient", "description": "Updates an existing client's information. Send all the fields plus the `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": "Client updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "ID of the updated client. It may be missing from the response." } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Cliente actualizado correctamente" } } } }, "400": { "description": "Validation errors (same format as on creation; includes `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": "Internal error while updating the client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar el cliente: " } } } } } }, "delete": { "summary": "Delete a client", "operationId": "deleteBranchClient", "description": "Deletes a client of the merchant. The ID is sent in the 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": "Client deleted", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "ID of the deleted client. It may be missing from the response." } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Cliente eliminado correctamente" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "The branchsClientId is missing or is not a valid UUID", "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": "Internal error while deleting the client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al eliminar el cliente: " } } } } } }, "patch": { "summary": "Mark or unmark a favorite client", "operationId": "toggleBranchClientFavorite", "description": "Marks a client as a favorite or removes that mark.", "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` or `true` to mark it as a favorite; `0` or `false` to remove it.", "example": 1 } } } } } }, "responses": { "200": { "description": "Favorite status updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "branchsClientId": { "type": "string", "format": "uuid", "description": "Client ID." }, "favorite": { "type": "boolean", "description": "`true` if the client was marked as a favorite; `false` if the mark was removed." } } } ] }, "example": { "response_code": 200, "response_status": "Success", "response_message": "Cliente marcado como favorito", "branchsClientId": "0199a1b2-2222-7e5f-8a6b-1c2d3e4f0003", "favorite": true } } } }, "400": { "description": "A parameter is missing or has an invalid value", "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": "Internal error while updating the favorite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al actualizar favorito del cliente: " } } } } } } }, "/api/branchs/branchsClient/search": { "get": { "summary": "Search branch clients", "operationId": "searchBranchClients", "description": "Searches the merchant's clients by text (name, phone, email…), with an optional favorites filter. Returns favorites first.", "tags": [ "Clientes de Sucursales (Branch Clients)" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Optional. Text to search for.", "example": "Cliente Prueba" }, { "in": "query", "name": "favorite", "schema": { "type": "string", "enum": [ "-1", "0", "1", "true" ], "default": "0" }, "description": "`-1` = all, `1` or `true` = favorites only, `0` = non-favorites only. If omitted or set to any other value, `0` is used: send `-1` to search all of them.", "example": "-1" } ], "responses": { "200": { "description": "Search completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchClientListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the clients.", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al buscar clientes de la sucursal", "data": [] } }, "general": { "summary": "General error.", "value": { "response_code": 500, "response_status": "error", "response_message": "Error al buscar clientes" } } } } } } } } }, "/api/branchs/history/orders": { "post": { "summary": "Get order history", "operationId": "getOrdersHistory", "description": "Returns the merchant's orders with their current status, courier and recipient, plus the period's totals (orders, in route, completed and cancelled).\nEach order includes its public tracking URL in `tracking.URLtracking`.\n\nThe body is required (without a body it returns 500), but all its fields are optional: with `{}` it returns the first page (20 orders), from the most recent to the oldest.\nWith `export: 1` it also generates an Excel file with all the results and returns its URL in `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": "All filters are optional and can be combined.", "properties": { "dateFrom": { "type": "string", "format": "date", "example": "2026-10-01" }, "dateTo": { "type": "string", "format": "date", "description": "Cannot be earlier than `dateFrom`.", "example": "2026-10-31" }, "ordersId": { "type": "string", "format": "uuid", "description": "Order ID (`data.ordersId` when creating it)." }, "comprobante": { "type": "string", "maxLength": 120, "description": "Order's receipt number." }, "statusMainId": { "type": "string", "format": "uuid", "description": "Order's current status (`statusMainId` from `GET /api/statusMain`)." }, "courierServiceId": { "type": "string", "format": "uuid", "description": "Shipping service (`courierServiceId` from `POST /api/courier`)." }, "branchsClientId": { "type": "string", "format": "uuid", "description": "Recipient client (`GET /api/branchs/branchsClient`)." }, "nomDestinatario": { "type": "string", "maxLength": 250, "description": "Recipient name." }, "departmentId": { "type": "string", "format": "uuid", "description": "Delivery department (`GET /api/open/departments`)." }, "municipalityId": { "type": "string", "format": "uuid", "description": "Delivery municipality (`POST /api/open/municipality`)." }, "onDelivery": { "type": "boolean", "description": "Orders with cash on delivery (also accepts 0 and 1)." }, "paidShipping": { "type": "boolean", "description": "Orders whose shipping is already paid (also accepts 0 and 1)." }, "favoriteClient": { "type": "boolean", "description": "Orders of clients marked as favorites (also accepts 0 and 1)." }, "branchsClientStatus": { "type": "boolean", "description": "Orders of active clients (also accepts 0 and 1)." }, "consignmentValue": { "type": "number", "minimum": 0, "description": "Amount collected from the recipient, with at most 2 decimals." }, "deliveryCost": { "type": "number", "minimum": 0, "description": "Shipping cost, with at most 2 decimals." } } }, "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` also generates an Excel file with all the results (not paginated)." } } }, "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": "Order history retrieved. The orders are in `data.data` and the pagination in `data.pagination`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "description": "History result.", "properties": { "pagination": { "$ref": "#/components/schemas/HistoryPagination" }, "totals": { "type": "object", "description": "Totals for the queried period.", "properties": { "totalOrders": { "description": "Orders in the period.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "inRoute": { "description": "Orders in route.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "completed": { "description": "Completed orders.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "cancelled": { "description": "Cancelled orders.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] } } }, "data": { "type": "array", "description": "Orders on the page.", "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": "Invalid filter, sorting or pagination. Only the first error found is reported, with the format `Error en campo \"\": ` (error in field \"\": ); the field name has no `filters.` prefix.\nPossible reasons (in Spanish): `debe ser 0 o 1` (must be 0 or 1; `export`), `debe ser formato YYYY-MM-DD válido` (must be a valid YYYY-MM-DD date), `dateFrom no puede ser mayor a dateTo` (dateFrom cannot be later than dateTo; field `dateRange`), `debe ser un UUID válido` (must be a valid UUID), `debe ser 0, 1, true o false` (must be 0, 1, true or false), `decimal inválido (máx 2 decimales)` (invalid decimal, max 2 decimals), `texto inválido` (invalid text; `comprobante`, `nomDestinatario`), `valor inválido` (invalid value; `pagination.page`, `pagination.limit`), `campo inválido` (invalid field; `order.by`) and `debe ser ASC o DESC` (must be ASC or DESC; `order.direction`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "fecha": { "summary": "Date with an invalid format.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"dateFrom\": debe ser formato YYYY-MM-DD válido" } }, "booleano": { "summary": "A yes/no filter has a value that is not allowed.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"onDelivery\": debe ser 0, 1, true o false" } }, "monto": { "summary": "Amount with more than 2 decimals or negative.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"deliveryCost\": decimal inválido (máx 2 decimales)" } }, "paginacion": { "summary": "page or limit is not an integer greater than 0.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"pagination.limit\": valor inválido" } }, "rango": { "summary": "dateFrom is later than dateTo.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"dateRange\": dateFrom no puede ser mayor a dateTo" } }, "uuid": { "summary": "An ID filter is not a valid UUID.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"statusMainId\": debe ser un UUID válido" } }, "orden": { "summary": "Sort field not allowed.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"order.by\": campo inválido" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "consulta": { "summary": "Error while querying the history.", "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": "General error (for example, no body or a body that is not valid JSON).", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener historial de órdenes" } } } } } } } } }, "/api/branchs/history/transactionsAndMovements": { "post": { "summary": "Get transaction and movement history", "operationId": "getTransactionsAndMovementsHistory", "description": "Returns the merchant's transactions (top-ups and payments) with their related balance movements: shipping charges, commissions, refunds and benefits.\nEach transaction includes the payment method, the wallet summary (previous balance, amount used and remaining balance) and the list of movements with their order, courier and service.\nBenefit movements (`movementIsBenefit: true`) include their details in `benefit`; in the other movements `benefit` is `null`.\n\nEvery body field is optional: without a body it returns the first page (20 transactions), from the most recent to the oldest.\nWith `export: 1` it also generates an Excel file with all the results and returns its URL in `export.URLDataExcel`.\n", "tags": [ "Historial de Sucursales (Branch History)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "description": "All filters are optional and can be combined.", "properties": { "dateFrom": { "type": "string", "format": "date", "example": "2026-10-01" }, "dateTo": { "type": "string", "format": "date", "description": "Cannot be earlier than `dateFrom`.", "example": "2026-10-31" }, "transactionId": { "type": "string", "format": "uuid", "description": "Transaction ID." }, "transactionAmount": { "type": "number", "minimum": 0, "description": "Transaction amount." }, "transactionGatewayId": { "type": "string", "format": "uuid", "description": "Transaction's payment gateway." }, "gatewayTransactionReference": { "type": "string", "maxLength": 150, "description": "Transaction reference in the payment gateway." }, "internalTransactionReference": { "type": "string", "maxLength": 150, "description": "Internal transaction reference." }, "typeCard": { "type": "string", "maxLength": 20, "description": "Card type (for example, `VISA`)." }, "cardOwner": { "type": "string", "maxLength": 120, "description": "Cardholder." }, "cardLast4": { "type": "string", "pattern": "^\\d{4}$", "description": "Last 4 digits of the card.", "example": "4242" }, "movementReasonId": { "type": "string", "format": "uuid", "description": "Movement reason (`GET /api/movementReason`)." }, "courierServiceId": { "type": "string", "format": "uuid", "description": "Movement's shipping service." }, "ordersId": { "type": "string", "format": "uuid", "description": "Movement's order (`data.ordersId` when creating it)." }, "comprobante": { "type": "string", "maxLength": 100, "description": "Order's receipt number." }, "deliveryCost": { "type": "number", "minimum": 0, "description": "Movement's shipping cost." }, "onlyFilteredMovements": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "With `1`, each transaction shows only the movements that match the filters; with `0`, all its movements." } } }, "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` also generates an Excel file with all the results (not paginated)." } } }, "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": "Transactions and movements retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/HistoryPagination" }, "totals": { "type": "object", "description": "Totals for the queried period.", "properties": { "totalTransactions": { "description": "Number of transactions in the period.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "totalVolume": { "description": "Total amount of the transactions in the period.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "totalBenefits": { "type": "object", "description": "Benefits in the period.", "properties": { "value": { "type": "number", "description": "Value for the period." } } } } }, "data": { "type": "array", "description": "Transactions on the page.", "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": "Invalid filter, sorting or pagination. Only the first error found is reported, with the format `Error en campo \"\": ` (error in field \"\": ).\nPossible reasons (in Spanish): `debe ser 0 o 1` (must be 0 or 1; `export` and `filters.onlyFilteredMovements`, as a number), `debe ser un UUID válido` (must be a valid UUID), `número inválido` (invalid number; negative amounts or values that are not numbers), `texto inválido (máx N caracteres)` (invalid text, max N characters), `debe contener exactamente 4 dígitos` (must contain exactly 4 digits), `debe ser una fecha válida (YYYY-MM-DD)` (must be a valid date), `dateFrom no puede ser mayor a dateTo` (dateFrom cannot be later than dateTo), `debe ser un entero mayor a 0` (must be an integer greater than 0; `pagination.page`), `debe ser un entero entre 1 y 50` (must be an integer between 1 and 50; `pagination.limit`) and `debe ser ASC o DESC` (must be ASC or DESC; `order.direction`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "uuid": { "summary": "An ID filter is not a valid UUID.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.ordersId\": debe ser un UUID válido" } }, "monto": { "summary": "An amount is negative or is not a number.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.transactionAmount\": número inválido" } }, "tarjeta": { "summary": "cardLast4 does not have 4 digits.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.cardLast4\": debe contener exactamente 4 dígitos" } }, "rango": { "summary": "dateFrom is later than 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 outside the allowed range.", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los movimientos del comercio" } } } } } } }, "/api/branchs/history/benefits": { "post": { "summary": "Get benefit history", "operationId": "getBenefitsHistory", "description": "Returns the benefits the merchant received, with their order, courier and the balance movement they generated. For example, the shipping cashback (`CBE`): a percentage of the shipping cost returned to the balance when the order is delivered, according to the merchant's subscription tier.\nIncludes the period's totals: number and amount of benefits, current and previous month amount, reversed amount and a breakdown by type.\n\nEvery body field is optional: without a body it returns the first page (20 benefits), from the most recent to the oldest.\nWith `export: 1` it also generates an Excel file with all the results and returns its URL in `export.URLDataExcel`.\n", "tags": [ "Historial de Sucursales (Branch History)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "description": "All filters are optional and can be combined.", "properties": { "dateFrom": { "type": "string", "format": "date", "example": "2026-10-01" }, "dateTo": { "type": "string", "format": "date", "description": "Cannot be earlier than `dateFrom`.", "example": "2026-10-31" }, "movementCode": { "type": "string", "maxLength": 20, "description": "Benefit type (`benefit.movementCode` from the response)." }, "status": { "type": "string", "enum": [ "APPLIED", "REVERSED" ], "description": "Benefit status, applied or reversed." }, "subscriptionTierId": { "type": "string", "format": "uuid", "description": "Subscription tier under which the benefit was granted." }, "ordersId": { "type": "string", "format": "uuid", "description": "Order that generated the benefit (`data.ordersId` when creating it)." }, "comprobante": { "type": "string", "maxLength": 100, "description": "Order's receipt number." } } }, "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` also generates an Excel file with all the results (not paginated)." } } }, "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": "Benefits retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/HistoryPagination" }, "totals": { "type": "object", "description": "Totals for the queried period.", "properties": { "totalBenefits": { "description": "Number of benefits in the period.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "totalAmount": { "description": "Total amount of benefits in the period.", "allOf": [ { "$ref": "#/components/schemas/HistoryMetric" } ] }, "currentMonthAmount": { "type": "number", "description": "Amount of benefits in the current month." }, "previousMonthAmount": { "type": "number", "description": "Amount of benefits in the previous month." }, "reversedAmount": { "type": "number", "description": "Amount of reversed benefits." }, "byType": { "type": "array", "description": "Breakdown by benefit type.", "items": { "type": "object", "properties": { "movementCode": { "type": "string", "description": "Benefit type code." }, "movementName": { "type": "string", "description": "Benefit type name." }, "count": { "type": "integer", "description": "Number of benefits of this type." }, "amount": { "type": "number", "description": "Total amount of this type." } } } } } }, "data": { "type": "array", "description": "Benefits on the page.", "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": "Invalid filter, sorting or pagination. Only the first error found is reported, with the format `Error en campo \"\": ` (error in field \"\": ).\nPossible reasons (in Spanish): `debe ser 0 o 1` (must be 0 or 1; `export`, as a number), `debe ser un código de texto válido (máx 20 caracteres)` (must be a valid text code, max 20 characters; `filters.movementCode`), `debe ser un UUID válido` (must be a valid UUID), `texto inválido (máx N caracteres)` (invalid text, max N characters; `filters.comprobante`, `filters.status`), `debe ser una fecha válida (YYYY-MM-DD)` (must be a valid date), `dateFrom no puede ser mayor a dateTo` (dateFrom cannot be later than dateTo), `debe ser un entero mayor a 0` (must be an integer greater than 0; `pagination.page`), `debe ser un entero entre 1 y 50` (must be an integer between 1 and 50; `pagination.limit`) and `debe ser ASC o DESC` (must be ASC or DESC; `order.direction`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "uuid": { "summary": "An ID filter is not a valid UUID.", "value": { "response_code": 400, "response_status": "Error", "response_message": "Error en campo \"filters.ordersId\": debe ser un UUID válido" } }, "codigo": { "summary": "movementCode is empty or has more than 20 characters.", "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 is later than 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 outside the allowed range.", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener los beneficios del comercio" } } } } } } }, "/api/branchs/history/settlements": { "post": { "summary": "Get settlement history", "operationId": "getSettlementsHistory", "description": "Returns the merchant's settlements (statements): the payment to the merchant of what was collected on delivery, minus the shipping cost and the commission.\nEach statement includes the bank account where it was deposited, its totals and the orders it settles.\n\nEvery body field is optional: without a body it returns the first page (20 statements), from the most recent to the oldest.\nWith `export: 1` it also generates an Excel file with all the results and returns its URL in `export.URLDataExcel`.\n", "tags": [ "Historial de Sucursales (Branch History)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "description": "All filters are optional and can be combined.", "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Settlement that includes this order (`data.ordersId` when creating it).", "example": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008" }, "comprobante": { "type": "string", "description": "Settlement that includes the order with this receipt number.", "example": "29137811" }, "expandActaByOrderSearch": { "type": "boolean", "description": "When searching by `orderId` or `comprobante`, `true` returns the statement with all its orders, not only the searched one. `1` and `0` are also accepted.", "example": true }, "dateType": { "type": "string", "enum": [ "deliveryDate", "settlementDate" ], "description": "Date the `dateFrom`–`dateTo` range applies to: the order's delivery date or the settlement date.", "example": "settlementDate" }, "dateFrom": { "type": "string", "format": "date", "description": "Sent together with `dateTo`.", "example": "2026-10-01" }, "dateTo": { "type": "string", "format": "date", "description": "Sent together with `dateFrom`.", "example": "2026-10-31" }, "codActa": { "type": "integer", "description": "Settlement statement number.", "example": 1024 }, "titular": { "type": "string", "description": "Bank account holder.", "example": "Comercio Prueba" }, "bankId": { "type": "string", "format": "uuid", "description": "Account's bank (`banks[].banksId` from `GET /api/open/banks`)." }, "typeAccountId": { "type": "string", "format": "uuid", "description": "Bank account type (`typeAccount[].typeAccountId` from `GET /api/open/banks`)." }, "accountNumber": { "type": "string", "description": "Bank account number.", "example": "0000000000" }, "consignmentValue": { "type": "number", "description": "Amount collected from the recipient." }, "deliveryCost": { "type": "number", "description": "Shipping cost." }, "commission": { "type": "number", "description": "Commission charged." }, "settledAmount": { "type": "number", "description": "Amount settled to the merchant." } } }, "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` also generates an Excel file with all the results (not paginated)." } } }, "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": "Settlement history retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BranchSuccessResponse" }, { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/HistoryPagination" }, "data": { "type": "array", "description": "Settlement statements on the page.", "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": "Invalid filters, sorting or pagination. Only the first error found is reported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "orderBy": { "summary": "Sort field not allowed.", "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": "Sort direction not allowed.", "value": { "response_code": 400, "response_status": "Error", "response_message": "orderDirection debe ser ASC o DESC" } }, "page": { "summary": "page is not an integer greater than 0.", "value": { "response_code": 400, "response_status": "Error", "response_message": "page debe ser un entero mayor a 0" } }, "fechas": { "summary": "dateFrom and dateTo must be sent together.", "value": { "response_code": 400, "response_status": "Error", "response_message": "dateFrom y dateTo deben enviarse juntos" } }, "dateType": { "summary": "dateType value not allowed.", "value": { "response_code": 400, "response_status": "Error", "response_message": "dateType inválido. Valores permitidos: deliveryDate, settlementDate" } }, "uuid": { "summary": "orderId, bankId or typeAccountId is not a valid UUID.", "value": { "response_code": 400, "response_status": "Error", "response_message": "orderId debe ser un UUID válido" } }, "limit": { "summary": "limit outside the allowed range.", "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": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "Error", "response_message": "Error al obtener el historial de liquidaciones" } } } } } } }, "/api/branchs/settlements/liquidationActs": { "post": { "summary": "Get a settlement detail", "operationId": "getSettlementDetail", "description": "Returns the detail of one of the merchant's settlement statements: the bank account where it was deposited, the orders it includes with their amounts, and the totals.\nFor each order: the amount collected (`montoEnvio`), the shipping cost (`costoEnvio`), the commission (`cme`) and the amount settled to the merchant (`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 of the settlement statement. It is not the statement number (`acta.codActa`) returned by the settlement history.", "example": "0199a1b2-1919-7e5f-8a6b-1c2d3e4f0081" } } } } } }, "responses": { "200": { "description": "Settlement detail retrieved", "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 is missing or is not a valid UUID", "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": "Internal error", "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" } } } } } } }, "/api/batchShipping": { "get": { "summary": "Generate the Excel template for batch shipments", "operationId": "getBatchShippingTemplate", "description": "Generates the Excel template (.xlsx) configured for the merchant and returns a temporary URL to download it. Fill in one row per order and upload it with `POST /api/batchShipping`.\n\nThe template has drop-down lists with the merchant's pickup addresses, the couriers with their services and service types, and the departments and municipalities. It has room for 499 orders (rows 2 to 500).\n\nThe URL is public (no token required) and the file is temporary: download it as soon as you receive it.\n", "tags": [ "Operaciones Masivas (Batch Operations)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Template generated", "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": "Temporary URL of the .xlsx file." } } } } }, "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 while generating the template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "error", "response_message": "Error al generar la plantilla Excel" } } } } } }, "post": { "summary": "Create batch orders (Excel upload)", "operationId": "createBatchOrders", "description": "Creates several orders from the filled-in Excel template (`GET /api/batchShipping`). Each row is validated and processed separately.\n**The response is 200 even if some rows fail:** check `isValid` and `response_message` of each row in `data[]`.\n`codeExcel` is the row number in the Excel file, to locate the errors.\n\n**How to send the file**\n\n- Send it as `multipart/form-data` in the `file` field, with the Excel content type\n (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`). If the file arrives with another type\n (for example `application/octet-stream`), it is rejected. With curl: `-F \"file=@plantilla.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\"`.\n- Only the .xlsx format is read. An .xls file (old format) is rejected with `El archivo no pudo ser leído como Excel`.\n- The first sheet is read; row 1 holds the headers and empty rows are skipped.\n- Fill in the template in Excel or another spreadsheet app that saves formula results: the hidden columns\n calculate the IDs (address, municipality, service) from what you pick in the lists. If the file is generated\n with a library that does not calculate formulas, the rows fail.\n\n**Columns and per-row validations**\n\nEach row is validated in this order and only the first error is reported:\n\n| Column | Data | Rule | Message if it fails |\n| --- | --- | --- | --- |\n| B | Client name | Required, 2 to 150 characters | `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 | Client phone | Required, 7 to 9 characters: digits and, optionally, a hyphen | `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 | Shipping address | Required, 5 to 250 characters | `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 | Department and municipality | Picked from the list | `No se pudo identificar el municipio del cliente. Verifica que el municipio exista y esté correctamente seleccionado` |\n| A | Pickup address | Picked from the list | `Seleccione una dirección de recolección válida` |\n| I | Courier | Required | `Seleccione un courier válido` |\n| J | Service | Required | `Seleccione un servicio` |\n| K | Service type | Required; the courier, service and type combination must exist in the list | `Seleccione un tipo de servicio`, `La combinación de courier, servicio y tipo de servicio no es válida` |\n| L | Delivery type | `Entrega Normal (Sin Cobro)` (normal delivery, no collection) or `Cobro Contra Entrega` (cash on delivery) | `Seleccione un tipo de entrega válido` |\n| N | Product description | Required, up to 150 characters | `Ingrese una descripción del producto`, `La descripción del producto es demasiado larga` |\n| H | Weight (lb) | Number greater than 0 | `Ingrese un peso válido` |\n| G | Number of packages | Integer from 1 to 50 | `Ingrese una cantidad de paquetes válida` |\n| M | Amount to collect | Greater than 0 with `Cobro Contra Entrega`; without collection, empty or greater than or equal to 0 | `Ingrese un monto a cobrar válido, por ejemplo 15.50`, `El monto a cobrar no puede ser negativo` |\n| O | Comments | Optional, up to 300 characters | `Los comentarios son demasiado largos` |\n\n**What each valid row does**\n\nSaves or updates the recipient in the merchant's clients and creates the order just like `POST /api/orders`:\nit generates the shipping label and deducts the cost from the balance. If the creation fails (for example, because of the balance or a courier error),\nthe row comes back with `isValid: false` and the message of that error. The other rows are still processed.\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": "Excel template (.xlsx) from `GET /api/batchShipping` with at least one data row. The request body accepts up to 30 MB." } } }, "encoding": { "file": { "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" } } } } }, "responses": { "200": { "description": "File processed; check the result of each row", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_code": { "type": "integer" }, "response_status": { "type": "string" }, "response_message": { "type": "string" }, "data": { "type": "array", "description": "One entry per row with data, in the same order as in the Excel file.", "items": { "type": "object", "description": "The shipping data (address, weight, packages, amounts) is only reliable when `isValid` is `true`; in rows with errors it may come back empty or as `0`.", "properties": { "codeExcel": { "type": "integer", "description": "Row number in the Excel file." }, "ordersId": { "description": "ID (UUID) of the created order. It comes back as the number `0` if the row did not create an order.", "oneOf": [ { "type": "string", "format": "uuid" }, { "type": "integer" } ] }, "courierName": { "type": "string" }, "comprobante": { "type": "string", "description": "Receipt number of the order; empty if it was not created. It is used in `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 = cash on delivery." }, "isValid": { "type": "boolean", "description": "`true` if the order was created." }, "response_message": { "type": "string", "description": "`Orden creada correctamente` or the reason why the row failed." }, "guide": { "type": "object", "properties": { "URLguide": { "type": "string", "description": "URL of the shipping label; empty if the order was not created." } } }, "tracking": { "type": "object", "properties": { "URLtracking": { "type": "string", "description": "URL of the public tracking page; empty if the order was not created or if it does not apply to the merchant." } } } } } } } }, "examples": { "mixto": { "summary": "One row created and one with an 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": "No row passed validation (no order was created)", "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": "The file is not valid. Possible messages: `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": "The file field was not sent, or it was sent as text", "value": { "response_code": 400, "response_status": "error", "response_message": "No se envió ningún archivo" } }, "tipoInvalido": { "summary": "The file does not have the Excel content type, or the body is not multipart/form-data", "value": { "response_code": 400, "response_status": "error", "response_message": "El archivo enviado no es un archivo Excel válido" } }, "noLegible": { "summary": "Corrupted file or .xls format", "value": { "response_code": 400, "response_status": "error", "response_message": "El archivo no pudo ser leído como Excel" } }, "sinRegistros": { "summary": "The template has no rows with data", "value": { "response_code": 400, "response_status": "error", "response_message": "El archivo Excel no contiene registros" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Internal error while processing the file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "error", "response_message": "Error al procesar el archivo Excel" } } } } } } }, "/api/batchShipping/guides": { "post": { "summary": "Generate batch shipping labels", "operationId": "generateBatchGuides", "description": "Generates a single PDF document with the shipping labels of several orders from the same courier and returns its URL.\nIt is only available for couriers that support batch shipping labels; with the others it responds 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 of the orders (`courierId` from the quote).", "example": "019f81b1-a481-77d5-be76-6c74b42c1e59" }, "comprobantes": { "type": "array", "minItems": 1, "description": "Receipt numbers of the orders (`data.comprobante` when they were created). The name `orders` is also accepted; if both are sent, `orders` is used.", "items": { "type": "string", "example": "29137811" }, "example": [ "29137811", "29137812" ] } } } } } }, "responses": { "200": { "description": "Shipping labels generated", "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 of the PDF with the shipping labels. It may be a temporary Volao file or a courier URL; download it as soon as you receive it." } } } } }, "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": "Missing parameters (`courierId` or a non-empty list of receipts), or the receipts are not valid for the 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": "The shipping label document could not be generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sinGuia": { "summary": "The courier does not support batch shipping labels or did not return the document", "value": { "response_code": 500, "response_status": "Error", "response_message": "No se pudo generar la guía masiva" } }, "validacion": { "summary": "The receipts could not be validated (for example, courierId is not a valid UUID)", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error validando guías masivas del courier" } }, "cuerpoInvalido": { "summary": "The body is not valid JSON", "value": { "response_code": 500, "response_status": "Error", "response_message": "Error al procesar guías masivas" } } } } } } } } }, "/api/auth/client/login": { "post": { "summary": "API client login", "operationId": "loginApiClient", "description": "Authenticates an integration client with `client_id` and `client_secret` and returns a JWT `access_token` that must be sent in the `Authorization: Bearer {token}` header in subsequent requests.\n", "tags": [ "Autenticación API" ], "security": [], "requestBody": { "required": true, "description": "API client credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientLoginRequest" } } } }, "responses": { "200": { "description": "Successful authentication", "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": "JWT token for authentication", "example": "eyJhbGciOiJIUzI1NiJ9..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "description": "Expiration time in seconds", "example": 900 } } } } } } } }, "400": { "description": "`client_id` or `client_secret` is missing, is not a string or is empty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "noEnviados": { "summary": "A field is missing or is not a string", "value": { "response_code": 400, "response_status": "Error", "response_message": "client_id y client_secret deben ser válidos." } }, "vacios": { "summary": "A field was sent as an empty string", "value": { "response_code": 400, "response_status": "Error", "response_message": "Debe enviar client_id y client_secret para continuar." } }, "soloEspacios": { "summary": "A field contains only spaces", "value": { "response_code": 400, "response_status": "Error", "response_message": "client_id no puede estar vacío." } } } } } }, "401": { "description": "Invalid credentials (the `client_id` does not exist or the `client_secret` does not match)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 401, "response_status": "error", "response_message": "Credenciales inválidas" } } } }, "403": { "description": "API client disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 403, "response_status": "error", "response_message": "API client desactivado" } } } }, "500": { "description": "Internal error, or the body is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "response_code": 500, "response_status": "error", "response_message": "Error interno al autenticar API client" } } } } } } } } }