Form

Formularios personalizables. Registra tanto los formularios de pago como los formularios de pruebas de entrega.

El atributo name contiene el nombre del método de pago a mostrar en la lista.

Si el formulario está desactivado, tendrá disabled = true.

El atributo icon es un campo numérico que indica el icono a mostrar. La lista de iconos es fija y está previamente configurada.

currency contiene la información de la moneda a usar para el pago. Este objeto contiene dos atributos adicionales, tax_flat_e2 y tax_percent, que contienen información de las tarifas adicionales a cobrar por usar el método de pago. Si cualquiera de esos valores es mayor a cero, se debe mostrar una advertencia indicando que se cobrará una tarifa adicional. Por ejemplo: Si tax_flat_e2 = 50 se mostrara algo como: "Al seleccionar Pago Móvil, se cobrará un impuesto adicional de $0.50" (texto de ejemplo). Si tax_percent = 0.05 se mostrará "impuesto de 5%" o si ambos campos tienen valor, por ejemplo, tax_flat_e2 = 30; tax_percent = 0.03 se cobrará "3% + $0.30"

Por otra parte, el campo label_url muestra una imagen grande en el formulario. Útil para mostrar QR. Podría ser null.

El atributo data contiene los parámetros a mostrar del formulario. Se trata de un array de objetos que contienen un único atributo. Según el nombre de ese atributo, se debe mostrar un componente diferente en el formulario:

text: Se trata de un texto a mostrar. No se requiere respuesta del usuario. Útil para mostrar información como el número de pago móvil o cuenta bancaria para el depósito.
- question: Título a mostrar.
- content: Texto descriptivo.
input: Se trata de un campo de entrada de texto convencional.
- question: Título de la pregunta.
- required: Indica si es obligatorio para el servidor. Se debe mostrar un asterisco rojo y validar que no esté vacío al momento de enviar.
- hint: El texto de ayuda a mostrar en el campo (placeholder).
- regex: Regla para validar el campo. Se debe ignorar el primer y último caracter del regex para usar en JS.
- type: El tipo de entrada. Podría ser: text (normal), text_area (multilinea), date (calendario), numeric (sólo números), bank (mostrar icono de banco).
- key: Booleano que indica que el campo contiene el campo clave de identificador del pago. Se utiliza para la validación de pagos automatizada.
boolean: Se trata de un check. Útil para aceptar términos.
- question: Título a mostrar.
- required: Indica si es obligatorio estar checked == true para enviar el formulario.
option: Campo de selección de opciones. Se trata de un Select de elección simple. Útil para elegir el banco o el tipo de DNI (V, E, J, etc).
- question: Título de la pregunta.
- required: Indica si es obligatorio para el servidor. En cualquier caso se debe inicializar con un campo en blanco al estilo "Seleccione una opción: " y NO tener la primera opción por defecto. En caso de required == true se debe obligar a elegir una opción para enviar el formulario.
- choices: un array de string con las distintas opciones a elegir,
- type: puede ser text y bank
text_button: Botón de texto informativo, no hay que responder en el formulario (es informativo). Se muestra un título igualmente, una descripción y un botón debajo. Útil para mostrar información muy extensa.
- question: Título a mostrar.
- content: Texto descriptivo.
- button_text: Texto a mostrar en el botón. Por ejemplo: "Ver cuentas bancarias".
- button_content: Contenido a mostrar (en un diálogo) cuando presionas el botón. Como título del diálogo se puede usar el button_text y el contenido es button_content.
file: Campo para subir un archivo.
- question: Título a mostrar.
- required: Indica si es obligatorio para el servidor.
- allowed_types: Array de tipos de archivos admitidos.
- type: Indica si es un archivo cualquiera file o imagen image.

Estructura de Datos

Atributo	Tipo	Descripción
`id`	`int`
`type`	`int`	Tipo/slot del formulario: `1` = prueba de entrega; `2`-`20` = métodos de pago manual. En las rutas se usa como `{form_type}`.
`data`	`array`	Definición de los campos del formulario (array de componentes); ver el detalle de cada tipo de componente arriba.
`name`	`string\\|null`	Nombre del método de pago a mostrar en la lista; null si no aplica.
`disabled`	`bool`	`true` si el formulario está desactivado y no debe ofrecerse.
`created_at`	`datetime\\|null`	Fecha de creación.
`updated_at`	`datetime\\|null`	Fecha de última modificación.
`company_id`	`int`	Compañía dueña del formulario.
`icon`	`int`	Índice del icono a mostrar (lista fija predefinida).
`currency`	`array`	Moneda y tarifas del método de pago: `iso`, `tax_flat_e2` (recargo fijo, céntimos) y `tax_percent` (recargo porcentual, fracción).
`branch_id`	`int\\|null`	Comercio dueño del formulario; null si pertenece a la compañía (caso marketplace).
`label_url`	`string\\|null`	URL de una imagen grande a mostrar en el formulario (por ejemplo un QR); puede ser null.
`internal_name`	`string\\|null`	Nombre interno para identificar el formulario en el panel; no visible para el cliente.
`allLogs`	`ApiLog>`
`company`	`Company`
`logs`	`ApiLog>`
`resources`	`UploadedResource>`

{
    "id": 185,
    "type": 4,
    "data": [
        {
            "text": {
                "question": "Usuario del comercio",
                "content": ".Zen DEV"
            }
        },
        {
            "input": {
                "question": "¿Quién envia el pago?",
                "required": false,
                "hint": "Coloca tu usuario de Reserve",
                "regex": "^[a-zA-Z0-9_]*^",
                "type": "text"
            }
        }
    ],
    "name": "Reserve",
    "disabled": true,
    "created_at": "2021-05-19 16:59:16",
    "updated_at": "2023-07-07 12:58:57",
    "company_id": 116,
    "icon": 7,
    "currency": {
        "iso": "USD",
        "tax_flat_e2": 0,
        "tax_percent": 0,
        "id": 475,
        "enabled": true,
        "symbol": "$",
        "conversion_factor": 1,
        "related_iso": "USD",
        "decimals_count": 2,
        "format": "0.00$",
        "decimal_point": ".",
        "use_thousands_separator": true,
        "thousands_separator": ",",
        "is_local": true,
        "is_international": true,
        "created_at": "2021-07-15 19:16:41",
        "updated_at": "2024-02-22 13:34:01",
        "company_id": 116,
        "is_custom": true,
        "branch_id": 37,
        "auto_sync": false,
        "auto_sync_provider": "legacy",
        "use_conversion": false,
        "available": true,
        "related_iso_expected": "USD",
        "related_iso_error": false
    },
    "branch_id": 37,
    "label_url": "http://127.0.0.1:8000/storage/companies/69/form/form_label_185_1621458192.jpg",
    "internal_name": null
}

Endpoints

Insertar Form

Insertar Form de Branch

Crear o actualizar un formulario

Crea el Form del {form_type} indicado (o lo actualiza si ya existe) para la compañía o el comercio. El cuerpo form es la lista de componentes; sólo se conservan las claves admitidas por cada tipo (text, input, boolean, option, text_button, file). Si no se envía currency se usa la moneda local de la compañía sin recargos.

{warning} Responde 400 invalid_type si {form_type} no está entre 1 y 20.

Método	URI	Cabeceras
PUT	`/companies/{company}/branches/{branchId}/forms/{form_type}`	Authorization

{
    "name": "string|max:32",
    "internal_name": "nullable|string|in:bancamiga_pm,bancamiga_ci,humaniz",
    "icon": "integer",
    "currency": {
        "iso": "required_with:currency|min:3|max:8|string",
        "tax_percent": "required_with:currency|numeric|between:0.0000,1.0000",
        "tax_flat_e2": "required_with:currency|integer|min:0"
    },
    "branch_id": "integer|min:1",
    "form": [
        {
            "boolean": {
                "question": "required_with:form.*.boolean|max:64|string",
                "required": "required_with:form.*.boolean|boolean"
            },
            "option": {
                "question": "required_with:form.*.option|max:64|string",
                "required": "required_with:form.*.option|boolean",
                "choices": [
                    "required_with:form.*.option.choices|max:48|string"
                ],
                "type": "string|in:text,date,bank"
            },
            "input": {
                "question": "required_with:form.*.input|max:64|string",
                "hint": "max:32|string",
                "required": "required_with:form.*.input|boolean",
                "regex": "max:255|pattern",
                "type": "string|in:text,text_area,date,numeric,bank",
                "key": "boolean"
            },
            "text": {
                "question": "required_with:form.*.text|max:64|string",
                "content": "required_with:form.*.text|max:512|string"
            },
            "text_button": {
                "question": "required_with:form.*.text_button|max:64|string",
                "content": "required_with:form.*.text_button|max:255|string",
                "button_text": "required_with:form.*.text_button|max:48|string",
                "button_content": "required_with:form.*.text_button|max:1024|string"
            },
            "file": {
                "question": "required_with:form.*.file|string",
                "required": "required_with:form.*.file|boolean",
                "allowed_types": [
                    "required_with:form.*.file.allowed_types|max:128|string"
                ],
                "type": "string|in:file,image"
            }
        }
    ]
}

Insertar Form de Branch

Crear o actualizar un formulario

{warning} Responde 400 invalid_type si {form_type} no está entre 1 y 20.

Método	URI	Cabeceras
PUT	`/companies/{company}/branches/{branchId}/forms/{form_type}`	Authorization

{
    "name": "string|max:32",
    "internal_name": "nullable|string|in:bancamiga_pm,bancamiga_ci,humaniz",
    "icon": "integer",
    "currency": {
        "iso": "required_with:currency|min:3|max:8|string",
        "tax_percent": "required_with:currency|numeric|between:0.0000,1.0000",
        "tax_flat_e2": "required_with:currency|integer|min:0"
    },
    "branch_id": "integer|min:1",
    "form": [
        {
            "boolean": {
                "question": "required_with:form.*.boolean|max:64|string",
                "required": "required_with:form.*.boolean|boolean"
            },
            "option": {
                "question": "required_with:form.*.option|max:64|string",
                "required": "required_with:form.*.option|boolean",
                "choices": [
                    "required_with:form.*.option.choices|max:48|string"
                ],
                "type": "string|in:text,date,bank"
            },
            "input": {
                "question": "required_with:form.*.input|max:64|string",
                "hint": "max:32|string",
                "required": "required_with:form.*.input|boolean",
                "regex": "max:255|pattern",
                "type": "string|in:text,text_area,date,numeric,bank",
                "key": "boolean"
            },
            "text": {
                "question": "required_with:form.*.text|max:64|string",
                "content": "required_with:form.*.text|max:512|string"
            },
            "text_button": {
                "question": "required_with:form.*.text_button|max:64|string",
                "content": "required_with:form.*.text_button|max:255|string",
                "button_text": "required_with:form.*.text_button|max:48|string",
                "button_content": "required_with:form.*.text_button|max:1024|string"
            },
            "file": {
                "question": "required_with:form.*.file|string",
                "required": "required_with:form.*.file|boolean",
                "allowed_types": [
                    "required_with:form.*.file.allowed_types|max:128|string"
                ],
                "type": "string|in:file,image"
            }
        }
    ]
}

Listar Form

Listar Form de Branch

Listar formularios

Devuelve los Form de la compañía (o del comercio, con el prefijo branches/{branchId}), paginados. En marketplaces, un usuario no administrador que consulta con branchId recibe tanto los formularios propios del comercio como los de la compañía (branch_id = null).

Método	URI	Cabeceras
GET	`/companies/{company}/branches/{branchId}/forms`	Authorization

Listar Form de Branch

Listar formularios

Método	URI	Cabeceras
GET	`/companies/{company}/branches/{branchId}/forms`	Authorization

Mostrar Form

Mostrar Form de Branch

Ver un formulario

Devuelve el Form de la compañía o comercio identificado por {form_type} (su type).

Método	URI	Cabeceras
GET	`/companies/{company}/branches/{branchId}/forms/{form_type}`	Authorization

Mostrar Form de Branch

Ver un formulario

Devuelve el Form de la compañía o comercio identificado por {form_type} (su type).

Método	URI	Cabeceras
GET	`/companies/{company}/branches/{branchId}/forms/{form_type}`	Authorization

Eliminar Form

Eliminar Form de Branch

Eliminar un formulario

Borra el Form de la compañía o comercio identificado por {form_type}.

Método	URI	Cabeceras
DELETE	`/companies/{company}/branches/{branchId}/forms/{form_type}`	Authorization

Eliminar Form de Branch

Eliminar un formulario

Borra el Form de la compañía o comercio identificado por {form_type}.

Método	URI	Cabeceras
DELETE	`/companies/{company}/branches/{branchId}/forms/{form_type}`	Authorization

Acciones de Form

Calcular el recargo de un formulario de pago

Devuelve el desglose del pago para el {form_type} dado aplicando su moneda y recargos (tax_flat_e2, tax_percent) sobre order_e2 y tip_e2, opcionalmente convertido a currency_to_use.

Método	URI	Cabeceras
GET	`/companies/{company}/branches/{branchId}/forms/{form_type}/get-tax`	Authorization

{
    "order_e2": "required|integer|min:0",
    "tip_e2": "required|integer|min:0",
    "currency_to_use": "string|min:3|max:8",
    "branch_id": "nullable|integer"
}

Crear un formulario de pago en el primer slot libre

Busca el primer type disponible en el rango de pagos manuales (2–20) y crea allí el Form con el contenido recibido.

{warning} Responde 400 no_slots_available si los 19 slots de pago manual ya están ocupados.

Método	URI	Cabeceras
POST	`/companies/{company}/branches/{branchId}/forms/payment`	Authorization

{
    "name": "string|max:32",
    "internal_name": "nullable|string|in:bancamiga_pm,bancamiga_ci,humaniz",
    "icon": "integer",
    "currency": {
        "iso": "required_with:currency|min:3|max:8|string",
        "tax_percent": "required_with:currency|numeric|between:0.0000,1.0000",
        "tax_flat_e2": "required_with:currency|integer|min:0"
    },
    "branch_id": "integer|min:1",
    "form": [
        {
            "boolean": {
                "question": "required_with:form.*.boolean|max:64|string",
                "required": "required_with:form.*.boolean|boolean"
            },
            "option": {
                "question": "required_with:form.*.option|max:64|string",
                "required": "required_with:form.*.option|boolean",
                "choices": [
                    "required_with:form.*.option.choices|max:48|string"
                ],
                "type": "string|in:text,date,bank"
            },
            "input": {
                "question": "required_with:form.*.input|max:64|string",
                "hint": "max:32|string",
                "required": "required_with:form.*.input|boolean",
                "regex": "max:255|pattern",
                "type": "string|in:text,text_area,date,numeric,bank",
                "key": "boolean"
            },
            "text": {
                "question": "required_with:form.*.text|max:64|string",
                "content": "required_with:form.*.text|max:512|string"
            },
            "text_button": {
                "question": "required_with:form.*.text_button|max:64|string",
                "content": "required_with:form.*.text_button|max:255|string",
                "button_text": "required_with:form.*.text_button|max:48|string",
                "button_content": "required_with:form.*.text_button|max:1024|string"
            },
            "file": {
                "question": "required_with:form.*.file|string",
                "required": "required_with:form.*.file|boolean",
                "allowed_types": [
                    "required_with:form.*.file.allowed_types|max:128|string"
                ],
                "type": "string|in:file,image"
            }
        }
    ]
}

Activar un formulario

Pone disabled = false en el Form indicado por {form_type}.

Método	URI	Cabeceras
PATCH	`/companies/{company}/branches/{branchId}/forms/{form_type}/enable`	Authorization

Desactivar un formulario

Pone disabled = true en el Form indicado por {form_type}; deja de ofrecerse sin borrar su configuración.

Método	URI	Cabeceras
PATCH	`/companies/{company}/branches/{branchId}/forms/{form_type}/disable`	Authorization

Calcular el recargo de un formulario de pago

Devuelve el desglose del pago para el {form_type} dado aplicando su moneda y recargos (tax_flat_e2, tax_percent) sobre order_e2 y tip_e2, opcionalmente convertido a currency_to_use.

Método	URI	Cabeceras
GET	`/companies/{company}/branches/{branchId}/forms/{form_type}/get-tax`	Authorization

{
    "order_e2": "required|integer|min:0",
    "tip_e2": "required|integer|min:0",
    "currency_to_use": "string|min:3|max:8",
    "branch_id": "nullable|integer"
}

Crear un formulario de pago en el primer slot libre

Busca el primer type disponible en el rango de pagos manuales (2–20) y crea allí el Form con el contenido recibido.

{warning} Responde 400 no_slots_available si los 19 slots de pago manual ya están ocupados.

Método	URI	Cabeceras
POST	`/companies/{company}/branches/{branchId}/forms/payment`	Authorization

{
    "name": "string|max:32",
    "internal_name": "nullable|string|in:bancamiga_pm,bancamiga_ci,humaniz",
    "icon": "integer",
    "currency": {
        "iso": "required_with:currency|min:3|max:8|string",
        "tax_percent": "required_with:currency|numeric|between:0.0000,1.0000",
        "tax_flat_e2": "required_with:currency|integer|min:0"
    },
    "branch_id": "integer|min:1",
    "form": [
        {
            "boolean": {
                "question": "required_with:form.*.boolean|max:64|string",
                "required": "required_with:form.*.boolean|boolean"
            },
            "option": {
                "question": "required_with:form.*.option|max:64|string",
                "required": "required_with:form.*.option|boolean",
                "choices": [
                    "required_with:form.*.option.choices|max:48|string"
                ],
                "type": "string|in:text,date,bank"
            },
            "input": {
                "question": "required_with:form.*.input|max:64|string",
                "hint": "max:32|string",
                "required": "required_with:form.*.input|boolean",
                "regex": "max:255|pattern",
                "type": "string|in:text,text_area,date,numeric,bank",
                "key": "boolean"
            },
            "text": {
                "question": "required_with:form.*.text|max:64|string",
                "content": "required_with:form.*.text|max:512|string"
            },
            "text_button": {
                "question": "required_with:form.*.text_button|max:64|string",
                "content": "required_with:form.*.text_button|max:255|string",
                "button_text": "required_with:form.*.text_button|max:48|string",
                "button_content": "required_with:form.*.text_button|max:1024|string"
            },
            "file": {
                "question": "required_with:form.*.file|string",
                "required": "required_with:form.*.file|boolean",
                "allowed_types": [
                    "required_with:form.*.file.allowed_types|max:128|string"
                ],
                "type": "string|in:file,image"
            }
        }
    ]
}

Activar un formulario

Pone disabled = false en el Form indicado por {form_type}.

Método	URI	Cabeceras
PATCH	`/companies/{company}/branches/{branchId}/forms/{form_type}/enable`	Authorization

Desactivar un formulario

Pone disabled = true en el Form indicado por {form_type}; deja de ofrecerse sin borrar su configuración.

Método	URI	Cabeceras
PATCH	`/companies/{company}/branches/{branchId}/forms/{form_type}/disable`	Authorization

Subir la imagen de un formulario

Guarda el archivo image como label_url del Form (imagen grande del formulario, por ejemplo un QR de pago). Enviar la petición sin image deja label_url en null.

Método	URI	Cabeceras
POST	`/companies/{company}/forms/{formId}/upload-label`	Authorization

{
    "image": "nullable|image|mimes:jpeg,png|max:2048"
}

Relaciones

allLogs HasMany ApiLog
company BelongsTo Company
logs HasMany ApiLog

Administración

Métodos de Pago

Calificaciones

Form

Estructura de Datos

Endpoints

Insertar Form

Insertar Form de Branch

Insertar Form de Branch

Listar Form

Listar Form de Branch

Listar Form de Branch

Mostrar Form

Mostrar Form de Branch

Mostrar Form de Branch

Eliminar Form

Eliminar Form de Branch

Eliminar Form de Branch

Acciones de Form

Calcular el recargo de un formulario de pago

Crear un formulario de pago en el primer slot libre

Activar un formulario

Desactivar un formulario

Calcular el recargo de un formulario de pago

Crear un formulario de pago en el primer slot libre

Activar un formulario

Desactivar un formulario

Subir la imagen de un formulario

Relaciones