Direcciones de envío

Antes de empezar

• Un cliente puede tener varias direcciones y solo una por defecto. Al marcar una como predeterminada, las demás dejan de serlo.
• La dirección por defecto es la que se usa para calcular el envío cuando no se indica el destino.
• Si se borra la dirección por defecto, no se elige otra automáticamente.

Listar direcciones

GET /api/v1/ecommerce/addresses

Respuesta

{
  "success": true,
  "message": "Listado de tipo de direcciones mostrados de forma correcta.",
  "data": [
    {
      "id": 5,
      "description": "Casa",
      "address": "Av. Arequipa 1234, Dpto 501",
      "country": "PE",
      "extra": [
        { "national_division": "Departamento", "value": "Lima", "ubigeo": "15" },
        { "national_division": "Provincia", "value": "Lima", "ubigeo": "1501" },
        { "national_division": "Distrito", "value": "Miraflores", "ubigeo": "150122" }
      ],
      "postal_code": "15074",
      "default": true
    }
  ]
}

Campo	Tipo	Qué es
description	texto	Nombre que el cliente le da, por ejemplo «Casa»
address	texto	Calle, número y referencias
country	texto	Código del país, por ejemplo PE
extra	lista	Niveles territoriales de la dirección, tal como se guardaron
postal_code	texto	Código postal. Vale Ninguno si no se indicó
default	booleano	Si es la dirección por defecto

Guardar una dirección

POST /api/v1/ecommerce/addresses/register

Cuerpo

Campo	Tipo	Obligatorio	Reglas
description	texto	Sí	Máximo 250 caracteres
address	texto	Sí	Máximo 250 caracteres
country_id	texto	Sí, envíalo siempre	2 letras de un país activo, por ejemplo PE. Si lo omites o lo envías null, la validación lo deja pasar pero el guardado falla: responde 500 en vez de 422
extra	lista	Sí	Entre 1 y 5 niveles territoriales
extra[].national_division	texto	Sí	Nombre del nivel: Departamento, Provincia, Distrito… Máximo 100 caracteres
extra[].value	texto	Sí	Valor de ese nivel, por ejemplo Lima. Máximo 100 caracteres
extra[].ubigeo	texto	No	Código de ubigeo de ese nivel. Máximo 10 caracteres
postal_code	texto	No	Máximo 15 caracteres
default	booleano	Sí	true para que sea la dirección por defecto

{
  "description": "Casa",
  "address": "Av. Arequipa 1234, Dpto 501",
  "country_id": "PE",
  "extra": [
    { "national_division": "Departamento", "value": "Lima", "ubigeo": "15" },
    { "national_division": "Provincia", "value": "Lima", "ubigeo": "1501" },
    { "national_division": "Distrito", "value": "Miraflores", "ubigeo": "150122" }
  ],
  "postal_code": "15074",
  "default": true
}

Para calcular el envío a domicilio o a agencia, el tercer nivel de extra (el distrito) debe llevar su ubigeo de 6 cifras.

Respuesta

Devuelve la dirección guardada, con los mismos campos que el listado.

Si algo sale mal

HTTP	code	Cuándo	Qué hacer
422	VALIDATION_ERROR	Falta un campo, se pasa de largo o el país no existe	Corrige el campo que indica errors

Editar una dirección

PUT /api/v1/ecommerce/addresses/update/{addressId}

• addressId: identificador de la dirección.
• El cuerpo es el mismo que al guardarla. extra se reemplaza entero, así que envía todos sus niveles.

Devuelve la dirección actualizada.

Si algo sale mal

HTTP	code	Cuándo	Qué hacer
422	VALIDATION_ERROR	Algún dato no cumple las reglas	Corrige el campo que indica errors
404	ADDRESS_NOT_FOUND	La dirección no existe o no es del cliente	Vuelve a listar las direcciones

Borrar una dirección

DELETE /api/v1/ecommerce/addresses/delete/{addressId}

{ "success": true, "message": "Información procesada con éxito", "data": null }

Si algo sale mal

HTTP	code	Cuándo
404	ADDRESS_NOT_FOUND	La dirección no existe o no es del cliente