Crear o Actualizar Persona

CREAR O ACTUALIZAR PERSONA

CABECERA

Endpoint para registrar o actualizar información de personas en el sistema TitanicSoft desde Synergy. Una persona puede ser registrada simultáneamente como Cliente, Proveedor y/o Personal según las banderas (flags) enviadas en la solicitud.

Endpoint: /api/persona/

• POST - Para crear una nueva persona (synergy_id NO debe existir)
• PUT - Para actualizar una persona existente (synergy_id DEBE existir)

---

CUERPO

Ejemplo mínimo - Cliente

{
    "fl_proveedor": 0,
    "fl_personal": 0,
    "fl_cliente": 1,
    "synergy_id": "CLI-1001",
    "tipo_documento": "RUC",
    "numero_documento": "20123456789",
    "telefono": "964567883",
    "ubigeo": "010103",
    "razon_social": "Cliente Demo SAC",
    "persona_encargado": "Juan Perez",
    "email": "cliente@demo.com",
    "moneda": "PEN",
    "tipo_linea_credito": 1
}

Ejemplo mínimo - Proveedor

{
    "fl_proveedor": 1,
    "fl_personal": 0,
    "fl_cliente": 0,
    "synergy_id": "PROV-2001",
    "tipo_documento": "RUC",
    "numero_documento": "20567891234",
    "telefono": "987654321",
    "ubigeo": "150101",
    "razon_social": "Proveedor Demo EIRL",
    "persona_encargado": "Maria Lopez"
}

Ejemplo mínimo - Personal

{
    "fl_proveedor": 0,
    "fl_personal": 1,
    "fl_cliente": 0,
    "synergy_id": "PER-3001",
    "tipo_documento": "DNI",
    "numero_documento": "12345678",
    "telefono": "912345678",
    "ubigeo": "130101",
    "nombres": "Carlos",
    "apellidos": "Ramirez",
    "genero": "MASCULINO",
    "fecha_nacimiento": "1990-01-01",
    "tipo_personal": "CONDUCTOR"
}

---

Validaciones Detalladas

Campos Obligatorios (Siempre Requeridos)

Atributo	Valor Esperado	Tipo de dato	Requisito	Longitud
fl_proveedor	0 = no es proveedor 1 = es proveedor	Integer	obligatorio	1 exacto
fl_personal	0 = no es personal 1 = es personal	Integer	obligatorio	1 exacto
fl_cliente	0 = no es cliente 1 = es cliente	Integer	obligatorio	1 exacto
synergy_id	Ejemplo: “1234” - Identificador único en Synergy	String	obligatorio	1 hasta 30
tipo_documento	DNI RUC CARNET DE EXTRANJERIA PASAPORTE	String	obligatorio	1 hasta 30
numero_documento	Ejemplo: RUC, número de DNI, Etc.	String	obligatorio	1 hasta 15
direccion	Dirección completa	String	opcional	1 hasta 250
telefono	Ejemplo: 964567883	String	obligatorio	9 hasta 15
ubigeo	Ejemplo: 010103	String	obligatorio	6 exactos

Nota importante: Al menos uno de los flags (fl_cliente, fl_proveedor, fl_personal) debe ser 1.

---

Campos Condicionales según fl_cliente = 1

Atributo	Valor Esperado	Tipo de dato	Requisito	Longitud
razon_social	Razón o nombre completo	String	obligatorio si fl_cliente=1 o fl_proveedor=1	1 hasta 100
persona_encargado	Nombre completo, puede ser un representante del cliente	String	obligatorio si fl_cliente=1	1 hasta 100
email	Dirección de email debe ser válido	String	obligatorio si fl_cliente=1	1 hasta 250
moneda	PEN = SOLES USD = DOLARES	String	obligatorio si fl_cliente=1	3 exactos
tipo_linea_credito	1 = CONTADO 2 = CREDITO	Integer	obligatorio si fl_cliente=1	1 exacto
dias_linea_credito	Es obligatorio si fl_cliente = 1 y la línea es a CREDITO	Integer	opcional	1 hasta 3

---

Campos Condicionales según fl_proveedor = 1

Atributo	Valor Esperado	Tipo de dato	Requisito	Longitud
razon_social	Razón o nombre completo	String	obligatorio si fl_proveedor=1	1 hasta 100
persona_encargado	Nombre completo	String	obligatorio si fl_proveedor=1	1 hasta 100

---

Campos Condicionales según fl_personal = 1

Atributo	Valor Esperado	Tipo de dato	Requisito	Longitud
nombres	Nombres de la persona	String	obligatorio si fl_personal=1	1 hasta 100
apellidos	Apellidos de la persona	String	obligatorio si fl_personal=1	1 hasta 100
genero	FEMENINO MASCULINO	String	obligatorio si fl_personal=1	-
fecha_nacimiento	Ejemplo: 1990-01-01 (Y-m-d)	String	obligatorio si fl_personal=1	10 exactos
tipo_personal	Ejemplo: CONDUCTOR, ADMINISTRATIVO	String	obligatorio si fl_personal=1	1 hasta 50
licencia_conducir	Ejemplo: B-123456	String	opcional	9 hasta 10
cat_licencia_conducir	Ejemplo: A-1	String	opcional	1 hasta 10

---

RESPUESTA EXITOSA

POST (Creación) - Código HTTP 201

{
    "codigo_http": 201,
    "estado": "success",
    "accion": "creada",
    "titanic_id": 123,
    "synergy_id": "1234",
    "id_cliente": 123,
    "id_proveedor": null,
    "id_personal": 456,
    "mensaje": "Persona creada exitosamente"
}

PUT (Actualización) - Código HTTP 200

{
    "codigo_http": 200,
    "estado": "success",
    "accion": "actualizada",
    "titanic_id": 123,
    "synergy_id": "1234",
    "id_cliente": 123,
    "id_proveedor": null,
    "id_personal": 456,
    "mensaje": "Persona actualizada exitosamente"
}

---

POSIBLES ERRORES DE VALIDACIÓN

1. Método HTTP No Permitido - Código 405

Escenario: Se utiliza un método diferente a POST o PUT

{
    "codigo_http": 405,
    "estado": "method_not_allowed",
    "mensaje": "Método no permitido. Use POST para crear o PUT para actualizar."
}

---

2. Error de Validación de Campos - Código 400

Escenario: Los datos enviados no cumplen con las reglas de validación

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Error en la validación",
    "detalles": {
        "synergy_id": "El campo synergy_id es requerido",
        "tipo_documento": "Tipo de documento no permitido. Valores permitidos: DNI, RUC, CARNET DE EXTRANJERIA, PASAPORTE"
    }
}

---

3. Al Menos Un Flag Debe Ser 1 - Código 400

Escenario: Todos los flags (fl_cliente, fl_proveedor, fl_personal) son 0

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Al menos uno de los flags (fl_cliente, fl_proveedor, fl_personal) debe ser 1"
}

---

4. Error en Validaciones Condicionales - Código 400

Escenario: Faltan campos obligatorios según los flags activados

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Error en validaciones condicionales",
    "detalles": {
        "razon_social": "El campo razon_social es obligatorio si fl_cliente=1",
        "email": "El campo email es obligatorio si fl_cliente=1"
    }
}

---

5. Conflicto - Persona Ya Existe (POST) - Código 409

Escenario: Se intenta crear una persona con POST pero el synergy_id ya existe

{
    "codigo_http": 409,
    "estado": "conflict",
    "mensaje": "La persona ya existe con este synergy_id",
    "detalles": {
        "synergy_id": "1234",
        "tabla": "cliente",
        "documento": "12345678",
        "solucion": "Use PUT para actualizar la persona existente"
    }
}

---

6. No Encontrado - Persona No Existe (PUT) - Código 404

Escenario: Se intenta actualizar una persona con PUT pero el synergy_id no existe

{
    "codigo_http": 404,
    "estado": "not_found",
    "mensaje": "La persona no existe con este synergy_id",
    "detalles": {
        "synergy_id": "1234",
        "solucion": "Use POST para crear una nueva persona"
    }
}

---

7. Error de Validación de Documento - Código 400

Escenario: El número de documento no cumple con el formato según el tipo

{
    "codigo_http": 400,
    "estado": "validation_error",
    "mensaje": "Error en validación de documento",
    "detalles": {
        "numero_documento": "El DNI debe tener 8 dígitos"
    }
}