Descargar Devoluciones

Permite obtener el listado de devoluciones aprobadas que aún no han sido transmitidas al ERP, incluyendo el detalle de los ítems de cada devolución. Este endpoint está diseñado para que los sistemas contables de los clientes puedan descargar las devoluciones generadas en RSales e inyectarlas en sus propios sistemas. Soporta filtros por vendedor y fecha de creación, así como ordenamiento configurable y paginación.

Importante

Este endpoint solo retorna devoluciones con estado APROBADO y que no han sido descargadas. Únicamente se incluyen en la respuesta los registros de tipo D (Devolución).

Método: GET

Endpoint

https://api.ventasremotas.com/v1/returns/pending

Nota

Es necesario el envío del token de acceso Subscription-Key para hacer uso de este endpoint. Para ver cómo generar el token, vea Activación Suscripción a RSales API.

Encabezados de la solicitud

Header	Valor	Descripción	Requerido
Accept	application/json	Indica que la respuesta debe estar en formato JSON	No
Subscription-Key	{subscription_key}	Clave de suscripción para acceder a la API	Sí
Authorization	Bearer {access_token}	Token de acceso obtenido del endpoint /token	Sí

---

Parámetros de Consulta (Query Parameters)

Todos los parámetros son opcionales. Si no se especifican, se retornan todas las devoluciones aprobadas pendientes de transmisión con la paginación por defecto.

Filtros

Parámetro	Tipo	Descripción
seller_id	String	Filtra por código exacto de vendedor. Longitud máxima: 18 caracteres.
created_from	Date	Retorna devoluciones cuya fecha de creación es mayor o igual a este valor. Formato: YYYY-MM-DD.

Ordenamiento

Parámetro	Tipo	Descripción
sort	String	Campo y dirección de ordenamiento. Por defecto: fecha de creación descendente.

Campos de ordenamiento disponibles

Valor	Descripción
created_at	Ordena por fecha de creación ascendente (ASC)
-created_at	Ordena por fecha de creación descendente (DESC)

Ordenamiento por defecto

Si no se especifica el parámetro sort, los resultados se ordenan por fecha de creación descendente (más recientes primero).

Paginación

Parámetro	Tipo	Por defecto	Restricciones	Descripción
page	Number	1	Mínimo: 1	Número de página (1-indexed)
limit	Number	100	Mínimo: 1, Máximo: 500	Cantidad de resultados por página

---

Ejemplo de Solicitud

Petición básica (sin filtros)

curl -X GET "https://api.ventasremotas.com/v1/returns/pending" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con filtro por vendedor

curl -X GET "https://api.ventasremotas.com/v1/returns/pending?seller_id=V001" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con filtro de fecha y paginación

curl -X GET "https://api.ventasremotas.com/v1/returns/pending?created_from=2024-01-01&page=1&limit=50" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con múltiples filtros y ordenamiento

curl -X GET "https://api.ventasremotas.com/v1/returns/pending?seller_id=V001&created_from=2024-06-01&sort=created_at&page=1&limit=200" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

---

Ejemplo de Respuesta

200 - OK

{
    "data": [
        {
            "code": "DEV-20250301-001",
            "client_id": "CLI-045",
            "seller_id": "V001",
            "return_number": "DEV1045",
            "created_at": "2025-03-01T09:30:00",
            "updated_at": "2025-03-01T14:15:00",
            "observations": "Entregar en horario de la mañana",
            "document_number": "DOC-98765",
            "latitude": 4.7109886,
            "longitude": -74.072092,
            "transmission_date": null,
            "authorizer_user": "USR-ADMIN",
            "authorized_at": "2025-03-01T12:00:00",
            "cell_info": "Operador XYZ - 4G",
            "address": "Calle 100 #15-25",
            "warehouse": "BOD-001",
            "visit_time": 35,
            "reference": "REF-2025-001",
            "management_code": "GES-001",
            "withholding_base": 500000.0,
            "withholding": 15000.0,
            "total_withholding": 15000.0,
            "rejection_observations": null,
            "reason": null,
            "last_erp_state": null,
            "location": "LOC-NORTE",
            "payment_method_code": "FP-001",
            "items": [
                {
                    "item_number": 1,
                    "product_code": "PROD-001",
                    "product_inventory": 150.0,
                    "product_price": 25000.0,
                    "product_tax": 4750.0,
                    "discount1": 5.0,
                    "discount2": 0.0,
                    "discount3": 0.0,
                    "total": 237500.0,
                    "total_discount": 12500.0,
                    "product_quantity": 10.0,
                    "factor": 1.0,
                    "factor_description": "Unidad",
                    "invoice_product_quantity": null,
                    "invoice_factor": null,
                    "invoice_total": null,
                    "other_values": null,
                    "observations": null,
                    "return_cause": "CAUSAL-01",
                    "batch_number": "LOTE-2025-A",
                    "invoice_number": null,
                    "bonus": null
                },
                {
                    "item_number": 2,
                    "product_code": "PROD-015",
                    "product_inventory": 80.0,
                    "product_price": 45000.0,
                    "product_tax": 8550.0,
                    "discount1": 10.0,
                    "discount2": 2.0,
                    "discount3": 0.0,
                    "total": 396900.0,
                    "total_discount": 54000.0,
                    "product_quantity": 5.0,
                    "factor": 12.0,
                    "factor_description": "Docena",
                    "invoice_product_quantity": null,
                    "invoice_factor": null,
                    "invoice_total": null,
                    "other_values": null,
                    "observations": "Producto en promoción",
                    "return_cause": "CAUSAL-03",
                    "batch_number": null,
                    "invoice_number": null,
                    "bonus": "Y"
                }
            ]
        },
        {
            "code": "DEV-20250228-003",
            "client_id": "CLI-012",
            "seller_id": "V002",
            "return_number": null,
            "created_at": "2025-02-28T16:45:00",
            "updated_at": "2025-03-01T08:30:00",
            "observations": null,
            "document_number": "FAC-12345",
            "latitude": 6.2518,
            "longitude": -75.5636,
            "transmission_date": null,
            "authorizer_user": "USR-ADMIN",
            "authorized_at": "2025-02-28T17:00:00",
            "cell_info": null,
            "address": "Carrera 50 #30-10",
            "warehouse": "BOD-002",
            "visit_time": 20,
            "reference": null,
            "management_code": null,
            "withholding_base": null,
            "withholding": null,
            "total_withholding": null,
            "rejection_observations": null,
            "reason": null,
            "last_erp_state": null,
            "location": "LOC-SUR",
            "payment_method_code": "FP-002",
            "items": [
                {
                    "item_number": 1,
                    "product_code": "PROD-100",
                    "product_inventory": 200.0,
                    "product_price": 12000.0,
                    "product_tax": 2280.0,
                    "discount1": 0.0,
                    "discount2": 0.0,
                    "discount3": 0.0,
                    "total": 285600.0,
                    "total_discount": 0.0,
                    "product_quantity": 20.0,
                    "factor": 1.0,
                    "factor_description": "Unidad",
                    "invoice_product_quantity": 20.0,
                    "invoice_factor": 1.0,
                    "invoice_total": 285600.0,
                    "other_values": null,
                    "observations": null,
                    "return_cause": "CAUSAL-02",
                    "batch_number": null,
                    "invoice_number": "FAC-12345",
                    "bonus": null
                }
            ]
        }
    ],
    "meta": {
        "totalItems": 47,
        "itemCount": 2,
        "itemsPerPage": 100,
        "totalPages": 1,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/returns/pending?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/returns/pending?page=1&limit=100",
        "prev": null,
        "next": null,
        "last": "https://api.ventasremotas.com/v1/returns/pending?page=1&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Devolución)

Cada elemento del array data contiene los siguientes campos:

Campo	Tipo	Descripción
code	String	Número generado automáticamente por R-Sales para identificar la transacción
client_id	String	Código único de identificación del cliente en el ERP
seller_id	String	Código interno del vendedor como se define en el ERP
return_number	String	Número de la devolución generado por el móvil (prefijo + consecutivo) cuando la empresa tiene activa la numeración de devoluciones. Si no la tiene, es un texto libre opcional digitado por el vendedor en el campo “Nº Orden” del móvil (puede ser null o vacío)
created_at	DateTime	Fecha de creación de la devolución. Formato: yyyy-MM-ddTHH:mm:ss
updated_at	DateTime	Fecha de modificación de la devolución, solo el sistema puede actualizar este campo. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
observations	String	Observaciones generales digitadas por el asesor al diligenciar la devolución (puede ser null)
document_number	String	Número de documento (factura, nota crédito, nota débito, etc.) generado por el ERP (puede ser null)
latitude	Number	Coordenada de latitud de donde se hizo la transacción (puede ser null)
longitude	Number	Coordenada de longitud de donde se hizo la transacción (puede ser null)
transmission_date	DateTime	Fecha de transmisión de la devolución a los servidores de ADATEC. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
authorizer_user	String	Usuario que aprueba la devolución, si aplica (puede ser null)
authorized_at	DateTime	Fecha de aprobación de la devolución si se requiere aprobación. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
cell_info	String	Versión de la aplicación e IMEI del teléfono o tableta (puede ser null)
address	String	Dirección geo-referenciada por el GPS donde se tomó la devolución (puede ser null)
warehouse	String	Bodega para la cual se realizó la devolución (puede ser null)
visit_time	Number	Tiempo en segundos de cuánto se tardó el asesor digitando la devolución (puede ser null)
reference	String	Número de confirmación generado por el ERP (puede ser null)
management_code	String	Código de gestión asociado (puede ser null)
withholding_base	Number	Base de retención de la devolución (puede ser null)
withholding	Number	Porcentaje o valor de retención (puede ser null)
total_withholding	Number	Total de retención calculada (puede ser null)
rejection_observations	String	Observaciones de rechazo, si aplica (puede ser null)
reason	String	Motivo asociado a la devolución (puede ser null)
last_erp_state	String	Último estado reportado por el ERP (puede ser null)
location	String	Código de ubicación (puede ser null)
payment_method_code	String	Código de la forma de pago utilizada (puede ser null)
items	Array	Lista de ítems (productos) de la devolución. Ver detalle en la tabla siguiente

Objeto items[] (Ítem de la devolución)

Cada elemento del array items dentro de una devolución contiene:

Campo	Tipo	Descripción
item_number	Number	Orden relativo del producto dentro de la devolución
product_code	String	Código del producto devuelto
product_inventory	Number	Producto bonificado digitado por el asesor, si es -1 no es bonificado, de lo contrario es la cantidad bonificada (puede ser null)
product_price	Number	Valor unitario antes de impuestos
product_tax	Number	Valor en porcentaje del impuesto del producto (puede ser null)
discount1	Number	Descuento 1 dado. Valor de 0 a 100
discount2	Number	Descuento 2 dado. Valor de 0 a 100
discount3	Number	Descuento 3 dado. Valor de 0 a 100
total	Number	Valor total de la devolución antes de impuestos
total_discount	Number	Valor total de la devolución antes de impuestos con descuento incluido (puede ser null)
product_quantity	Number	Cantidad devuelta
factor	Number	Unidad de empaque de la unidad devuelta (ejemplo: 24 si se devuelve Caja x 24) (puede ser null)
factor_description	String	Descripción del factor de venta (ejemplo: Caja X 24) (puede ser null)
invoice_product_quantity	Number	Cantidad facturada (puede ser null)
invoice_factor	Number	Factor de conversión en la factura (puede ser null)
invoice_total	Number	Total antes de impuestos (puede ser null)
other_values	Number	Otros impuestos del producto, si aplica (puede ser null)
observations	String	Observaciones por producto (puede ser null)
return_cause	String	Causal de devolución, si aplica (puede ser null)
batch_number	String	Número de lote del producto (puede ser null)
invoice_number	String	Número de factura asociada al ítem (puede ser null)
bonus	String	Indica si el ítem es bonificado (puede ser null)

Objeto meta (Metadatos de paginación)

Campo	Tipo	Descripción
totalItems	Number	Cantidad total de devoluciones que coinciden con los filtros
itemCount	Number	Cantidad de devoluciones en la página actual
itemsPerPage	Number	Cantidad de items por página solicitados
totalPages	Number	Total de páginas disponibles
currentPage	Number	Número de la página actual

Objeto links (Enlaces de navegación)

Campo	Tipo	Descripción
self	String	URL de la página actual
first	String	URL de la primera página
prev	String	URL de la página anterior (null si es la primera página)
next	String	URL de la página siguiente (null si es la última página)
last	String	URL de la última página

Status 400

Los errores de validación de parámetros de consulta retornan un array de errores, donde cada error indica el parámetro problemático:

Filtro no válido

{
    "statusCode": 400,
    "errors": [
        {
            "param": "invalid_param",
            "message": "The field is not a valid filter parameter"
        }
    ]
}

Valor de filtro vacío

{
    "statusCode": 400,
    "errors": [
        {
            "param": "seller_id",
            "message": "Value must not be empty"
        }
    ]
}

Fecha con formato inválido

{
    "statusCode": 400,
    "errors": [
        {
            "param": "created_from",
            "message": "Value '15-01-2024' is not a valid date (expected format: YYYY-MM-DD)"
        }
    ]
}

Valor excede longitud máxima

{
    "statusCode": 400,
    "errors": [
        {
            "param": "seller_id",
            "message": "Value exceeds maximum length of 18"
        }
    ]
}

Campo de ordenamiento inválido

{
    "statusCode": 400,
    "errors": [
        {
            "param": "sort",
            "message": "The field 'invalid_field' is not a valid sort field."
        }
    ]
}

Parámetro sort vacío

{
    "statusCode": 400,
    "errors": [
        {
            "param": "sort",
            "message": "The parameter must not be empty"
        }
    ]
}

Parámetro de paginación inválido

{
    "statusCode": 400,
    "errors": [
        {
            "param": "page",
            "message": "The parameter must be a valid integer"
        }
    ]
}

Página menor al mínimo

{
    "statusCode": 400,
    "errors": [
        {
            "param": "page",
            "message": "The parameter must be greater than or equal to 1"
        }
    ]
}

Límite excede el máximo

{
    "statusCode": 400,
    "errors": [
        {
            "param": "limit",
            "message": "The parameter must be less than or equal to 500"
        }
    ]
}

Límite vacío

{
    "statusCode": 400,
    "errors": [
        {
            "param": "limit",
            "message": "The parameter must not be empty"
        }
    ]
}

Errores múltiples

El endpoint puede retornar múltiples errores de validación en una sola respuesta. Por ejemplo, si se envía un filtro inválido y un parámetro de paginación incorrecto al mismo tiempo, ambos errores aparecerán en el array de errors.

Tabla resumen de errores de validación

Errores de filtros:

Error	Aplica a
The field is not a valid filter parameter	Cualquier parámetro no reconocido
Value must not be empty	seller_id
Value 'X' is not a valid date (expected format: YYYY-MM-DD)	created_from
Value exceeds maximum length of 18	seller_id

Errores de ordenamiento:

Error	Aplica a
The parameter must not be empty	sort
The field 'X' is not a valid sort field.	sort

Errores de paginación:

Error	Aplica a
The parameter must not be empty	page, limit
The parameter must be a valid integer	page, limit
The parameter must be greater than or equal to 1	page, limit
The parameter must be less than or equal to 500	limit

Status 500

Error de conexión a base de datos

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Error connecting to database"
        }
    ]
}

Error de operación en base de datos

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Database operation failed"
        }
    ]
}

Error en validaciones

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error in the validations"
        }
    ]
}

Error inesperado

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error"
        }
    ]
}

Error del Servidor

Estos errores indican problemas internos en el servidor o la base de datos. Si persisten, contacta al equipo de soporte.