Ir al contenido
IDPOS IDPOS Developers

Crear un anticipo

POST
/stores/{storeKey}/advances

Crea un anticipo para un cliente de la tienda. El cliente se busca por su documento de identidad y se crea si no existe. La moneda debe estar habilitada en la tienda y la tienda debe tener una caja activa.

Si pay_now es true, se registra el cobro del anticipo con el método de pago indicado en payment, que debe estar habilitado en la tienda. Si además issue_receipt es true, se emite el comprobante y se envía por correo a customer.email.

La respuesta no incluye el identificador del anticipo creado. Si el cobro falla después de crear el anticipo, la respuesta es 400, el anticipo queda creado sin cobro y la respuesta no incluye su identificador.

Authorizations

Sección titulada «Authorizations »

Parameters

Sección titulada « Parameters »

Path Parameters

Sección titulada «Path Parameters »
storeKey
required
string format: uuid

Identificador (UUID) de la tienda.

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

Request Body required

Sección titulada «Request Body required »
object
description
required

Descripción del anticipo.

string
>= 4 characters <= 191 characters
amount
required

Importe del anticipo.

number
> 0 < 1000000
currency
required

Identificador de la moneda. Debe estar habilitada en la tienda.

string format: uuid
customer
required

Datos del cliente. No admite campos adicionales.

object
name
required

Nombres del cliente.

string
<= 191 characters
lastname
required

Apellidos del cliente.

string
<= 191 characters
email
required

Correo electrónico del cliente.

string format: email
<= 191 characters
identification_type
required

Tipo de documento.

string
Allowed values: dni passport foreigners_card ruc
identification_value
required

Número de documento, sin espacios. Se valida según el tipo de documento; por ejemplo, el DNI tiene 8 dígitos.

string
/^\S+$/
pay_now

Si es true, se registra el cobro del anticipo. Requiere payment.

boolean
payment

Datos del cobro. Obligatorio cuando pay_now es true. No admite campos adicionales.

object
payment_method
required

Identificador del método de pago. Debe estar habilitado en la tienda.

string format: uuid
reference_number
required

Número de referencia del cobro, solo dígitos.

string
>= 4 characters <= 20 characters /^[0-9]+$/
last_four_digits
required

Últimos cuatro dígitos de la tarjeta.

string
/^[0-9]{4}$/
issue_receipt

Si es true y pay_now es true, se emite el comprobante y se envía por correo a customer.email.

boolean
Examples

Anticipo sin cobro

{
  "description": "Anticipo para evento corporativo",
  "amount": 500,
  "currency": "719b61f7-0e77-4e7c-8e78-7a9b51791c29",
  "customer": {
    "name": "Lucía",
    "lastname": "Paredes Quispe",
    "email": "lucia.paredes@example.com",
    "identification_type": "dni",
    "identification_value": "12345678"
  }
}

Responses

Sección titulada « Responses »

201

Sección titulada «201 »

Confirma que el anticipo se creó. El cuerpo solo trae un mensaje de confirmación en data.message.

  • No incluye el identificador del anticipo creado.
  • Con pay_now en true, un 201 indica que el anticipo se creó y que su cobro quedó registrado.
  • Un 400 no garantiza que el anticipo no se haya creado: puede haber quedado creado sin cobro, o cobrado si falló la emisión del comprobante.
object
data
required

Resultado de la operación, con un mensaje de confirmación.

object
message
required

Mensaje de confirmación.

string
Examples
{
  "data": {
    "message": "Anticipo creado correctamente"
  }
}

400

Sección titulada «400 »

No se pudo crear el anticipo. El campo error.message trae un texto del error; su redacción puede cambiar, por lo que no debe usarlo como identificador del motivo. Si el error ocurrió en el cobro, el anticipo puede haberse creado sin cobro.

Formato de error con error.message.

object
error
required

Detalle del error, con su mensaje.

object
message
required

Descripción del error.

string
Examples
{
  "error": {
    "message": "La moneda no esta habilitada para esta tienda"
  }
}

401

Sección titulada «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"
  }
}

403

Sección titulada «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

Sección titulada «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."
    ]
  }
}