Integraciones y API

Integraciones internas

El permiso hola-doc.integrations permite administrar:

• API keys de integración.
• Socio comercial asignado a cada key.
• Porcentaje o reglas de comisión.
• Mapeos de SKU a plan.
• Tiendas asociadas al partner.
• SKUs de acceso a cabina.
• Proveedores de exportación y costos por plan.

API key

Las integraciones externas usan el header:

X-Api-Key: {api-key}

Una key inválida o inactiva responde 401 Unauthorized.

Ingesta de transacciones

Endpoint externo:

POST /api/hola-doc/transactions/ingest

Uso principal: recibir ventas y devoluciones desde POS.

Campos clave de transacción:

Campo	Uso
retailStoreId	Tienda o punto de venta.
businessDayDate	Fecha de negocio.
workstationId	Caja o estación.
transNumber	Número único de factura.
operatorId	Operador o cajero.
customerId	Cédula o documento del cliente.
customerDateOfBirth	Fecha de nacimiento.
items[].itemId	SKU que debe estar mapeado.

El endpoint puede responder 200 aunque existan transacciones rechazadas. Siempre revise created, duplicates, errors, rejected y processingErrors.

Consulta de registro

Endpoint externo:

POST /api/hola-doc/registry/lookup

Permite consultar el estado de una persona por cédula sin modificar datos.

Rechazos persistidos

Rechazos por reglas de negocio se guardan para consulta operativa. Ejemplos:

• Menor de edad.
• Edad sobre el límite de inscripción.
• Conflicto de correo.
• Suscripción suspendida.
• Mezcla de productos de cabina y suscripción.
• Nota de crédito sin suscripción activa (ver Notas de crédito).
• Acceso de cabina ya consumido.

Los rechazos de formato no necesariamente se persisten.

Límites

• Batch máximo de ingesta: 10,000 transacciones.
• Transacciones duplicadas por transNumber se reportan como duplicadas y no se procesan de nuevo.