Webhooks

Permiso de la clave: webhooks:gestionar.

En vez de consultar el estado de cada comprobante, registre una URL https de su backend y BusinessLink le avisa cuando la DGII responde.

Registrar

POST /v1/webhooks

{"url": "https://miapp.com/api/webhooks/businesslink", "eventos": ["ecf.aceptado", "ecf.rechazado"], "descripcion": "Produccion"}

La respuesta incluye el secreto, que solo se muestra esa vez. Guárdelo para verificar la firma.

Eventos

Evento Significado
ecf.aceptado La DGII aceptó el comprobante.
ecf.aceptado_condicional Aceptado con observaciones.
ecf.rechazado La DGII lo rechazó.
webhook.prueba Evento de prueba (POST /v1/webhooks/{id}/probar).

Use "*" para todos. El cuerpo trae datos.encf, datos.estado y datos.mensajes. Una clave bl_test_ recibe los eventos del sandbox.

Verificar la firma

Cabecera BL-Signature: t=<unix>,v1=<hex> donde v1 = HMAC-SHA256(secreto, t + "." + cuerpo_crudo). Rechace firmas de más de 5 minutos. Responda 2xx en menos de 10 segundos.

Reintentos

Si su servidor falla, BusinessLink reintenta con esperas crecientes (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h): unos 2 días en total. El mismo evento (id) puede llegar más de una vez: ignore los repetidos.

Administrar

  • GET /v1/webhooks: lista (sin el secreto).
  • DELETE /v1/webhooks/{id}: borra el webhook y su historial.
  • GET /v1/webhooks/{id}/entregas: historial de entregas de 30 días.

¿Dudas? Escríbenos o escribe a soporte@businesslink.do.