factadesarrolladores API 0.1.0-esqueleto

Almacenamiento y retención

Facta no es el archivo fiscal de nadie: el documento firmado tiene que aterrizar en un destino de almacenamiento que la empresa controla. Esta guía cuenta, de principio a fin, cómo funciona: qué guarda Facta, por cuánto tiempo, qué le avisa a la empresa y qué tiene que hacer usted para que el documento no se pierda.

El recorrido completo, de la emisión al borrado

Esto es todo lo que pasa con un documento sellado. Si lee solo una sección de esta guía, que sea esta.

  1. Emitir. POST /v1/dte devuelve el documento sellado. En ese momento Facta guarda una copia temporal cifrada y una copia de retención de una hora. Ninguna de las dos es su archivo.
  2. Guardar. Usted guarda el JSON en un lugar suyo: un destino sincronizado con la llave (S3, R2, Supabase Storage, FTP/SFTP, Almacenamiento Facta), su propio disco o su base de datos. Si ese guardado falla, el almacenamiento de emergencia del SDK (emergencyStore) conserva el documento mientras lo resuelve.
  3. Informar. Guardar no basta: Facta no puede ver su disco. Hay que decirle que ya lo tiene, con POST /v1/dte/{codigoGeneracion}/storage-confirmation. Si Facta mismo escribió la copia (Almacenamiento Facta o un destino propio que el SDK reportó con /byos), el documento queda marcado solo y no hay nada más que hacer.
  4. Si no se informa, el dueño de la empresa recibe un correo desde el primer día con la tabla completa de lo que falta, y GET /v1/storage/unconfirmed lista esos mismos documentos con su fecha de borrado.
  5. Borrado. La copia temporal se borra 30 días después de sellado. Si Facta mismo verifica una copia suya (Almacenamiento Facta, o un destino que Facta escribió y leyó de vuelta), la fecha se adelanta a 2 días después de esa verificación. Un informe suyo (storage-confirmation, el reporte del SDK o «Ya las guardé» en la app) deja el documento marcado y fuera de los correos, pero no adelanta la fecha: Facta no puede comprobar lo que no ve. Esa es la fecha que anuncian el listado y los correos. Después de ella, GET /v1/dte/{codigoGeneracion}/file contesta 410 temporary_copy_expired salvo que Facta tenga otra copia (Almacenamiento Facta).

Las tres capas, una por una

CapaCuánto duraPara qué sirveQuién la creaCómo deja de depender de ella
Área de retención1 horaCubre el tramo entre sellar y que la escritura al destino se confirme.Facta, al sellar.Se vence sola. GET /v1/dte/holding la lista.
Copia temporal cifrada30 días; 2 días después de que Facta verifica una copiaRed de seguridad: de ella salen GET /v1/dte/{cg}/file y la reparación de copias.Facta, al sellar.Que el documento quede marcado como guardado (un informe lo saca de los correos) y que Facta verifique una copia (adelanta la fecha); se borra en la fecha anunciada.
Almacenamiento de emergencia (emergencyStore)Hasta que usted lo vacíeSalvar el documento en su propio servidor cuando el guardado normal falló.El SDK, en su servidor.No marca nada por sí solo. Después hay que informar.

La retención de una hora y la copia temporal se confunden con facilidad. La primera es una ventana corta de seguridad; la segunda es la que da el plazo real de 30 días y la que se informa o se pierde.

Cómo se marca un documento como guardado

Un documento queda marcado cuando ocurre cualquiera de estas cosas. El campo por de la respuesta (y confirmado.por en GET /v1/storage/copies) dice cuál fue la primera:

porQué pasó¿Facta lo comprobó?
facta_managedAlmacenamiento Facta tiene el JSON guardado.Sí
facta_byosFacta escribió y verificó la copia en un destino suyo.Sí
sdk_reportEl SDK escribió en un destino sincronizado y lo avisó con /byos.No: es un informe. No adelanta el borrado
api_reportUsted llamó a storage-confirmation.Solo si Facta puede rearmar el JSON (ver abajo). Aun así no adelanta el borrado
app_reportSe marcó desde la app («Ya las guardé»).No: es un informe. No adelanta el borrado
adminLo marcó el soporte de Facta.— (adelanta el borrado a 2 días, como una verificación)

Una copia que solo existe en un navegador no cuenta.

Informar con storage-confirmation

Descargue el JSON, guárdelo, calcule el SHA-256 de esos mismos bytes y envíelo con un nombre corto del lugar (nunca una ruta con secretos):

curlTerminal
CG=7875BC7A-9580-441D-94E4-FA455E9D8BD0

# 1. Descargue el JSON tal como se guarda.
curl -s "$FACTA_API_BASE_URL/v1/dte/$CG/file?kind=json" \
  -H "X-Facta-Key: $FACTA_API_KEY" -o "$CG.json"

# 2. Guárdelo donde corresponda y calcule el hash de ese archivo.
HASH=$(shasum -a 256 "$CG.json" | cut -d' ' -f1)

# 3. Informe que ya lo tiene.
curl -X POST "$FACTA_API_BASE_URL/v1/dte/$CG/storage-confirmation" \
  -H "X-Facta-Key: $FACTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"donde\": \"disco-contabilidad\", \"sha256\": \"$HASH\"}"

La respuesta trae { confirmado, por, yaConfirmado, verificado, informado, borradoEl }:

  • verificado: true — el documento se emitió por la API, Facta pudo rearmar el JSON y el hash coincidió.
  • informado: true — Facta no pudo comprobarlo (el documento salió de la app y su copia está cifrada con una llave que ningún servidor tiene, o la copia temporal ya se había borrado). Queda como un informe suyo, nunca como verificado.
  • 422 storage_hash_mismatch — el hash no es el del JSON de ese documento (archivo cortado, otro documento). No se registra nada: descargue de nuevo y calcule el hash sobre los bytes guardados.
  • Repetir la llamada es seguro: contesta 200 con yaConfirmado: true y conserva la primera fuente; si después Facta verifica una copia, esa verificación reemplaza al informe y recién entonces se adelanta el borrado.

La llave necesita el alcance issue. Antes de usarla compruebe que GET /v1/storage/status anuncia capabilities.storageConfirmation en 1 o más; sin ese campo el servidor no conoce la ruta (ni borra nada).

Qué recibe el dueño de la empresa

Desde el primer día en que queda un documento sin marcar, el dueño de la empresa recibe un correo de Facta DTE con la tabla completa: tipo, número de control, fecha de emisión y fecha de borrado de cada documento pendiente, y un resumen con el total. El correo no lleva contenido ni datos del receptor.

CuándoQué dice
Al cumplirse 24 horas con documentos sin marcarEl primer aviso, con la tabla completa.
Cada semana mientras sigan pendientesLa tabla al día, con lo que se borra primero arriba.
7 días antes del borradoLos documentos que se borran dentro de una semana.
1 día antes del borradoLos que se borran mañana.

Nunca más de un correo al día por empresa. Un documento sale de los correos en cuanto se marca como guardado. Los correos se envían solo en producción (01); en pruebas (00) la misma información se ve en la app. Si la dirección del dueño rebotó o se quejó, Facta no borra esos documentos y lo muestra en Inicio, porque nadie fue avisado.

Cómo ver qué falta: la lista de documentos sin confirmar

curlTerminal
curl "$FACTA_API_BASE_URL/v1/storage/unconfirmed?limit=50" \
  -H "X-Facta-Key: $FACTA_API_KEY"

Responde { documentos, total, siguiente }. Cada documento trae codigoGeneracion, numeroControl, tipoDte, fecEmi, selladoEn, borradoEl, diasRestantes y copias (facta: stored | pending | none, y byos: cuántos informes hay en destinos propios). Los que se borran antes vienen primero; siguiente es el cursor de la página que sigue. No devuelve contenido, rutas ni datos del receptor.

GET /v1/storage/status repite el resumen en sinConfirmar: { total, primeroSeBorraEl }, para saber con una sola llamada si hay algo pendiente.

Hágalo diario. Un trabajo programado que recorra la lista, descargue cada documento, lo guarde y lo informe vacía el problema antes de que llegue el primer correo. La próxima versión del SDK de TypeScript lo trae hecho (storeAndConfirmUnconfirmed, todavía sin publicar); en los demás lenguajes, el repositorio trae un ejemplo completo y probado por lenguaje (sdks/<lenguaje>/examples/confirmar-almacenamiento.*): listar, descargar, guardar e informar con el SHA-256.

Almacenamiento de emergencia: salva, pero no informa

Cuando el guardado normal falla (el destino no contesta, no hay destino sincronizado, la copia del servidor es solo temporal), el SDK de TypeScript puede llamar a emergencyStore (ya publicado), un lugar que usted pone en su servidor para conservar el documento y el PDF. Protege contra la retención de una hora: evita que el documento quede sin ninguna copia mientras se arregla el destino.

Por sí solo no marca el documento como guardado. Facta no sabe que existe. Después de emergencyStore, usted tiene que informar: llamar a confirmDocumentStorage (o a POST …/storage-confirmation) con el hash de lo que quedó guardado, ya sea cuando facta.emergency.replicate lo copió a un destino o cuando lo pasó a su almacenamiento definitivo. Mientras no lo haga, el documento sigue en la lista de pendientes y en los correos.

Un destino conectado es un requisito, no un extra

Antes de reservar cualquier correlativo, el servidor comprueba que la empresa tiene al menos un destino de almacenamiento —Almacenamiento Facta, S3, R2, Supabase Storage, FTP/SFTP— conectado y verificado en los últimos 30 días. Sin eso, la petición se detiene con 422 no_storage_destination, y no gasta correlativo: corre antes que nada más, porque firmar un documento que no tiene dónde aterrizar lo dejaría sin ninguna copia salvo la de esa misma respuesta HTTP — y esa respuesta se pierde con el primer proceso que se cae.

Google Drive no cuenta como almacenamiento de la API (decisión de seguridad del 17-oct-2026): una empresa cuyo único destino es Drive se trata como una empresa sin destino. Para usar la API conecte Almacenamiento Facta u otro destino compatible (S3 y compatibles, Supabase Storage, FTP/SFTP). La ruta POST /v1/destinations/{id}/drive-token responde 403 drive_not_available_for_api.

Conecte el destino desde la app (vea el paso correspondiente en Empezar); no hay forma de resolver este error desde la API.

El área de retención: una copia de una hora (detalle)

Cuando un documento se firma, una copia cifrada queda además en un área de retención propia de Facta, durante una hora. No es el destino real — es la red de seguridad para el tramo entre que el documento se firma y que su escritura al destino real se confirma.

GET /v1/dte/holding lista lo que hay ahí ahora mismo: evidencia de estado —dónde aterrizó, cuántos intentos, cuándo vence, cuántas veces se descargó—, nunca rutas de bucket ni el contenido en sí.

curlTerminal
curl "$FACTA_API_BASE_URL/v1/dte/holding?limit=50" \
  -H "X-Facta-Key: $FACTA_API_KEY"

Pasada la hora, la descarga sigue funcionando — hasta que la copia temporal se borra

GET /v1/dte/{codigoGeneracion}/file no deja de contestar cuando la hora de retención termina: el documento se rearma desde la copia temporal cifrada de la reserva del correlativo. Esa copia ya no es permanente: dura 30 días después de sellado, o 2 días después de que Facta verifica una copia suya (un informe suyo no adelanta la fecha). Pasada la fecha, la ruta contesta 410 temporary_copy_expired (salvo que Almacenamiento Facta tenga el archivo), y POST /v1/storage/copies/{codigoGeneracion}/repair contesta 409 nothing_to_repair_from. Vea Descargar el JSON y el PDF para el detalle completo.

Qué guarda Almacenamiento Facta

Si su empresa lo tiene, Facta guarda el JSON y el PDF de cada emisión y, desde que existe el tipo invalidation, también el evento de una anulación. GET /v1/storage/status dice qué tipos acepta (supportedKinds: json, pdf e invalidation) y cuáles no (unsupportedKinds: hoy solo ticket). GET /v1/storage/copies lista los recibos, con una fila kind: invalidation por cada anulación.

Los eventos de retorno también quedan allí, en la carpeta eventos/ del documento, como eventos/<CODIGO-DEL-EVENTO>.json y .pdf.

Si prefiere sus propios destinos, avise de cada copia con POST /v1/storage/copies/{codigoGeneracion}/byos; ese aviso marca el documento como guardado (por: sdk_report), pero es un informe: Facta no lo verifica. Con capabilities.byosCopyReport en 2 o más acepta además { "kind": "invalidation", "secretId": "…", "jsonPath": "…" } para el evento de una anulación; vea Anular un documento sellado.

Lo que cada cliente hace por usted

  • SDK de TypeScript (métodos nuevos en la próxima versión, aún sin publicar): issueAndArchive guarda en el archivo local y en los destinos sincronizados, y confirma solo cuando un destino quedó escrito. FileInvoiceArchive cuenta como guardado únicamente si usted lo activa con confirmArchive: true. listUnconfirmedDocuments, confirmDocumentStorage y storeAndConfirmUnconfirmed completan el ciclo. Consulte Estado de publicación.
  • PHP y los demás lenguajes: downloadDocument devuelve los bytes exactos; guardarlos e informar con storage-confirmation es trabajo de su código. Los ejemplos confirmar-almacenamiento de cada lenguaje hacen ese recorrido.

Otras guías

Escriba para buscar Por ejemplo: idempotencia, contingencia, 422, emitir.

↑ ↓ moverse Enter abrir Esc cerrar