# Crear una instantánea de préstamo

Crear una nueva instantánea de préstamo para un cliente. Cada solicitud exitosa registra la instantánea con una fecha objetivo de cobro, establecida para el mismo día o el siguiente día hábil en México, y Belvo intenta realizar el cobro en esa fecha. La respuesta devuelve el id de la instantánea recién creada.

El monto recaudado no se toma de esta solicitud. Se calcula según la estrategia de cobro que Belvo aplica a tus préstamos, basada en el totalBalance que envías, y un solo préstamo puede resultar en más de un intento de cobro. Cuando un intento de cobro se completa, Belvo envía una notificación webhook con el resultado.

Endpoint: POST /loans
Version: 1.0.0
Security: ApiKeyAuth, ApiKeySecret

## Request fields (application/json):

  - `paymentMethodId` (string, required)
    El paymentMethod.id asociado con este préstamo. El método de pago debe existir y pertenecer al comerciante.

  - `merchantCustomerId` (string, required)
    Su identificador único para el cliente. Máximo 50 caracteres, solo alfanumérico.

  - `daysOverdue` (integer, required)
    El número de días que el préstamo está vencido. Debe ser 0 o mayor.

  - `totalBalance` (number, required)
    El monto aún adeudado en el préstamo. La estrategia de cobro de Belvo utiliza este valor como base para calcular cuánto cobrar, por lo que envíe el monto pendiente en lugar del monto original del préstamo. Debe ser positivo y no exceder 9999999999.99.

  - `principalAmount` (number, required)
    El monto principal del préstamo. Este valor no se utiliza para determinar cuánto cobra Belvo; el monto cobrado se calcula a partir de totalBalance. Debe ser positivo y no exceder 9999999999.99.

  - `defaultDate` (string, required)
    La fecha en que el cliente incumplió con este préstamo, en formato YYYY-MM-DD.

  - `issueDate` (string, required)
    La fecha en que se emitió originalmente el préstamo, en formato YYYY-MM-DD.

  - `loanAmount` (number)
    El monto original del préstamo. Debe ser mayor que 0.

  - `interestAmount` (number)
    El monto de interés acumulado. Debe ser 0 o mayor.

  - `feesAmount` (number)
    Cualquier tarifa asociada con el préstamo. Debe ser 0 o mayor.

  - `latePaymentInterestAmount` (number)
    Intereses acumulados debido al pago tardío. Debe ser 0 o mayor.

  - `openingCommissionAmount` (number)
    Comisión de apertura cobrada por el préstamo. Debe ser 0 o mayor.

  - `yearlyOrdinalInterestRate` (number)
    La tasa de interés anual con hasta 4 decimales.

  - `customerSalary` (number)
    El salario del cliente. Debe ser positivo y no exceder 99999999.99.

  - `customerAddress` (string)
    La dirección del cliente. Máximo 200 caracteres.

  - `creditStatus` (string)
    El estado de crédito del préstamo. Puede ser uno de los siguientes:
  - past_due
    El pago está vencido.
  - restructured
    El préstamo ha sido reestructurado.
  - canceled
    El préstamo ha sido cancelado.
  - in_arrears
    El préstamo está en mora.
    Enum: "past_due", "restructured", "canceled", "in_arrears"

  - `paidInstallments` (integer)
    El número de cuotas ya pagadas. Debe ser 0 o mayor.

  - `paidAmount` (number)
    El monto total ya pagado hacia el préstamo. Este valor no reduce totalBalance; envíe el monto aún adeudado en totalBalance. Debe ser 0 o mayor.

  - `lastPaymentDate` (string)
    La fecha del último pago en formato YYYY-MM-DD.

  - `lastPaymentAmount` (number)
    El monto del último pago. Debe ser 0 o mayor.

  - `mainPhoneNumber` (string)
    El número de teléfono principal del cliente con el prefijo del código de país.

  - `reference` (string)
    Su referencia para este préstamo. Máximo 50 caracteres.

## Response 201 fields (application/json):

  - `id` (string)
    El identificador único del registro de historial de préstamo recién creado.
    Example: "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"

## Response 400 fields (application/json):

  - `statusCode` (integer)
    El código de estado HTTP para este error.
    Example: 400

  - `error` (string)
    La descripción del código de estado HTTP para este error.
    Example: "Bad Request"

  - `message` (any)
    Una breve descripción del error, indicando qué está mal con la solicitud.
> Nota: Devolvemos una cadena o un arreglo de cadenas, dependiendo del/los error(es) de validación.

La descripción puede ser (entre otras):

  - id must be a UUID
  - Not enough balance
  - amount is not a valid decimal number.
  - currency must be one of the following values: cop, mxn, usd
  - reference must be a string
  - Customer not found for merchant
  - documentType is a required field
    Example: "id must be a UUID"

## Response 401 fields (application/json):

  - `statusCode` (integer)
    El código de estado HTTP para este error.
    Example: 401

  - `error` (string)
    La descripción del código de estado HTTP para este error.
    Example: "Unauthorized"

  - `message` (string)
    Una breve descripción del error, indicando qué está mal con la solicitud. En el caso de un error 401 Unauthorized, el mensaje es:

  - Unauthorized credentials
    Example: "Unauthorized credentials"

## Response 403 fields (application/json):

  - `statusCode` (integer)
    El código de estado HTTP para este error.
    Example: 403

  - `error` (string)
    La descripción del código de estado HTTP para este error.
    Example: "Forbidden"

  - `message` (string)
    Una breve descripción del error, indicando por qué la solicitud está prohibida.
    Example: "Forbidden"

## Response 404 fields (application/json):

  - `statusCode` (integer)
    El código de estado HTTP para este error.
    Example: 404

  - `error` (string)
    La descripción del código de estado HTTP para este error.
    Example: "Not Found"

  - `message` (string)
    Una breve descripción del error, indicando qué está mal con la solicitud. La descripción puede ser (entre otras):

  - Payout Target not found
  - Payment method not found
  - Customer not found
    Example: "Payout Target not found"

## Response 409 fields (application/json):

  - `statusCode` (integer)
    El código de estado HTTP para este error.
    Example: 409

  - `error` (string)
    La descripción del código de estado HTTP para este error.
    Example: "Conflict"

  - `message` (string)
    Una breve descripción del error, indicando la naturaleza del conflicto. La descripción puede ser (entre otras):

  - A loan snapshot with this merchantCustomerId and defaultDate already exists
  - An operation is already in progress for this idempotency key
    Example: "A loan snapshot with this merchantCustomerId and defaultDate already exists"