Preparar y firmar por separado

POST /v1/dte hace las dos cosas en un viaje: reserva el número, construye el documento y lo firma. POST /v1/dte/prepare y POST /v1/dte/sign parten ese mismo trabajo en dos llamadas, para quien necesita revisar los totales del documento — o dejar que otra persona lo apruebe — antes de gastar la firma del certificado.

Por qué existen las dos rutas

prepare no pide X-Facta-Sign-Key: reservar el correlativo y construir el documento canónico es todo lo que hace, y firmar no está entre esas dos cosas. Un token robado que solo alcance a llamar prepare no puede firmar nada — necesita además la contraseña del vault, que solo entra en sign.

curl -X POST "$FACTA_API_BASE_URL/v1/dte/prepare" \
  -H "X-Facta-Key: $FACTA_API_KEY" \
  -H "Idempotency-Key: venta-2026-09-02-00417" \
  -H "Content-Type: application/json" \
  -d '{
        "tipoDte": "01",
        "items": [{ "descripcion": "Café", "cantidad": 2, "precioUni": 1.5 }]
      }'

La respuesta trae los totales ya calculados, el numeroControl ya reservado y un prepareToken.

El prepareToken no es una credencial

Sola, no firma nada: es un MAC sobre el hash canónico del documento, y su único trabajo es garantizar que lo que se firma es exactamente lo que obtuvo ese número. El hash se calcula sobre el JSON con las claves ordenadas, así que un cliente que reordene el objeto al deserializarlo — PHP, Go, Python — sigue verificando.

Pase el documento de vuelta sin tocar un centavo. Un cambio, aunque sea de un centavo, se rechaza con 422 prepare_token_invalid en vez de firmarse.

curl -X POST "$FACTA_API_BASE_URL/v1/dte/sign" \
  -H "X-Facta-Key: $FACTA_API_KEY" \
  -H "X-Facta-Sign-Key: $FACTA_SIGN_KEY" \
  -H "Idempotency-Key: venta-2026-09-02-00417" \
  -H "Content-Type: application/json" \
  -d '{
        "prepareToken": "<el que devolvió prepare>",
        "documento": "<preparado.documento, sin tocar un centavo>"
      }'

La misma Idempotency-Key en las dos llamadas

prepare y sign gastan correlativo cada una por su cuenta, así que las dos exigen Idempotency-Key — pero no necesitan ser la misma cadena entre sí: son dos operaciones distintas encadenadas por el prepareToken, no una sola. Lo que sí importa es reusar la misma clave si reintenta cada llamada por separado.

Cuándo usar esto en vez de emitir

Cuando alguien —una persona, un sistema de aprobación— necesita ver el documento y sus totales antes de que exista una firma que no se puede deshacer. Para el camino normal, sin ese paso intermedio, POST /v1/dte hace lo mismo en una sola llamada y es lo que documenta la guía Emitir un DTE.

Otras guías