Listar Pedidos/Facturas/Devoluciones/Cotizaciones

Permite obtener el listado de transacciones de venta (pedidos, facturas, devoluciones y cotizaciones) registradas en el sistema de forma paginada, incluyendo el detalle de los ítems de cada transacción. A diferencia de Descargar Pedidos/Facturas, que solo retorna pedidos y facturas aprobados pendientes de descargar, este endpoint permite consultar los 4 tipos de transacción (P, F, C, D) en cualquier estado, y soporta filtros por vendedor, cliente, tipo de transacción, estado y fecha de creación, así como ordenamiento configurable y paginación.

Método: GET

Endpoint

https://api.ventasremotas.com/v1/orders

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 transacciones de venta no transmitidas al ERP 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.
client_id	String	Filtra por código exacto de cliente. Longitud máxima: 18 caracteres.
type	String	Filtra por tipo de transacción. Valores permitidos: P (Pedido), F (Factura), C (Cotización), D (Devolución).
created_from	Date	Retorna transacciones cuya fecha de creación es mayor o igual a este valor. Formato: YYYY-MM-DD.
state	String	Filtra por estado de la transacción. Valores permitidos: APROBADO, PENDIENTE, RECHAZADO, RETENIDO, DESPACHADO.

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/orders" \
  -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/orders?seller_id=V001" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con filtro por cliente

curl -X GET "https://api.ventasremotas.com/v1/orders?client_id=CLI-001" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con filtro por tipo de transacción

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

Petición con filtro por estado

curl -X GET "https://api.ventasremotas.com/v1/orders?state=PENDIENTE" \
  -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/orders?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/orders?seller_id=V001&client_id=CLI-001&type=F&state=APROBADO&created_from=2024-06-01&sort=-created_at&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": "COT-20250301-010",
            "client_id": "CLI-045",
            "seller_id": "V001",
            "order_number": "ORD-2025-1542",
            "delivery_date": "2025-03-05T00:00:00",
            "created_at": "2025-03-01T09:30:00",
            "updated_at": "2025-03-01T14:15:00",
            "observations": "Cotización pendiente de aprobación del cliente",
            "document_number": null,
            "payment_method": "CRÉDITO",
            "payment_date": null,
            "latitude": 4.7109886,
            "longitude": -74.072092,
            "transmission_date": null,
            "authorizer_user": null,
            "authorized_at": null,
            "invoice_date": null,
            "cell_info": "Operador XYZ - 4G",
            "address": "Calle 100 #15-25",
            "warehouse": "BOD-001",
            "type": "C",
            "state": "PENDIENTE",
            "signature": "https://rsales-multimedia.ventasremotas.com/api/proxy/EMPRESA001/imagenes/FIRMA-COT-20250301-010-a1b2c3d4e5f6.JPG",
            "visit_time": 35,
            "reference": null,
            "management_code": "GES-001",
            "withholding_base": null,
            "withholding": null,
            "total_withholding": null,
            "order_origin": 2,
            "rejection_observations": null,
            "reason": null,
            "last_erp_state": null,
            "quotation_code": null,
            "promoted_quotation": "N",
            "location": "LOC-NORTE",
            "payment_method_code": "FP-001",
            "voucher": "https://rsales-multimedia.ventasremotas.com/api/proxy/EMPRESA001/imagenes/PC_COT-20250301-010-a1b2c3d4e5f6.JPG",
            "voucher_delivery_note": "",
            "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": null,
                    "batch_number": "LOTE-2025-A",
                    "invoice_number": null,
                    "bonus": null
                }
            ]
        },
        {
            "code": "DEV-20250228-004",
            "client_id": "CLI-012",
            "seller_id": "V002",
            "order_number": null,
            "delivery_date": "2025-03-02T00:00:00",
            "created_at": "2025-02-28T16:45:00",
            "updated_at": "2025-03-01T08:30:00",
            "observations": "Devolución por producto averiado",
            "document_number": "FAC-12345",
            "payment_method": "CONTADO",
            "payment_date": null,
            "latitude": 6.2518,
            "longitude": -75.5636,
            "transmission_date": null,
            "authorizer_user": "USR-ADMIN",
            "authorized_at": "2025-02-28T17:00:00",
            "invoice_date": null,
            "cell_info": null,
            "address": "Carrera 50 #30-10",
            "warehouse": "BOD-002",
            "type": "D",
            "state": "APROBADO",
            "signature": "",
            "visit_time": 20,
            "reference": null,
            "management_code": null,
            "withholding_base": null,
            "withholding": null,
            "total_withholding": null,
            "order_origin": 1,
            "rejection_observations": null,
            "reason": "PRODUCTO_AVERIADO",
            "last_erp_state": null,
            "quotation_code": null,
            "promoted_quotation": null,
            "location": "LOC-SUR",
            "payment_method_code": "FP-002",
            "voucher": "https://rsales-multimedia.ventasremotas.com/api/proxy/EMPRESA001/imagenes/PC_DEV-20250228-004-a1b2c3d4e5f6.JPG",
            "voucher_delivery_note": "https://rsales-multimedia.ventasremotas.com/api/proxy/EMPRESA001/imagenes/PA_DEV-20250228-004-a1b2c3d4e5f6.JPG",
            "items": [
                {
                    "item_number": 1,
                    "product_code": "PROD-100",
                    "product_inventory": null,
                    "product_price": 12000.0,
                    "product_tax": 2280.0,
                    "discount1": 0.0,
                    "discount2": 0.0,
                    "discount3": 0.0,
                    "total": 14280.0,
                    "total_discount": 0.0,
                    "product_quantity": 1.0,
                    "factor": 1.0,
                    "factor_description": "Unidad",
                    "invoice_product_quantity": null,
                    "invoice_factor": null,
                    "invoice_total": null,
                    "other_values": null,
                    "observations": null,
                    "return_cause": "PRODUCTO_AVERIADO",
                    "batch_number": null,
                    "invoice_number": "FAC-12345",
                    "bonus": null
                }
            ]
        }
    ],
    "meta": {
        "totalItems": 132,
        "itemCount": 2,
        "itemsPerPage": 100,
        "totalPages": 2,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/orders?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/orders?page=1&limit=100",
        "prev": null,
        "next": "https://api.ventasremotas.com/v1/orders?page=2&limit=100",
        "last": "https://api.ventasremotas.com/v1/orders?page=2&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Transacción de venta)

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
order_number	String	Orden de compra entregada por el cliente, digitada por el vendedor (puede ser null)
delivery_date	DateTime	Fecha tentativa de entrega, por defecto es la fecha de creación + 2 días. Formato: yyyy-MM-ddTHH:mm:ss
created_at	DateTime	Fecha de creación de la transacción. Formato: yyyy-MM-ddTHH:mm:ss
updated_at	DateTime	Fecha de modificació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 (puede ser null)
document_number	String	Número de factura si el ERP la proporciona (puede ser null)
payment_method	String	Forma de pago, por defecto es la configurada en el cliente, pero puede ser modificada por el vendedor (puede ser null)
payment_date	DateTime	Fecha tentativa de pago, calculada con la fecha de creación + los días de plazo configurado en el cliente. Formato: yyyy-MM-ddTHH:mm:ss (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 transacción a los servidores de ADATEC. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
authorizer_user	String	Usuario que aprueba la transacción, si aplica (puede ser null)
authorized_at	DateTime	Fecha de aprobación si se requiere aprobación. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
invoice_date	DateTime	Fecha de facturación del sistema si el ERP lo proporciona. 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 transacción (puede ser null)
warehouse	String	Bodega para la cual se realizó la transacción (puede ser null)
type	String	Tipo de transacción: P (Pedido), F (Factura), C (Cotización), D (Devolución)
state	String	Estado de la transacción: PENDIENTE, APROBADO, RETENIDO, RECHAZADO, DESPACHADO
signature	String	URL de la foto de la firma de la transacción, disponible para los 4 tipos de transacción (puede ser null o vacío)
visit_time	Number	Tiempo en segundos de cuánto se tardó el asesor digitando la transacció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 transacció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)
order_origin	Number	Origen de la transacción: 1 (WEB), 2 (MÓVIL) (puede ser null)
rejection_observations	String	Observaciones de rechazo, si aplica (puede ser null)
reason	String	Motivo asociado a la transacción, por ejemplo la causal de una devolución (puede ser null)
last_erp_state	String	Último estado reportado por el ERP (puede ser null)
quotation_code	String	Código de la cotización de origen, si el pedido nace de una cotización (puede ser null)
promoted_quotation	String	Indica si la cotización fue promovida a pedido: Y o N (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)
voucher	String	URL de la foto del comprobante de la transacción, disponible para los 4 tipos de transacción (puede ser null o vacío)
voucher_delivery_note	String	URL de la foto del comprobante de albarán, solo aplica para devoluciones (type: D) (puede ser null o vacío)
items	Array	Lista de ítems (productos) de la transacción. Ver detalle en la tabla siguiente

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

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

Campo	Tipo	Descripción
item_number	Number	Orden relativo del producto dentro de la transacción
product_code	String	Código de producto
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 antes de impuestos
total_discount	Number	Valor total antes de impuestos con descuento incluido (puede ser null)
product_quantity	Number	Cantidad
factor	Number	Unidad de empaque de la unidad (ejemplo: 24 si se pide 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 transacciones que coinciden con los filtros
itemCount	Number	Cantidad de transacciones 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"
        }
    ]
}

Valor no permitido para tipo de transacción

{
    "statusCode": 400,
    "errors": [
        {
            "param": "type",
            "message": "Value must be one of: P, F, C, D"
        }
    ]
}

Valor no permitido para estado

{
    "statusCode": 400,
    "errors": [
        {
            "param": "state",
            "message": "Value must be one of: APROBADO, PENDIENTE, RECHAZADO, RETENIDO, DESPACHADO"
        }
    ]
}

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, client_id, type, state
Value 'X' is not a valid date (expected format: YYYY-MM-DD)	created_from
Value exceeds maximum length of 18	seller_id, client_id
Value must be one of: P, F, C, D	type
Value must be one of: APROBADO, PENDIENTE, RECHAZADO, RETENIDO, DESPACHADO	state

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.