Cuenta corporativa
Una cuenta corporativa agrupa a las personas de una empresa y organiza sus documentos en carpetas. Para tu integración cambia la llave, las carpetas y quién ve el secreto.
La llave
En una cuenta corporativa la llave la emite REDCUMBRE, no ValidaFirma: se obtiene con el CLI de REDCUMBRE, redcumbre llaves validafirma. Una llave que alcanza toda la cuenta lleva el rol VALIDAFIRMA_API_CUENTA; una que alcanza solo algunas carpetas, el rol VALIDAFIRMA_API. Si intentas crearla con el CLI de ValidaFirma, la respuesta es LLAVES_LAS_EMITE_REDCUMBRE. validafirma pasar-a-produccion también la pide a REDCUMBRE en una corporativa.
La llave viaja siempre con la cabecera Authorization: Bearer, la misma de las recetas, en una cuenta personal y en una corporativa. X-API-Key sigue vigente para quien ya integró con ella. Si tu llave alcanza más de una cuenta, cada petición nombra la suya con la cabecera X-Cuenta-Id: sin ella responde RCAPI_CUENTA_NO_NOMBRADA con la lista de cuentas posibles, y con una cuenta fuera de esa lista, RCAPI_CUENTA_FUERA_DEL_CONTEXTO. El CLI la envía por ti: elige la cuenta una vez con validafirma init --cuenta <id>.
Dónde queda la llave: validafirma init la deja en el proyecto y, en una corporativa, el .env trae VALIDAFIRMA_API_CUENTA con la ruta de un archivo JSON cuyo campo token es la llave; tu código lee ese campo y lo envía como Authorization: Bearer. El archivo y la llave no van al repositorio.
Para confirmar con qué cuenta y modo trabaja una llave, usa GET /api/auth/whoami: responde la cuenta, su modalidad y el tipo de credencial, sin mostrar la llave.
Las carpetas y sus alcances
En una corporativa los documentos nacen en una carpeta. GET /api/fes/carpetas lista las carpetas a las que tu llave tiene acceso; en una cuenta personal responde CARPETAS_NO_DISPONIBLES. Si tu llave no tiene acceso a la carpeta de un documento, lo ves como DOCUMENTO_NO_ENCONTRADO; si lo ves pero tu nivel no alcanza para la operación, ACCESO_DENEGADO.
Al crear un documento, la carpeta se indica con carpeta_id. Si no la indicas:
- Si tu llave tiene una carpeta por defecto, el documento nace ahí. La marca quien administra la cuenta, una por llave.
- Si no la tiene y la cuenta no exige carpeta, el documento queda en la carpeta personal, fuera de las carpetas de la empresa.
- Si la cuenta exige que todo documento nazca en una carpeta, la creación se rechaza.
| Código | Cuándo | Qué hacer |
|---|---|---|
CARPETA_NO_ENCONTRADA |
La carpeta indicada no existe o tu llave no la ve. | Elige una de las que lista GET /api/fes/carpetas. |
CARPETA_ARCHIVADA |
La carpeta indicada está archivada y no recibe documentos nuevos. | Elige otra carpeta, o pide que se desarchive. |
CARPETA_POR_DEFECTO_ARCHIVADA |
No indicaste carpeta y la carpeta por defecto de tu llave está archivada. | Indica la carpeta, o pide otra carpeta por defecto. |
CARPETA_OBLIGATORIA |
La cuenta exige carpeta y no indicaste ninguna. | Indica carpeta_id. |
CUENTA_SIN_CARPETAS_ACTIVAS |
La cuenta exige carpeta y no tiene ninguna activa. | Quien administra la cuenta crea una carpeta o desarchiva una. |
El secreto del webhook
El secreto de webhooks lo ve solo quien administra la cuenta, en /panel/integraciones, sección «Webhooks». Si el panel no te lo muestra, quien administra la cuenta lo copia a la configuración de tu sistema.
El costo
ValidaFirma no cobra a una cuenta corporativa: el consumo se informa a tu plan de REDCUMBRE. El bloque cobro de la respuesta lo dice tal como corresponde a tu cuenta.
La nube en una corporativa
Lo que creas en una carpeta queda también en la nube de quienes la tienen conectada y la ven en el panel. Llega a la nube de cada persona que conectó la suya y tiene activa esa carpeta, aunque no sea quien creó la llave.
Como vía de vuelta del firmado vale lo mismo que en una cuenta personal (ver la nube), con el mismo respaldo: la consulta de lo pendiente.
Para tu agente
Antes de operar, verifica la cuenta con GET /api/auth/whoami. Si el error es RCAPI_CUENTA_NO_NOMBRADA, hay más de una cuenta posible: pregúntale a la persona cuál usar, de la lista que trae el mismo error, y nombra esa cuenta en cada petición con la cabecera X-Cuenta-Id. Si una cuenta nombrada da DOCUMENTO_NO_ENCONTRADO, revisa que X-Cuenta-Id sea la cuenta del documento. Muestra a la persona el bloque cobro tal como llega. Si el panel no le muestra el secreto de webhooks, pídele que se lo pida a quien administra la cuenta; nunca lo pidas por el chat. Una llave corporativa no la emites tú: dile a la persona que la obtenga con redcumbre llaves validafirma.