Crear Formas de Pago

Permite crear una o múltiples formas de pago en el sistema mediante una única petición. Este endpoint está diseñado para operaciones en lote (batch), permitiendo insertar hasta 10,000 registros por petición.

Método: POST

Endpoint

https://api.ventasremotas.com/v1/payment-methods/batch-create

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
Content-Type	application/json	Indica que los datos se envían en formato JSON
Accept	application/json	Indica que la respuesta debe estar en formato JSON
Subscription-Key	{subscription_key}	Clave de suscripción para acceder a la API
Authorization	Bearer {access_token}	Token de acceso obtenido del endpoint /token

---

Parámetros del Cuerpo (Body)

El body debe ser un array de objetos, donde cada objeto representa una forma de pago a crear.

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 formas de pago 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 para una forma de pago, envíelo con valor null.

Campo	Tipo	Nulo	Restricciones	Descripción
code	string (max 10)	No	No permite: espacio, #, %, &, *, {, }, \, :, <, >, ?, /, +, .	Código único de la forma de pago
description	string (max 50)	No		Descripción de la forma de pago
orders_state	string (max 50)	Sí	Valores permitidos: APROBADO, RETENIDO, PENDIENTE, RECHAZADO	Estado por defecto que se asignará a los pedidos al utilizar esta forma de pago
payments_state	string (max 50)	Sí	Valores permitidos: APROBADO, RETENIDO, PENDIENTE, RECHAZADO	Estado por defecto que se asignará a los recaudos al utilizar esta forma de pago
invoices_state	string (max 50)	Sí	Valores permitidos: APROBADO, RETENIDO, PENDIENTE, RECHAZADO	Estado por defecto que se asignará a las facturas al utilizar esta forma de pago
quotes_state	string (max 50)	Sí	Valores permitidos: APROBADO, RETENIDO, PENDIENTE, RECHAZADO	Estado por defecto que se asignará a las cotizaciones al utilizar esta forma de pago
returns_state	string (max 50)	Sí	Valores permitidos: APROBADO, RETENIDO, PENDIENTE, RECHAZADO	Estado por defecto que se asignará a las devoluciones al utilizar esta forma de pago
online_invoices_state	string (max 100)	Sí	Valores permitidos: APROBADO, RETENIDO, PENDIENTE, RECHAZADO	Estado por defecto para facturas con pago en línea
online_orders_state	string (max 100)	Sí	Valores permitidos: APROBADO, RETENIDO, PENDIENTE, RECHAZADO	Estado por defecto para pedidos con pago en línea
online_quotes_state	string (max 100)	Sí	Valores permitidos: APROBADO, RETENIDO, PENDIENTE, RECHAZADO	Estado por defecto para cotizaciones con pago en línea
module	string (max 1)	Sí	Valores permitidos: P, R, A	Módulo en el que se podrá utilizar la forma de pago. P = Transacciones de Venta (Pedidos, Cotizaciones, Facturas y Devoluciones), R = Recaudos, A = Ambos
method_type	string (max 1)	Sí	Valores permitidos: 0, 1, 2, 3	Tipo de pago. 0 = Ninguna, 1 = Efectivo, 2 = Cheque, 3 = Consignación
require_bank	string (max 1)	Sí	Valores permitidos: Y, N	Indica si se requiere obligatoriamente seleccionar un banco
require_account_number	string (max 1)	Sí	Valores permitidos: Y, N	Indica si se requiere obligatoriamente ingresar el número de cuenta bancaria
accumulate_payment	string (max 1)	Sí	Valores permitidos: Y, N	Indica si se debe acumular el recaudo
state	string (max 1)	No	Valores permitidos: Y, N	Estado de la forma de pago (Activo/Inactivo)
exclusive_for_sales	string (max 1)	Sí	Valores permitidos: F, P	Indica si la forma de pago es exclusiva para el módulo de Facturas (F) o para el módulo de Pedidos (P). Aplica si a nivel de usuario la opción “Permitir Cambiar formas de pago” está en “Uso exclusivo para venta”
maximum_value_per_transaction	decimal (18, 0)	Sí		Valor máximo permitido por transacción en los módulos de venta (Pedido, Factura, Devolución o Cotización)
payment_type	string (max 1)	Sí	Valores permitidos: 0, 1, 2, 3	Mostrar en tipo de recaudo. 0 = Ninguna, 1 = Ambos, 2 = Abono, 3 = Anticipo
require_attachment	string (max 1)	Sí	Valores permitidos: Y, N	Indica si se requiere obligatoriamente adjuntar un archivo o comprobante
require_receipt_number	string (max 1)	Sí	Valores permitidos: Y, N	Indica si se requiere obligatoriamente ingresar el número de comprobante
allow_online_payment	string (max 1)	Sí	Valores permitidos: Y, N	Indica si la forma de pago permite pago en línea
require_bank_account_origin	string (max 1)	Sí	Valores permitidos: Y, N	Indica si se requiere obligatoriamente la cuenta bancaria de origen
require_bank_origin_cheque	string (max 1)	Sí	Valores permitidos: Y, N	Indica si se requiere obligatoriamente el banco de origen del cheque

Formato de tipos de dato

• string (max N): Cadena de texto con longitud máxima de N caracteres.
• decimal (p, s): Número decimal donde p es la precisión total (dígitos enteros + decimales) y s es la escala (dígitos decimales).
  • Ejemplo: decimal (18, 0) permite hasta 18 dígitos enteros sin decimales (ej: 999999999999999999)

---

Ejemplo de Solicitud

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

[
  {
    "code": "EFE",
    "description": "Efectivo",
    "orders_state": "APROBADO",
    "payments_state": "APROBADO",
    "invoices_state": "APROBADO",
    "quotes_state": "APROBADO",
    "returns_state": "APROBADO",
    "online_invoices_state": null,
    "online_orders_state": null,
    "online_quotes_state": null,
    "module": "A",
    "method_type": "1",
    "require_bank": "N",
    "require_account_number": "N",
    "accumulate_payment": "N",
    "state": "Y",
    "exclusive_for_sales": null,
    "maximum_value_per_transaction": null,
    "payment_type": "1",
    "require_attachment": "N",
    "require_receipt_number": "N",
    "allow_online_payment": "N",
    "require_bank_account_origin": "N",
    "require_bank_origin_cheque": "N"
  },
  {
    "code": "CHQ",
    "description": "Cheque",
    "orders_state": "RETENIDO",
    "payments_state": "RETENIDO",
    "invoices_state": "RETENIDO",
    "quotes_state": "RETENIDO",
    "returns_state": "RETENIDO",
    "online_invoices_state": null,
    "online_orders_state": null,
    "online_quotes_state": null,
    "module": "P",
    "method_type": "2",
    "require_bank": "Y",
    "require_account_number": "Y",
    "accumulate_payment": "N",
    "state": "Y",
    "exclusive_for_sales": "F",
    "maximum_value_per_transaction": 5000000,
    "payment_type": "0",
    "require_attachment": "Y",
    "require_receipt_number": "Y",
    "allow_online_payment": "N",
    "require_bank_account_origin": "Y",
    "require_bank_origin_cheque": "Y"
  }
]

---

Ejemplo de Respuesta

201 - OK

{
    "statusCode": 201,
    "message": "Payment methods created successfully"
}

Importante

Las formas de pago que ya existan en el sistema (mismo code) serán ignoradas sin generar error. Solo se insertarán las formas de pago nuevas.

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": "code",
                    "message": "Field is required"
                },
                {
                    "field": "description",
                    "message": "Field is required"
                }
            ]
        },
        {
            "index": 2,
            "errors": [
                {
                    "field": "code",
                    "message": "Field exceeds maximum length of 10 characters"
                }
            ]
        }
    ]
}

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 decimal	El valor no es un número decimal válido
Field must be a valid decimal (e.g., 1.5, 10.25)	El formato del decimal es inválido
Field must be a valid decimal number	El valor no es un número decimal válido (NaN, Infinity)

Errores de longitud y precisión:

Error	Descripción
Field exceeds maximum length of X characters	La cadena excede la longitud máxima permitida
Field exceeds maximum of X integer digits (precision: P, scale: S)	El número excede los dígitos enteros permitidos

Errores de valores permitidos:

Error	Descripción
Value must be one of: X, Y	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 code 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 formas de pago 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 en validaciones

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

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.