Crear un cliente de una tienda

POST

/stores/{storeKey}/customers

Servidor de la API. El valor de host lo proporciona IDBI.

Crea el cliente en la tienda. Si ya existe un cliente con el mismo documento de identidad, se reutiliza y se actualizan sus datos de contacto.

Solo name es obligatorio. Los demás campos son opcionales y aceptan null o una cadena vacía, que se tratan como no enviados. Un cliente con documento de tipo ruc se registra como empresa.

Los tipos de documento admitidos dependen del país de la tienda. El número se valida según su tipo: por ejemplo, un DNI tiene 8 dígitos. Un documento con un formato inválido responde 422.

Authorizations

OpenApiKey
OpenApiToken

Parameters

Path Parameters

storeKey

required

string format: uuid

Identificador (UUID) de la tienda.

Example

2b7d9e40-c1a3-4f58-8e06-5a4d3c7b9f12

Request Body^required

object

name

required

Nombres del cliente, o razón social si el documento es ruc.

string

<= 191 characters

last_name

Apellidos del cliente.

string | null

<= 191 characters

birthdate

Fecha de nacimiento en formato AAAA-MM-DD.

string | null format: date

address

Dirección del cliente.

string | null

location_code

Código de ubicación geográfica (ubigeo).

string | null

sex

Sexo del cliente. Si se omite, se usa other.

string | null

Allowed values: male female other

identification

Documento de identidad del cliente. Si se omite, el cliente se crea sin documento.

object

type

Tipo de documento. Los valores admitidos dependen del país de la tienda; estos son los de Perú.

string | null

Allowed values: dni passport foreigners_card ruc

value

Número de documento, sin espacios. Se valida según el tipo.

string | null

email

Correo electrónico del cliente.

string | null format: email

phone

Teléfono del cliente.

object

country_code

Código de país del teléfono, sin +. Si se omite, se usa 51.

string | null

number

Número de teléfono. Debe ser un número válido para el código de país.

string | null

observations

Observaciones sobre el cliente en la tienda.

string | null

Examples

Solo el nombre

{
  "name": "Lucía"
}

Persona con DNI

{
  "name": "Lucía",
  "last_name": "Paredes Quispe",
  "identification": {
    "type": "dni",
    "value": "12345678"
  },
  "email": "lucia.paredes@example.com",
  "phone": {
    "number": "987654321"
  },
  "birthdate": "1990-04-17",
  "observations": "Prefiere atención en terraza"
}

Responses

201

El cliente de la tienda con los datos registrados. Guarde su uuid para identificarlo después.

Si ya existía un cliente con el mismo documento de identidad (o, si no envía documento, con el mismo nombre), trae ese cliente. Solo se actualizan el correo y el teléfono enviados; los demás datos no cambian.
identification y phone se omiten de la respuesta cuando el cliente no tiene documento o teléfono.
birthdate (AAAA-MM-DD, sin hora ni zona horaria) solo se informa si el cliente es una persona; en una organización es null. address solo se informa si el cliente es una organización.
email puede ser null.

object

data

required

object

uuid

required

Identificador del cliente.

string format: uuid

name

required

Nombre completo del cliente.

string

birthdate

required

Fecha de nacimiento en formato AAAA-MM-DD, sin hora ni zona horaria. Solo se informa cuando el cliente es una persona.

string | null format: date

address

required

Dirección. Solo se informa cuando el cliente es una organización.

string | null

email

required

Correo electrónico del cliente.

string | null

phone

Teléfono del cliente. El campo se omite cuando el cliente no tiene teléfono.

object

country_code

required

Código de país.

string

value

required

Número de teléfono.

string

identification

Documento de identidad. El campo se omite cuando el cliente no tiene documento.

object

type

required

Tipo de documento, por ejemplo dni o ruc.

string

value

required

Número de documento.

string

Examples

{
  "data": {
    "uuid": "b3e91a75-2c08-4d46-8a1f-7e5d0c9b4a62",
    "name": "Lucía Paredes Quispe",
    "birthdate": "1990-04-17",
    "address": null,
    "email": "lucia.paredes@example.com",
    "phone": {
      "country_code": "51",
      "value": "987654321"
    },
    "identification": {
      "type": "dni",
      "value": "12345678"
    }
  }
}

400

No se pudo crear el cliente. Si la causa es una regla de negocio, message la describe. Ante un error inesperado, message es Ocurrió un error inesperado, intenta nuevamente; reintente la petición y, si persiste, comuníquese con IDBI.

Formato de error con un único campo message.

object

message

required

Descripción del error.

string

Examples

{
  "message": "Ocurrió un error inesperado, intenta nuevamente"
}

401

Credenciales ausentes, inválidas, deshabilitadas o vencidas. El campo error.description indica el motivo.

Formato de error de la autenticación y del control de acceso del token.

object

error

required

Detalle del error, con su código, su mensaje y su descripción.

object

code

required

Siempre es 0.

integer

message

required

Mensaje del error.

string

description

required

Detalle del error, cuando existe.

string | null

Examples

Falta una de las cabeceras

{
  "error": {
    "code": 0,
    "message": "No autorizado",
    "description": "El token es obligatorio"
  }
}

Token que no corresponde a la clave

{
  "error": {
    "code": 0,
    "message": "No autorizado",
    "description": "El token es inválido"
  }
}

Clave inexistente

{
  "error": {
    "code": 0,
    "message": "No autorizado",
    "description": "El token no fue encontrado"
  }
}

Token deshabilitado

{
  "error": {
    "code": 0,
    "message": "No autorizado",
    "description": "El token está deshabilitado"
  }
}

Token vencido

{
  "error": {
    "code": 0,
    "message": "No autorizado",
    "description": "El token expiró"
  }
}

403

La tienda indicada en la ruta no pertenece al token. La respuesta es la misma para una tienda ajena y para una tienda inexistente.

Formato de error de la autenticación y del control de acceso del token.

object

error

required

Detalle del error, con su código, su mensaje y su descripción.

object

code

required

Siempre es 0.

integer

message

required

Mensaje del error.

string

description

required

Detalle del error, cuando existe.

string | null

Examples

{
  "error": {
    "code": 0,
    "message": "Acceso denegado",
    "description": "El token no tiene acceso a la tienda solicitada"
  }
}

422

Los datos enviados no cumplen las reglas de validación.

Formato de error cuando los datos enviados no superan la validación.

object

message

required

Mensaje general de validación.

string

errors

required

Mensajes de error agrupados por nombre de campo.

object

key

additional properties

Array<string>

Examples

{
  "message": "Uno o más de los datos que has ingresado no cumplen con los requisitos mínimos.",
  "errors": {
    "amount": [
      "El campo amount es obligatorio."
    ]
  }
}

Crear un cliente de una tienda

Authorizations

Parameters

Path Parameters

Example

Request Body required

Examples

Responses

201

Examples

400

Examples

401

Examples

403

Examples

422

Examples

Request Body^required