API Credito Serfigas - Documentacion

Documentacion completa para integrar el sistema de Credito Serfigas en sus aplicaciones.

Introduccion

La API de Credito Serfigas permite a desarrolladores integrar el sistema de credito en factura de gas con aplicaciones externas.

URL Base: /api/brilla/v1

Caracteristicas

  • Autenticacion mediante tokens JWT
  • Endpoints REST con respuestas JSON
  • Validacion de seguridad con preguntas personalizadas
  • Consulta de cupo y creditos en tiempo real

Autenticacion

La API utiliza tokens Bearer para autenticacion. Primero debe generar un token usando sus credenciales.

1. Obtener Token

POST /api/brilla/v1/token/generate 
{
    "vat": "123456789",
    "contract_number": "12345678",
    "question_id": 1,
    "answer": "su_respuesta"
}
Respuesta Exitosa:
{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_at": "2025-01-15T10:30:00",
    "message": "Token generado exitosamente. Valido por 30 dias."
}

2. Usar Token en Peticiones

Incluya el token en el header Authorization:

curl -X GET "https://api.serfigas.com/api/brilla/v1/credits" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Endpoints Publicos

Estos endpoints no requieren autenticacion.

POST Registro de Cliente

/api/brilla/v1/register

Registra un nuevo cliente en el sistema Serfigas.

Payload:
{
    "vat": "123456789",
    "vat_type": "cedula",
    "name": "Juan Perez",
    "email": "juan@email.com",
    "phone": "3001234567",
    "contract_number": "12345678",
    "birth_date": "1990-01-15",
    "birth_city": "Cartagena",
    "id_expedition_date": "2010-03-20",
    "id_expedition_city": "Cartagena",
    "address": "Calle 50 #20-30",
    "city": "Cartagena",
    "attachments": [
        {"name": "cedula_frente.jpg", "data": "base64..."},
        {"name": "cedula_atras.jpg", "data": "base64..."},
        {"name": "factura_gas.pdf", "data": "base64..."}
    ]
}
Respuesta:
{
    "success": true,
    "message": "Solicitud recibida exitosamente. En unos minutos recibira respuesta.",
    "request_id": 123,
    "state": "pending",
    "tracking_code": "BRL202501150001"
}
GET Estado de Registro

/api/brilla/v1/register/status/{tracking_code}

Consulta el estado de una solicitud de registro.

Ejemplo:
curl -X GET "https://api.serfigas.com/api/brilla/v1/register/status/BRL202501150001"
POST Validar Contrato

/api/brilla/v1/validate/contract

Valida si un documento y contrato son validos.

{
    "vat": "123456789",
    "contract_number": "12345678"
}

Endpoints Autenticados

Requieren header Authorization: Bearer {token}

Todos estos endpoints requieren un token valido

Consulta de Cupo

GET Resumen de Cupo

/api/brilla/v1/credits/summary

Obtiene el resumen de cupo disponible y creditos activos.

Respuesta:
{
    "success": true,
    "data": {
        "credit_limit": 5000000,
        "available": 3500000,
        "used": 1500000,
        "active_credits": 2,
        "total_pending": 1500000,
        "contract": {
            "number": "12345678",
            "active": true
        }
    }
}

Creditos

GET Listar Creditos

/api/brilla/v1/credits

Respuesta:
{
    "success": true,
    "data": {
        "credits": [
            {
                "id": 1,
                "name": "BRILLA/2025/0001",
                "amount": 1000000,
                "pending_amount": 500000,
                "periods": 12,
                "rate": 1.99,
                "state": "posted",
                "start_date": "2025-01-01",
                "end_date": "2025-12-01"
            }
        ],
        "total_pending": 500000,
        "active_count": 1
    }
}
GET Detalle de Credito con Amortizacion

/api/brilla/v1/credits/{loan_id}

Respuesta:
{
    "success": true,
    "data": {
        "credit": {
            "id": 1,
            "name": "BRILLA/2025/0001",
            "amount": 1000000,
            "pending_amount": 500000,
            "periods": 12,
            "rate": 1.99,
            "state": "posted"
        },
        "amortization": [
            {
                "sequence": 1,
                "date": "2025-02-01",
                "payment_amount": 93417,
                "principal_amount": 73517,
                "interest_amount": 19900,
                "pending_principal": 926483,
                "state": "paid"
            },
            {
                "sequence": 2,
                "date": "2025-03-01",
                "payment_amount": 93417,
                "principal_amount": 74981,
                "interest_amount": 18436,
                "pending_principal": 851502,
                "state": "pending"
            }
        ],
        "payments": {
            "total_paid": 93417,
            "total_pending": 1027587,
            "paid_count": 1,
            "pending_count": 11
        }
    }
}
GET Historial de Pagos

/api/brilla/v1/credits/{loan_id}/payments

Codigos de Error

Codigo HTTP Codigo Error Descripcion
400 bad_request Datos invalidos en la peticion
401 unauthorized Token invalido o expirado
404 not_found Recurso no encontrado
429 rate_limit Demasiadas peticiones
500 server_error Error interno del servidor

Ejemplos de Integracion

import requests

BASE_URL = "https://api.serfigas.com/api/brilla/v1"

# 1. Generar Token
response = requests.post(f"{BASE_URL}/token/generate", json={
    "vat": "123456789",
    "contract_number": "12345678",
    "question_id": 1,
    "answer": "mi_respuesta"
})
token = response.json()["token"]

# 2. Consultar Cupo
headers = {"Authorization": f"Bearer {token}"}
cupo = requests.get(f"{BASE_URL}/credits/summary", headers=headers)
print(cupo.json())

# 3. Listar Creditos
creditos = requests.get(f"{BASE_URL}/credits", headers=headers)
print(creditos.json())
const BASE_URL = "https://api.serfigas.com/api/brilla/v1";

// 1. Generar Token
const tokenResponse = await fetch(`${BASE_URL}/token/generate`, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        vat: "123456789",
        contract_number: "12345678",
        question_id: 1,
        answer: "mi_respuesta"
    })
});
const {token} = await tokenResponse.json();

// 2. Consultar Cupo
const cupoResponse = await fetch(`${BASE_URL}/credits/summary`, {
    headers: {'Authorization': `Bearer ${token}`}
});
const cupo = await cupoResponse.json();
console.log(cupo);
# 1. Generar Token
curl -X POST "https://api.serfigas.com/api/brilla/v1/token/generate" \
  -H "Content-Type: application/json" \
  -d '{"vat":"123456789","contract_number":"12345678","question_id":1,"answer":"mi_respuesta"}'

# 2. Consultar Cupo (reemplazar TOKEN)
curl -X GET "https://api.serfigas.com/api/brilla/v1/credits/summary" \
  -H "Authorization: Bearer TOKEN"

# 3. Listar Creditos
curl -X GET "https://api.serfigas.com/api/brilla/v1/credits" \
  -H "Authorization: Bearer TOKEN"

Soporte

Para soporte tecnico contacte: