Ir al contenido principal

Registrar Pago de Factura [BETA]

Permite registrar el pago de una factura existente en el sistema. Si no se especifica la forma de pago, el sistema intentará determinarla automáticamente basándose en el cliente autenticado o utilizará la forma de pago por defecto configurada (Consignación bancaria).

Endpoint: https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/register-payment

{{instancia}}: Hace referencia a la instancia de cada inmobiliaria.

Petición

Método POST
Content-Type application/json
Authorization Bearer token, Token obtenido al consumir el servicio Login
Parámetros del Body (JSON)
Parámetro Tipo Obligatorio Valor por defecto Descripción
factura_id string - Identificador único de la factura a la cual se registrará el pago.
monto float - Monto del pago a registrar. Debe ser un número positivo y no puede exceder el saldo pendiente de la factura.
fecha_pago string - Fecha en que se realizó el pago. Formato: Y-m-d (ej: 2026-02-05).
forma_pago_id integer No Auto ID de la forma de pago. Si no se proporciona, se determina automáticamente según el cliente o la configuración por defecto.
n_comprobante string No - Número de comprobante o referencia del pago realizado.

Ejemplo de petición (Body JSON)

{
    "factura_id": "366",
    "monto": 50000,
    "fecha_pago": "2026-02-05",
    "forma_pago_id": 1,
    "n_comprobante": "REF123456"
}

Ejemplo mínimo (solo campos requeridos):

{
    "factura_id": "366",
    "monto": 50000,
    "fecha_pago": "2026-02-05"
}

Respuestas

Respuesta Exitosa (200)

Cuando el pago se registra correctamente, la respuesta incluye los detalles del pago registrado.

{
    "success": true,
    "status": 200,
    "message": "Pago registrado exitosamente.",
    "body": {
        "factura_id": "366",
        "monto_pagado": 50000,
        "fecha_pago": "2026-02-05",
        "forma_pago_id": 1,
        "forma_pago": "Consignación bancaria",
        "gateway": null,
        "client_name": "MiAplicacion"
    }
}
Claves y Descripciones del JSON de Respuesta
Clave Tipo Descripción

success

Booleano Indica si la operación fue exitosa (true) o fallida (false).
status Entero Código HTTP de la respuesta: 200 (exitoso), 400 (error de validación), 404 (no encontrado), 422 (error de negocio), 500 (error interno).
message Texto Mensaje descriptivo del resultado de la operación.
body Objeto Contiene los detalles del pago registrado cuando la operación es exitosa. Es nulo cuando hay error.
errors Array Lista de errores de validación. Solo presente cuando status es 400.
Cuerpo de Respuesta Exitosa (body)

Cuando la operación es exitosa, el objeto body contiene las siguientes claves:

Clave Tipo Descripción
factura_id Texto ID de la factura a la que se aplicó el pago.
monto_pagado Numérico Monto del pago registrado.
fecha_pago Texto Fecha del pago en formato Y-m-d.
forma_pago_id Entero ID de la forma de pago utilizada.
forma_pago Texto Nombre de la forma de pago utilizada.
gateway Texto Nombre de la pasarela de pago si aplica. Nulo si no se usó pasarela.
client_name Texto Nombre del cliente OAuth autenticado que realizó la petición.

Respuestas de Error

Error de Validación (400)

Se retorna cuando los parámetros enviados no cumplen con las validaciones requeridas.

{
    "success": false,
    "status": 400,
    "message": "Errores de validación",
    "body": null,
    "errors": [
        "El parámetro \"factura_id\" es requerido.",
        "El parámetro \"monto\" debe ser un número positivo.",
        "El parámetro \"fecha_pago\" debe tener el formato Y-m-d (ej: 2026-02-02)."
    ]
}
Factura No Encontrada (404)

Se retorna cuando no existe una factura con el ID proporcionado.

{
    "success": false,
    "status": 404,
    "message": "No se encontró la factura con el ID proporcionado.",
    "body": null
}
Error de Negocio (422)

Se retorna cuando la factura existe pero no puede recibir el pago por razones de negocio.

Factura no activa:

{
    "success": false,
    "status": 422,
    "message": "La factura no está en estado activo/pendiente de pago. Estado actual: Pagada",
    "body": null
}

Monto excede saldo:

{
    "success": false,
    "status": 422,
    "message": "El monto a pagar (100000) excede el saldo de la factura (50000).",
    "body": null
}

Forma de pago no determinada:

{
    "success": false,
    "status": 422,
    "message": "No se pudo determinar la forma de pago automáticamente. Por favor especifique el parámetro \"forma_pago_id\".",
    "body": null
}
Error Interno (500)

Se retorna cuando ocurre un error inesperado en el servidor.

{
    "success": false,
    "status": 500,
    "message": "Error interno del servidor al registrar el pago.",
    "body": null
}

Códigos de Respuesta HTTP


**Código** **Descripción**
200 Pago registrado exitosamente.
400 Error de validación en los parámetros enviados o forma de pago inexistente.
404 La factura especificada no existe.
422 Error de regla de negocio: factura no activa, monto excede saldo, o no se pudo determinar forma de pago.
500 Error interno del servidor.

Notas Importantes

  1. Determinación Automática de Forma de Pago: Si no se proporciona forma_pago_id, el sistema intentará:

    • Primero, determinar la forma de pago basándose en el cliente OAuth autenticado (integración con pasarelas de pago).
    • Si no encuentra una pasarela asociada, buscará la forma de pago por defecto configurada con código DIAN 42 (Consignación bancaria).
  2. Estados de Factura: Solo se pueden registrar pagos en facturas con estado "Facturada" (estado_id = 1). Los estados posibles son:

    • 1: Facturada (permite pagos)
    • 2: Anulada
    • 3: Pagada
    • 5: Borrador
    • 6: Anulada por NC
  3. Pagos Parciales: El sistema permite pagos parciales. El monto debe ser mayor a cero y no puede exceder el saldo pendiente de la factura.

  4. Formas de Pago: Para obtener el listado de formas de pago disponibles, consulte el endpoint Listar Formas de Pago.

Ejemplos


Curl
curl -X POST "https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/register-payment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN" \
  -d '{
    "factura_id": "366",
    "monto": 50000,
    "fecha_pago": "2026-02-05",
    "n_comprobante": "REF123456"
  }'

PHP Curl
<?php

$instance = 'your_instance'; // Reemplace con su instancia actual
$token = 'YOUR_AUTHENTICATION_TOKEN'; // Reemplace con el token obtenido desde el servicio de login

// Datos del pago a registrar
$paymentData = [
    'factura_id' => '366',
    'monto' => 50000,
    'fecha_pago' => '2026-02-05',
    'forma_pago_id' => 1, // Opcional
    'n_comprobante' => 'REF123456' // Opcional
];

$url = "https://{$instance}.arrendasoft.co/service/v2/public/invoices/register-payment";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($paymentData));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo "HTTP Status Code: " . $http_code . "\n";
    echo "Response: " . $response . "\n";
    
    // Procesar la respuesta
    $result = json_decode($response, true);
    
    if ($result['success']) {
        echo "Pago registrado exitosamente.\n";
        echo "Factura: " . $result['body']['factura_id'] . "\n";
        echo "Monto pagado: " . $result['body']['monto_pagado'] . "\n";
        echo "Forma de pago: " . $result['body']['forma_pago'] . "\n";
    } else {
        echo "Error: " . $result['message'] . "\n";
        if (isset($result['errors'])) {
            foreach ($result['errors'] as $error) {
                echo "- " . $error . "\n";
            }
        }
    }
}
curl_close($ch);

?>

JavaScript Fetch
const instance = 'your_instance'; // Reemplace con su instancia actual
const token = 'YOUR_AUTHENTICATION_TOKEN'; // Reemplace con el token obtenido

const paymentData = {
    factura_id: '366',
    monto: 50000,
    fecha_pago: '2026-02-05',
    n_comprobante: 'REF123456'
};

fetch(`https://${instance}.arrendasoft.co/service/v2/public/invoices/register-payment`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(paymentData)
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('Pago registrado exitosamente');
        console.log('Factura:', data.body.factura_id);
        console.log('Monto pagado:', data.body.monto_pagado);
        console.log('Forma de pago:', data.body.forma_pago);
    } else {
        console.error('Error:', data.message);
        if (data.errors) {
            data.errors.forEach(error => console.error('-', error));
        }
    }
})
.catch(error => console.error('Error de conexión:', error));