Recorrido rápido

Preparar el servicio y crear la empresa

npm ci
npm run dev:env
docker compose up -d --wait
npm run build
npm run db:migrate
npm run dev:bootstrap
npm run dev:webhooks

• dev:env crea .env con secretos aleatorios; si ya existe, lo conserva.
• dev:bootstrap crea una sola vez una empresa ficticia con su propietario, su clave y un rango de numeración SIM. Guarda la credencial en .local/credentials.json y una factura lista para enviar en .local/invoice.json. Si ya lo ejecutaste en este equipo, reutiliza esos archivos y no borres .local/bootstrap.lock.
• dev:webhooks crea las claves dedicadas del proceso de webhooks en .local/webhooks/ y su configuración en .local/webhooks.env. Si ya existen, el comando falla a propósito: reutilízalas.

En producción, las empresas no se crean así: las incorpora un operador de Trifaco (ver Incorporación).

Arrancar la API y los workers

Abre tres terminales en la raíz del repositorio:

WEBHOOK_PUBLIC_KEY_FILE="$PWD/.local/webhooks/public.pem" npm run start:api

Comprueba que la API responde:

curl --silent http://127.0.0.1:3000/health/ready

Revisar la empresa y su preparación

Toda operación /v1 lleva la credencial en X-API-Key. Para no dejarla en el historial de la terminal, pásala a curl desde un archivo privado:

node -e 'const {secret}=require("./.local/credentials.json");require("fs").writeFileSync(".local/api.headers",`X-API-Key: ${secret}\n`,{mode:0o600})'
curl --silent --header @.local/api.headers http://127.0.0.1:3000/v1/company
curl --silent --header @.local/api.headers http://127.0.0.1:3000/v1/company/readiness
curl --silent --header @.local/api.headers http://127.0.0.1:3000/v1/capabilities

• GET /v1/company devuelve el perfil y status.
• GET /v1/company/readiness lista cada requisito (identity, numbering, certificate…) con su estado, sin modificar nada. status: ready es disponibilidad administrativa: cada admisión vuelve a comprobar firma, configuración y rango.
• GET /v1/capabilities debe incluir invoice.simulation habilitada y environment: simulation.

Prevalidar, emitir y consultar la factura

Elige una de las dos implementaciones. Ambas usan el mismo cuerpo y la misma clave de idempotencia por defecto, así que ejecutar las dos recupera la misma admisión.

npm run example:simulation

Los dos recorridos:

1. consultan empresa, capacidades y rangos;
2. envían la factura a POST /v1/invoice-validations y exigen valid: true;
3. la admiten con POST /v1/invoices → 202 con document_id, operation_id y status_url;
4. repiten a propósito el mismo envío con la misma Idempotency-Key y comprueban que devuelve el mismo document_id;
5. consultan GET /v1/documents/{id} hasta 20 veces, una por segundo.

Resultado esperado: processing_status: completed y dian.status: validated con código SIMULATION_ONLY y ambiente simulation. No acredita una validación real. Si se agotan las consultas, el ejemplo queda en pending sin emitir otra factura: vuelve a consultar con el mismo ID.

La prevalidación comprueba estructura y reglas fiscales, pero no certificado, autorización ni numeración. 202 solo significa recibido y guardado.

Recibir el webhook

El receptor de ejemplo verifica la firma, el reloj, la empresa y el ambiente; guarda cada evento en una bandeja durable con deduplicación por event_id y responde 204 solo después de guardarlo.

1. Abre un túnel HTTPS hacia el puerto del receptor y copia la URL pública que muestre:

   cloudflared tunnel --url http://127.0.0.1:3082

2. Registra el destino inactivo. El comando guarda el secreto, que se entrega una sola vez, en .local/webhook-receiver.json (0600) y falla si ese archivo ya existe:

   node dist/backend/examples/webhook-register.js register .local/credentials.json .local/webhook-receiver.json receiver-register-001 https://TU-TUNEL/webhooks/trifaco

3. En otra terminal, arranca el receptor:

   node dist/backend/examples/webhook-receiver.js .local/webhook-receiver.json .local/webhook-inbox

4. Con el receptor activo, activa el destino:

   node dist/backend/examples/webhook-register.js activate .local/credentials.json .local/webhook-receiver.json receiver-activate-001

Código: webhook-register.ts y webhook-receiver.ts. Los destinos no reciben eventos anteriores a su activación. El contrato completo del aviso está en Verificar y recibir.

Emitir, esperar el aviso y descargar los archivos

El piloto necesita una factura nueva. Si reutilizas .local/invoice.json, la API devuelve el documento del paso 4, cuyo aviso se generó antes de activar el destino, y el piloto agota la espera. Crea una copia con otra referencia y otra fecha de emisión, y consérvala sin cambios:

node -e '
const f=require("./.local/invoice.json");
f.external_reference=`WEBHOOK-${Date.now()}`;
f.issued_at=new Date().toISOString();
require("fs").writeFileSync(".local/invoice-webhook.json",JSON.stringify(f,null,2),{mode:0o600,flag:"wx"})'
node dist/backend/examples/webhook-pilot.js .local/credentials.json .local/invoice-webhook.json invoice-webhook-001

El piloto (webhook-pilot.ts):

1. prevalida y admite la factura una sola vez;
2. espera en .local/webhook-inbox el evento final de ese documento (hasta 60 s);
3. consulta el estado actual del documento, porque los avisos pueden llegar desordenados;
4. lista sus archivos con GET /v1/documents/{id}/artifacts y descarga el PDF y la vista previa XML con GET /v1/artifacts/{id}/content, verificando tamaño y SHA-256;
5. guarda los archivos en .local/webhook-downloads/, nombrados por su ID y sin sobrescribir.

Salida esperada (IDs distintos):

{"event_id":"…","document_id":"…","event_type":"document.validated","status":"validated","artifacts":["…","…"]}

La clave invoice-webhook-001 queda ligada a esa copia. Para otra prueba, crea otra copia con otro nombre y usa otra clave: repetir la clave con otro cuerpo devuelve 409 IDEMPOTENCY_CONFLICT.

Si se agota la espera, conserva el documento, los bytes y la clave: consulta el documento y los intentos del evento en lugar de emitir otra factura.