Autorizaciones de Documentos

El sistema de autorizaciones permite gestionar excepciones comerciales que requieren aprobación de un supervisor antes de proceder. Casos típicos incluyen descuentos que exceden las políticas de la empresa, precios especiales para clientes VIP, y excepciones a límites de crédito.

Requisitos Previos

Antes de usar la API de autorizaciones necesitas:

Una API Key con uno de estos roles: ADMIN, SUPER-ADMIN, SUPERVISOR-VENTAS, OPERADOR, o FULL-API
El flujo de autorización habilitado en la configuración del tenant
Para aprobar/rechazar: rol de supervisor (ADMIN, SUPER-ADMIN, SUPERVISOR-VENTAS, FULL-API)

Conceptos Clave

Solicitud vs Items

El sistema utiliza un modelo consolidado: una solicitud agrupa múltiples items de autorización relacionados con un mismo documento. Esto permite:

Una sola notificación por documento (no una por cada línea)
Resolución eficiente: aprobar/rechazar todo o resolver items individualmente
Trazabilidad completa: historial consolidado por documento

Estados de la Solicitud

Estado	Descripción	Siguiente acción
`PENDIENTE`	Esperando resolución de supervisor	Aprobar, rechazar o resolver items
`APROBADA`	Todos los items aprobados	Documento listo para procesar
`RECHAZADA`	Todos los items rechazados	Operador debe corregir y re-solicitar
`PARCIAL`	Algunos items aprobados, otros rechazados	Operador debe corregir items rechazados
`EXPIRADA`	Tiempo de espera agotado	Operador debe crear nueva solicitud

Tipos de Documento

Tipo	Integración	Descripción
`BHE`	✅ Completa	Boleta de Honorarios Electrónica
`FACTURA`	⚠️ Manual	Factura Electrónica
`BOLETA`	⚠️ Manual	Boleta de Venta
`COTIZACION`	⚠️ Manual	Cotización
`NOTA_CREDITO`	⚠️ Manual	Nota de Crédito

Tipos de Autorización

Tipo	Descripción
`DESCUENTO_LINEA`	Descuento por línea de producto/servicio
`PRECIO_ESPECIAL_LINEA`	Precio especial por línea
`LIMITE_CREDITO`	Excede límite de crédito del cliente
`EXCEPCION_COMERCIAL`	Excepción a política comercial
`PLAZO_PAGO_EXTENDIDO`	Plazo de pago mayor al permitido
`MONTO_MAXIMO_DOCUMENTO`	Documento excede monto máximo
`OTRO`	Otro tipo de autorización

Alcance

Alcance	Descripción
`LINEA`	Autorización específica para una línea del documento
`DOCUMENTO`	Autorización que aplica a todo el documento

Flujo de Autorización

Operador                     Redcumbre                    Supervisor
   │                             │                            │
   │── POST /autorizaciones-v2 ──▶│                            │
   │   (crea solicitud)          │                            │
   │                             │                            │
   │◀── Response ────────────────│                            │
   │   (id, estado: PENDIENTE)   │                            │
   │                             │── Notificación ───────────▶│
   │                             │   (push, email, in-app)    │
   │                             │                            │
   │                             │◀── POST /:id/aprobar ──────│
   │                             │    o POST /:id/rechazar    │
   │                             │    o POST /:id/resolver    │
   │                             │                            │
   │◀── Notificación ────────────│                            │
   │   (resultado)               │                            │
   │                             │                            │
   │  [Si BHE: Borrador →        │                            │
   │   AUTORIZADO/RECHAZADO]     │                            │

Tiempos de expiración:

Default: 1 semana (configurable por tenant)
Solicitudes expiradas se marcan automáticamente como EXPIRADA
El operador debe crear una nueva solicitud si expira

Crear Solicitud

Endpoint: POST /{tenantSlug}/autorizaciones-v2

Crea una nueva solicitud de autorización consolidada con uno o más items.

Request

curl -X POST "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoDocumento": "BHE",
    "borradorId": "cm5borrador123",
    "items": [
      {
        "tipo": "DESCUENTO_LINEA",
        "alcance": "LINEA",
        "lineaId": "linea-001",
        "productoId": "prod-abc123",
        "productoNombre": "Consultoría Tributaria",
        "codigoSku": "CONS-TRIB-01",
        "valorPermitido": 10,
        "valorSolicitado": 25,
        "unidad": "PORCENTAJE",
        "motivo": "Cliente VIP con contrato anual",
        "contexto": {
          "cantidad": 1,
          "precioUnitario": 500000
        }
      }
    ]
  }'

Campos del Request

Campo	Tipo	Requerido	Descripción
`tipoDocumento`	enum	Sí	Tipo de documento (BHE, FACTURA, etc.)
`borradorId`	string	No	ID del borrador asociado (solo BHE)
`items`	array	Sí	Lista de items de autorización (mín 1)

Campos de cada Item

Campo	Tipo	Requerido	Descripción
`tipo`	enum	Sí	Tipo de autorización
`alcance`	enum	Sí	`LINEA` o `DOCUMENTO`
`lineaId`	string	Condicional	ID de la línea (requerido si alcance = LINEA)
`productoId`	string	No	ID del producto asociado
`productoNombre`	string	No	Nombre del producto (snapshot)
`codigoSku`	string	No	Código SKU del producto
`valorPermitido`	number	No	Valor máximo según política
`valorSolicitado`	number	No	Valor que se solicita
`unidad`	enum	No	`PORCENTAJE`, `MONTO`, `DIAS`
`motivo`	string	Sí	Justificación de la solicitud
`contexto`	object	No	Datos adicionales según tipo

Response (201 Created)

{
  "id": "cm5solicitud123",
  "tenantId": "8",
  "tipoDocumento": "BHE",
  "borradorId": "cm5borrador123",
  "solicitanteUserId": "user-001",
  "solicitanteNombre": "Juan Pérez",
  "autorizadorUserId": null,
  "autorizadorNombre": null,
  "estado": "PENDIENTE",
  "createdAt": "2025-12-19T10:00:00Z",
  "expiresAt": "2025-12-26T10:00:00Z",
  "resueltaAt": null,
  "items": [
    {
      "id": "cm5item001",
      "tipo": "DESCUENTO_LINEA",
      "alcance": "LINEA",
      "lineaId": "linea-001",
      "productoId": "prod-abc123",
      "productoNombre": "Consultoría Tributaria",
      "codigoSku": "CONS-TRIB-01",
      "valorPermitido": 10,
      "valorSolicitado": 25,
      "unidad": "PORCENTAJE",
      "motivo": "Cliente VIP con contrato anual",
      "contexto": { "cantidad": 1, "precioUnitario": 500000 },
      "estado": "PENDIENTE",
      "comentarioResolucion": null
    }
  ]
}

Listar Solicitudes

Endpoint: GET /{tenantSlug}/autorizaciones-v2

Lista solicitudes con filtros y paginación.

Query Parameters

Parámetro	Tipo	Descripción
`estado`	enum	Filtrar por estado (default: `PENDIENTE`)
`tipoDocumento`	enum	Filtrar por tipo de documento
`tipoAutorizacion`	enum	Filtrar por tipo de autorización
`solicitanteUserId`	string	Filtrar por solicitante (solo admins)
`page`	number	Página (default: 1)
`limit`	number	Resultados por página (default: 20, max: 100)

Comportamiento por Rol

Rol	Comportamiento
`SUPER-ADMIN`, `ADMIN`, `SUPERVISOR-VENTAS`, `FULL-API`	Ve todas las solicitudes del tenant
`OPERADOR`	Solo ve sus propias solicitudes

Request

curl -X GET "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2?estado=PENDIENTE&limit=20" \
  -H "Authorization: Bearer {api_key}"

Response (200 OK)

{
  "data": [
    {
      "id": "cm5solicitud123",
      "tipoDocumento": "BHE",
      "solicitanteNombre": "Juan Pérez",
      "estado": "PENDIENTE",
      "createdAt": "2025-12-19T10:00:00Z",
      "expiresAt": "2025-12-26T10:00:00Z",
      "items": [...]
    }
  ],
  "total": 15,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

Obtener Detalle

Endpoint: GET /{tenantSlug}/autorizaciones-v2/{id}

Obtiene el detalle completo de una solicitud incluyendo items y borrador asociado.

Request

curl -X GET "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2/{id}" \
  -H "Authorization: Bearer {api_key}"

Response (200 OK)

{
  "id": "cm5solicitud123",
  "tenantId": "8",
  "tipoDocumento": "BHE",
  "borradorId": "cm5borrador123",
  "solicitanteUserId": "user-001",
  "solicitanteNombre": "Juan Pérez",
  "autorizadorUserId": null,
  "autorizadorNombre": null,
  "estado": "PENDIENTE",
  "createdAt": "2025-12-19T10:00:00Z",
  "expiresAt": "2025-12-26T10:00:00Z",
  "resueltaAt": null,
  "items": [...],
  "bheBorrador": {
    "id": "cm5borrador123",
    "estado": "EN_AUTORIZACION",
    "montoBruto": 450000,
    "ppm": 61875,
    "montoLiquido": 388125
  }
}

Aprobar Solicitud

Endpoint: POST /{tenantSlug}/autorizaciones-v2/{id}/aprobar

Aprueba todos los items de una solicitud pendiente.

Efectos

Todos los items pasan a estado APROBADO
La solicitud pasa a estado APROBADA
Si hay borrador BHE asociado, se marca como AUTORIZADO (listo para emitir)
Se notifica al solicitante

Request

curl -X POST "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2/{id}/aprobar" \
  -H "Authorization: Bearer {api_key}"

Response (200 OK)

{
  "id": "cm5solicitud123",
  "estado": "APROBADA",
  "autorizadorUserId": "supervisor-001",
  "autorizadorNombre": "María García",
  "resueltaAt": "2025-12-19T12:30:00Z",
  "items": [
    {
      "id": "cm5item001",
      "estado": "APROBADO"
    }
  ]
}

Rechazar Solicitud

Endpoint: POST /{tenantSlug}/autorizaciones-v2/{id}/rechazar

Rechaza todos los items de una solicitud pendiente.

Request

curl -X POST "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2/{id}/rechazar" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "comentario": "Descuento demasiado alto para este cliente"
  }'

Campos del Request

Campo	Tipo	Requerido	Descripción
`comentario`	string	No	Motivo del rechazo

Efectos

Todos los items pasan a estado RECHAZADO
La solicitud pasa a estado RECHAZADA
Si hay borrador BHE asociado, se marca como RECHAZADO
Se notifica al solicitante con el comentario
El solicitante puede editar el borrador y volver a solicitar autorización

Response (200 OK)

{
  "id": "cm5solicitud123",
  "estado": "RECHAZADA",
  "autorizadorUserId": "supervisor-001",
  "autorizadorNombre": "María García",
  "resueltaAt": "2025-12-19T12:30:00Z",
  "items": [
    {
      "id": "cm5item001",
      "estado": "RECHAZADO",
      "comentarioResolucion": "Descuento demasiado alto para este cliente"
    }
  ]
}

Resolver Items Individualmente

Endpoint: POST /{tenantSlug}/autorizaciones-v2/{id}/resolver

Resuelve una solicitud aprobando o rechazando items de forma individual (resolución parcial).

Request

curl -X POST "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2/{id}/resolver" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "resoluciones": [
      { "itemId": "cm5item001", "aprobado": true },
      { "itemId": "cm5item002", "aprobado": false, "comentario": "Descuento excesivo" }
    ]
  }'

Campos de cada Resolución

Campo	Tipo	Requerido	Descripción
`itemId`	string	Sí	ID del item a resolver
`aprobado`	boolean	Sí	`true` para aprobar, `false` para rechazar
`comentario`	string	No	Comentario (típicamente para rechazos)

Estado Final

Resultado	Estado Solicitud	Estado Borrador BHE
Todos aprobados	`APROBADA`	`AUTORIZADO`
Todos rechazados	`RECHAZADA`	`RECHAZADO`
Mixto	`PARCIAL`	`RECHAZADO`

Response (200 OK)

{
  "id": "cm5solicitud123",
  "estado": "PARCIAL",
  "autorizadorUserId": "supervisor-001",
  "autorizadorNombre": "María García",
  "resueltaAt": "2025-12-19T12:30:00Z",
  "items": [
    {
      "id": "cm5item001",
      "estado": "APROBADO",
      "comentarioResolucion": null
    },
    {
      "id": "cm5item002",
      "estado": "RECHAZADO",
      "comentarioResolucion": "Descuento excesivo"
    }
  ]
}

Integración con BHE (Borradores)

Cuando un borrador BHE requiere autorización (ej: descuento excede el máximo), el flujo completo es:

Operador                   Redcumbre                    Supervisor
   │                           │                            │
   │── POST /bhe/borradores ──▶│                            │
   │   (con descuento > max)   │                            │
   │                           │                            │
   │◀── Response ──────────────│                            │
   │   (requiereAutorizacion)  │                            │
   │                           │                            │
   │── POST /borradores/:id/   │                            │
   │   solicitar-autorizacion ▶│                            │
   │                           │                            │
   │   [Borrador →             │                            │
   │    EN_AUTORIZACION]       │                            │
   │                           │── Notifica ───────────────▶│
   │                           │                            │
   │                           │◀── Aprueba ────────────────│
   │                           │                            │
   │◀── Notificación ──────────│                            │
   │   (AUTORIZADO)            │                            │
   │                           │                            │
   │── POST /borradores/:id/   │                            │
   │   emitir ────────────────▶│                            │
   │                           │                            │
   │◀── BHE Emitida ───────────│                            │

Estados del Borrador

Estado Borrador	Descripción
`BORRADOR`	Editable, puede solicitar autorización
`EN_AUTORIZACION`	Esperando aprobación
`AUTORIZADO`	Aprobado, listo para emitir
`RECHAZADO`	Rechazado, puede editarse y re-solicitar
`EMITIDO`	BHE emitida exitosamente

Modo Sandbox (Testing)

El modo sandbox permite probar la API sin persistir datos ni afectar el sistema real.

Activación

El modo sandbox se activa automáticamente cuando tu API Key tiene isSandbox: true.

IDs de Prueba

Usa estos IDs para probar diferentes escenarios:

ID	GET /:id	POST aprobar	POST rechazar	POST resolver
`sandbox-sol-pending`	Estado PENDIENTE	✅ Éxito	✅ Éxito	✅ Éxito
`sandbox-sol-approved`	Estado APROBADA	❌ Error 400	❌ Error 400	❌ Error 400
`sandbox-sol-rejected`	Estado RECHAZADA	❌ Error 400	❌ Error 400	❌ Error 400
`sandbox-sol-partial`	Estado PARCIAL	❌ Error 400	❌ Error 400	❌ Error 400
`sandbox-sol-expired`	Estado EXPIRADA	❌ Error 400	❌ Error 400	❌ Error 400
`sandbox-sol-notfound`	❌ Error 404	❌ Error 404	❌ Error 404	❌ Error 404

ItemIds de Prueba

Para usar con POST /:id/resolver y el ID sandbox-sol-pending:

ItemId	Descripción
`sandbox-item-001`	Item tipo DESCUENTO_LINEA
`sandbox-item-002`	Item tipo PRECIO_ESPECIAL_LINEA

Ejemplo en Sandbox

# Crear solicitud (no persiste)
curl -X POST "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2" \
  -H "Authorization: Bearer {sandbox_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoDocumento": "BHE",
    "items": [{
      "tipo": "DESCUENTO_LINEA",
      "alcance": "LINEA",
      "lineaId": "linea-001",
      "valorPermitido": 10,
      "valorSolicitado": 25,
      "unidad": "PORCENTAJE",
      "motivo": "Test sandbox"
    }]
  }'

# Consultar solicitud pendiente
curl -X GET "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2/sandbox-sol-pending" \
  -H "Authorization: Bearer {sandbox_api_key}"

# Aprobar solicitud
curl -X POST "https://api.redcumbre.cl/{tenantSlug}/autorizaciones-v2/sandbox-sol-pending/aprobar" \
  -H "Authorization: Bearer {sandbox_api_key}"

Códigos de Error

Errores de Validación (400)

Error	Descripción
`Debe incluir al menos un item de autorización`	Array `items` vacío o no enviado
`La solicitud ya fue aprobada/rechazada`	Intento de resolver solicitud no pendiente
`La solicitud ha expirado`	Solicitud pasó su fecha de expiración
`El flujo de autorización no está habilitado`	Tenant no tiene habilitada la funcionalidad
`Item X no pertenece a esta solicitud`	ItemId inválido en resolución

Errores de Acceso (403)

Error	Descripción
`No tienes acceso a esta solicitud`	Operador intentando ver solicitud de otro
`Forbidden`	Rol sin permisos para la operación

Errores de Recurso (404)

Error	Descripción
`Solicitud X no encontrada`	ID de solicitud no existe o no pertenece al tenant

Expiración Automática

Las solicitudes pendientes expiran automáticamente según la configuración del tenant:

Configuración	Default	Descripción
`timeoutAutorizacionMinutos`	10080 (1 semana)	Tiempo máximo de espera

Proceso de Expiración

Un cron job verifica solicitudes pendientes con expiresAt < now
Los items se marcan como RECHAZADO con comentario “Solicitud expirada por timeout”
La solicitud pasa a estado EXPIRADA
Si hay borrador BHE asociado, se marca como RECHAZADO
Se notifica al solicitante

API Reference

Para detalles técnicos completos y especificaciones de todos los endpoints:

👉 Ver endpoints de Autorizaciones en Swagger