Saltar al contenido

Documentación

La cuenta corporativa: el mismo llamado, con otra llave.

En una cuenta corporativa cambian 3 cosas para tu integración: la llave, las carpetas donde nacen los documentos y quién ve el secreto de los avisos.

01

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.

Esta página muestra la guía del integrador de ValidaFirma, la misma que lee tu agente convalidafirma guia. Versión 4bdd67c3cb79, escrita para la versión 1.0.0 del contrato y publicada el .

La cuenta corporativa parte con una conversación

Te contamos cómo se activa en rCAPI, qué plan calza con lo que firmas al mes y cómo ordenar las carpetas y las llaves de tus sistemas.