Notify Unpaid Fees

POST /savings-contracts/notify-unpaid-fees

Notifica sobre tarifas no pagadas en múltiples contratos de ahorro en una sola operación bulk.

Endpoint

POST /savings-contracts/notify-unpaid-fees

Authentication

api-key: YOUR_API_KEY
Content-Type: application/json

Request Body

Campo	Tipo	Requerido	Descripción
contract_ids	array	✓	Array de IDs de contratos con tarifas impagas

Ejemplo de solicitud

# Production
curl -X POST \
     -H "api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "contract_ids": [
         "contract_111",
         "contract_222",
         "contract_333"
       ]
     }' \
     "https://api.erolapp.com/api/v1/savings-contracts/notify-unpaid-fees"

# Staging
curl -X POST \
     -H "api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "contract_ids": [
         "contract_111",
         "contract_222",
         "contract_333"
       ]
     }' \
     "https://be-staging.erolapp.com/api/v1/savings-contracts/notify-unpaid-fees"

Response

Código de estado: 200 OK

{
  "success": true,
  "message": "Unpaid fees notifications processed successfully",
  "data": {
    "processed_contracts": 3,
    "contract_ids": [
      "contract_111",
      "contract_222",
      "contract_333"
    ],
    "processed_at": "2024-08-10T10:30:00Z",
    "actions_triggered": [
      "fee_reminder_email",
      "status_update_to_overdue",
      "payment_retry_scheduled"
    ]
  },
  "meta": {
    "timestamp": "2024-08-10T10:30:00Z",
    "request_id": "req_ghi789"
  }
}

Casos de uso

• Notificación masiva de tarifas de mantenimiento impagas
• Activación de recordatorios de pago automáticos
• Marcado de contratos con pagos en mora
• Procesamiento de tarifas administrativas vencidas
• Actualización de estado crediticio de clientes

Tipos de tarifas comunes

Tipo de tarifa	Descripción	Frecuencia
maintenance_fee	Tarifa de mantenimiento de cuenta	Mensual
admin_fee	Tarifa administrativa	Trimestral
transaction_fee	Tarifa por transacción	Por operación
penalty_fee	Tarifa por penalización	Según incumplimiento

Notas importantes

• Este endpoint procesa las notificaciones de forma asíncrona
• Los contratos deben estar activos para procesar tarifas impagas
• La respuesta 200 confirma que el proceso se inició correctamente
• Se pueden activar múltiples acciones: emails, SMS, actualizaciones de estado
• El procesamiento real puede tardar algunos minutos

Acciones automáticas activadas

Tras la notificación, el sistema puede activar automáticamente:

• ✉️ Envío de recordatorios por email
• 📱 Envío de SMS de notificación
• 🔄 Reprogramación de intentos de cobro
• ⚠️ Actualización de estado a “overdue”
• 📊 Actualización de scoring crediticio

Error Responses

Si hay errores en el procesamiento:

{
  "success": false,
  "error": {
    "code": "INACTIVE_CONTRACTS",
    "message": "Cannot process unpaid fees for inactive contracts",
    "details": {
      "inactive_ids": ["contract_999"],
      "current_statuses": {
        "contract_999": "cancelled"
      },
      "valid_count": 2,
      "invalid_count": 1
    }
  }
}

Estados de contrato afectados

Estado Inicial	Estado Final	Descripción
active	overdue	Contrato con pagos vencidos
active	pending_payment	Esperando resolución de pago