Modificar Direcciones de Envío

Método: POST

Endpoint

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

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
Content-Type	application/json	Indica que los datos se envían en formato JSON	Sí
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í*

* Requerido en producción (Azure valida automáticamente).

---

Parámetros del Cuerpo (Body)

El body debe ser un array de objetos, donde cada objeto representa una dirección de envío a actualizar.

Límites

Parámetro	Valor	Descripción
Mínimo de items	1	El array no puede estar vacío
Máximo de items	10,000	Número máximo de direcciones de envío por petición

Campos

El cuerpo (Body) de la solicitud debe enviarse en formato JSON y debe incluir un array con los siguientes parámetros.

Importante

Todos los campos requeridos deben estar presentes en cada objeto del array, incluso los campos que admiten nulo (Nulo: Sí). Si un campo no aplica, envíelo con valor null. La actualización reemplaza todos los campos del registro, por lo que debe enviar el estado completo deseado.

Campos de identificación

La dirección se identifica por una de dos llaves alternativas:

1. Por erp_code, cuando se envía con valor.
2. Por code (el código único de la dirección en la base de datos), cuando erp_code es null o vacío.

El erp_code tiene prioridad sobre el code

Si un objeto envía los dos, la búsqueda se hace por erp_code y el code se ignora. Por eso no es posible asignar o cambiar el erp_code de una dirección: el valor enviado es el que se usa para encontrarla, así que un erp_code que aún no existe simplemente no coincide con ningún registro y el objeto se ignora.

Campo	Tipo	Nulo	Restricciones	Descripción
code	number	Sí		Código único de la dirección en la base de datos. Llave de identificación alternativa, usada cuando erp_code es null
client_id	string (max 18)	No	No permite: espacio, #, %, &, *, {, }, \, :, <, >, ?, /, +, .	Código del cliente al que pertenece la dirección. Acota la búsqueda: el registro debe pertenecer a este cliente
description	string (max 200)	No		Nombre o descripción de la dirección de envío
country	string (max 50)	No		País de la dirección
region	string (max 50)	Sí		Región o departamento
city	string (max 100)	No		Ciudad de la dirección
address	string (max 500)	No		Dirección física completa
observations	string (max 500)	Sí		Observaciones o instrucciones de entrega
is_default	string (max 1)	No	Valores permitidos: Y, N	Indica si es la dirección predeterminada del cliente
is_active	string (max 1)	No	Valores permitidos: Y, N	Estado de la dirección (Activa/Inactiva)
erp_code	string (max 50)	Sí	Único por empresa	Código de la dirección en el sistema ERP. Es la llave de identificación principal

Formato de tipos de dato

• string (max N): Cadena de texto con longitud máxima de N caracteres.
• number: Número entero.

---

Ejemplo de Solicitud

Aquí tienes un ejemplo de cómo debería quedar el cuerpo de la solicitud en formato JSON:

[
  {
    "code": null,
    "client_id": "CLI-001",
    "description": "Bodega Principal",
    "country": "Colombia",
    "region": "Cundinamarca",
    "city": "Bogotá",
    "address": "Calle 100 #15-25 Bodega 3 - Actualizado",
    "observations": "Entregar en horario de 7am a 6pm",
    "is_default": "Y",
    "is_active": "Y",
    "erp_code": "ERP-DIR-001"
  },
  {
    "code": 1024,
    "client_id": "CLI-001",
    "description": "Bodega Norte - Renombrada",
    "country": "Colombia",
    "region": "Cundinamarca",
    "city": "Bogotá",
    "address": "Autopista Norte #200-10",
    "observations": null,
    "is_default": "N",
    "is_active": "Y",
    "erp_code": null
  }
]

---

Ejemplo de Respuesta

200 - OK

{
    "statusCode": 200,
    "message": "Shipping addresses updated successfully"
}

Comportamiento de actualización

• Si se envía erp_code, la coincidencia se realiza por empresa + client_id + erp_code.
• Si erp_code es null o vacío, la coincidencia se realiza por empresa + client_id + code.
• Los objetos que no coincidan por ninguna de las dos condiciones serán ignorados sin generar error. Esto incluye los que envíen code y erp_code ambos en null, los que envíen un code de otro cliente o de otra empresa, y los que envíen un erp_code que aún no existe.

Status 400

{
    "statusCode": 400,
    "errors": [
        {
            "message": "Invalid JSON in request body"
        }
    ]
}

Status 415

{
    "statusCode": 415,
    "errors": [
        {
            "message": "Content-Type: application/json is required"
        }
    ]
}

Status 422

Errores globales (estructura del body)

Si el body no es un array:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Request body must be an array"
        }
    ]
}

Si el array está vacío:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Request body cannot be empty"
        }
    ]
}

Si excede el límite de 10,000 items:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Array exceeds maximum limit of 10000 items"
        }
    ]
}

Errores por item (validación de campos)

Los errores se agrupan por el índice del item en el array:

{
    "statusCode": 422,
    "errors": [
        {
            "index": 0,
            "errors": [
                {
                    "field": "city",
                    "message": "Field is required"
                },
                {
                    "field": "is_active",
                    "message": "Value must be one of: Y, N"
                }
            ]
        }
    ]
}

Tipos de Errores de Validación por Campo

Errores de presencia y nulidad:

Error	Descripción
Field is required	El campo no fue enviado en el objeto (la clave no existe)
Field cannot be null or empty	El campo fue enviado con valor null o vacío y no acepta nulos
Unknown field	Se envió un campo que no existe en la configuración
Item must be an object	Un elemento del array no es un objeto JSON

Errores de tipo de dato:

Error	Descripción
Field must be a string	El valor no es una cadena de texto
Field must be of type integer	El valor de code no es un número entero
Field must be a valid integer	El valor de code es una cadena que no representa un entero

Errores de longitud:

Error	Descripción
Field exceeds maximum length of X characters	La cadena excede la longitud máxima permitida

Errores de valores permitidos:

Error	Descripción
Value must be one of: Y, N	El valor no está en la lista de valores permitidos

Errores de formato:

Error	Descripción
Field contains forbidden characters. The following are not allowed: space, #, %, &, *, {, }, \, :, <, >, ?, /, +, .	El campo client_id contiene caracteres prohibidos

Status 423

{
    "statusCode": 423,
    "errors": [
        {
            "message": "Resource is locked and cannot be accessed."
        }
    ]
}

Recurso bloqueado

Este error ocurre cuando otra operación de creación o actualización de direcciones de envío con la misma Subscription-Key está en progreso. Espere a que la operación anterior finalice e intente nuevamente.

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 Redis

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Redis operation failed"
        }
    ]
}

Error inesperado

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error"
        }
    ]
}

Error del Servidor

Estos errores indican problemas internos en el servidor, la base de datos o el servicio de cache. Si persisten, contacta al equipo de soporte.