--- title: "Webhook" description: "Integración mediante Webhook" type: "docs" category: "doc" tags: [] authors: [Anonymous] date: "2026-09-16" last_update: "2026-09-16" time_minutes: 1 draft: false unlisted: false url: "https://www.libredte.cl/docs/integracion/webhook" --- # Integración mediante Webhook --- ## Notificaciones de Pago Envío de notificación al recibir un pago # Recibir notificaciones de pagos de tus clientes Puedes configurar un **servicio web** propio para recibir notificaciones automáticas cuando tus clientes realicen pagos en la plataforma de LibreDTE. ## ¿Cómo funciona? Cuando se registra un pago, LibreDTE realiza una solicitud **HTTP POST** a la URL que definas. El cuerpo de la solicitud contiene un **JSON** con los datos del pago. Ejemplo de URL de tu servicio: ``` https://example.com/api/pagos/notificar ``` Ejemplo de payload recibido: ```json { "emisor": 76192083, "codigo": "aWRfcGFnbwo=", "receptor": 11222333, "fecha": "2020-04-01", "pagado": "2020-04-21", "medio": "webpay", "datos": null } ``` ## Campos incluidos | Campo | Descripción | |-----------|---------------------------------------------------------| | `emisor` | RUT del emisor del cobro (sin dígito verificador) | | `codigo` | Código único del cobro (útil para validación posterior) | | `receptor`| RUT del receptor del cobro (sin DV) | | `fecha` | Fecha de emisión del cobro | | `pagado` | Fecha en que se realizó el pago | | `medio` | Medio de pago utilizado (ej. `webpay`) | | `datos` | Información adicional del medio de pago (opcional) | ## Validación del cobro > [!WARNING] No confíes solo en la notificación > > Siempre debes validar el pago consultando directamente a LibreDTE usando el **código del cobro**. > Esto garantiza que la notificación sea auténtica y evita errores o fraudes. ## Ejemplo práctico El siguiente código incluye cómo recibir el JSON, procesarlo y consultar a LibreDTE para verificar el estado del cobro. ```php /** * Ejemplo básico de servicio web para recibir una notificación de pago * desde LibreDTE. */ // Se utiliza el API Client de LibreDTE, instalar dependencia con: // composer require libredte/libredte-api-client use libredte\api_client\ApiClient; use libredte\api_client\ApiException; // Configuración de autenticación. $emisor = 76192083; // RUT sin puntos ni DV. $hash = ''; // Se obtiene en el perfil del usuario. $user = ''; // Lo defines al configurar el webhook en LibreDTE. $pass = ''; // Lo defines al configurar el webhook en LibreDTE. // Verificar si la consulta tiene las credenciales válidas. if (!auth_check($user, $pass)) { throw new ApiException( 'Usuario no autenticado o credenciales incorrectas.' ); } // Recibir datos del servicio web y extraer EnvioDTE o EnvioBOLETA. $payload = json_decode(file_get_contents('php://input'), true); if (!$payload) { throw new ApiException('No se recibieron datos del cobro.'); } // Verificar que el cobro efectivamente esté pagado. $libredte = new ApiClient($hash); $resource = sprintf( '/pagos/cobros/info/%s/%d', $payload['codigo'] ?? throw new ApiException( 'No se recibió el código del cobro que fue pagado.' ), $emisor ); $response = $libredte->get($resource); if (($response['status']['code'] ?? null) !== 200) { throw new ApiException((sprintf( 'Error al realizar la consulta del cobro: %s', $response['body'] )); } $cobro = (object) $response['body']; // Revisar si el cobro está pagado realmente. Esto asegura que está // pagado, ya que se consultó a LibreDTE previamente por el estado. if ($cobro->pagado) { cobro_pagado($cobro); } // Función que verifica las credenciales utilizando HTTP Auth Basic. function auth_check(string $user, string $pass): bool { // Error si no se definen las credenciales en la configuración. if (empty($user) || empty($pass)) { return false; } // Obtener cabecera de HTTP Auth Basic. $headers = apache_request_headers(); if (empty($headers['Authorization'])) { return false; } // Validar credenciales. [$basic, $Authorization] = explode(' ', $headers['Authorization']); [$u, $p] = explode(':', base64_decode($Authorization)); $status = $u === $user && $p === $pass; return $status; } // Función para hacer lo que se requiera con el cobro pagado. function cobro_pagado(object $cobro): mixed { print_r($cobro); } ``` > [!TIP] > > Puedes usar este sistema para automatizar acciones como activar servicios, enviar correos o generar documentos tras el pago. --- ## Obtener ítems desde tu aplicación Productos y servicios desde API externa # Obtener ítems desde tu aplicación Puedes integrar tu sistema con LibreDTE para que la plataforma consulte automáticamente los datos de un ítem desde tu servicio web. ## Requisitos del endpoint Debes exponer un recurso `GET` que permita obtener la información del ítem a partir de su código. Ejemplos de URL válidas: - `https://example.com/items/CODIGO` - `https://example.com/items?codigo=CODIGO` ## Formato de respuesta Tu servicio debe devolver un objeto JSON con los datos del ítem, utilizando la siguiente estructura: ```json { "TpoCodigo": "INT1", "VlrCodigo": "dte-cert", "NmbItem": "Asesoría DTE", "DscItem": "Certificación DTE", "IndExe": 1, "UnmdItem": "", "PrcItem": 125000, "ValorDR": 0, "TpoValor": "%", "CodImpAdic": null } ``` ## Campos esperados | Campo | Descripción | |--------------|-----------------------------------------------------| | `TpoCodigo` | Tipo de código (ej: `INT1` para interno) | | `VlrCodigo` | Valor del código (ej: SKU o identificador) | | `NmbItem` | Nombre del ítem | | `DscItem` | Descripción del ítem | | `IndExe` | Indicador de exención (`1` si está exento) | | `UnmdItem` | Unidad de medida (puede estar vacío) | | `PrcItem` | Precio unitario del ítem | | `ValorDR` | Valor de descuento o recargo (si aplica) | | `TpoValor` | Tipo de valor (`%` o monto fijo) | | `CodImpAdic` | Código de impuesto adicional (si corresponde) | > [!CHECK] DRY: Don't Repeat Yourself > > Este mecanismo permite mantener la información de ítems sincronizada entre tu sistema y LibreDTE sin necesidad de cargas manuales. --- ## Respuesta a DTE recibidos Generar una respuesta automática # Responder automáticamente DTE recibidos LibreDTE permite automatizar la recepción o reclamo de documentos electrónicos (DTE) que llegan por intercambio, mediante un **servicio web propio**. Este sistema permite automatizar gran parte del flujo de intercambio, mejorando tiempos de respuesta y reduciendo errores manuales. ## ¿Cómo funciona? Debes crear un endpoint HTTP que reciba solicitudes `POST`. LibreDTE enviará en el cuerpo un JSON que contiene el archivo `EnvioDTE` codificado en base64. ### Ejemplo de endpoint ```text https://example.com/api/intercambios/procesar ``` ### Ejemplo de payload recibido ```json { "xml": "aWRfcGFnbwo=" } ``` ## Tipos de respuesta esperada Tu servicio debe responder con JSON. Hay múltiples opciones dependiendo del comportamiento deseado: ### 1. Recibir todos los documentos (estado **ERM**) ```json true ``` ### 2. Reclamar todos los documentos (estado **RCD**) ```json false ``` ### 3. No procesar (deja el intercambio sin respuesta automática) Cualquier valor de tipo **string** en la respuesta se interpreta como que no se logró determinar qué hacer, y se omite la acción (el intercambio queda pendiente de procesamiento manual). El string puede usarse, de hecho, para **reportar el motivo** por el cual no se está procesando la respuesta: ```json "null" ``` o, por ejemplo: ```json "Sin stock para validar recepción." ``` > [!WARNING] > > La respuesta debe ser un **string** (con comillas), no el literal JSON `null`. Un `null` sin comillas no equivale a "no procesar": se interpreta como un valor booleano falso, es decir, como **reclamar todo el intercambio**. ### 4. Procesar por documento (recibir y reclamar según DTE) Si el intercambio tiene más de un DTE, se puede indicar qué documentos se deben recibir o reclamar: ```json { "recibir": [ { "TipoDTE": 33, "Folio": 1 } ], "reclamar": [ { "TipoDTE": 33, "Folio": 2 } ] } ``` Los índices `recibir` y `reclamar` son arreglos de arreglos (objetos) que pueden tener los siguientes índices: ```json // esto no es una respuesta válida, es sólo un ejemplo de cómo asignar datos de un DTE { "TipoDTE": 31, "Folio": 1, "FchEmis": "2018-05-21", "RUTEmisor": "76192083-9", "RUTRecep": "88777666-5", "MntTotal": 1000, "EstadoRecepDTE": "ERM", "RecepDTEGlosa": "Otorga recibo de mercaderías o servicios" } ``` > [!INFO] > > Solo `TipoDTE` y `Folio` son obligatorios. Sin embargo, se recomienda incluir `RUTEmisor`, `EstadoRecepDTE` y `RecepDTEGlosa` si hay más de un DTE. Los índices `EstadoRecepDTE` y `RecepDTEGlosa` permiten definir los estados que se asignarán (por defecto es `ERM` para recibidos y `RCD` para reclamados). --- ## Configuración general opcional También puedes incluir un bloque `config` con información adicional, por ejemplo la sucursal que recibe el DTE o el período donde se debe asignar: ```json { "accion": true, "config": { "NmbContacto": "Esteban", "MailContacto": "usuario@empresa.cl", "sucursal": 0, "Recinto": "Casa matriz", "responder_a": "dte@proveedor.cl", "periodo": "202509" } } ``` En el índice `accion` se puede indicar cualquiera de las respuestas antes vistas (`true`, `false`, o el objeto con `recibir`/`reclamar`). En el índice `config`, todos los campos son opcionales; si no se indica alguno, será determinado automáticamente por el sistema. | Campo | Descripción | |----------------|--------------------------------------------------| | `NmbContacto` | Nombre del contacto para consultas | | `MailContacto` | Email del contacto | | `sucursal` | Código de sucursal (0 = casa matriz) | | `Recinto` | Nombre del lugar de recepción | | `responder_a` | Email del proveedor (recomendado: no asignar) | | `periodo` | Período tributario en formato `AAAAMM`; debería ser siempre el actual | --- > [!WARNING] Tus Documentos, Tu Responsabilidad > > Aunque puedas responder automáticamente, **es tu responsabilidad validar el contenido del EnvioDTE** y establecer políticas claras de aceptación o reclamo. > --- Última actualización el 16/09/2026