Integración - Actualización de contactos

Proyecto Milla

Documentación - Endpoints /cliente_alta y /cliente_baja

Autenticación y Seguridad

  • Autenticación requerida: Sí (auth='user')
  • Método de autenticación: Los usuarios deben autenticarse a través del endpoint /web/session/authenticate para obtener una sesión válida.

Pasos para Autenticarse

  1. Autenticarse en Odoo:

    • Realiza una solicitud POST al endpoint /web/session/authenticate con las credenciales del usuario.
    • Obtendrás una cookie de sesión (session_id).

  2. Usar la Sesión en las Solicitudes:

    • Incluye el session_id en las cookies de la solicitud.

Endpoint: /cliente_alta

  • Método HTTP: POST
  • Tipo de contenido: application/json
  • Autenticación: Requerida (auth='user')
  • Descripción: Permite dar de alta a un cliente en el sistema Odoo.

Parámetros de Entrada

  • tipo_documento_cliente (string, requerido): Tipo de documento del cliente. Valores permitidos:

    • '1': DNI
    • '4': Carné de extranjería
    • '7': Pasaporte
    • 'A', 'B', 'C', 'D', 'E', 'F': Otros documentos

  • numero_documento_cliente (string, requerido): Número de documento del cliente.

    • Si tipo_documento_cliente es '1', debe tener 8 dígitos y ser numérico.
    • Para otros tipos, debe tener al menos 4 caracteres.

  • apellidos_nombres_cliente (string, requerido): Apellidos y nombres completos del cliente.

  • ruc_empleador (string, requerido): RUC del empleador. Debe tener 11 dígitos y ser numérico.

  • fecha_ingreso_cliente (string, requerido): Fecha de ingreso del cliente en formato "dd/mm/aaaa".

  • email (string, opcional): Correo electrónico del cliente.

  • celular (string, opcional): Número de celular del cliente.

Ejemplo de Solicitud

Paso 1: Autenticarse

Solicitud:

http

POST /web/session/authenticate HTTP/1.1
Content-Type: application/json

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "db": "nombre_de_la_base_de_datos",
        "login": "usuario@example.com",
        "password": "tu_contraseña"
    },
    "id": 1
}

Respuesta:

json

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "uid": 2,
        "user_context": {...},
        "company_id": 1,
        "partner_id": 3,
        "session_id": "session_id_obtenido"
    }
}

Paso 2: Invocar el Endpoint /cliente_alta

Solicitud:

http

POST /cliente_alta HTTP/1.1
Content-Type: application/json
Cookie: session_id=session_id_obtenido
jso
 {
    "tipo_documento_cliente": "1",
    "numero_documento_cliente": "12345678",
    "apellidos_nombres_cliente": "Juan Pérez",
    "ruc_empleador": "20123456789",
    "fecha_ingreso_cliente": "25/09/2021",
    "email": "juan.perez@example.com",
    "celular": "987654321"
}

Respuestas

Éxito (200 OK)

El cliente ha sido dado de alta correctamente.

Ejemplo de respuesta:

json

{
    "status": 200,
    "message": "El cliente Juan Pérez fue dado de alta correctamente."
}

Error de validación (400 Bad Request)

Faltan campos requeridos o hay errores en los datos proporcionados.

Ejemplo de respuesta:

json

{
    "status": 400,
    "message": "El tipo de documento del cliente debe ser un texto.\r\nEl número de documento del cliente debe tener como mínimo 4 caracteres."
}

Recurso no encontrado (404 Not Found)

No se encontró el empleador con el RUC proporcionado.

Ejemplo de respuesta:

json
 
{
    "status": 404,
    "message": "No se encontró al empleador con RUC: 20123456789."
}

Conflicto (409 Conflict)

El cliente ya se encuentra dado de alta.

Ejemplo de respuesta:

json

{
    "status": 409,
    "message": "El cliente Juan Pérez ya se encuentra dado de alta. Para darle de alta nuevamente, primero debe ser dado de baja."
}

Error del servidor (500 Internal Server Error)

Ocurrió un error interno al procesar la solicitud.

Ejemplo de respuesta:

json

{
    "status": 500,
    "message": "Error al procesar la solicitud."
}

Endpoint: /cliente_baja

  • Método HTTP: POST
  • Tipo de contenido: application/json
  • Autenticación: Requerida (auth='user')
  • Descripción: Permite dar de baja a un cliente en el sistema Odoo.

Parámetros de Entrada

  • tipo_documento_cliente (string, requerido): Tipo de documento del cliente. Valores permitidos (igual que en /cliente_alta).

  • numero_documento_cliente (string, requerido): Número de documento del cliente.

    • Si tipo_documento_cliente es '1', debe tener 8 dígitos y ser numérico.
    • Para otros tipos, debe tener al menos 4 caracteres.

  • ruc_empleador (string, requerido): RUC del empleador. Debe tener 11 dígitos y ser numérico.

  • fecha_cese_cliente (string, requerido): Fecha de cese del cliente en formato "dd/mm/aaaa".

Ejemplo de Solicitud

Paso 1: Autenticarse

(Este paso es el mismo que en el endpoint /cliente_alta)

Paso 2: Invocar el Endpoint /cliente_baja

Solicitud:

http

POST /cliente_baja HTTP/1.1
Content-Type: application/json
Cookie: session_id=session_id_obtenido
json

{
    "tipo_documento_cliente": "1",
    "numero_documento_cliente": "12345678",
    "ruc_empleador": "20123456789",
    "fecha_cese_cliente": "30/09/2023"
}

Respuestas

Éxito (200 OK)

El cliente ha sido dado de baja correctamente.

Ejemplo de respuesta:

json

{
    "status": 200,
    "message": "El cliente Juan Pérez ha sido dado de baja correctamente."
}

Error de validación (400 Bad Request)

Faltan campos requeridos o hay errores en los datos proporcionados.

Ejemplo de respuesta:

json

{
    "status": 400,
    "message": "La fecha de cese del cliente debe ser un texto con el formato dd/mm/aaaa.\r\nEl RUC del empleador debe tener 11 caracteres."
}

Recurso no encontrado (404 Not Found)

No se encontró el empleador o el cliente con los datos proporcionados.

Ejemplo de respuesta:

json

{
    "status": 404,
    "message": "No se encontró el cliente con número de documento 12345678 cuyo empleador sea RUC 20123456789."
}

Conflicto (409 Conflict)

El cliente ya se encuentra dado de baja.

Ejemplo de respuesta:

json
 
{
    "status": 409,
    "message": "El cliente Juan Pérez ya se encuentra dado de baja."
}

Error del servidor (500 Internal Server Error)

Ocurrió un error interno al procesar la solicitud.

Ejemplo de respuesta:

json

{
    "status": 500,
    "message": "Error al procesar la solicitud."
}

Proceso Detallado de Autenticación

1. Autenticarse en Odoo

Solicitud de Autenticación:

http

POST /web/session/authenticate HTTP/1.1
Content-Type: application/json

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "db": "nombre_de_la_base_de_datos",
        "login": "usuario@example.com",
        "password": "tu_contraseña"
    },
    "id": 1
}

Respuesta Exitosa:

json

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "uid": 2,
        "user_context": {...},
        "company_id": 1,
        "partner_id": 3,
        "session_id": "session_id_obtenido"

    }
}

2. Realizar Solicitudes a los Endpoints Protegidos

Incluye el session_id en las cookies.

Validaciones y Reglas de Negocio

  • Campos Requeridos: Verifica que todos los campos obligatorios estén presentes y no estén vacíos.
  • Tipos de Datos: Todos los campos deben ser de tipo string.
  • Tipo de Documento: Debe ser uno de los valores permitidos.
  • Número de Documento:
    • Si el tipo es '1', debe tener exactamente 8 dígitos y ser numérico.
    • Para otros tipos, debe tener al menos 4 caracteres.
  • RUC del Empleador: Debe tener exactamente 11 dígitos y ser numérico. Se verifica que el empleador exista en el sistema.
  • Fechas: Las fechas deben tener el formato "dd/mm/aaaa" y ser fechas válidas.

Consideraciones de Seguridad

  • Sesiones: Las sesiones tienen una duración limitada. Si la sesión expira, debes volver a autenticarse.
  • Almacenamiento Seguro: Asegúrate de almacenar de forma segura el session_id en tu aplicación cliente.
  • Comunicación Segura: Utiliza siempre HTTPS para las comunicaciones con el servidor Odoo para proteger los datos en tránsito.