Llaves y cuenta corporativa: un sistema, una llave.

Mismo host, misma API, mismo contrato. Lo que cambia entre una cuenta y otra es de dónde sale la llave y en qué cabecera va. Y en las dos, si un documento es de prueba o real lo decide la llave, nunca un parámetro: pasar de prueba a real es cambiar la llave.

curl -X POST https://api.validafirma.cl/api/fes/documentos \
  -H "Authorization: Bearer $RCAPI_API_KEY" \
  -F "documento=@contrato.pdf" \
  -F 'firmantes=[{"rut":"49999901-1","canal":"email","email":"camila@ejemplo.cl"}]' \
  -F "carpeta_id=3c9e8f20-7a1b-4d55-b6e2-0f4a9d1c7e33" \
  -F "webhook_url=https://tu-sistema.cl/webhooks/validafirma"

GET /api/auth/whoami es la primera llamada de una integración: dice de qué cuenta es la llave, en qué modalidad y en qué modo. Antes de crear el primer documento, confirma que la cuenta y el modo son los que esperas.

curl https://api.validafirma.cl/api/auth/whoami \
  -H "Authorization: Bearer $RCAPI_API_KEY"

{
  "cuenta": { "id": "b2c3d4e5-…", "nombre": "Mi Empresa SpA", "modalidad": "corporativa" },
  "credencial": {
    "tipo": "rcapi_key",
    "nombre": "Integración ERP (prueba)",
    "permisos": [],
    "roles": ["VALIDAFIRMA_API"],
    "sandbox": true
  }
}

cuenta.modalidad

personal o corporativa.

credencial.nombre

El nombre de la llave, para que sepas cuál de tus sistemas está llamando.

credencial.sandbox

true con una llave de prueba y false con una real. Es la misma forma en que responde rCAPI.

En la cuenta personal es la misma llamada, con X-API-Key.

En la cuenta corporativa cada sistema que integra —el ERP, el portal de recursos humanos, el CRM— debería tener su propia credencial. Así cada uno tiene su alcance y su carpeta por defecto, y cada documento queda registrado con la llave que lo creó, o con la persona, si lo creó alguien desde el panel.

La carpeta por defecto

Un administrador puede marcar una de las carpetas de una llave como su carpeta por defecto. Si el ERP de recursos humanos tiene «Contratos» como carpeta por defecto, todo lo que crea sin carpeta_id nace en Contratos, y tu código no necesita saber el identificador de la carpeta. Si la llave no tiene carpeta por defecto, lo que crea sin carpeta_id nace en su carpeta personal.

Si la carpeta por defecto se archiva, lo que la llave cree sin carpeta_id se rechaza con409 CARPETA_POR_DEFECTO_ARCHIVADA, un mensaje que la nombra («Tu carpeta por defecto «X» está archivada…») y la carpeta en carpeta, con su id y sunombre.

• Rotar conserva. Regenerar la credencial en rCAPI mantiene sus accesos y su carpeta por defecto.
• Revocar borra. Una llave eliminada pierde sus accesos, y la que la reemplace parte sin ninguno: no los hereda.
• Sólo las rutas del integrador. Una llave crea, consulta, reenvía, cancela, descarga y lista sus carpetas. También ve los firmantes y las estadísticas, calcula el costo, pide, consulta y descarga exportaciones del archivo, y llama a whoami y a la simulación del modo de prueba. No administra carpetas ni accesos, no emite poderes de firma y no ve el secreto de webhooks.

Las carpetas agrupan los documentos de la cuenta corporativa por faena, obra, área o cliente. Son planas, sin subcarpetas, y un documento está en una sola. No cuestan nada. Sólo un administrador las crea, las renombra, las archiva y reparte accesos, a personas o a llaves, desde el panel: esa administración no es parte de la API.

Cuatro niveles de acceso

El nivel va con su valor en la API y, al lado, la etiqueta con que lo muestra el panel. No es una escala:escritura deja crear y ve menos que lectura.

• El rol manda sobre el nivel. Administradores y revisores ven todo; un operador ve sus carpetas y su carpeta personal.
• La carpeta personal es donde nace un documento creado sincarpeta_id por quien no tiene carpeta por defecto. La ven quien lo creó, los administradores, los revisores y las llaves con alcance de cuenta.
• Carpeta obligatoria. Un administrador puede encender «Exigir que todo documento nuevo nazca en una carpeta», que viene apagado. Con la exigencia encendida, un documento sin carpeta_id nace igual en la carpeta por defecto de la llave. Si no tiene una, y las personas nunca la tienen, se rechaza con 400 CARPETA_OBLIGATORIA, o con409 CUENTA_SIN_CARPETAS_ACTIVAS si la cuenta no tiene ninguna carpeta activa.
• Archivar no borra. Una carpeta archivada no recibe documentos nuevos; los que tiene siguen consultables, y los pendientes se pueden reenviar o cancelar.

Las carpetas desde tu sistema

Al crear, indicas la carpeta con carpeta_id. Para saber cuáles alcanza tu llave,GET /api/fes/carpetas lista las que ves, con tu nivel en cada una y es_defecto: true en tu carpeta por defecto, y trae ademáscarpeta_obligatoria, que dice si la cuenta exige carpeta. Con alcance de cuenta las ves todas; donde la llave no tiene un acceso propio, nivel llega nulo conorigen_del_acceso: "rol". Por defecto lista las activas: ?estado=acepta activa, archivada o todas, ylimite va de 50 por defecto a 200 como máximo. En una cuenta personal responde404 CARPETAS_NO_DISPONIBLES: ahí las carpetas no existen.

curl https://api.validafirma.cl/api/fes/carpetas \
  -H "Authorization: Bearer $RCAPI_API_KEY"

{
  "carpetas": [
    {
      "id": "aaaaaaaa-0000-0000-0000-000000000001",
      "nombre": "Faena Norte",
      "estado": "activa",
      "created_at": "2026-09-01T10:00:00.000Z",
      "nivel": "escritura",
      "es_defecto": true,
      "origen_del_acceso": "acceso"
    }
  ],
  "pagina": 1,
  "limite": 50,
  "total": 1
}

En la cuenta corporativa, los usuarios y sus roles los gobierna rCAPI: en ValidaFirma no se asignan. Cada persona entra con su acceso de REDCUMBRE y tiene uno de tres roles. También cuentan como administradores el administrador de la empresa en la plataforma de REDCUMBRE y la operación de REDCUMBRE, que no puede cambiar la protección del plan.

• AdministradorVALIDAFIRMA_ADMINTodo lo de la cuenta: crea y archiva carpetas, reparte accesos, emite poderes de firma, ve y rota el secreto de webhooks y maneja la protección del plan. Ve todos los documentos de la cuenta.
• RevisorVALIDAFIRMA_REVISORVe y descarga todo lo de la cuenta, incluidas las carpetas personales, exporta el archivo y ve la bitácora. No escribe nada: no crea, no reenvía, no cancela.
• OperadorVALIDAFIRMA_OPERADORCrea documentos y opera lo suyo y lo de las carpetas donde tiene acceso, con el nivel que tiene en cada una.

• Cada documento queda registrado con la persona o la llave que lo creó, y la bitácora registra lo que hacen en la cuenta las personas, las llaves y REDCUMBRE.
• Ante el firmante, quien envía es la empresa, con su razón social, nunca la persona o la llave que creó el documento.
• Los avisos al emisor de lo que crea una llave, como el correo con enlace al panel cuando el documento queda firmado, llegan al correo de avisos de la cuenta y, si no hay uno, a los administradores.

Lo que la cuenta corporativa ofrece a la empresa, más allá de la integración, está en el Plan empresa.

En las dos, lo que crea una llave de prueba no se cobra. Los precios están en precios.

Cada aviso del webhook va firmado con un secreto de la cuenta, uno por modo: whsec_live_ para lo real y whsec_test_ para lo de prueba. Lo ve y lo rota sólo una persona con sesión en el panel, en la tarjeta «Secreto de webhooks»: «Revelar», luego «Copiar» y «Ocultar», y «Rotar». En la cuenta personal está en «API Keys», del menú de usuario, que sólo existe en las cuentas personales. En la corporativa la sección es del administrador, con el rol VALIDAFIRMA_ADMIN: quien opera o consulta no tiene entrada a ella. Una credencial de máquina que lo pide recibe403 SECRETO_SOLO_CON_SESION_DE_PERSONA.

Al rotarlo, el modal «Rotar el secreto de webhooks» pregunta qué pasa con el anterior: «Deja de firmar ahora», la opción marcada, o «Sigue firmando 24 horas». Con la segunda, durante esas 24 horas el aviso trae dos firmas, una con cada secreto, y vale cualquiera. Se confirma con «Sí, rotar». Los documentos creados con una llave que después se revoca siguen mandando sus webhooks. Cómo comprobar la firma, en webhooks.