Documentación Técnica: API de Integración

Especificación de consumo para servicios de Denuncias y Consultas.

1. Introducción

El presente documento detalla la especificación técnica y el flujo de consumo de la API de Integración. La arquitectura se basa en servicios RESTful protegidos mediante el estándar OAuth 2.0.

El ciclo de vida de una integración consta de dos fases obligatorias:

Autenticación: Obtención de un Token de Acceso (Bearer Token).
Operación: Consumo de los métodos de negocio (Crear Denuncia, Consultar Caso) utilizando dicho token.

2. Autenticación (Obtener Token)

Para interactuar con los endpoints protegidos, el cliente debe obtener un token mediante el flujo Resource Owner Password Credentials.

POST /token

Encabezados (Headers)

Header	Valor
Content-Type	`application/x-www-form-urlencoded`

Cuerpo de la Solicitud (Body)

Clave	Valor	Descripción
`grant_type`	password	Valor fijo. Indica el tipo de flujo OAuth.
`username`	[Usuario Asignado]	Credencial de usuario API.
`password`	[Contraseña Asignada]	Credencial de contraseña API.

Respuesta Exitosa (200 OK)

Retorna el token de acceso y los metadatos del contexto del usuario (IDs de negocio permitidos).

{
    "access_token": "pfLk6U9VryYeZnq... (token encriptado) ...PwA",
    "token_type": "bearer",
    "expires_in": 86399,
    "id_cliente": "12345",
    "lista_negocios": "7,8,12",
    "usuario": "api_user"
}

Importante: Debe almacenar el valor de access_token para las llamadas futuras. Utilice lista_negocios y id_cliente como referencia para saber qué datos puede consultar.

3. Método: Crear Denuncia

Permite el ingreso de una nueva denuncia en el sistema.

POST /api/denuncia

Encabezados (Headers)

Header	Valor
Content-Type	`application/json`
Authorization	`Bearer [access_token]`

Cuerpo de la Solicitud (JSON Schema)

Todos los campos son obligatorios excepto idComuna.

Campo	Tipo	Descripción
id_negocio	Integer	ID del negocio (Debe coincidir con los permisos del token).
id_cliente	Integer	ID del cliente/usuario.
poliza	Integer	Número de póliza.
rut_cliente	String	RUT del cliente.
nombre_cliente	String	Nombre de pila.
apPaterno_cliente	String	Apellido paterno.
apMaterno_cliente	String	Apellido materno.
fono_cliente	Long	Teléfono numérico.
mail	String	Correo electrónico.
direccion	String	Dirección del siniestro.
idComuna	Integer	ID interno de comuna (Opcional).
comuna	String	Nombre de la comuna.
ciudad	String	Nombre de la ciudad.
nroSiniestro	Integer	Número de siniestro o referencia.
nroBoleta	String	Número de boleta/factura.
tipoProducto	String	Categoría del producto.
marca	String	Marca del producto.
modelo	String	Modelo del producto.
fechaDenuncia	DateTime	ISO 8601 (YYYY-MM-DDTHH:mm:ss).
fechaSiniestro	DateTime	ISO 8601 (YYYY-MM-DDTHH:mm:ss).
tipoSiniestro	Integer	Código de tipo de siniestro.
relato	String	Descripción del incidente.

Ejemplo de JSON

{
    "id_negocio": 4,
    "id_cliente": 123,
    "poliza": 987654,
    "rut_cliente": "12345678-9",
    "nombre_cliente": "María",
    "apPaterno_cliente": "Pérez",
    "apMaterno_cliente": "Gómez",
    "fono_cliente": 987654321,
    "mail": "maria.perez@example.com",
    "direccion": "Av. Providencia 1550",
    "idComuna": 6,
    "comuna": "Santiago",
    "ciudad": "Santiago",
    "nroSiniestro": 9832,
    "nroBoleta": "BOL987654",
    "tipoProducto": "Refrigerador",
    "marca": "LG",
    "modelo": "No Frost",
    "fechaDenuncia": "2025-10-28T10:30:00",
    "fechaSiniestro": "2025-10-26T15:45:00",
    "tipoSiniestro": 2,
    "relato": "El refrigerador dejó de funcionar."
}

Respuesta Exitosa (200 OK)

{
    "MSG_ERROR": "Denuncia recibida correctamente",
    "COD_ERROR": 100,
    "NUM_CASO": 5255
}

4. Método: Consultar Caso

Permite obtener el estado y detalles de un caso específico. La respuesta es generada dinámicamente según el resultado de la base de datos.

POST /api/consulta

Cuerpo de la Solicitud (JSON)

{
    "id_negocio": 7,
    "id_cliente": 123,
    "id_caso": 5255
}

Nota: El id_negocio enviado debe estar presente en la lista de permisos de su token.

Respuesta Exitosa (200 OK - Dinámica)

[
    {
        "NUM_CASO": 5255,
        "ESTADO_CASO": "En Proceso",
        "PRODUCTO": "Refrigerador LG",
        "FECHA_INGRESO": "2025-11-15T14:30:00"
    }
]

5. Códigos de Error

La API utiliza códigos de estado HTTP estándar para reportar errores.

Código	Descripción
400 Bad Request	La solicitud es inválida. Puede deberse a un JSON mal formado, campos obligatorios faltantes o datos vacíos.
401 Unauthorized	No se envió el token, el token ha expirado o la firma es inválida.
403 Forbidden	Acceso denegado por reglas de negocio. El `id_negocio` solicitado no corresponde a los permisos del usuario autenticado.
500 Internal Server Error	Error en el procesamiento del servidor o base de datos. Consulte el campo `MSG_ERROR` en la respuesta para más detalles.