28 eventos por suscripción y cero suposiciones

Configuras la URL desde la app, eliges los eventos y opcionalmente añades cabeceras personalizadas para autenticar tu receptor. La forma del payload es estándar y la lista de eventos vive sembrada en la migración inicial.

Resumen

Cuando un evento ocurre dentro del espacio de trabajo, factura.com.do envía un POST con cuerpo JSON a la URL que registraste. La entrega es fire-and-forget: tu receptor responde 2xx y la entrega queda persistida en el log de ejecución de webhooks. Si responde distinto, no hay reintento automático.

Modelo de suscripción

La suscripción se administra desde la sección Webhooks del espacio de trabajo, no por API pública. Configuras URL destino, método HTTP (GET/POST/PUT), cabeceras personalizadas (nombre-valor) y selección de eventos. La app expone un endpoint de prueba interno para verificar conectividad antes de activar.

Forma del payload

Todos los eventos comparten la misma forma de cuerpo: Event, el nombre del evento; Timestamp, en ISO 8601 y en la hora local del servidor (con su desfase, no normalizada a UTC), y data, específico del evento. Las claves llegan en PascalCase.

{
  "Event": "dgii.aprobado",
  "Timestamp": "2026-05-08T10:33:21.4830000-04:00",
  "data": {
    "DocumentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "StatusId": 5
  }
}

Catálogo de 28 eventos

Los 28 eventos cubren cotizaciones, facturas, notas, gastos, estados DGII y catálogo. Todos están sembrados desde la migración inicial; suscríbete solo a los que tu integración necesita.

Forma del data por evento

El envelope (<code>Event</code>, <code>Timestamp</code>, <code>data</code>) es invariante. Lo que cambia es el contenido de <code>data</code>. Estos son los campos que emite el dispatcher; ignora los que no uses, porque pueden aparecer campos nuevos.

Cada elemento de Lines trae LineId, ProductId, ProductVariantId, WarehouseId, Code, Order, Description, IsService, IsExempt, Quantity, UnitId, UnitPrice, Discount, DiscountPercentage, Recharge, NetAmount, TotalDiscount, TotalTax, TotalWithholdings, Subtotal, Taxes y Withholdings. Accounting es el desglose contable del encabezado: DocumentTypeId, BranchId, SequenceTypeId, IssuedAt, LimitDate, PaymentTermId, CurrencyCode, CurrencyRate, TaxableAmount, ExemptAmount, TotalDiscount, DiscountPercentage, TotalTaxes, TotalWithholdings, Total, AmountDue, Freight, Tip, TratamientoItbis, TipoBienServicioComprado y AwaitsFiscalValidation.

Receptor de ejemplo

Un receptor mínimo valida la cabecera secreta, lee el evento y enruta. Devuelve 2xx en cuanto persistas o encoles el trabajo; si tu lógica falla, persiste en background y reconcilia más tarde.

// webhook-handler.ts (Express)
import type { Request, Response } from "express";

const SECRETO = process.env.FACTURA_WEBHOOK_SECRET!;

export function manejarWebhook(req: Request, res: Response) {
  if (req.header("X-Webhook-Secret") !== SECRETO) {
    return res.status(401).end();
  }

  const { Event, Timestamp, data } = req.body;

  switch (Event) {
    case "dgii.aprobado":
      return procesar(res, data, "aprobado");
    case "dgii.rechazado":
      return procesar(res, data, "rechazado");
    case "dgii.en_proceso":
      return procesar(res, data, "en_proceso");
    case "dgii.aceptado_condicional":
      return procesar(res, data, "aceptado_condicional");
    default:
      return res.status(204).end();
  }
}

function procesar(res: Response, data: unknown, estado: string) {
  return res.status(200).json({ estado });
}

# webhook_handler.py (FastAPI)
import os
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()
SECRETO = os.environ["FACTURA_WEBHOOK_SECRET"]

@app.post("/webhooks/factura")
async def recibir(req: Request, x_webhook_secret: str = Header(default="")):
    if x_webhook_secret != SECRETO:
        raise HTTPException(status_code=401)

    body = await req.json()
    event = body["Event"]

    if event == "dgii.aprobado":
        # persiste en tu ERP
        return {"estado": "aprobado"}
    if event == "dgii.rechazado":
        return {"estado": "rechazado"}
    return {}

Reconciliación y eventos de plugins

Como la entrega no se reintenta, un evento perdido no vuelve a llegar. Estas rutas permiten recuperar lo que no llegó barriendo un rango de fechas: accounting-sync devuelve la misma proyección contable del webhook y treasury-sync, la cartera (qué se debe y a quién). Aceptan la X-Api-Key. plugins/events es distinto: solo lo usan los plugins instalados, con su propio token, para publicar eventos hacia otros plugins.

Siguientes pasos