#Documentos

El document library es el repositorio de archivos oficiales de una Fiscal Entity que Clarisfy descarga del SAT, versiona y almacena: Constancia de Situación Fiscal (CSF), Opinión de Cumplimiento (32-D), declaraciones, llaves públicas de e.firma, entre otros. Estos endpoints permiten listar, descargar el archivo, ver su trazabilidad y gestionarlo. Cuelgan de https://api.clarisfy.com/api/v1/document-library.

#El objeto Document

Campo	Tipo	Descripción
`id`	string	Identificador del documento (`doc_…`).
`fiscal_entity_id`	string	La `FiscalEntity` (RFC) dueña (`fe_…`).
`kind`	string	Tipo: `csf`, `opinion_32d`, `declaracion_anual`, `declaracion_mensual`, `efirma_public_keys`, `certificates`, `miinformacion`, `indicators`, `other`.
`filename`	string	Nombre del archivo (p. ej. `constancia.pdf`).
`mime_type`	string	Tipo MIME (p. ej. `application/pdf`).
`size_bytes`	integer	Tamaño en bytes.
`sha256`	string	SHA-256 del archivo (hex).
`is_current`	boolean	`true` si es la versión vigente de ese tipo.
`period_year`	integer \| null	Año fiscal (tipos por periodo, p. ej. declaraciones).
`period_month`	integer \| null	Mes fiscal (declaración mensual).
`metadata`	object	Metadata libre (editable por admin).
`created_at`	string	Alta del documento (ISO 8601).
`created_by`	string \| null	Quién lo creó (`usr_…`), o `null` si lo ingirió el sistema.
`deleted_at`	string \| null	Fecha de soft-delete, o `null`.

#Lista de documentos del RFC

GET/document-library

Documentos del RFC, más recientes primero, con paginación por cursor.

Parámetro (query)	Tipo	Descripción
`fiscalEntityId`	string	Requerido. Identificador de la `FiscalEntity` (`fe_…`).
`kind`	string	Filtra por tipo de documento.
`pageSize`	integer	Tamaño de página (1–200, por defecto 50).
`cursor`	string	`doc_…` de la última fila de la página previa (paginación).
`includeDeleted`	boolean	Incluye documentos eliminados (soft-deleted).

curl "https://api.clarisfy.com/api/v1/document-library?fiscalEntityId=fe_9a1c2b3d4e5f6071&pageSize=50" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "id": "doc_01j9z3n8q7f2v6m4k1c0abcdef",
      "fiscal_entity_id": "fe_9a1c2b3d4e5f6071",
      "kind": "csf",
      "filename": "constancia.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 48213,
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "is_current": true,
      "period_year": null,
      "period_month": null,
      "metadata": {},
      "created_at": "2026-07-10T18:30:00+00:00",
      "created_by": null,
      "deleted_at": null
    }
  ],
  "next_cursor": null
}

next_cursor trae el cursor de la siguiente página, o null si no hay más.

#Descarga el archivo

GET/document-library/{document_id}/content

Devuelve el binario del documento (Content-Disposition: attachment). Cada descarga registra una entrada de auditoría read (ver trazabilidad).

curl https://api.clarisfy.com/api/v1/document-library/doc_01j9z3n8q7f2v6m4k1c0abcdef/content \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -o constancia.pdf

El Content-Type es el mime_type del documento. 404 si el documento no existe o pertenece a otra organización.

#Trazabilidad de un documento

GET/document-library/{document_id}/audit

Historial de acciones sobre el documento (lecturas, cambios de metadata, …), recientes primero.

Parámetro (query)	Tipo	Descripción
`limit`	integer	Máx. entradas (1–500, por defecto 100).

curl https://api.clarisfy.com/api/v1/document-library/doc_01j9z3n8q7f2v6m4k1c0abcdef/audit \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

[
  {
    "id": "a1b2c3d4-...",
    "action": "read",
    "actor": "usr_01j9z3n8q7f2v6m4k1c0abcdef",
    "request_id": null,
    "payload": { "filename": "constancia.pdf", "size_bytes": 48213 },
    "created_at": "2026-07-10T18:35:00+00:00"
  }
]

#Actualiza la metadata

PATCH/document-library/{document_id}

Reemplaza por completo el objeto metadata del documento. Devuelve el documento actualizado.

curl -X PATCH https://api.clarisfy.com/api/v1/document-library/doc_01j9z3n8q7f2v6m4k1c0abcdef \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"reviewed": true, "note": "vigente al cierre"}}'

#Solicita una descarga del SAT (actualizar)

POST/fiscal-entities/{fiscal_entity_id}/documents/{document_type}/download

Dispara que Clarisfy vuelva a descargar un documento directo del SAT y lo deposite en el document library. Es asíncrono: responde 202 con un correlation_id; el archivo aparece en la lista cuando termina.

Parámetro (ruta)	Tipo	Descripción
`fiscal_entity_id`	string	Identificador de la `FiscalEntity` (`fe_…`).
`document_type`	string	Uno de: `csf`, `opinion_32d`, `declaracion_anual`, `declaracion_mensual`, `efirma_public_keys`, `miinformacion`, `certificates`.

curl -X POST https://api.clarisfy.com/api/v1/fiscal-entities/fe_9a1c2b3d4e5f6071/documents/csf/download \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "status": "queued",
  "document_type": "csf",
  "correlation_id": "7c3f6a2e-3b1a-4c9e-9d2f-8a1b2c3d4e5f"
}

#Errores

Código HTTP	Causa
`400`	`fiscal_entity_id` con formato inválido.
`404`	Tu organización no tiene una conexión activa a esa Fiscal Entity.
`409`	El RFC no tiene CIEC almacenada (conexión `draft` / nunca validada) y el tipo la requiere.
`422`	`document_type` no es uno de los valores permitidos.
`429`	Solo `miinformacion`: ya se actualizó hoy (una vez por RFC por día). Incluye `Retry-After`.