Desarrollo de Conector de Facturación Electrónica para Odoo en Panamá con python en Google Cloud

Se requiere el desarrollo (python) de un sistema centralizado para el timbrado de Factura Electrónica en Panamá, con integración directa desde Odoo. El proyecto implica la creación de dos conectores principales para la alimentación de datos de facturación con un núcleo común:

A) Núcleo común (para ambos conectores):
Endpoint/servicio central para:
Validar request y resolver a qué empresa pertenece.
Validaciones básicas (campos obligatorios, totales, impuestos, etc.).
Envío a timbrado
Manejo de estados: recibido → en_proceso → timbrado → rechazado/error.
Idempotencia: si llega dos veces la misma factura, no timbrar doble.
Reintentos controlados y cola (para no perder facturas).

1. Conector Email: Este módulo deberá ser capaz de recibir archivos XML en formato Factur-X CII enviados por correo electrónico desde Odoo. La funcionalidad incluirá la extracción de los datos relevantes contenidos en el XML para su posterior procesamiento y envío al servicio de timbrado.

2. Conector API: Se desarrollará un conector que permita extraer datos de facturas directamente desde una instancia de Odoo Online Custom a través de su API. Este conector deberá manejar la comunicación vía JSON para obtener la información necesaria y prepararla para el proceso de timbrado.

El objetivo es establecer un flujo de trabajo eficiente y automatizado para la emisión de facturas electrónicas conformes con la normativa panameña, asegurando la correcta extracción, procesamiento y timbrado de la información.

1. conector email:
automatización de timbrado fe panamá desde odoo vía email (factur-x/cii) → pac (soap) en google cloud (multiempresa / multisucursal)

alcance funcional
1.    Configuración de servidor en Google Cloud para recibir correo que contiene el pdf y xml, quizás bucket.
2.    Ingesta por correo (IMAP)
a.    Recibir emails que contengan pdf + xml de odoo.
b.    Detectar y descargar adjunto XML Factur-X (cii) y descartar pdf.
3.    Extracción y mapeo (Odoo xml → pac)
a.    Parsear Factur-X (CII) y extraer cabecera, cliente, líneas, impuestos, totales, moneda, etc.
b.    Construir el xml en formato del pac (soap “enviar” y nodos internos del proveedor).
4.    Envío al PAC + manejo de respuesta
a.    Enviar el xml al endpoint del pac (soap).
b.    Registrar respuesta (aceptado/rechazado, CUFE o equivalente, mensajes de error).
c.    Responder a Odoo por email devolviendo el resultado (por ejemplo: XML de respuesta/acuse).
a.    Manejo de errores por: xml incompleto, validaciones del pac, caídas de red, timeouts.
b.    Reintentos controlados y “recomendaciones” de corrección cuando falten datos (ej: descripción de línea obligatoria).
a.    Debe ser fácil agregar nuevas empresas/DBs al sistema.

Requerimientos no funcionales / arquitectura
4.    Configuración simple por empresa: ideal por archivo config (yaml/json) o mini ui web para administrar empresas/sucursales (opcional).
Quiero una seguridad básica para que otra empresa no pueda timbrar “suplantando” por correo. La empresa puede identificarse por nombre/RUC/dominio, pero debe existir un control adicional. La propuesta debe incluir:
1.    Validación de correo entrante con spf/dkim/dmarc (cuando sea posible).
2.    Token por empresa (secreto) para autorizar timbrado
3.    Lista blanca de remitentes permitidos (opcional).

2. conector api
título: integración odoo ↔ (pac panamá) – plataforma intermediaria multi-empresa (python)
breve descripción:
construcción en python de una plataforma en la nube que lea facturas/notas desde odoo vía api (sin modificar odoo) y las envíe a hka thefactory (pac panamá) para timbrado/autorización. Debe ser multi-empresa (multi-tenant), escalable para operación masiva, con manejo de estados, reintentos y descarga de xml/pdf.

Objetivos:
•    Extraer datos de Odoo con mínima invasión (solo lectura, sin Studio, sin campos nuevos).
•    Mapear documentos contables estándar de Odoo a los servicios del PAC.
•    Timbrar / consultar estado / regresar xml/pdf / anular.
•    Operar con múltiples empresas (cada una con sus credenciales Odoo + tokens PAC).
Alcance:
3.    Extracción de información vía API Odoo utilizando json-2 api.
5.    Recepción de respuesta del PAC a Odoo en el seguimiento (chatter) y escribiendo en el campo ref el número de factura electrónica.
6.    Manejo de errores por envío, con recomendaciones para que la factura pueda timbrarse y renvíos.
7.    Entrega con presentación con explicación de la solución en 1 hora.
8.    Soporte post entrega durante dos semanas semana (4 horas totales).
9.    Asesoría para la llave que se debe recibir de la empresa emisora de la factura.
10.    No se permite crear campos nuevos en Odoo ni instalar módulos custom en Odoo.

Entregables
1.    Repositorio con código completo.
2.    Dockerfile + docker-compose para correr local/staging.
3.    Esquema DB + migraciones.
4.    Colección Postman/Insomnia.
5.    Documento de mapeo Odoo → HKA (campos clave).
6.    Guía de despliegue y operación (crear tenant, correr sync, ver estados, reintentos).
7.    Tests mínimos (mapeo + estados + un E2E “happy path” en staging).