--- title: "Servicios Web (API)" description: "" type: "docs" category: "doc" tags: [] authors: [Anonymous] date: "2026-08-21" last_update: "2026-08-21" time_minutes: 1 draft: false unlisted: false url: "https://www.bhexpress.cl/docs/api" --- ## BHExpress API **BHExpress** provee en [bhexpress.cl](https://bhexpress.cl) una API para interactuar con diferentes características del software BHExpress. En general, permite la consulta y emisión de **Boletas de Honorarios Electrónicas (BHE)**. > ¡Tenemos una API que ni el propio SII tiene disponible! Si requiere soporte con el uso de la API, por favor [abrir un ticket de soporte](https://app.bhexpress.cl/ayuda). **Revisa la documentación dinámica de la API en** [API BHExpress Interactiva](https://app.bhexpress.cl/docs/devtools) --- # Autenticación mediante Token La API soporta sólo el método de autenticación mediante Token. Se debe generar un *Token* a través de la [plataforma web de BHExpress](https://app.bhexpress.cl/usuarios/perfil#token) y hacer las solicitudes enviando el token en la cabecera: ``` Authorization: Token TOKEN ``` ## Error Token inválido El mensaje: ``` {"detail": "Token inválido."} ``` Puede ser a causa de los siguientes motivos: * No se envió el *token*. * Se envió un *access token* incorrecto. --- # Realizando peticiones Los parámetros que se puedan pasar a la API tienen 3 posibles ubicaciones: * **Variable en el** ***PATH*** **del recurso consumido** parámetros que identifican un elemento en el recurso que se está consumiendo. Pueden existir casos donde cierto parámetro sea opcional, en cuyo caso se indicará en cada recurso. * **Variable agregada a la URL** parámetros que permiten modificar el comportamiento de la consulta. Por ejemplo para cambiar el formato de la respuesta o el delimitador usado en los CSV. Estos parámetros siempre serán opcionales. * **Variable en el cuerpo de la solicitud** **`POST`** agregada como un diccionario de datos en JSON. Este tipo de variables se usará principalmente para envío de datos para creación o modificación de datos en los recursos. A menos que se especifique lo contrario, todos los cuerpos de las llamadas a la API deben ser JSON con la cabecera: ``` Content-Type: application/json ``` Y de forma similar, la aplicación, a menos que se indique o soliciten los datos en un formato diferente, debe aceptar los datos en formato JSON con la cabecera: ``` Accept: application/json ``` Adicionalmente, la mayoría de consultas requieren la cabecera `X-Bhexpress-Emisor` (indicado en cada recurso). Esta cabecera debe contener el RUT del emisor sin puntos, con guión y dígito verificador. Ejemplo: ``` X-Bhexpress-Emisor: 11222333-K ``` Esta cabecera es la que permite indicar a la API con qué emisor de los que el usuario tiene acceso se desea trabajar. ## Formato respuesta En general, la respuesta siempre será primero en JSON, a menos que el recurso de la API especifíque lo contrario. --- # Errores | Código | Descripción HTTP | Descripción BHExpress | |--------|--------------------------|----------------------------------------------------------| | 400 | Bad Request | Petición inválida | | 401 | Unauthorized | Token incorrecto | | 403 | Forbidden | No tiene autorización para acceder | | 404 | Not Found | Recurso no encontrado | | 405 | Method Not Allowed | Método no permitido | | 406 | Not Acceptable | Formato de respuesta incorrecto | | 410 | Gone | El recurso solicitado ya no existe | | 423 | Locked | Cuenta bloqueada por incumplimiento | | 429 | Too Many Requests | Límite de peticiones superado | | 500 | Internal Server Error | Error inesperado del servidor o del SII | | 503 | Service Unavailable | Servicio temporalmente no disponible | En caso de error, el formato será: ```json { ​​"status": "Código error", ​​"code": "error", ​​"detail": "Detalle del error." } ``` --- # Clientes de la API | Lenguaje | Autor | Repositorio | |----------|-----------|--------------------------------------------------------| | PHP | BHExpress | https://github.com/BHExpress/bhexpress-api-client-php | Index: - Boletas de Honorarios - Anular una BHE - Listado de BHE emitidas - Datos de una BHE emitida - Calcular monto bruto - Enviar Boleta por email - Emitir una BHE - ESCPOS de una BHE emitida - Estadísticas - Calcular monto líquido - PDF de una BHE emitida - Probar emisión de una BHE - Emisores - Usuarios autorizados - Agregar usuario autorizado - Quitar usuario autorizado - Listado de roles - Agregar un permiso a un rol - Quitar un permiso de un rol - Listado de emisores - Receptores - Listado de receptores - Información receptor - Servicios - Listado de servicios - Información servicio ### Boletas de Honorarios #### POST /api/v1/bhe/anular/{boleta_numero} Anular una BHE Recurso que permite anular una boleta de honorarios electrónica previamente emitida. **Causas de anulación posibles:** - `1`: No se efectuó el pago de los servicios por parte del receptor. - `2`: No se efectuó la prestación de servicios. - `3`: Error en la digitación. **Respuesta JSON:** - `boleta_anulada` puede tener los siguientes valores: - `S`: la boleta estaba vigente y fue anulada. - `A`: la boleta ya estaba anulada previamente. - `E`: ocurrió un error al intentar anular la boleta. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `boleta_numero` (path, integer, required) — Número de la boleta de honorarios electrónica a anular - `format` (query, string) Request body example: ``` { "causa": 1 } ``` Responses: - `200` — Respuesta de anulación #### GET /api/v1/bhe/boletas Listado de BHE emitidas Recurso que permite obtener el listado paginado de boletas de honorarios electrónicas emitidas. Se pueden aplicar múltiples filtros. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `fecha_desde` (query, string) — Filtrar por fecha desde (YYYY-MM-DD) - `fecha_hasta` (query, string) — Filtrar por fecha hasta (YYYY-MM-DD) - `format` (query, string) - `page` (query, integer) — A page number within the paginated result set. - `periodo` (query, string) — Periodo en formato YYYYMM - `receptor_codigo` (query, string) — Código interno del receptor Responses: - `200` — Lista de boletas emitidas #### GET /api/v1/bhe/boletas/{boleta_numero} Datos de una BHE emitida Recurso para obtener los datos de una boleta de honorarios electrónica emitida. **Casos posibles:** - Si la boleta fue emitida en BHExpress → el campo `datos` contiene el JSON de emisión. - Si `datos` es `null` → la boleta no fue emitida en BHExpress, pero fue importada desde el SII mediante la sincronización automática. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `boleta_numero` (path, integer, required) — Número de la boleta de honorarios electrónica - `format` (query, string) Responses: - `200` — Boleta encontrada exitosamente #### GET /api/v1/bhe/bruto/{liquido}/{periodo} Calcular monto bruto Recurso que permite calcular el monto bruto a partir del monto líquido. **Parámetros requeridos:** - `liquido`: Monto líquido (entero) - `periodo`: Periodo en formato `YYYYMM` Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) - `liquido` (path, integer, required) — Monto líquido (entero) - `periodo` (path, string, required) — Periodo en formato `YYYYMM` Responses: - `200` — Montos calculados #### POST /api/v1/bhe/email/{boleta_numero} Enviar Boleta por email Recurso que permite enviar la boleta por correo electrónico. Este recurso usa al **SII** para el envío, por lo que el receptor recibirá un correo del **Servicio de Impuestos Internos** con el PDF adjunto. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `boleta_numero` (path, integer, required) — Número de la boleta de honorarios electrónica - `format` (query, string) Request body example: ``` { "destinatario": { "email": "juan@example.com" } } ``` Responses: - `200` — Correo enviado exitosamente #### POST /api/v1/bhe/emitir Emitir una BHE Emite una **Boleta de Honorarios Electrónica** (BHE) válida y oficial ante el SII. --- ### Retención El campo **`TipoRetencion`** puede tener los siguientes valores: - `0`: sin retención. Para sociedades de profesionales que tributan en 1era categoría. - `1`: la retención la hace el receptor de la boleta. - `2`: la retención la hace el contribuyente emisor de la boleta. --- ### Receptores La API permite emitir una boleta **sin datos del receptor**. Para esto se debe: - Omitir el campo `Receptor` en el JSON - O bien enviar `'RUTRecep': '0-0'` > ⚠️ Si se indica un RUT real (`RUTRecep`) y este existe en el SII, **se usarán los datos oficiales del SII**, ignorando cualquier otro dato enviado. --- ### Cabeceras de respuesta La respuesta incluye: - `X-Bhexpress-Boletas`: total de boletas creadas este mes (incluye esta). - `X-Bhexpress-Cuota`: límite mensual de boletas del emisor. **Importante:** La cuota cuenta todas las boletas creadas en el mes, sin importar su fecha de emisión. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) Request body example: ``` { "Encabezado": { "IdDoc": { "FchEmis": "2022-11-12", "TipoRetencion": 2 }, "Emisor": { "RUTEmisor": "" }, "Receptor": { "RUTRecep": "0-0", "RznSocRecep": "Receptor generico", "DirRecep": "Santa Cruz", "CmnaRecep": "Santa Cruz" } }, "Detalle": [ { "NmbItem": "Item con monto final solamente (lo básico en SII)", "MontoItem": 100 }, { "CdgItem": "CASO2", "NmbItem": "Se agrega código al item", "MontoItem": 300 }, { "NmbItem": "Se agrega cantidad al item (se indica precio unitario)", "QtyItem": 1, "PrcItem": 120 }, { "NmbItem": "Se agrega cantidad al item (se indica precio unitario)", "QtyItem": 0.5, "PrcItem": 120 }, { "CdgItem": "CASO2", "NmbItem": "Se agrega código y cantidad al item (se indica precio unitario)", "QtyItem": 2, "PrcItem": 250 }, { "CdgItem": "COMPLETO", "NmbItem": "Caso más completo, con código, cantidad, precio unitario y descuento en porcentaje", "QtyItem": 10, "PrcItem": 75, "DescuentoPct": 10 }, { "CdgItem": "COMPLETO", "NmbItem": "Caso más completo, con codigo, cantidad, precio unitario y descuento en monto fijo", "QtyItem": 10, "PrcItem": 75, "DescuentoMonto": 50 }, { "NmbItem": "En este caso el MontoItem es descartado por que va cantidad y precio unitario", "QtyItem": 2, "PrcItem": 10, "MontoItem": 100 } ] } ``` Responses: - `200` — Boleta creada exitosamente #### GET /api/v1/bhe/escpos/{boleta_numero} ESCPOS de una BHE emitida Recurso para obtener el código **ESCPOS** de una boleta de honorarios electrónica emitida. El archivo puede descargarse en formato `.escpos` o dentro de un `.zip`, según el parámetro `compress`. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `boleta_numero` (path, integer, required) — Número de la boleta a obtener en PDF - `compress` (query, integer) — Si es `1`, devuelve el PDF comprimido en un `.zip` - `format` (query, string) Responses: - `200` — Archivo ESCPOS entregado directamente #### GET /api/v1/bhe/estadisticas Estadísticas Recurso para obtener estadísticas de boletas de honorarios electrónicas emitidas. **Parámetro requerido:** `periodo` (formato: YYYYMM) - Ej: `202104` **La respuesta contiene 3 grupos de datos:** 1. **totales**: mínimos, máximos, sumas y promedios calculados para: - todas las boletas - las vigentes - las anuladas 2. **dias**: misma información que en `totales`, pero agrupada por día y ordenada de forma creciente por fecha. 3. **receptores**: mismos valores que `totales`, agrupados por receptor y ordenados de forma decreciente por el total líquido vigente. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `fecha_desde` (query, string) — Fecha desde para filtrar las boletas (YYYY-MM-DD) - `fecha_hasta` (query, string) — Fecha hasta para filtrar las boletas (YYYY-MM-DD) - `format` (query, string) - `periodo` (query, string, required) — Periodo en formato YYYYMM. Ej: `202104` - `receptor_codigo` (query, string) — Código interno del receptor Responses: - `200` — Estadísticas completas #### GET /api/v1/bhe/liquido/{bruto}/{periodo} Calcular monto líquido Recurso que permite calcular el monto líquido a partir del monto bruto. **Parámetros requeridos:** - `bruto`: Monto bruto - `periodo`: Periodo en formato `YYYYMM` Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `bruto` (path, integer, required) — Monto bruto - `format` (query, string) - `periodo` (path, string, required) — Periodo en formato `YYYYMM` Responses: - `200` — Montos calculados #### GET /api/v1/bhe/pdf/{boleta_numero} PDF de una BHE emitida Recurso para obtener el PDF de una boleta de honorarios electrónica emitida. El archivo puede descargarse en formato `.escpos` o dentro de un `.zip`, según el parámetro `compress`. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `boleta_numero` (path, integer, required) — Número de la boleta a obtener en PDF - `compress` (query, integer) — Si es `1`, devuelve el PDF comprimido en un `.zip` - `format` (query, string) Responses: - `200` — Archivo PDF de la boleta #### POST /api/v1/bhe/test Probar emisión de una BHE Este servicio web es similar al servicio web de emisión de una BHE, con la principal diferencia que **sólo prepara y prueba los datos** que se usarán para generar la BHE. - **No** envía los datos al SII. - Entrega como respuesta los datos **normalizados** de la BHE. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) Request body example: ``` { "Encabezado": { "IdDoc": { "FchEmis": "2022-11-12", "TipoRetencion": 2 }, "Emisor": { "RUTEmisor": "" }, "Receptor": { "RUTRecep": "0-0", "RznSocRecep": "Receptor generico", "DirRecep": "Santa Cruz", "CmnaRecep": "Santa Cruz" } }, "Detalle": [ { "NmbItem": "Item con monto final solamente (lo básico en SII)", "MontoItem": 100 }, { "CdgItem": "CASO2", "NmbItem": "Se agrega código al item", "MontoItem": 300 }, { "NmbItem": "Se agrega cantidad al item (se indica precio unitario)", "QtyItem": 1, "PrcItem": 120 }, { "NmbItem": "Se agrega cantidad al item (se indica precio unitario)", "QtyItem": 0.5, "PrcItem": 120 }, { "CdgItem": "CASO2", "NmbItem": "Se agrega código y cantidad al item (se indica precio unitario)", "QtyItem": 2, "PrcItem": 250 }, { "CdgItem": "COMPLETO", "NmbItem": "Caso más completo, con código, cantidad, precio unitario y descuento en porcentaje", "QtyItem": 10, "PrcItem": 75, "DescuentoPct": 10 }, { "CdgItem": "COMPLETO", "NmbItem": "Caso más completo, con codigo, cantidad, precio unitario y descuento en monto fijo", "QtyItem": 10, "PrcItem": 75, "DescuentoMonto": 50 }, { "NmbItem": "En este caso el MontoItem es descartado por que va cantidad y precio unitario", "QtyItem": 2, "PrcItem": 10, "MontoItem": 100 } ] } ``` Responses: - `200` — Boleta creada exitosamente ### Emisores #### GET /api/v1/bhe/emisor_usuarios Usuarios autorizados Recurso que entrega los usuarios autorizados de un emisor. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) Responses: - `200` — Listado de usuarios autorizados #### PUT /api/v1/bhe/emisor_usuarios Agregar usuario autorizado Recurso que permite autorizar un usuario con cierto rol en un emisor. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) Request body example: ``` { "usuario_username": "usuario_demo", "rol_id": 1 } ``` Responses: - `200` — Usuario autorizado exitosamente #### DELETE /api/v1/bhe/emisor_usuarios/{usuario_username}/{rol_id} Quitar usuario autorizado Recurso que permite quitar a un usuario con cierto rol en un emisor. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) - `rol_id` (path, integer, required) — ID del rol asignado al usuario - `usuario_username` (path, string, required) — Username del usuario a quitar Responses: - `200` — Usuario desautorizado exitosamente #### GET /api/v1/bhe/roles Listado de roles Recurso que entrega los roles de un emisor. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) Responses: - `200` — Listado de roles del emisor #### PUT /api/v1/bhe/roles Agregar un permiso a un rol Recurso que permite agregar permisos a un rol. Si el rol no existe, se puede crear indicando `rol` y `rol_descripcion`. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) Request body example: ``` { "rol_id": 1, "permisos": [ "bhe_emitir", "bhe_ver" ] } ``` Responses: - `200` — Rol actualizado o creado con éxito #### DELETE /api/v1/bhe/roles/{rol_id}/{permiso} Quitar un permiso de un rol Recurso que permite quitar un permiso asociado a un rol de un emisor. `rol_id` y `permiso` deben ser enviados en la URL. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) - `permiso` (path, string, required) — Nombre del permiso a quitar - `rol_id` (path, integer, required) — ID del rol Responses: - `200` — Permiso removido del rol #### GET /api/v1/usuarios/emisores Listado de emisores Recurso que permite obtener los emisores a los que el usuario tiene acceso. El token de autenticación define el usuario del cual se extraen los emisores disponibles. Parameters: - `format` (query, string) Responses: - `200` — Listado de emisores accesibles por el usuario autenticado ### Receptores #### GET /api/v1/bhe/receptores Listado de receptores Recurso que permite obtener el listado paginado de receptores. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) - `page` (query, integer) — A page number within the paginated result set. Responses: - `200` — Listado paginado de receptores #### GET /api/v1/bhe/receptores/{receptor_rut} Información receptor Recurso que permite obtener los datos de un receptor. Se deben enviar el RUT y, opcionalmente, el código del receptor. Si el receptor no tiene nombre, se asume que no existe. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) - `receptor_rut` (path, string, required) — RUT del receptor (sin puntos, con guión y dígito verificador) Responses: - `200` — Datos del receptor ### Servicios #### GET /api/v1/bhe/servicios Listado de servicios Recurso que permite obtener el listado paginado de servicios. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `format` (query, string) - `page` (query, integer) — A page number within the paginated result set. Responses: - `200` — Lista paginada de servicios #### GET /api/v1/bhe/servicios/{servicio_codigo} Información servicio Recurso que permite obtener los datos de un servicio. Opcionalmente permite calcular precios y descuentos en CLP para una fecha específica. Parameters: - `X-Bhexpress-Emisor` (header, string, required) — RUT del emisor en formato 11222333-K - `fecha` (query, string) — Fecha para calcular precios CLP. Formato YYYY-MM-DD - `format` (query, string) - `montos_clp` (query, string) — Opcional. Coma separada: `liquido`, `bruto` - `servicio_codigo` (path, string, required) — Código único del servicio Responses: - `200` — Datos del servicio --- Last updated on 21/08/2026