zohoInvoiceQueue

Procesa emisión de facturas de Zoho al PAC con reintentos automáticos.

• Endpoint: POST /queue/invoices/:invoice_id
• Reintentos: Automáticos con backoff exponencial
• Timeout: 5 minutos por intento
• Validaciones críticas: Prevención de CUFE duplicado y lock de 10 minutos entre emisiones

zohoCreditNoteQueue

Procesa emisión de notas de crédito de Zoho.

• Reintentos: Automáticos sin límite artificial
• Manejo de errores: Jobs fallidos almacenados en Redis
• Validaciones críticas: Prevención de CUFE duplicado y lock de 10 minutos entre emisiones

quickbooksInvoiceQueue

Procesa eventos de webhooks de QuickBooks en segundo plano.

• Triggered por: POST /quickbooks/event_processor
• Procesamiento: Facturas creadas/actualizadas automáticamente
• Reintentos inteligentes: Hasta 8 intentos con delays adaptativos

Reconciliación de Pagos Huérfanos

// Ejecutar manualmente
node jobs/reconcile_orphans_job.js

// Programar con cron (diario 2 AM)
0 2 * * * cd /path/to/aciv2 && node jobs/reconcile_orphans_job.js

Funcionalidades:

• Escanea todos los pagos en QuickBooks
• Identifica pagos sin líneas de aplicación
• Clasifica: eliminar ($0) vs vincular (>$0)
• Genera reporte con acciones recomendadas

Obtiene la URL de autorización de QuickBooks OAuth2.

Respuesta

{
  "authUri": "https://appcenter.intuit.com/connect/oauth2?...",
  "state": "random-state-string"
}

Establece los tokens de acceso después de la autorización OAuth2.

Body

{
  "code": "authorization_code",
  "realmId": "realm_id",
  "state": "state_string"
}

Revoca el refresh token de una conexión.

Parámetros

• sid - ID de la conexión

1. PrimaryTaxIdentifier (Campo Principal)

Ubicación en QuickBooks: Customer → Tax Info → Business ID No.

Este es el campo oficial de QuickBooks para identificación tributaria. Tiene prioridad 1 en la extracción de datos.

2. AlternatePhone.FreeFormNumber (Campo Alternativo)

Ubicación en QuickBooks: Customer → Phone → Other Phone

Campo de fallback con prioridad 2. Se usa si PrimaryTaxIdentifier está vacío o no tiene formato válido.

1. Persona Natural - Formato Estándar

XXXX9-734-1672 DV:56
XXXX8-123-4567 DV:12
XXXX1-234-5678 DV:34

Patrón: XXXX[provincia]-[tomo]-[asiento] DV:[dv]

• Provincia: 1-13 o E/N/PE (1 o 2 caracteres)
• DV puede escribirse con o sin dos puntos: DV:56 o DV56

2. Persona Natural - Con Prefijos Especiales (NT, AV, PI, etc.)

XXXX13-NT-2-727784 DV:49
XXXX8-AV-1-123456 DV:34
XXXX7-PI-3-654321 DV:78

Patrón 4 segmentos: XXXX[provincia]-[prefijo]-[grupo]-[numero] DV:[dv]

XXXX13-NT-727784 DV:49
XXXX8-AV-123456 DV:34

Patrón 3 segmentos: XXXX[provincia]-[prefijo]-[numero] DV:[dv]

3. Persona Natural - Con Provincias Especiales

XXXE-1234-12345 DV:23
XXXPE-5678-91011 DV:45
XXXN-9876-54321 DV:67

Provincias especiales:

• E - Extranjero naturalizado
• PE - Provincia especial
• N - Provincia N

4. Persona Jurídica (Empresa)

XXXX:1825706-1-709732 DV:90
XXXX:1234567-1-123456 DV:45
XXXX:9876543-2-654321 DV:78

Importante: El prefijo XXXX: (con dos puntos) es obligatorio para Persona Jurídica.

Patrón: XXXX:[numero]-[digito]-[correlativo] DV:[dv]

5. Extranjero con Pasaporte

XXXXPORTE:XYZABC123
XXXXPORTE:ABC123XYZ
XXXXPORTE:N1234567890

Patrón: XXXXPORTE:[numero_pasaporte]

Tipo Receptor automático: 04 - Extranjero

6. Formato con TIPO y TIPO_RECEPTOR Explícitos (Opcional)

XXXX9-734-1672 DV:56 TIPO:1 TIPO_RECEPTOR:01
XXXX:1825706-1-709732 DV:90 TIPO:2 TIPO_RECEPTOR:01
XXXX13-NT-2-727784 DV:49 TIPO:1 TIPO_RECEPTOR:03

Estos campos son opcionales y permiten especificar explícitamente:

• TIPO:1 - Persona Natural
• TIPO:2 - Persona Jurídica
• TIPO_RECEPTOR:01 - Contribuyente
• TIPO_RECEPTOR:02 - Consumidor Final
• TIPO_RECEPTOR:03 - Gobierno
• TIPO_RECEPTOR:04 - Extranjero

Si PrimaryTaxIdentifier está vacío, el sistema intentará extraer RUC/DV del campo AlternatePhone.FreeFormNumber (Other Phone).

Formatos Aceptados

// Formato estándar
9-734-1672 56
1825706-1-709732 DV90
8-123-4567 12

// Con DV explícito
9-734-1672 DV:56
1825706-1-709732 DV:90

// Cualquier formato con guiones
123-45-67890 12
E-1234-12345 23
PE-5678-91011 45

Ejemplo 1: Cliente Persona Natural

DisplayName: "JEAN CARLOS NARVAEZ"
GivenName: "Jean Carlos"
FamilyName: "Narvaez"
PrimaryTaxIdentifier: "XXXX9-734-1672 DV:56"

Resultado:
- RUC: 9-734-1672
- DV: 56
- TIPO: 1 (Persona Natural)
- TIPO_RECEPTOR: 01 (Contribuyente)

Ejemplo 2: Cliente Persona Jurídica (Empresa)

DisplayName: "EMPRESA XYZ S.A."
CompanyName: "EMPRESA XYZ S.A."
PrimaryTaxIdentifier: "XXXX:1825706-1-709732 DV:90"

Resultado:
- RUC: 1825706-1-709732
- DV: 90
- TIPO: 2 (Persona Jurídica)
- TIPO_RECEPTOR: 01 (Contribuyente)

Ejemplo 3: Cliente con Prefijo Especial NT

DisplayName: "GERALDINE JIMENEZ"
GivenName: "GERALDINE"
MiddleName: "DAILETH MANZANILLA"
FamilyName: "JIMENEZ"
PrimaryTaxIdentifier: "XXXX13-NT-2-727784 DV:49"

Resultado:
- RUC: 13-NT-2-727784
- DV: 49
- TIPO: 1 (Persona Natural)
- TIPO_RECEPTOR: 01 (Contribuyente)

Ejemplo 4: Cliente Extranjero con Pasaporte

DisplayName: "JOHN DOE"
GivenName: "John"
FamilyName: "Doe"
PrimaryTaxIdentifier: "XXXXPORTE:N1234567890"

Resultado:
- PASAPORTE: N1234567890
- RUC: null
- DV: null
- TIPO: null
- TIPO_RECEPTOR: 04 (Extranjero)

Ejemplo 5: Cliente sin RUC (Consumidor Final)

DisplayName: "CLIENTE GENERICO"
PrimaryTaxIdentifier: ""
AlternatePhone: null

Resultado:
- RUC: null
- DV: null
- TIPO: null
- TIPO_RECEPTOR: 02 (Consumidor Final)

Ejemplo 6: Usando AlternatePhone como Fallback

DisplayName: "MARIA GONZALEZ"
PrimaryTaxIdentifier: ""  // Vacío
AlternatePhone.FreeFormNumber: "8-456-7890 45"

Resultado:
- RUC: 8-456-7890
- DV: 45
- TIPO: 1 (Persona Natural)
- TIPO_RECEPTOR: 01 (Contribuyente)
- Source: AlternatePhone_Short

Obtiene una lista de facturas de QuickBooks.

Query Parameters

• limit - Límite de resultados (default: 100)
• offset - Offset para paginación
• startDate - Fecha de inicio (ISO 8601)
• endDate - Fecha de fin (ISO 8601)

Headers Requeridos

• Authorization - Token JWT con orgId

Obtiene facturas con autenticación básica (para uso interno).

Query Parameters

• id - ID de factura específica
• docNumber - Número de documento

Obtiene una factura específica por su ID.

Parámetros

• invoice_sid - ID de la factura

Obtiene detalles completos de una factura con minor version específica.

Query Parameters

• minorversion - Versión de la API de QuickBooks (default: 75)

Emite una factura al PAC (Proveedor Autorizado de Certificación).

Body

{
  "invoiceId": "123",
  "organization": "org_id"
}

Emite una nota de crédito al PAC.

Procesa eventos de webhooks de QuickBooks (create, update, delete).

Body

{
  "eventNotifications": [{
    "realmId": "realm_id",
    "dataChangeEvent": {
      "entities": [{
        "name": "Invoice",
        "id": "123",
        "operation": "Create"
      }]
    }
  }]
}

Health check para verificar el estado del procesador de eventos.

Obtiene la configuración de procesamiento de webhooks para una organización.

Actualiza la configuración de procesamiento de webhooks.

Body

{
  "realmId": "realm_id",
  "organizationId": "org_id",
  "docucenterEnabled": true,
  "reason": "Motivo del cambio"
}

Operaciones de mantenimiento para configuraciones de webhooks.

Query Parameters

• action - Tipo de operación: report | cleanup | consolidate
• days - Días de antigüedad para cleanup (default: 90)

Ejecuta mantenimiento completo (reporte, consolidación y limpieza).

Body

{
  "days": 90,
  "dryRun": true
}

Diagnóstico de mappings entre QuickBooks y Docucenter.

Limpia mappings obsoletos.

Body

{
  "dryRun": true
}

Obtiene la URL de autorización de Zoho OAuth2.

Parámetros

• sid - ID de la conexión

Genera access token y refresh token desde código de autorización.

Revoca el refresh token de Zoho.

Obtiene lista de facturas de Zoho Books.

Query Parameters

• page - Número de página
• per_page - Facturaspor página
• status - Estado: sent | draft | paid | void

Obtiene una factura específica por su número.

Emite facturas de Zoho al PAC.

Body

{
  "invoices": ["invoice_id_1", "invoice_id_2"]
}

Emite una factura específica al PAC (síncrono).

Parámetros

• invoice_id - ID de la factura en Zoho

Respuesta

{
  "success": true,
  "message": "FE01234567890...",
  "automaticallyRedirect": "No"
}

Emite una factura usando sistema de colas (asíncrono recomendado).

Parámetros

• invoice_id - ID de la factura en Zoho

Respuesta

{
  "success": true,
  "message": "Trabajo de emisión de factura en progreso.",
  "jobId": "12345",
  "invoiceId": "invoice_123",
  "automaticallyRedirect": "No"
}

Obtiene facturas electrónicas emitidas (shipments).

Query Parameters

• page - Número de página
• per_page - Resultados por página

Obtiene lista de notas de crédito de Zoho.

Obtiene una nota de crédito específica.

Emite notas de crédito al PAC.

Campos Obligatorios

Campos Opcionales

• cf_informaci_n_de_inter_s - Cuadro de texto (Información de interés del emisor)
• cf_estado_factura - Cuadro de texto (Estado de la factura)
• cf_n_mero_secuencial - Número (Número secuencial interno)
• cf_condiciones_de_entrega - Texto (Condiciones de entrega)

Campos para Exportación

• cf_moneda_de_la_operaci_n_de_e - Moneda de la operación
• cf_descripci_n_de_moneda_de_la - Descripción de la moneda
• cf_tipo_de_cambio_a_la_fecha_d - Tipo de cambio
• cf_monto_en_la_moneda_extranje - Monto en moneda extranjera (Decimal)
• cf_puerto_de_embarque_de_la_me - Puerto de embarque

Campos de Retención

• cf_c_digo_de_retenci_n_a_aplic - Código de retención (Menú desplegable):
  • 01-Pago por servicio profesional al estado 100%
  • 02-Pago por venta bienes/servicios al estado 50%
  • 03-Pago a no domiciliado 100%
  • 04-Pago por compra bienes/servicios 50%
  • 07-Pago a comercio TC/TD 50%
  • 08-Otros (disminución)

Tasas de ITBMS (Panamá)

Script para timbrar Factura (Deluge)

Ubicación: Preferencias → Facturas → Botones Personalizados

custom_field = invoice.get("custom_field_hash");
if(custom_field != null && custom_field.get("cf_cufe") != null && custom_field.get("cf_cufe") != "CUFE")
{
    return {"code":2830,"message":"Ya existe Factura autorizada: " + custom_field.get("cf_cufe")};
}
else
{
    invoiceId = invoice.get("invoice_id");
    Base64Encoded = zoho.encryption.base64Encode("email:password");
    AuthorizationBasic = " Basic " + Base64Encoded;
    headers = Map();
    headers.put("Accept","application/json");
    headers.put("Content-Type","application/json");
    headers.put("Authorization",AuthorizationBasic);
    requestMap = Map();
    requestMap.put("organization_id","your_org_id");
    setInvoice = postUrl("https://us-central1-zoho-books-edocs-integracion.cloudfunctions.net/aciv2/invoices/" + invoiceId,requestMap,headers);
    if(setInvoice.get("success") == false)
    {
        return {"code":2830,"message":setInvoice.get("message")};
    }
    else
    {
        return setInvoice;
    }
}

Script para timbrar Nota de Crédito (Deluge)

Ubicación: Preferencias → Notas de Crédito → Botones Personalizados

custom_field = creditnote.get("custom_field_hash");
if(custom_field != null && custom_field.get("cf_cufe") != null && custom_field.get("cf_cufe") != "CUFE")
{
    return {"code":2830,"message":"Ya existe Nota de crédito autorizada: " + custom_field.get("cf_cufe")};
}
else
{
    creditnoteId = creditnote.get("creditnote_id");
    Base64Encoded = zoho.encryption.base64Encode("email:password");
    AuthorizationBasic = " Basic " + Base64Encoded;
    headers = Map();
    headers.put("Accept","application/json");
    headers.put("Content-Type","application/json");
    headers.put("Authorization",AuthorizationBasic);
    requestMap = Map();
    requestMap.put("organization_id","your_org_id");
    setCreditNote = postUrl("https://us-central1-zoho-books-edocs-integracion.cloudfunctions.net/aciv2/credit_notes/" + creditnoteId,requestMap,headers);
    if(setCreditNote.get("success") == false)
    {
        return {"code":2830,"message":setCreditNote.get("message")};
    }
    else
    {
        return setCreditNote;
    }
}

Obtiene la URL de autorización de Xero OAuth2.

Establece los tokens de acceso de Xero.

Revoca el refresh token.

Obtiene facturas de Xero.

Obtiene una nota de crédito específica.

Obtiene una factura específica por su ID.

Emite facturas de Xero al PAC.

Emite una factura específica por su ID.

Parámetros

• invoice_id - ID de la factura en Xero

Respuesta

{
  "success": true,
  "message": "FE01234567890..."
}

Obtiene facturas con autenticación básica (para uso interno).

Obtiene nota de crédito con autenticación básica.

Exporta JSON de factura para pruebas y debugging.

Query Parameters

• invoice_sid - ID de la factura

Respuesta

{
  "path": "https://storage.googleapis.com/.../12345.txt"
}

Exporta JSON de nota de crédito.

Query Parameters

• invoice_sid - ID de la nota de crédito

Exporta JSON de factura emitida (shipment).

Query Parameters

• invoice_sid - ID de la factura emitida

Emite notas de crédito al PAC.

Obtiene la URL de autorización de Shopify.

Body

{
  "shop": "tienda.myshopify.com",
  "scopes": "read_orders,write_orders"
}

Establece el access token de Shopify.

Actualiza la configuración del cliente Shopify.

Revoca el token de acceso.

Obtiene órdenes de Shopify para facturación.

Query Parameters

• status - Estado de la orden
• limit - Límite de resultados
• since_id - ID mínimo para paginación

Lista de órdenes sin procesamiento adicional.

Obtiene una orden específica.

Obtiene reembolsos de una orden (para notas de crédito).

Procesa emisión de factura desde webhook de Shopify (automático).

Parámetros

• sid - ID de la organización

Respuesta

{
  "success": true,
  "error": false,
  "message": "Orden emitida correctamente",
  "data": {...},
  "timestamp": "2026-02-12T10:30:00.000Z"
}

Emite factura manualmente (invocación directa).

Parámetros

• sid - ID de la organización

Body

{
  "order_id": "123456789",
  "force": false
}

Emite nota de crédito manualmente desde un reembolso.

Lista los webhooks registrados en Shopify.

Registra un webhook en Shopify para notificaciones automáticas.

Body

{
  "topic": "orders/create",
  "address": "https://your-api.com/shopify/orders/to_emit/:sid",
  "format": "json"
}

Elimina un webhook registrado.

Body

{
  "webhook_id": "123456789"
}

Obtiene facturas electrónicas emitidas (shipments).

Query Parameters

• page - Número de página
• per_page - Resultados por página

Exporta JSON de factura emitida para debugging.

Query Parameters

• invoice_sid - ID de la factura emitida

Configura las credenciales de API de WooCommerce.

Parámetros

• sid - ID de la conexión

Body

{
  "url": "https://tienda.com",
  "consumerKey": "ck_xxxxxxxxxxxxxxxxxxxxx",
  "consumerSecret": "cs_xxxxxxxxxxxxxxxxxxxxx"
}

Obtiene lista de órdenes de WooCommerce para facturación.

Query Parameters

• status - Estado de órdenes: completed | processing | pending
• page - Número de página
• per_page - Órdenes por página
• after - Fecha de inicio (ISO 8601)
• before - Fecha de fin (ISO 8601)

Respuesta

{
  "code": 0,
  "message": "success",
  "data": [...],
  "page_context": {
    "page": 1,
    "per_page": 10,
    "has_more_page": false
  }
}

Emite una factura específica al PAC.

Parámetros

• invoice_id - ID de la orden en WooCommerce

Respuesta

{
  "success": true,
  "message": "FE01234567890...",
  "automaticallyRedirect": "No"
}

Procesa emisión de factura desde webhook de WooCommerce.

Parámetros

• sid - ID de la aplicación WooCommerce

Registra un webhook en WooCommerce para notificaciones automáticas.

Body

{
  "topic": "order.created",
  "delivery_url": "https://your-api.com/woo/invoices/to_emit/:sid"
}

Elimina un webhook registrado.

Body

{
  "webhook_id": "123"
}

Obtiene información de envíos asociados a órdenes.

Exporta PDF de factura emitida por su CUFE.

Parámetros

• cufe - Código Único de Factura Electrónica

Exporta XML de la factura electrónica.

Genera carta de representación gráfica en PDF.

Genera cinta de auditoría en PDF.

Busca pacientes en Dentalink.

Query Parameters

• q - Término de búsqueda (nombre, RUC, etc.)

Respuesta

{
  "patients": [{
    "id": "123",
    "name": "Juan Pérez",
    "ruc": "8-123-456",
    "email": "juan@example.com"
  }]
}

Obtiene los pagos de un paciente específico.

Parámetros

• sid - ID del paciente en Dentalink

Obtiene los tratamientos de un paciente.

Parámetros

• sid - ID del paciente

Respuesta

{
  "treatments": [{
    "id": "456",
    "name": "Ortodoncia",
    "status": "active",
    "amount": 1500.00
  }]
}

Obtiene detalles de una factura/tratamiento por su ID relativo.

Parámetros

• relative_id - ID relativo del tratamiento

Query Parameters

• organization_id - ID de la organización
• payment_id - IDs de pagos (separados por coma)
• treatment_id - IDs de tratamientos (separados por coma)
• treatment_detail_id - IDs de detalles (separados por coma)

Obtiene los pagos asociados a una factura/tratamiento.

Query Parameters

• organization_id - ID de la organización

Emite factura electrónica desde datos de Dentalink al PAC.

Body

{
  "patient_id": "123",
  "treatment_ids": ["456", "789"],
  "payment_ids": ["101", "102"]
}

Respuesta

{
  "success": true,
  "cufe": "FE01234567890...",
  "transactionId": "abc123"
}

Exporta JSON de factura para pruebas y debugging.

Query Parameters

• invoice_sid - ID de la factura

Respuesta

{
  "path": "https://storage.googleapis.com/.../invoice.txt"
}

Obtiene la organización asociada al token JWT.

Headers Requeridos

• Authorization - Token JWT con orgId

Respuesta

{
  "id": "org_123",
  "name": "Mi Organización",
  "ruc": "8-123-456",
  "connections": [...]  
}

Obtiene organizaciones asociadas a un SID específico.

Query Parameters

• module - Módulo (quickbooks, zoho, xero, etc.)

Obtiene conexiones asociadas a una organización.

Guarda configuración de organización incluyendo logo.

Body (multipart/form-data)

organization_id: org_123
mostrarTituloExportable: true
logo: [file]

Lista todas las conexiones de aplicaciones por tipo.

Parámetros

• application - quickbooks | zoho | xero | shopify | woocommerce | dentalink

Obtiene catálogo de ubicaciones fiscales de Panamá.

Crea una nueva ubicación en el catálogo.

Obtiene catálogo de países para facturación internacional.

Crea o actualiza un país en el catálogo.

Obtiene un país específico por su ID.

Obtiene un país por su código ISO (ej: PA, US, ES).

Obtiene catálogo de unidades de medida fiscales.

Obtiene catálogo de condiciones de entrega (Incoterms).

Obtiene catálogo de monedas para facturación multi-moneda.

Crea o actualiza una moneda en el catálogo.

Exporta el XML de una factura electrónica por su CUFE.

Parámetros

• cufe - Código Único de Factura Electrónica

Redirige al PDF de la factura electrónica según el PAC.

Parámetros

• cufe - Código Único de Factura Electrónica

Envía comprobante de factura por email al cliente.

Body

{
  "organization_id": "org_123"
}

Obtiene información del usuario autenticado desde el token JWT.

Respuesta

{
  "userId": "user_123",
  "email": "usuario@example.com",
  "admin": false
}

Búsqueda de usuario por email (solo para administradores).

Query Parameters

• email - Email del usuario a buscar