Integración Zoho-Tupana - Deluge/Webhook
Budget / SalaryHourly project
TypeFreelance project
LocationRemote
Posted1 hour ago
Integración de Zoho Creator con API de Tupana – Deluge + Webhook
Busco un desarrollador con experiencia comprobable en Zoho Creator, Deluge e integraciones mediante APIs REST para completar una integración entre una aplicación existente en Zoho Creator y la plataforma de facturación electrónica Tupana.
La aplicación y el formulario de emisión ya existen. El objetivo no es desarrollar el sistema desde cero, sino conectar correctamente el formulario actual con Tupana para que los datos de una boleta/factura puedan enviarse, procesarse y posteriormente actualizar el mismo registro de Zoho Creator con la información devuelta por Tupana.
Flujo que debe implementarse
1. Envío desde Zoho Creator hacia Tupana
Desde el formulario existente de emisión de boletas/facturas en Zoho Creator se debe:
- Identificar el registro que genera la solicitud de emisión.
- Tomar los campos correspondientes del registro.
- Construir el JSON requerido por la API de Tupana.
- Realizar la llamada HTTP desde Deluge al endpoint correspondiente de Tupana.
- Utilizar correctamente la API Key mediante el header de autenticación.
- Implementar el mecanismo de "Idempotency-Key" para evitar emisiones/lotes duplicados cuando exista un reintento de la operación.
- Registrar en Zoho el identificador de la operación/lote y el estado inicial de la solicitud.
- Gestionar correctamente respuestas HTTP exitosas y errores de validación/API.
El endpoint principal a integrar es:
"POST /v2/documents/batch/"
La API de Tupana permite enviar documentos en lote y devuelve inicialmente un "batch_id" y un estado de procesamiento.
2. Tipos de documento
La integración debe respetar el tipo de documento que corresponda según la información existente en Zoho Creator.
Tupana contempla, entre otros, factura electrónica DTE 33 y boletas de honorarios DTE 80/90. La estructura exacta deberá determinarse a partir de los campos actualmente utilizados en el formulario de Zoho.
No se requiere modificar innecesariamente la estructura actual de la aplicación. Primero se debe revisar el formulario y realizar el mapeo entre los campos existentes y los campos requeridos por Tupana.
3. Recepción de la respuesta mediante Webhook
Se debe implementar la recepción de la respuesta de Tupana mediante webhook.
Tupana actualmente dispone del evento "document.issued", que se ejecuta cuando el documento ha sido emitido correctamente. El webhook devuelve información como:
- ID del documento
- Folio
- Fecha de emisión
- Tipo de documento
- Datos del emisor/receptor
- Totales
- Detalles
- URL del PDF
- Información adicional disponible
La documentación de Tupana indica además que el webhook puede utilizar una firma HMAC-SHA256 mediante "X-Pana-Signature", por lo que se debe implementar la validación de seguridad si resulta aplicable al mecanismo utilizado.
4. Actualización del registro original en Zoho
La respuesta recibida debe relacionarse correctamente con el registro original que inició la emisión.
En el formulario de Zoho Creator ya existen campos destinados a almacenar la respuesta de Tupana:
- Mensaje del SII
- Folio
- Link PDF
- Fecha de la Boleta/Factura
El desarrollador deberá completar esos campos automáticamente cuando Tupana confirme la emisión.
También deberá quedar almacenado el identificador necesario para poder rastrear la operación y relacionar la respuesta con el registro correcto.
5. Manejo de errores
La integración debe contemplar como mínimo:
- Error de autenticación.
- Error de conexión/API.
- Errores HTTP.
- Errores de validación de datos.
- Respuestas incompletas.
- Reintentos.
- Prevención de duplicidad de documentos.
- Registro del motivo del error dentro de Zoho Creator.
- Evitar que una factura se genere nuevamente simplemente porque una solicitud fue repetida.
El objetivo es que un usuario pueda identificar desde Zoho si la emisión fue exitosa o si existe un problema, sin depender de revisar manualmente logs externos.
6. Sandbox y pruebas
La implementación deberá realizarse inicialmente utilizando el ambiente de pruebas de Tupana.
Se deberán realizar pruebas completas de extremo a extremo:
Zoho Creator → Deluge → API Tupana → procesamiento → Webhook → Zoho Creator
Se deberán comprobar al menos:
1. Emisión correcta de un documento.
2. Recepción del webhook.
3. Actualización del registro original.
4. Registro correcto del folio.
5. Registro de la fecha.
6. Registro del enlace al PDF cuando esté disponible.
7. Manejo de una solicitud con datos inválidos.
8. Comportamiento ante una respuesta de error.
9. Prevención de duplicados mediante idempotencia.
10. Correcta relación entre la respuesta de Tupana y el registro que originó la emisión.
7. Revisión de la aplicación existente
Antes de modificar el sistema, el desarrollador deberá revisar:
- Formulario actual de emisión.
- Campos existentes.
- Workflows relacionados.
- Funciones Deluge existentes.
- Integraciones actuales de la aplicación que puedan afectar el funcionamiento.
- Posibles automatizaciones existentes relacionadas con facturación.
No se debe modificar ni eliminar funcionalidad existente que no sea necesaria para esta integración.
Si existen integraciones previas dentro de la aplicación, se deberá trabajar de forma que la nueva integración no las afecte.
Entregables
El proyecto se considerará terminado cuando se entregue:
- Integración funcional Zoho Creator → Tupana.
- Integración funcional del webhook Tupana → Zoho Creator.
- Código Deluge implementado y organizado.
- Mapeo de campos correctamente configurado.
- Manejo de errores.
- Protección contra emisiones duplicadas.
- Actualización automática del registro original.
- Pruebas realizadas en Sandbox.
- Validación de al menos un flujo completo de emisión.
- Breve documentación indicando dónde quedó implementada la integración y cómo funciona.
- Instrucciones necesarias para pasar posteriormente de Sandbox a producción.
Requisitos del desarrollador
Busco específicamente experiencia con:
- Zoho Creator.
- Deluge.
- Zoho Creator REST/API integrations.
- Webhooks.
- APIs REST.
- JSON.
- Manejo de errores HTTP.
- Integraciones asíncronas.
- Sistemas de facturación electrónica o DTE, preferiblemente.
Es importante que el candidato pueda trabajar directamente dentro de Zoho Creator y no solamente proporcionar código externo.
La documentación oficial de Tupana está disponible y será proporcionada como referencia para la implementación.
Condición de aceptación
No se considera suficiente que la API responda correctamente.
La integración debe funcionar de principio a fin: crear la solicitud desde Zoho, procesarla en Tupana, recibir la respuesta y actualizar automáticamente el mismo registro de Zoho con los datos correspondientes.
El presupuesto es 5 por hora un total a pagar 120 usd al terminar y probado el trabajo
Busco un desarrollador con experiencia comprobable en Zoho Creator, Deluge e integraciones mediante APIs REST para completar una integración entre una aplicación existente en Zoho Creator y la plataforma de facturación electrónica Tupana.
La aplicación y el formulario de emisión ya existen. El objetivo no es desarrollar el sistema desde cero, sino conectar correctamente el formulario actual con Tupana para que los datos de una boleta/factura puedan enviarse, procesarse y posteriormente actualizar el mismo registro de Zoho Creator con la información devuelta por Tupana.
Flujo que debe implementarse
1. Envío desde Zoho Creator hacia Tupana
Desde el formulario existente de emisión de boletas/facturas en Zoho Creator se debe:
- Identificar el registro que genera la solicitud de emisión.
- Tomar los campos correspondientes del registro.
- Construir el JSON requerido por la API de Tupana.
- Realizar la llamada HTTP desde Deluge al endpoint correspondiente de Tupana.
- Utilizar correctamente la API Key mediante el header de autenticación.
- Implementar el mecanismo de "Idempotency-Key" para evitar emisiones/lotes duplicados cuando exista un reintento de la operación.
- Registrar en Zoho el identificador de la operación/lote y el estado inicial de la solicitud.
- Gestionar correctamente respuestas HTTP exitosas y errores de validación/API.
El endpoint principal a integrar es:
"POST /v2/documents/batch/"
La API de Tupana permite enviar documentos en lote y devuelve inicialmente un "batch_id" y un estado de procesamiento.
2. Tipos de documento
La integración debe respetar el tipo de documento que corresponda según la información existente en Zoho Creator.
Tupana contempla, entre otros, factura electrónica DTE 33 y boletas de honorarios DTE 80/90. La estructura exacta deberá determinarse a partir de los campos actualmente utilizados en el formulario de Zoho.
No se requiere modificar innecesariamente la estructura actual de la aplicación. Primero se debe revisar el formulario y realizar el mapeo entre los campos existentes y los campos requeridos por Tupana.
3. Recepción de la respuesta mediante Webhook
Se debe implementar la recepción de la respuesta de Tupana mediante webhook.
Tupana actualmente dispone del evento "document.issued", que se ejecuta cuando el documento ha sido emitido correctamente. El webhook devuelve información como:
- ID del documento
- Folio
- Fecha de emisión
- Tipo de documento
- Datos del emisor/receptor
- Totales
- Detalles
- URL del PDF
- Información adicional disponible
La documentación de Tupana indica además que el webhook puede utilizar una firma HMAC-SHA256 mediante "X-Pana-Signature", por lo que se debe implementar la validación de seguridad si resulta aplicable al mecanismo utilizado.
4. Actualización del registro original en Zoho
La respuesta recibida debe relacionarse correctamente con el registro original que inició la emisión.
En el formulario de Zoho Creator ya existen campos destinados a almacenar la respuesta de Tupana:
- Mensaje del SII
- Folio
- Link PDF
- Fecha de la Boleta/Factura
El desarrollador deberá completar esos campos automáticamente cuando Tupana confirme la emisión.
También deberá quedar almacenado el identificador necesario para poder rastrear la operación y relacionar la respuesta con el registro correcto.
5. Manejo de errores
La integración debe contemplar como mínimo:
- Error de autenticación.
- Error de conexión/API.
- Errores HTTP.
- Errores de validación de datos.
- Respuestas incompletas.
- Reintentos.
- Prevención de duplicidad de documentos.
- Registro del motivo del error dentro de Zoho Creator.
- Evitar que una factura se genere nuevamente simplemente porque una solicitud fue repetida.
El objetivo es que un usuario pueda identificar desde Zoho si la emisión fue exitosa o si existe un problema, sin depender de revisar manualmente logs externos.
6. Sandbox y pruebas
La implementación deberá realizarse inicialmente utilizando el ambiente de pruebas de Tupana.
Se deberán realizar pruebas completas de extremo a extremo:
Zoho Creator → Deluge → API Tupana → procesamiento → Webhook → Zoho Creator
Se deberán comprobar al menos:
1. Emisión correcta de un documento.
2. Recepción del webhook.
3. Actualización del registro original.
4. Registro correcto del folio.
5. Registro de la fecha.
6. Registro del enlace al PDF cuando esté disponible.
7. Manejo de una solicitud con datos inválidos.
8. Comportamiento ante una respuesta de error.
9. Prevención de duplicados mediante idempotencia.
10. Correcta relación entre la respuesta de Tupana y el registro que originó la emisión.
7. Revisión de la aplicación existente
Antes de modificar el sistema, el desarrollador deberá revisar:
- Formulario actual de emisión.
- Campos existentes.
- Workflows relacionados.
- Funciones Deluge existentes.
- Integraciones actuales de la aplicación que puedan afectar el funcionamiento.
- Posibles automatizaciones existentes relacionadas con facturación.
No se debe modificar ni eliminar funcionalidad existente que no sea necesaria para esta integración.
Si existen integraciones previas dentro de la aplicación, se deberá trabajar de forma que la nueva integración no las afecte.
Entregables
El proyecto se considerará terminado cuando se entregue:
- Integración funcional Zoho Creator → Tupana.
- Integración funcional del webhook Tupana → Zoho Creator.
- Código Deluge implementado y organizado.
- Mapeo de campos correctamente configurado.
- Manejo de errores.
- Protección contra emisiones duplicadas.
- Actualización automática del registro original.
- Pruebas realizadas en Sandbox.
- Validación de al menos un flujo completo de emisión.
- Breve documentación indicando dónde quedó implementada la integración y cómo funciona.
- Instrucciones necesarias para pasar posteriormente de Sandbox a producción.
Requisitos del desarrollador
Busco específicamente experiencia con:
- Zoho Creator.
- Deluge.
- Zoho Creator REST/API integrations.
- Webhooks.
- APIs REST.
- JSON.
- Manejo de errores HTTP.
- Integraciones asíncronas.
- Sistemas de facturación electrónica o DTE, preferiblemente.
Es importante que el candidato pueda trabajar directamente dentro de Zoho Creator y no solamente proporcionar código externo.
La documentación oficial de Tupana está disponible y será proporcionada como referencia para la implementación.
Condición de aceptación
No se considera suficiente que la API responda correctamente.
La integración debe funcionar de principio a fin: crear la solicitud desde Zoho, procesarla en Tupana, recibir la respuesta y actualizar automáticamente el mismo registro de Zoho con los datos correspondientes.
El presupuesto es 5 por hora un total a pagar 120 usd al terminar y probado el trabajo
Apply on Freelancer →
Project sourced from Freelancer.com. Applications happen directly on the original platform — we never collect your data.