Eventos en vivo

Todo lo que le pasa a un comprobante o a un correo queda como un evento: el mismo objeto que recibe un webhook. Además de recibirlos, puedes consultarlos y seguirlos en vivo.

Listar

curl "https://api.emitay.com/v1/events?type=document.rejected&limit=10" \
  -H "Authorization: Bearer $EMITAY_API_KEY"

El listado va del más nuevo al más antiguo y filtra por type y por document_id. Con document_id obtienes la historia de un comprobante: lo que le pasó a él y a los correos que lo llevaron.

const historia = await emitay.events.list({ document_id: "doc_…" });
for (const evento of historia.data) console.log(evento.created_at, evento.type);

Seguir en vivo

GET /v1/events/stream es un stream de server-sent events: una conexión abierta por la que llega cada evento en cuanto ocurre. No hay que exponer ninguna URL, así que sirve donde un webhook no llega: una terminal, un panel interno, tu máquina de desarrollo.

for await (const event of emitay.events.stream({ types: ["document.rejected"] })) {
  console.error(event.data.object.series, event.data.object.sunat?.description);
}

El iterador del SDK se reconecta solo, retoma donde quedó y no entrega un evento dos veces. Termina con break o con una signal. Con lastEventId empieza después de un evento que ya procesaste.

En la terminal, sin escribir código:

npx emitay events --follow

El paquete emitay aún no está en npm

El SDK y su línea de comandos están terminados, pero el paquete emitay todavía no está publicado en npm: hasta entonces npm install emitay y npx emitay responden «404 Not Found».

Mientras tanto, los eventos se ven en el panel, en Eventos, y el flujo en vivo se lee con curl, como sigue.

El formato, sin el SDK

curl -N https://api.emitay.com/v1/events/stream \
  -H "Authorization: Bearer $EMITAY_API_KEY"

• Un mensaje por evento: event: es su tipo, data: el evento en JSON e id: su id.
• Cada 15 segundos llega un comentario (: heartbeat) que mantiene viva la conexión.
• Al abrir, el stream empieza en el presente y envía un mensaje que solo lleva un id: la posición desde la que reanudar.
• Para reanudar tras un corte, envía la cabecera Last-Event-ID con el último id que recibiste: llegan primero los eventos posteriores a ese y luego los nuevos, sin huecos.

¿Stream o webhooks?

	Webhooks	Stream
Necesita una URL pública	Sí	No
Llega si tu proceso está caído	Sí: Emitay reintenta durante más de un día	No: al reconectar, pides desde tu último id
Para qué	El backend que integra	Terminales, paneles, desarrollo

Para un backend, usa webhooks. La referencia está en Eventos.