Listar Recaudos

Permite obtener el listado de recaudos (recibos de caja) registrados por los vendedores y cobradores en R-Sales de forma paginada, incluyendo el detalle de los documentos de cartera abonados en cada recaudo. A diferencia de Descargar Recaudos, que solo retorna recaudos aprobados pendientes de descargar, este endpoint permite consultar los recaudos en cualquier estado (PENDIENTE, RETENIDO, APROBADO, RECHAZADO) e incluye las URL del comprobante de pago y de la firma. Soporta filtros por vendedor, cliente, estado y fecha de creación, así como ordenamiento configurable y paginación.

Método: GET

Endpoint

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

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 recaudos de la empresa con la paginación por defecto.

Filtros

Parámetro	Tipo	Descripción
`seller_id`	String	Filtra por código exacto del vendedor o cobrador que elaboró el recaudo. Longitud máxima: 18 caracteres.
`client_id`	String	Filtra por código exacto del cliente. Longitud máxima: 18 caracteres.
`created_from`	Date	Retorna recaudos cuya fecha de creación es mayor o igual a este valor. Formato: `YYYY-MM-DD`.
`state`	String	Filtra por estado del recaudo. Valores permitidos: `APROBADO`, `PENDIENTE`, `RECHAZADO`, `RETENIDO`.

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)

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/receipts" \
  -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/receipts?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/receipts?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 estado

curl -X GET "https://api.ventasremotas.com/v1/receipts?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/receipts?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/receipts?seller_id=V001&client_id=CLI-001&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

{
    "data": [
        {
            "code": "CLI001V001250301093000",
            "client_id": "CLI-001",
            "seller_id": "V001",
            "receipt_number": "RC-000123",
            "created_at": "2025-03-01T09:30:00",
            "payment_method": "CHEQUE",
            "payment_date": "2025-03-01T00:00:00",
            "observations": "Cheque posfechado según acuerdo con el cliente",
            "check_number": "0004567",
            "transfer_number": null,
            "state": "APROBADO",
            "latitude": 4.7109886,
            "longitude": -74.072092,
            "transmission_date": "2025-03-01T09:31:12",
            "address": "Calle 100 #15-25",
            "precision": 12.5,
            "battery": 78.0,
            "cell_info": "3.2.1 - 356938035643809",
            "management_code": "GES-001",
            "total_received": 1500000.0,
            "bank_code": "BCO-01",
            "account_code": "123-456789-01",
            "appointment_code": 5001,
            "visit_time": 180,
            "accumulate_payment": "N",
            "reference": null,
            "approved_by": "admin",
            "approved_at": "2025-03-01T11:05:00",
            "retained_by": null,
            "retained_at": null,
            "retention_observations": null,
            "retention_reason": null,
            "rejected_by": null,
            "rejected_at": null,
            "rejection_observations": null,
            "reason": null,
            "type": "R",
            "last_erp_state": null,
            "check_source_account": "9876543210",
            "check_source_bank": "BCO-02",
            "voucher": "https://rsales-multimedia.ventasremotas.com/api/proxy/EMPRESA001/imagenes/CP_CLI001V001250301093000-a1b2c3d4e5f6.JPG",
            "signature": "https://rsales-multimedia.ventasremotas.com/api/proxy/EMPRESA001/imagenes/RF_CLI001V001250301093000-a1b2c3d4e5f6.JPG",
            "items": [
                {
                    "item_number": 1,
                    "category": "DC",
                    "document_number": "FAC-12345",
                    "document_type": "FACTURA",
                    "document_date": "2025-02-01T00:00:00",
                    "discount1": 0.0,
                    "discount1_label": "Dscto Comercial",
                    "discount2": 0.0,
                    "discount2_label": "Rte.FUENTE",
                    "discount3": 25000.0,
                    "discount3_label": "Rte.IVA",
                    "discount4": 0.0,
                    "discount4_label": "Rte.ICA",
                    "document_balance": 2000000.0,
                    "net_balance": 1875000.0,
                    "paid_value": 1500000.0,
                    "pending_balance": 375000.0,
                    "crossed_document": null,
                    "crossed_document_type": null,
                    "crossed_document_total": null,
                    "crossed_document_value": -100000.0,
                    "observations": null,
                    "client_id": "CLI-001"
                },
                {
                    "item_number": 2,
                    "category": "NC",
                    "document_number": "NC-00087",
                    "document_type": "NOTA CRÉDITO",
                    "document_date": "2025-02-15T00:00:00",
                    "discount1": 0.0,
                    "discount1_label": "Dscto Comercial",
                    "discount2": 0.0,
                    "discount2_label": "Rte.FUENTE",
                    "discount3": 0.0,
                    "discount3_label": "Rte.IVA",
                    "discount4": 0.0,
                    "discount4_label": "Rte.ICA",
                    "document_balance": -100000.0,
                    "net_balance": 0.0,
                    "paid_value": 0.0,
                    "pending_balance": 0.0,
                    "crossed_document": "FAC-12345",
                    "crossed_document_type": "FACTURA",
                    "crossed_document_total": -100000.0,
                    "crossed_document_value": -100000.0,
                    "observations": null,
                    "client_id": "CLI-001"
                }
            ]
        },
        {
            "code": "CLI045V002250228164500",
            "client_id": "CLI-045",
            "seller_id": "V002",
            "receipt_number": "RC-000122",
            "created_at": "2025-02-28T16:45:00",
            "payment_method": "EFECTIVO",
            "payment_date": "2025-02-28T00:00:00",
            "observations": null,
            "check_number": null,
            "transfer_number": null,
            "state": "PENDIENTE",
            "latitude": 6.2518,
            "longitude": -75.5636,
            "transmission_date": "2025-02-28T16:46:03",
            "address": "Carrera 50 #30-10",
            "precision": 8.0,
            "battery": 42.0,
            "cell_info": "3.2.1 - 356938035643810",
            "management_code": null,
            "total_received": 300000.0,
            "bank_code": null,
            "account_code": null,
            "appointment_code": -1,
            "visit_time": 65,
            "accumulate_payment": "Y",
            "reference": null,
            "approved_by": null,
            "approved_at": null,
            "retained_by": null,
            "retained_at": null,
            "retention_observations": null,
            "retention_reason": null,
            "rejected_by": null,
            "rejected_at": null,
            "rejection_observations": null,
            "reason": null,
            "type": "A",
            "last_erp_state": null,
            "check_source_account": null,
            "check_source_bank": null,
            "voucher": "",
            "signature": "",
            "items": [
                {
                    "item_number": 1,
                    "category": "DC",
                    "document_number": "ANT-CLI045V002250228164500",
                    "document_type": "ANTICIPO",
                    "document_date": "2025-02-28T16:45:00",
                    "discount1": 0.0,
                    "discount1_label": "Dscto Comercial",
                    "discount2": 0.0,
                    "discount2_label": "Rte.FUENTE",
                    "discount3": 0.0,
                    "discount3_label": "Rte.IVA",
                    "discount4": 0.0,
                    "discount4_label": "Rte.ICA",
                    "document_balance": 0.0,
                    "net_balance": 0.0,
                    "paid_value": 300000.0,
                    "pending_balance": -300000.0,
                    "crossed_document": null,
                    "crossed_document_type": null,
                    "crossed_document_total": null,
                    "crossed_document_value": null,
                    "observations": "Anticipo para pedido de marzo",
                    "client_id": "CLI-045"
                }
            ]
        }
    ],
    "meta": {
        "totalItems": 132,
        "itemCount": 2,
        "itemsPerPage": 100,
        "totalPages": 2,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/receipts?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/receipts?page=1&limit=100",
        "prev": null,
        "next": "https://api.ventasremotas.com/v1/receipts?page=2&limit=100",
        "last": "https://api.ventasremotas.com/v1/receipts?page=2&limit=100"
    }
}

Descripción de campos de respuesta

Objeto `data[]` (Recaudo)

Cada elemento del array data contiene los siguientes campos:

Campo	Tipo	Descripción
`code`	String	Código de la transacción, generado automáticamente por R-Sales para identificar el recaudo
`client_id`	String	Código del cliente al que se le elaboró el recaudo
`seller_id`	String	Código del usuario (vendedor o cobrador) que elaboró el recaudo
`receipt_number`	String	Número de recibo que el usuario entrega al cliente; puede ser automático o manual
`created_at`	DateTime	Fecha de creación del recaudo. Formato: `yyyy-MM-ddTHH:mm:ss`
`payment_method`	String	Descripción de la forma de pago seleccionada por el usuario para indicar cómo se hizo el pago
`payment_date`	DateTime	Fecha de pago seleccionada por el usuario al digitar el recaudo. Formato: `yyyy-MM-ddTHH:mm:ss`
`observations`	String	Observaciones generales digitadas por el usuario al diligenciar el recaudo (puede ser `null`)
`check_number`	String	Número del cheque diligenciado por el usuario; aplica según la forma de pago (puede ser `null`)
`transfer_number`	String	Número de la transferencia bancaria diligenciado por el usuario; aplica según la forma de pago (puede ser `null`)
`state`	String	Estado del recaudo: `PENDIENTE`, `RETENIDO`, `RECHAZADO`, `APROBADO` (puede ser `null`)
`latitude`	Number	Coordenada de latitud desde donde se reportó el recaudo (puede ser `null`)
`longitude`	Number	Coordenada de longitud desde donde se reportó el recaudo (puede ser `null`)
`transmission_date`	DateTime	Fecha en que el recaudo se transmitió al servidor de ADATEC. Formato: `yyyy-MM-ddTHH:mm:ss` (puede ser `null`)
`address`	String	Dirección geo-referenciada desde donde se reportó el recaudo (puede ser `null`)
`precision`	Number	Precisión del GPS al momento de reportar el recaudo (puede ser `null`)
`battery`	Number	Nivel de batería del dispositivo al momento de reportar el recaudo (puede ser `null`)
`cell_info`	String	Versión de la aplicación e IMEI del teléfono o tableta (puede ser `null`)
`management_code`	String	Código de la gestión en la que se elaboró el recaudo (puede ser `null`)
`total_received`	Number	Total recibido en el recaudo (puede ser `null`)
`bank_code`	String	Código del banco seleccionado por el usuario; aplica según la forma de pago (puede ser `null`)
`account_code`	String	Código de la cuenta bancaria propia de la empresa seleccionada por el usuario; aplica según la forma de pago (puede ser `null`)
`appointment_code`	Number	Código de la agenda en la que se elaboró el recaudo; `-1` cuando no aplica (puede ser `null`)
`visit_time`	Number	Tiempo en segundos que tardó el usuario diligenciando el recaudo (puede ser `null`)
`accumulate_payment`	String	Indica si la forma de pago acumula el recaudo para consignarlo después: `Y` o `N` (puede ser `null`)
`reference`	String	Referencia de confirmación del recaudo en el ERP, registrada mediante Modificar Recaudos (puede ser `null`)
`approved_by`	String	Usuario administrativo que aprobó el recaudo (puede ser `null`)
`approved_at`	DateTime	Fecha en que el usuario administrativo aprobó el recaudo. Formato: `yyyy-MM-ddTHH:mm:ss` (puede ser `null`)
`retained_by`	String	Usuario administrativo que retuvo el recaudo (puede ser `null`)
`retained_at`	DateTime	Fecha en que el usuario administrativo retuvo el recaudo. Formato: `yyyy-MM-ddTHH:mm:ss` (puede ser `null`)
`retention_observations`	String	Observaciones que dejó el usuario administrativo al retener el recaudo (puede ser `null`)
`retention_reason`	String	Causal o motivo por el que se retuvo el recaudo (puede ser `null`)
`rejected_by`	String	Usuario administrativo que rechazó el recaudo (puede ser `null`)
`rejected_at`	DateTime	Fecha en que el usuario administrativo rechazó el recaudo. Formato: `yyyy-MM-ddTHH:mm:ss` (puede ser `null`)
`rejection_observations`	String	Observaciones que dejó el usuario administrativo al rechazar el recaudo (puede ser `null`)
`reason`	String	Causal o motivo por el que se rechazó el recaudo (puede ser `null`)
`type`	String	Tipo de recaudo: `R` Abono, `A` Anticipo (puede ser `null`)
`last_erp_state`	String	Último estado del recaudo reportado por el ERP, registrado mediante Modificar Recaudos (puede ser `null`)
`check_source_account`	String	Cuenta bancaria del cliente de la que proviene el cheque; aplica cuando el pago fue en cheque (puede ser `null`)
`check_source_bank`	String	Banco del cheque; aplica cuando el pago fue en cheque (puede ser `null`)
`voucher`	String	URL de la foto del comprobante o voucher del pago (vacío si el recaudo no tiene comprobante)
`signature`	String	URL de la foto de la firma del recaudo (vacío si el recaudo no tiene firma)
`items`	Array	Lista de documentos abonados en el recaudo. Ver detalle en la tabla siguiente

Objeto `items[]` (Documento abonado)

Cada elemento del array items dentro de un recaudo contiene:

Campo	Tipo	Descripción
`item_number`	Number	Consecutivo del documento dentro del recaudo (puede ser `null`)
`category`	String	Categoría del documento: `DC` documento de cartera (factura) o anticipo, `NC` nota crédito (puede ser `null`)
`document_number`	String	Según la categoría: número real de la factura, número real de la nota crédito o número ficticio que identifica el anticipo
`document_type`	String	Según la categoría: tipo real de la factura, tipo real de la nota crédito o tipo ficticio del anticipo (puede ser `null`)
`document_date`	DateTime	Según la categoría: fecha real de la factura, fecha real de la nota crédito o fecha en que se hizo el anticipo. Formato: `yyyy-MM-ddTHH:mm:ss` (puede ser `null`)
`discount1`	Number	Solo facturas reales: valor del descuento 1 aplicado a la factura, si está activo para aplicar; su etiqueta viene en `discount1_label`
`discount1_label`	String	Etiqueta del descuento 1 configurada por la empresa en R-Sales, la misma que ve el usuario al registrar el recaudo (puede ser `null`)
`discount2`	Number	Solo facturas reales: valor del descuento 2 aplicado a la factura, si está activo para aplicar; su etiqueta viene en `discount2_label`
`discount2_label`	String	Etiqueta del descuento 2 configurada por la empresa en R-Sales, la misma que ve el usuario al registrar el recaudo (puede ser `null`)
`discount3`	Number	Solo facturas reales: valor del descuento 3 aplicado a la factura, si está activo para aplicar; su etiqueta viene en `discount3_label`
`discount3_label`	String	Etiqueta del descuento 3 configurada por la empresa en R-Sales, la misma que ve el usuario al registrar el recaudo (puede ser `null`)
`discount4`	Number	Solo facturas reales: valor del descuento 4 aplicado a la factura, si está activo para aplicar; su etiqueta viene en `discount4_label`
`discount4_label`	String	Etiqueta del descuento 4 configurada por la empresa en R-Sales, la misma que ve el usuario al registrar el recaudo (puede ser `null`)
`document_balance`	Number	Según la categoría: saldo original de la factura antes de reportar el pago, o saldo disponible de la nota crédito antes del cruce
`net_balance`	Number	Solo facturas reales: saldo de la factura después de restar los descuentos y sumar las notas crédito cruzadas; es el saldo neto sobre el que se aplica el abono
`paid_value`	Number	Monto que el usuario abonó a la factura o al anticipo
`pending_balance`	Number	Según la categoría: lo que queda debiendo la factura después del abono (`net_balance` − `paid_value`), o el saldo que le queda a la nota crédito tras el cruce. Para anticipos siempre es un valor negativo
`crossed_document`	String	Solo notas crédito: factura contra la que se cruzó la nota (puede ser `null`)
`crossed_document_type`	String	Solo notas crédito: tipo de la factura contra la que se cruzó la nota (puede ser `null`)
`crossed_document_total`	Number	Solo notas crédito: saldo total de la nota antes del cruce (puede ser `null`)
`crossed_document_value`	Number	Si el documento es una factura, total de las notas crédito aplicadas a esa factura; si es una nota crédito, valor de la nota usado en el cruce (puede ser `null`)
`observations`	String	Observaciones digitadas por el usuario al agregar el documento al recaudo (puede ser `null`)
`client_id`	String	Código del cliente del documento (puede ser `null`)

Objeto `meta` (Metadatos de paginación)

Campo	Tipo	Descripción
`totalItems`	Number	Cantidad total de recaudos que coinciden con los filtros
`itemCount`	Number	Cantidad de recaudos 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

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 estado

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

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"
        }
    ]
}

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`, `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: APROBADO, PENDIENTE, RECHAZADO, RETENIDO`	`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`

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.