Descargar Formularios

Permite obtener el listado de formularios gestionados que aún no han sido transmitidos al ERP, incluyendo el detalle de preguntas y respuestas de cada formulario. Este endpoint está diseñado para que los sistemas de los clientes puedan descargar los formularios diligenciados en RSales e inyectarlos en sus propios sistemas. Soporta filtros por vendedor, cliente, código de formulario y fecha de creación, así como ordenamiento configurable y paginación.

Importante

Este endpoint solo retorna formularios que no han sido transmitidos y que no pertenecen a flujos de solicitud.

Método: GET

Endpoint

https://api.ventasremotas.com/v1/forms/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 formularios 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.
client_id	String	Filtra por código exacto de cliente. Longitud máxima: 18 caracteres.
created_from	Date	Retorna formularios 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: 100	Cantidad de resultados por página

---

Ejemplo de Solicitud

Petición básica (sin filtros)

curl -X GET "https://api.ventasremotas.com/v1/forms/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/forms/pending?seller_id=VEN-001" \
  -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/forms/pending?created_from=2026-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/forms/pending?seller_id=VEN-001&client_id=CLI-001&created_from=2026-01-01&sort=created_at&page=1&limit=100" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

---

Ejemplo de Respuesta

200 - OK

{
    "data": [
        {
            "seller_id": "VEN-001",
            "result_code": 98501,
            "client_id": "CLI-001",
            "name": "Formulario de Visita",
            "type": "VISITA",
            "created_at": "2026-01-15T09:30:00",
            "latitude": 4.7109886,
            "longitude": -74.072092,
            "address": "Calle 100 #15-25",
            "show_in": "V",
            "cell_info": "1.0.0|357123456789012",
            "precision": 12.5,
            "battery": 85.0,
            "management_code": "GES-001",
            "total_score": 100.0,
            "obtained_score": 87.5,
            "visit_time": 180,
            "results": [
                {
                    "question_code": 1,
                    "parent_question_code": null,
                    "question_type": "Selección única",
                    "question": "¿El cliente exhibe el producto correctamente?",
                    "value": "Sí",
                    "not_applicable": "N",
                    "total_score": 25.0,
                    "obtained_score": 25.0
                },
                {
                    "question_code": 2,
                    "parent_question_code": null,
                    "question_type": "Texto libre",
                    "question": "Observaciones generales",
                    "value": "Todo en orden",
                    "not_applicable": "N",
                    "total_score": 0.0,
                    "obtained_score": 0.0
                }
            ]
        },
        {
            "seller_id": "VEN-002",
            "result_code": 98502,
            "client_id": null,
            "name": "Formulario de Auditoría",
            "type": "Visita",
            "created_at": "2026-01-15T10:00:00",
            "latitude": null,
            "longitude": null,
            "address": null,
            "show_in": null,
            "cell_info": null,
            "precision": null,
            "battery": null,
            "management_code": null,
            "total_score": null,
            "obtained_score": null,
            "visit_time": null,
            "results": []
        }
    ],
    "meta": {
        "totalItems": 42,
        "itemCount": 2,
        "itemsPerPage": 100,
        "totalPages": 1,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/forms/pending?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/forms/pending?page=1&limit=100",
        "prev": null,
        "next": null,
        "last": "https://api.ventasremotas.com/v1/forms/pending?page=1&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Formulario)

Cada elemento del array data contiene los siguientes campos:

Campo	Tipo	Descripción
seller_id	String	Código del vendedor que diligenció el formulario (puede ser null)
result_code	Number	Código único del resultado del formulario diligenciado
client_id	String	Código del cliente asociado al formulario (puede ser null)
name	String	Nombre o título del formulario según su configuración en RSales
type	String	Tipo o categoría del formulario según su configuración en RSales. Ejemplos: VISITA, AUDITORÍA (puede ser null)
created_at	DateTime	Fecha de creación del formulario. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
latitude	Number	Coordenada de latitud registrada al diligenciar el formulario (puede ser null)
longitude	Number	Coordenada de longitud registrada al diligenciar el formulario (puede ser null)
address	String	Dirección geo-referenciada registrada al momento de diligenciar el formulario (puede ser null)
show_in	String	Contexto en que se diligenció el formulario. V: diligenciado durante una visita activa al cliente; P: formulario planeado sin visita activa asociada. Puede venir vacío o null
cell_info	String	Versión de la aplicación e IMEI del dispositivo, en formato version|IMEI. Ejemplo: 1.0.0|357123456789012 (puede ser null)
precision	Number	Precisión del GPS en metros al momento del registro (puede ser null)
battery	Number	Porcentaje de batería del dispositivo al momento del registro. Valor de 0 a 100 (puede ser null)
management_code	String	Código de gestión de visita asociado al formulario, si fue diligenciado dentro de una gestión (puede ser null)
total_score	Number	Puntaje total posible del formulario según su configuración (puede ser null)
obtained_score	Number	Puntaje obtenido por el vendedor al diligenciar el formulario (puede ser null)
visit_time	Number	Tiempo en segundos que tardó el vendedor en diligenciar el formulario (puede ser null)
results	Array	Lista de preguntas y respuestas del formulario. Puede venir vacío

Objeto results[] (Pregunta / Respuesta)

Cada elemento del array results dentro de un formulario contiene:

Campo	Tipo	Descripción
question_code	Number	Código único de la pregunta
parent_question_code	Number	Código de la pregunta padre, cuando se trate de preguntas anidadas o de una pregunta interna dentro de una tabla. (puede ser null)
question_type	String	Tipo de pregunta según la configuración del formulario. Valores posibles: Simple, Multiple, Descripcion, Imagen, Audio, Documento, Numero, Video, Fecha, Firma, Correo Electrónico, Tabla, Escaner código de Barras/QR
question	String	Texto de la pregunta tal como fue configurada en el formulario
value	String	Respuesta registrada por el vendedor. Para preguntas de selección, contiene el texto de la opción seleccionada; para texto libre, el valor ingresado (puede ser null)
not_applicable	String	Indica si la pregunta fue marcada como no aplica por el vendedor. Y: marcada como no aplica, N: respondida normalmente
total_score	Number	Puntaje total posible para esta pregunta según la configuración del formulario
obtained_score	Number	Puntaje obtenido en esta pregunta según la respuesta seleccionada

Objeto meta (Metadatos de paginación)

Campo	Tipo	Descripción
totalItems	Number	Cantidad total de formularios que coinciden con los filtros
itemCount	Number	Cantidad de formularios 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-2026' 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 100"
        }
    ]
}

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
Value 'X' is not a valid date (expected format: YYYY-MM-DD)	created_from
Value exceeds maximum length of 18	seller_id, client_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 100	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.