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 | Sí | - | Identificador único de la factura a la cual se registrará el pago. |
| monto | float | Sí | - | Monto del pago a registrar. Debe ser un número positivo y no puede exceder el saldo pendiente de la factura. |
| fecha_pago | string | Sí | - | 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 |
|---|---|---|
|
|
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
-
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).
-
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
-
Pagos Parciales: El sistema permite pagos parciales. El monto debe ser mayor a cero y no puede exceder el saldo pendiente de la factura.
-
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));