Descargar Pedidos/Facturas

Permite obtener el listado de pedidos y facturas aprobados que aún no han sido transmitidos al ERP, incluyendo el detalle de los ítems de cada pedido. Este endpoint está diseñado para que los sistemas contables de los clientes puedan descargar los pedidos y facturas generados en RSales e inyectarlos 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 pedidos y facturas con estado APROBADO y que no han sido descargados. Los registros de tipo P (Pedido) y F (Factura) son incluidos en la respuesta.

Método: GET

Endpoint

https://api.ventasremotas.com/v1/orders/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 todos los pedidos/facturas aprobados 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 pedidos 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/orders/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/orders/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/orders/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/orders/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": "PED-20250301-001",
            "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": "Entregar en horario de la mañana",
            "document_number": "DOC-98765",
            "payment_method": "CRÉDITO",
            "payment_date": "2025-04-01T00:00:00",
            "latitude": 4.7109886,
            "longitude": -74.072092,
            "transmission_date": null,
            "authorizer_user": "USR-ADMIN",
            "authorized_at": "2025-03-01T12:00:00",
            "invoice_date": null,
            "cell_info": "Operador XYZ - 4G",
            "address": "Calle 100 #15-25",
            "warehouse": "BOD-001",
            "type": "P",
            "visit_time": 35,
            "reference": "REF-2025-001",
            "management_code": "GES-001",
            "withholding_base": 500000.0,
            "withholding": 15000.0,
            "total_withholding": 15000.0,
            "order_origin": 2,
            "rejection_observations": null,
            "reason": null,
            "last_erp_state": null,
            "quotation_code": 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": null,
                    "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": null,
                    "batch_number": null,
                    "invoice_number": null,
                    "bonus": "Y"
                }
            ]
        },
        {
            "code": "FAC-20250228-003",
            "client_id": "CLI-012",
            "seller_id": "V002",
            "order_number": "ORD-2025-1538",
            "delivery_date": "2025-03-02T00:00:00",
            "created_at": "2025-02-28T16:45:00",
            "updated_at": "2025-03-01T08:30:00",
            "observations": null,
            "document_number": "FAC-12345",
            "payment_method": "CONTADO",
            "payment_date": "2025-02-28T00:00:00",
            "latitude": 6.2518,
            "longitude": -75.5636,
            "transmission_date": null,
            "authorizer_user": "USR-ADMIN",
            "authorized_at": "2025-02-28T17:00:00",
            "invoice_date": "2025-02-28T17:10:00",
            "cell_info": null,
            "address": "Carrera 50 #30-10",
            "warehouse": "BOD-002",
            "type": "F",
            "visit_time": 20,
            "reference": null,
            "management_code": null,
            "withholding_base": null,
            "withholding": null,
            "total_withholding": null,
            "order_origin": 1,
            "rejection_observations": null,
            "reason": null,
            "last_erp_state": null,
            "quotation_code": "COT-2025-050",
            "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": null,
                    "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/orders/pending?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/orders/pending?page=1&limit=100",
        "prev": null,
        "next": null,
        "last": "https://api.ventasremotas.com/v1/orders/pending?page=1&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Pedido/Factura)

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 del pedido, por defecto es la fecha de creación + 2 días. Formato: yyyy-MM-ddTHH:mm:ss
created_at	DateTime	Fecha de creación del pedido. Formato: yyyy-MM-ddTHH:mm:ss
updated_at	DateTime	Fecha de modificación del pedido, 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 el pedido (puede ser null)
document_number	String	Número de factura si el ERP la proporciona (puede ser null)
payment_method	String	Forma de pago del pedido, 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, se calcula tomando 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 del pedido a los servidores de ADATEC. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
authorizer_user	String	Usuario que aprueba el pedido, si aplica (puede ser null)
authorized_at	DateTime	Fecha de aprobación del pedido 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ó el pedido (puede ser null)
warehouse	String	Bodega para la cual se realizó el pedido (puede ser null)
type	String	Tipo de transacción: F (Factura), P (Pedido) (puede ser null)
visit_time	Number	Tiempo en segundos de cuánto se tardó el asesor digitando el pedido (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 del pedido (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 del pedido: 1 (WEB), 2 (MÓVIL) (puede ser null)
rejection_observations	String	Observaciones de rechazo, si aplica (puede ser null)
reason	String	Motivo asociado al pedido (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)
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) del pedido. Ver detalle en la tabla siguiente

Objeto items[] (Ítem del pedido)

Cada elemento del array items dentro de un pedido contiene:

Campo	Tipo	Descripción
item_number	Number	Orden relativo del producto dentro de la factura
product_code	String	Código de producto facturado
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 del pedido antes de impuestos
total_discount	Number	Valor total del pedido antes de impuestos con descuento incluido (puede ser null)
product_quantity	Number	Cantidad del pedido
factor	Number	Unidad de empaque de la unidad del pedido (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 pedidos/facturas que coinciden con los filtros
itemCount	Number	Cantidad de pedidos/facturas 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.