API Serfigas v1
Introduccion
AUTENTICACION
POST /token/generate POST /token/refresh GET /token/info POST /token/revoke
REGISTRO (Publico)
POST /register GET /register/status POST /validate/contract
CREDITOS
GET /credits GET /credits/{id} GET /credits/summary
VENTAS
POST /sale/validate POST /sale/create POST /sale/{id}/confirm GET /sale/{id} GET /sales
FACTURAS
GET /invoices GET /invoices/pending POST /invoices/{id}/pay
PAGOS
GET /payments GET /payment/{hash} Codigos de Error

API Serfigas v1

API REST para integracion de comercios con el sistema de Credito Serfigas.

URL Base: https://serfigas.201.244.32.107.nip.io/api/serfigas/v1
Autenticacion

Todos los endpoints (excepto registro) requieren token Bearer en el header:

Authorization: Bearer {token}
Content-Type

Todas las peticiones deben incluir:

Content-Type: application/json
Codigos de Respuesta HTTP
200OK - Solicitud exitosa
201Created - Recurso creado
400Bad Request - Datos invalidos
401Unauthorized - Token invalido/expirado
403Forbidden - Sin permisos
404Not Found - Recurso no existe
429Too Many Requests - Rate limit
500Internal Error - Error servidor
Ejemplo General con cURL
# Peticion GET con autenticacion
curl -X GET "https://tu-servidor.com/api/serfigas/v1/credits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {tu_token}"

# Peticion POST con datos
curl -X POST "https://tu-servidor.com/api/serfigas/v1/token/generate" \
  -H "Content-Type: application/json" \
  -d '{"vat": "1234567890", "contract_number": "GAS-001-2024"}'

Autenticacion

POST /token/generate Publico

Genera un token de autenticacion para el cliente. Solo requiere documento y contrato de gas.

Parametros (Body JSON)
CampoTipoRequeridoDescripcion
vatstringSiNumero de documento del cliente
contract_numberstringSiNumero de contrato de gas
expiration_minutesintegerNoMinutos de validez (5-60, default: 15)
Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/token/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "vat": "1234567890",
    "contract_number": "GAS-001-2024"
  }'
Respuesta Exitosa 200 OK
{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_at": "2024-12-13T11:30:00",
    "expires_in_seconds": 1800,
    "message": "Token generado exitosamente"
}
Respuestas de Error
// HTTP 404 Not Found
{
    "success": false,
    "error_code": "CLIENT_NOT_FOUND",
    "error": "Cliente no encontrado"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "CONTRACT_MISMATCH",
    "error": "Contrato no corresponde al cliente"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "CONTRACT_INACTIVE",
    "error": "Contrato inactivo"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "VALIDATION_ERROR",
    "error": "Faltan datos requeridos: vat, contract_number"
}

// HTTP 429 Too Many Requests
{
    "success": false,
    "error_code": "CLIENT_BLOCKED_TEMPORARY",
    "error": "Cuenta bloqueada por 25 minutos. Intente en 18 minutos.",
    "blocked_minutes_remaining": 18,
    "block_level": 1
}
POST /token/refresh Requiere Auth

Renueva un token antes de que expire.

Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/token/refresh" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-12-13T12:00:00",
    "expires_in_seconds": 1800,
    "message": "Token renovado exitosamente"
}
Respuestas de Error
// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_EXPIRED",
    "error": "Token expirado"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_INVALID",
    "error": "Token invalido"
}
GET /token/info Requiere Auth

Obtiene informacion del token actual.

Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/token/info" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "token_type": "bearer",
        "expires_at": "2024-12-13T11:30:00",
        "remaining_seconds": 1523,
        "has_certificate": false,
        "partner": {
            "id": 123,
            "name": "Juan Perez",
            "vat": "1234567890"
        }
    }
}
Respuestas de Error
// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "AUTH_REQUIRED",
    "error": "Autenticacion requerida"
}
POST /token/revoke Requiere Auth

Revoca todos los tokens activos del cliente.

Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/token/revoke" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "message": "Token revocado exitosamente"
}

Registro (Publico)

POST /register Publico

Registra una solicitud de nuevo cliente Serfigas.

Parametros (Body JSON)
CampoTipoRequeridoDescripcion
vatstringSiNumero de documento
vat_typestringNoTipo: cedula, nit, pasaporte
namestringSiNombre completo
emailstringSiCorreo electronico
phonestringSiTelefono de contacto
contract_numberstringSiNumero contrato de gas
birth_datedateNoFecha nacimiento (YYYY-MM-DD)
birth_citystringNoCiudad de nacimiento
addressstringNoDireccion de residencia
citystringNoCiudad
attachmentsarrayNoDocumentos adjuntos
Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/register" \
  -H "Content-Type: application/json" \
  -d '{
    "vat": "1234567890",
    "vat_type": "cedula",
    "name": "Juan Perez Garcia",
    "email": "juan.perez@email.com",
    "phone": "3001234567",
    "contract_number": "GAS-001-2024",
    "birth_date": "1985-06-15",
    "birth_city": "Cartagena",
    "address": "Calle 50 #20-30",
    "city": "Cartagena"
  }'
Respuesta Exitosa 201 Created
{
    "success": true,
    "message": "Solicitud recibida exitosamente. En unos minutos recibiras respuesta.",
    "request_id": 456,
    "state": "pending",
    "tracking_code": "SFG-2024-00456"
}
Respuestas de Error
// HTTP 400 Bad Request - Solicitud ya existe
{
    "success": false,
    "error_code": "REQUEST_EXISTS",
    "error": "Ya existe una solicitud pendiente para este documento",
    "request_id": 123,
    "state": "pending"
}

// HTTP 400 Bad Request - Ya es cliente activo
{
    "success": false,
    "error_code": "CLIENT_EXISTS",
    "error": "Ya eres cliente Serfigas activo",
    "message": "Puedes usar tu cuenta existente para realizar compras"
}

// HTTP 400 Bad Request - Campos faltantes
{
    "success": false,
    "error_code": "VALIDATION_ERROR",
    "error": "Campos requeridos faltantes: email, phone"
}

// HTTP 404 Not Found - Contrato no existe
{
    "success": false,
    "error_code": "CONTRACT_NOT_FOUND",
    "error": "Contrato no encontrado"
}

// HTTP 500 Internal Server Error
{
    "success": false,
    "error_code": "PROCESSING_ERROR",
    "error": "Error procesando la solicitud"
}
GET /register/status/{tracking_code} Publico

Consulta el estado de una solicitud de registro.

Parametros URL
CampoTipoDescripcion
tracking_codestringCodigo de seguimiento (ej: SFG-2024-00456)
Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/register/status/SFG-2024-00456" \
  -H "Content-Type: application/json"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "request_id": 456,
        "state": "approved",
        "state_label": "Aprobado",
        "message": "Su solicitud ha sido aprobada. Ya puede usar su credito Serfigas.",
        "created_at": "2024-12-13T10:00:00",
        "updated_at": "2024-12-13T10:30:00"
    }
}
Estados Posibles
pendingPendiente de revision
reviewingEn revision
approvedAprobado
rejectedRechazado
Respuestas de Error
// HTTP 404 Not Found
{
    "success": false,
    "error_code": "REQUEST_NOT_FOUND",
    "error": "Solicitud no encontrada"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "VALIDATION_ERROR",
    "error": "Codigo de seguimiento invalido"
}
POST /validate/contract Publico

Valida si un documento y contrato son validos.

Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/validate/contract" \
  -H "Content-Type: application/json" \
  -d '{
    "vat": "1234567890",
    "contract_number": "GAS-001-2024"
  }'
Respuesta Exitosa 200 OK
{
    "success": true,
    "client": {
        "name": "Juan Perez",
        "has_credit": true,
        "contract_active": true
    }
}
Respuestas de Error
// HTTP 404 Not Found
{
    "success": false,
    "error_code": "CLIENT_NOT_FOUND",
    "error": "No se encontro cliente con estos datos"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "CONTRACT_INACTIVE",
    "error": "El contrato no esta activo"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "CONTRACT_MISMATCH",
    "error": "Contrato no corresponde al cliente"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "VALIDATION_ERROR",
    "error": "Faltan datos requeridos: vat, contract_number"
}

Creditos

GET /credits Requiere Auth

Lista todos los creditos del cliente autenticado.

Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/credits" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "credits": [
            {
                "id": 1,
                "name": "SERFIGAS/SO001",
                "amount": 1500000,
                "pending_amount": 875000,
                "periods": 12,
                "rate": 1.99,
                "state": "posted",
                "start_date": "2024-06-01",
                "end_date": "2025-05-31"
            }
        ],
        "total_pending": 875000,
        "active_count": 1
    }
}
Respuestas de Error
// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_INVALID",
    "error": "Token invalido"
}
GET /credits/{loan_id} Requiere Auth

Detalle de un credito con tabla de amortizacion.

Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/credits/1" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "credit": {
            "id": 1,
            "name": "SERFIGAS/SO001",
            "amount": 1500000,
            "pending_amount": 875000,
            "periods": 12,
            "rate": 1.99,
            "state": "posted",
            "start_date": "2024-06-01",
            "end_date": "2025-05-31"
        },
        "amortization": [
            {
                "sequence": 1,
                "date": "2024-07-01",
                "payment_amount": 142500,
                "principal_amount": 112650,
                "interest_amount": 29850,
                "pending_principal": 1387350,
                "state": "paid"
            },
            {
                "sequence": 2,
                "date": "2024-08-01",
                "payment_amount": 142500,
                "principal_amount": 114893,
                "interest_amount": 27607,
                "pending_principal": 1272457,
                "state": "pending"
            }
        ],
        "payments": {
            "total_paid": 570000,
            "total_pending": 1140000,
            "paid_count": 4,
            "pending_count": 8
        }
    }
}
Respuestas de Error
// HTTP 404 Not Found
{
    "success": false,
    "error_code": "NOT_FOUND",
    "error": "Recurso no encontrado"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_INVALID",
    "error": "Token invalido"
}
GET /credits/summary Requiere Auth

Resumen del cupo y creditos del cliente.

Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/credits/summary" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "credit_limit": 5000000,
        "available": 3325000,
        "used": 1675000,
        "active_credits": 2,
        "total_pending": 1675000,
        "contract": {
            "number": "GAS-001-2024",
            "active": true
        }
    }
}
Respuestas de Error
// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "AUTH_REQUIRED",
    "error": "Autenticacion requerida"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_EXPIRED",
    "error": "Token expirado"
}

Ventas

POST /sale/validate Requiere Auth

Valida datos antes de crear una venta. Retorna pregunta de seguridad y opciones de cuotas.

Parametros (Body JSON)
CampoTipoRequeridoDescripcion
partner_vatstringSiDocumento del cliente
contract_numberstringSiNumero de contrato
amountnumberSiMonto de la compra
installmentsintegerNoCuotas (default: 12)
Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/sale/validate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {tu_token}" \
  -d '{
    "partner_vat": "1234567890",
    "contract_number": "GAS-001-2024",
    "amount": 1500000,
    "installments": 12
  }'
Respuesta Exitosa 200 OK
{
    "success": true,
    "validated": true,
    "client": {
        "id": 123,
        "name": "Juan Perez",
        "vat": "1234567890",
        "contract_number": "GAS-001-2024",
        "contract_active": true
    },
    "cupo": {
        "limite": 5000000,
        "disponible": 3500000,
        "disponible_despues": 2000000
    },
    "brilla": {
        "amount": 1500000,
        "installments": 12,
        "installment_amount": 142500,
        "total_amount": 1710000,
        "interest_rate": 1.99,
        "installment_options": [
            {"installments": 6, "installment_amount": 268500, "total_amount": 1611000},
            {"installments": 12, "installment_amount": 142500, "total_amount": 1710000},
            {"installments": 24, "installment_amount": 78500, "total_amount": 1884000}
        ]
    },
    "security_question": {
        "question_id": 3,
        "question": "En que ciudad naciste?",
        "hint": "Ciudad de Colombia"
    },
    "require_security": true,
    "message": "Validacion exitosa"
}
Respuestas de Error
// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "INSUFFICIENT_CREDIT",
    "error": "Cupo insuficiente",
    "cupo": {
        "limite": 5000000,
        "disponible": 1000000,
        "solicitado": 1500000
    }
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "CONTRACT_MISMATCH",
    "error": "Contrato no corresponde al cliente"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "CONTRACT_INACTIVE",
    "error": "Contrato inactivo"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "AMOUNT_TOO_LOW",
    "error": "Monto menor al minimo"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "AMOUNT_TOO_HIGH",
    "error": "Monto mayor al maximo"
}

// HTTP 404 Not Found
{
    "success": false,
    "error_code": "CLIENT_NOT_FOUND",
    "error": "Cliente no encontrado"
}

// HTTP 503 Service Unavailable
{
    "success": false,
    "error_code": "SERVICE_UNAVAILABLE",
    "error": "Servicio Serfigas no disponible"
}
POST /sale/create Requiere Auth

Crea una orden de venta. Requiere pregunta de seguridad.

Parametros (Body JSON)
CampoTipoRequeridoDescripcion
partner_vatstringSiDocumento del cliente
contract_numberstringSiNumero de contrato
installmentsintegerSiNumero de cuotas
question_idintegerSiID pregunta seguridad
answerstringSiRespuesta seguridad
productsarraySiLista de productos
external_referencestringNoReferencia externa
notesstringNoNotas del pedido
Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/sale/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {tu_token}" \
  -d '{
    "partner_vat": "1234567890",
    "contract_number": "GAS-001-2024",
    "installments": 12,
    "question_id": 3,
    "answer": "Cartagena",
    "products": [
      {"code": "NEV001", "name": "Nevera Samsung", "quantity": 1, "price": 1200000},
      {"code": "MIC001", "name": "Microondas LG", "quantity": 1, "price": 300000}
    ],
    "external_reference": "TIENDA-2024-001"
  }'
Respuesta Exitosa 200 OK
{
    "success": true,
    "order": {
        "id": 789,
        "name": "SO001",
        "amount_total": 1500000,
        "state": "draft"
    },
    "client": {
        "id": 123,
        "name": "Juan Perez",
        "contract": "GAS-001-2024"
    },
    "brilla": {
        "installments": 12,
        "installment_amount": 142500,
        "total_amount": 1710000,
        "interest_rate": 1.99
    },
    "next_step": "Confirme la orden con POST /sale/{order_id}/confirm",
    "message": "Orden creada exitosamente"
}
Respuestas de Error
// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "SECURITY_REQUIRED",
    "error": "Respuesta de seguridad requerida",
    "security_question": {
        "question_id": 3,
        "question": "En que ciudad naciste?",
        "hint": "Ciudad de Colombia"
    }
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "SECURITY_FAILED",
    "error": "Respuesta de seguridad incorrecta"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "INSUFFICIENT_CREDIT",
    "error": "Cupo insuficiente",
    "cupo": {"disponible": 500000, "solicitado": 1500000}
}

// HTTP 500 Internal Server Error
{
    "success": false,
    "error_code": "PROCESSING_ERROR",
    "error": "Error procesando la solicitud"
}
POST /sale/{order_id}/confirm Requiere Auth

Confirma una orden y procesa el credito. Retorna hash unico para seguimiento.

Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/sale/789/confirm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {tu_token}" \
  -d '{
    "installments": 12,
    "question_id": 3,
    "answer": "Cartagena"
  }'
Respuesta Exitosa 200 OK
{
    "success": true,
    "payment_hash": "A1B2C3D4E5F6G7H8I9J0K1L2",
    "order": {
        "id": 789,
        "name": "SO001",
        "state": "sale"
    },
    "brilla": {
        "status": "approved",
        "state": "done",
        "installments": 12,
        "installment_amount": 142500,
        "total_amount": 1710000
    },
    "message": "Credito aprobado exitosamente"
}
Respuestas de Error
// HTTP 404 Not Found
{
    "success": false,
    "error_code": "ORDER_NOT_FOUND",
    "error": "Orden no encontrada"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "ORDER_INVALID_STATE",
    "error": "Estado de orden invalido",
    "current_state": "sale"
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "SECURITY_REQUIRED",
    "error": "Respuesta de seguridad requerida",
    "security_question": {
        "question_id": 3,
        "question": "En que ciudad naciste?",
        "hint": "Ciudad"
    }
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "SECURITY_FAILED",
    "error": "Respuesta de seguridad incorrecta"
}

// HTTP 403 Forbidden
{
    "success": false,
    "error_code": "FORBIDDEN",
    "error": "Acceso denegado"
}

// HTTP 503 Service Unavailable
{
    "success": false,
    "error_code": "SERVICE_UNAVAILABLE",
    "error": "Servicio Serfigas no disponible"
}

// HTTP 500 Internal Server Error
{
    "success": false,
    "error_code": "PROCESSING_ERROR",
    "error": "Error procesando la solicitud"
}
GET /sale/{order_id} Requiere Auth

Detalle de una orden de venta.

Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/sale/789" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "order": {
            "id": 789,
            "name": "SO001",
            "date": "2024-12-13T10:30:00",
            "state": "sale",
            "amount_total": 1500000,
            "external_ref": "TIENDA-2024-001",
            "lines": [
                {"product": "Nevera Samsung 250L", "quantity": 1, "price_unit": 1200000, "subtotal": 1200000},
                {"product": "Microondas LG", "quantity": 1, "price_unit": 300000, "subtotal": 300000}
            ]
        },
        "brilla": {
            "transaction_id": 456,
            "reference": "BRILLA/SO001",
            "state": "done",
            "installments": 12,
            "installment_amount": 142500,
            "total_amount": 1710000,
            "loan_id": 123
        }
    }
}
Respuestas de Error
// HTTP 404 Not Found
{
    "success": false,
    "error_code": "ORDER_NOT_FOUND",
    "error": "Orden no encontrada"
}

// HTTP 403 Forbidden
{
    "success": false,
    "error_code": "FORBIDDEN",
    "error": "Acceso denegado"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_INVALID",
    "error": "Token invalido"
}
GET /sales Requiere Auth

Lista ordenes de venta del cliente.

Parametros Query
CampoTipoDefaultDescripcion
statestring-Filtrar por estado (draft, sale, done, cancel)
limitinteger20Registros por pagina
offsetinteger0Registros a saltar
Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/sales?state=sale&limit=10" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "sales": [
            {
                "id": 789,
                "name": "SO001",
                "date": "2024-12-13T10:30:00",
                "state": "sale",
                "amount_total": 1500000,
                "brilla_state": "done",
                "brilla_installments": 12
            }
        ],
        "total": 15,
        "limit": 20,
        "offset": 0
    }
}
Respuestas de Error
// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "AUTH_REQUIRED",
    "error": "Autenticacion requerida"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_EXPIRED",
    "error": "Token expirado"
}

Facturas

GET /invoices Requiere Auth

Lista facturas del cliente.

Parametros Query
CampoTipoDescripcion
statestringdraft, posted, paid
typestringout_invoice, out_refund
limitintegerDefault: 20
offsetintegerDefault: 0
Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/invoices?state=posted&limit=10" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "invoices": [
            {
                "id": 101,
                "name": "INV/2024/0001",
                "date": "2024-12-01",
                "due_date": "2024-12-31",
                "amount_total": 142500,
                "amount_residual": 0,
                "state": "posted",
                "payment_state": "paid",
                "is_brilla": true
            }
        ],
        "total": 12,
        "limit": 20,
        "offset": 0
    }
}
Respuestas de Error
// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "AUTH_REQUIRED",
    "error": "Autenticacion requerida"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_EXPIRED",
    "error": "Token expirado"
}
GET /invoices/pending Requiere Auth

Facturas pendientes de pago con resumen de mora.

Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/invoices/pending" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "invoices": [
            {
                "id": 102,
                "name": "INV/2024/0002",
                "date": "2024-11-01",
                "due_date": "2024-11-30",
                "amount_total": 142500,
                "amount_residual": 142500,
                "is_overdue": true,
                "days_overdue": 13
            },
            {
                "id": 103,
                "name": "INV/2024/0003",
                "date": "2024-12-01",
                "due_date": "2024-12-31",
                "amount_total": 142500,
                "amount_residual": 142500,
                "is_overdue": false,
                "days_overdue": 0
            }
        ],
        "summary": {
            "count": 2,
            "total_pending": 285000,
            "overdue_count": 1,
            "overdue_amount": 142500
        }
    }
}
Respuestas de Error
// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "AUTH_REQUIRED",
    "error": "Autenticacion requerida"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_EXPIRED",
    "error": "Token expirado"
}
POST /invoices/{invoice_id}/pay Requiere Auth

Registra un pago para una factura.

Ejemplo cURL
curl -X POST "https://tu-servidor.com/api/serfigas/v1/invoices/102/pay" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {tu_token}" \
  -d '{
    "amount": 142500,
    "payment_method": "transfer",
    "reference": "PAGO-001",
    "date": "2024-12-13"
  }'
Respuesta Exitosa 200 OK
{
    "success": true,
    "payment": {
        "id": 201,
        "name": "PAGO/2024/0001",
        "amount": 142500,
        "date": "2024-12-13",
        "state": "posted"
    },
    "invoice": {
        "id": 102,
        "amount_residual": 0,
        "payment_state": "paid"
    },
    "message": "Pago registrado exitosamente"
}
Respuestas de Error
// HTTP 404 Not Found
{
    "success": false,
    "error_code": "INVOICE_NOT_FOUND",
    "error": "Factura no encontrada"
}

// HTTP 400 Bad Request - Factura ya pagada
{
    "success": false,
    "error_code": "INVOICE_ALREADY_PAID",
    "error": "La factura ya esta pagada"
}

// HTTP 400 Bad Request - Monto excede saldo
{
    "success": false,
    "error_code": "AMOUNT_EXCEEDS_BALANCE",
    "error": "Monto excede el saldo pendiente: 142500",
    "amount_residual": 142500
}

// HTTP 400 Bad Request
{
    "success": false,
    "error_code": "VALIDATION_ERROR",
    "error": "Faltan datos requeridos: amount"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_INVALID",
    "error": "Token invalido"
}

Pagos

GET /payments Requiere Auth

Historial de pagos del cliente.

Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/payments?limit=20&offset=0" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "payments": [
            {
                "id": 201,
                "name": "PAGO/2024/0001",
                "date": "2024-12-13",
                "amount": 142500,
                "ref": "PAGO-001",
                "journal": "Banco"
            }
        ],
        "total": 10,
        "limit": 20,
        "offset": 0
    }
}
Respuestas de Error
// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "AUTH_REQUIRED",
    "error": "Autenticacion requerida"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "TOKEN_EXPIRED",
    "error": "Token expirado"
}
GET /payment/{payment_hash} Requiere Auth

Consulta estado de un pago Serfigas por su hash unico.

Ejemplo cURL
curl -X GET "https://tu-servidor.com/api/serfigas/v1/payment/A1B2C3D4E5F6G7H8I9J0K1L2" \
  -H "Authorization: Bearer {tu_token}"
Respuesta Exitosa 200 OK
{
    "success": true,
    "data": {
        "payment_hash": "A1B2C3D4E5F6G7H8I9J0K1L2",
        "reference": "BRILLA/SO001",
        "state": "done",
        "amount": 1500000,
        "brilla": {
            "installments": 12,
            "installment_amount": 142500,
            "total_amount": 1710000,
            "loan_id": 123
        },
        "created_at": "2024-12-13T10:30:00",
        "updated_at": "2024-12-13T10:35:00"
    }
}
Respuestas de Error
// HTTP 404 Not Found
{
    "success": false,
    "error_code": "PAYMENT_NOT_FOUND",
    "error": "Pago no encontrado"
}

// HTTP 403 Forbidden
{
    "success": false,
    "error_code": "FORBIDDEN",
    "error": "Acceso denegado"
}

// HTTP 401 Unauthorized
{
    "success": false,
    "error_code": "AUTH_REQUIRED",
    "error": "Autenticacion requerida"
}

Codigos de Error

Codigo HTTP Mensaje Descripcion
Autenticacion
AUTH_REQUIRED401Autenticacion requeridaNo se envio token
TOKEN_EXPIRED401Token expiradoEl token ha expirado
TOKEN_INVALID401Token invalidoToken mal formado o no existe
FORBIDDEN403Acceso denegadoSin permisos para este recurso
Cliente
CLIENT_NOT_FOUND404Cliente no encontradoNo existe cliente con ese documento
CONTRACT_NOT_FOUND404Contrato no encontradoNumero de contrato no existe
CONTRACT_MISMATCH400Contrato no correspondeEl contrato no pertenece al cliente
CONTRACT_INACTIVE400Contrato inactivoEl contrato de gas esta suspendido
Bloqueos
CLIENT_BLOCKED_TEMPORARY429Cliente bloqueadoDemasiados intentos fallidos
CLIENT_REQUIRES_SUPPORT403Contacte soporteCuenta bloqueada permanentemente
TOO_MANY_ATTEMPTS429Demasiados intentosRate limit excedido
Credito
INSUFFICIENT_CREDIT400Cupo insuficienteNo tiene cupo disponible
AMOUNT_TOO_LOW400Monto muy bajoNo alcanza el minimo
AMOUNT_TOO_HIGH400Monto muy altoExcede el maximo permitido
Seguridad
SECURITY_REQUIRED400Seguridad requeridaDebe responder pregunta
SECURITY_FAILED400Respuesta incorrectaLa respuesta no coincide
SECURITY_NOT_CONFIGURED400Sin preguntasCliente sin preguntas configuradas
Ordenes
ORDER_NOT_FOUND404Orden no encontradaNo existe la orden
ORDER_INVALID_STATE400Estado invalidoLa orden no puede procesarse
Sistema
SERVICE_UNAVAILABLE503Servicio no disponibleSistema en mantenimiento
PROCESSING_ERROR500Error procesandoError interno del servidor
Formato de Error
{
    "success": false,
    "error_code": "INSUFFICIENT_CREDIT",
    "error": "Cupo insuficiente",
    "cupo": {
        "disponible": 500000,
        "solicitado": 1500000
    }
}

// Con bloqueo temporal
{
    "success": false,
    "error_code": "CLIENT_BLOCKED_TEMPORARY",
    "error": "Cuenta bloqueada por 25 minutos. Intente en 18 minutos.",
    "blocked_minutes_remaining": 18,
    "block_level": 1
}
Soporte Tecnico

Para obtener credenciales de API o asistencia tecnica:
api@serfigas.com | 605-123-4567

API Version 1.0
Ultima actualizacion: Diciembre 2024