Listar Direcciones de Envío

Método: GET

Endpoint

https://api.ventasremotas.com/v1/shipping-addresses

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 direcciones de envío con la paginación por defecto.

Filtros

Parámetro	Tipo	Descripción
client_id	String	Filtra por código exacto de cliente. Longitud máxima: 18 caracteres.
is_active	String	Filtra por estado de la dirección. Valores permitidos: Y (activa), N (inactiva). Longitud máxima: 1 carácter.
created_from	Date	Retorna registros cuya fecha de creación es mayor o igual a este valor. Formato: YYYY-MM-DD.
modified_from	Date	Retorna registros cuya fecha de modificación es mayor o igual a este valor. Formato: YYYY-MM-DD.

Filtros de fecha

Los filtros created_from y modified_from se agrupan con un operador OR cuando se usan juntos. Esto significa que al enviar ambos, se retornarán registros que cumplan cualquiera de las dos condiciones (creados desde esa fecha o modificados desde esa fecha).

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: 1000	Cantidad de resultados por página

---

Ejemplo de Solicitud

Petición básica (sin filtros)

curl -X GET "https://api.ventasremotas.com/v1/shipping-addresses" \
  -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/shipping-addresses?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 y paginación

curl -X GET "https://api.ventasremotas.com/v1/shipping-addresses?is_active=Y&page=1&limit=50" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con filtro de fecha

curl -X GET "https://api.ventasremotas.com/v1/shipping-addresses?created_from=2024-01-01&sort=-created_at&limit=100" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

---

Ejemplo de Respuesta

200 - OK

{
    "data": [
        {
            "code": 1024,
            "client_id": "CLI-001",
            "description": "Bodega Principal",
            "country": "Colombia",
            "region": "Cundinamarca",
            "city": "Bogotá",
            "address": "Calle 100 #15-25 Bodega 3",
            "observations": "Entregar en horario de 8am a 5pm",
            "is_default": "Y",
            "is_active": "Y",
            "erp_code": "ERP-DIR-001",
            "created_at": "2024-06-15T10:30:00",
            "updated_at": "2024-09-20T14:15:00"
        }
    ],
    "meta": {
        "totalItems": 320,
        "itemCount": 100,
        "itemsPerPage": 100,
        "totalPages": 4,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/shipping-addresses?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/shipping-addresses?page=1&limit=100",
        "prev": null,
        "next": "https://api.ventasremotas.com/v1/shipping-addresses?page=2&limit=100",
        "last": "https://api.ventasremotas.com/v1/shipping-addresses?page=4&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Dirección de Envío)

Cada elemento del array data contiene los siguientes campos:

Campo	Tipo	Descripción
code	Number	Código único de la dirección en la base de datos. Es inmutable y sirve como clave de identificación al actualizar
client_id	String	Código del cliente al que pertenece la dirección
description	String	Nombre o descripción identificadora de la dirección de envío
country	String	País de la dirección
region	String	Región o departamento (puede ser null)
city	String	Ciudad de la dirección
address	String	Dirección física completa
observations	String	Observaciones o instrucciones de entrega (puede ser null)
is_default	String	Indica si es la dirección predeterminada del cliente: Y o N
is_active	String	Estado de la dirección (Activa/Inactiva): Y o N
erp_code	String	Código de la dirección en el sistema ERP. Actúa como clave alternativa de identificación (puede ser null)
created_at	DateTime	Fecha y hora de creación. Formato: yyyy-MM-ddTHH:mm:ss
updated_at	DateTime	Fecha y hora de última modificación. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)

Objeto meta (Metadatos de paginación)

Campo	Tipo	Descripción
totalItems	Number	Cantidad total de registros que coinciden con los filtros
itemCount	Number	Cantidad de registros 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": "client_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)"
        }
    ]
}

Campo de ordenamiento inválido

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

Parámetro de paginación inválido

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

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.

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 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.