Se emite al crear una nueva orden de venta.
Lista de eventos
Se emite cuando una orden cambia de datos o estado.
Se emite cuando la orden es cancelada.
Se emite cuando la orden queda finalizada.
Se emite al terminar la post-emision de un CFE.
Se emite cuando se registra un CFE recibido.
Se emite cuando DGI rechaza un CFE en la segunda respuesta del sobre.
Cambio de estado de contrato por reglas de uso.
Se emite cuando DGI observa un CFE en la segunda respuesta del sobre.
Se emite cuando el receptor (sobre entre empresas) rechaza el CFE.
Se emite cuando el receptor informa estado observado (CE) para un CFE en intercambio entre empresas.
Primeros pasos
Registro de endpoint para integradores: POST /api/v1/webhooks.
Configura tu URL de recepcion, define eventos suscritos y usa el payload JSON para procesar cambios de forma automatica.
Alta de endpoint
Endpoint: POST /api/v1/webhooks
Campos requeridos: url, events.
Parametro de query: idEmpresa (si no existe empresa en sesion).
secret se recomienda para habilitar firma HMAC en la entrega.
Ejemplo minimo
curl -X POST "$BASE_URL/api/v1/webhooks?idEmpresa=123" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
"url": "https://integrador.com/webhooks/bluetech",
"events": ["Cfe.Emitido"]
}'Ejemplo completo
curl -X POST "$BASE_URL/api/v1/webhooks?idEmpresa=123" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
"name": "ERP Produccion",
"url": "https://integrador.com/webhooks/bluetech",
"enabled": true,
"secret": "tu_clave_hmac",
"headers": {
"X-Integrador": "erp-central"
},
"events": [
"OrdenDeVenta.Creada",
"OrdenDeVenta.Finalizada",
"Cfe.Emitido"
]
}'Respuesta esperada (201)
{
"id": 845,
"url": "https://integrador.com/webhooks/bluetech",
"events": [
"OrdenDeVenta.Creada",
"OrdenDeVenta.Finalizada",
"Cfe.Emitido"
],
"enabled": true
}Errores frecuentes (400)
{
"error": "Campos requeridos: url, events."
}{
"error": "Payload vacío o inválido."
}Confirmacion y reintentos
Un webhook se toma como entregado cuando tu endpoint responde cualquier codigo 2xx (por ejemplo 200, 202 o 204).
Regla de entrega
2xx -> entregado (sin reintento)
429 -> reintenta
5xx -> reintenta
4xx -> no reintenta (se toma como fallo permanente)
timeout / error de red -> reintentaVentana de reintentos
Demoras progresivas:
5s, 60s, 120s, 300s, 600s, 1800s, 3600s, 7200s, 21600s
El maximo de intentos depende de la configuracion del endpoint.
En alta por API, el valor por defecto es 8 intentos.
Si se agotan los intentos, el evento queda como agotado.Recomendacion para integradores
1) Validar firma HMAC y estructura JSON.
2) Encolar procesamiento interno.
3) Responder 2xx rapido.
4) Procesar de forma idempotente usando Idempotency-Key.Personalizacion
Cuando publiquemos nuevos eventos o cambios de contrato, se anunciaran en Changelog para que puedas adaptar tu integracion.