Crear Carpeta

Este endpoint permite crear una nueva carpeta dentro de la cuenta del cliente. Las carpetas permiten organizar los documentos por categorías, procesos o cualquier lógica definida por el integrador.

Endpoint

POST

 https://app.firmeasy.legal/api/v1/folders

Autenticación

Se requiere enviar el token de autenticación obtenido previamente:

Authorization: Bearer {access}

Headers

Para autorizar el acceso a la API es necesario incluir el token de autenticación en el encabezado Authorization, utilizando el esquema Bearer. Además, el encabezado Content-Type debe especificar que el cuerpo de la solicitud (si lo hubiera) se envía en formato JSON.

Nombre	Tipo	Descripción	Límites
Authorization *	string	Token de acceso obtenido en el login, con el prefijo 'Bearer'.	Obligatorio

Campos Obligatorios

Los campos marcados con un asterisco (*) son obligatorios y deben ser proporcionados en la solicitud. Los demás campos son opcionales.

Cuerpo de la solicitud

En el cuerpo de la solicitud se envían los parámetros necesarios para realizar la operación.

Nombre	Tipo	Descripción	Límites
external_id	string	Identificador externo asignado por el cliente. Permite referenciar la carpeta desde el sistema propio del cliente.	Máx: 255 caracteres
name *	string	Nombre de la carpeta a crear.	Máx: 100 caracteres
description	string	Descripción opcional de la carpeta.	Mayor a 5 caracteres y menor que 255
parent_id	string	Token de la carpeta padre. Permite crear subcarpetas dentro de otra carpeta.	Debe ser un UUID

Ejemplo de request

{
  "external_id": "73a4c1b7-42fe-4b2f-b3dd-91ec1d8e2f5a",
  "name": "Proyecto Aurora",
  "description": "Descripción de prueba para un contrato"
  // "parent_id": "4f6c1e82-71d9-45e3-a1d2-c34c9a8b9f17"
}

Respuesta exitosa

{
  "external_id": "e2a47c9f-9d16-4d85-9240-1a9a7b0a8f35",
  "token": "8d17c3b4-71f0-4c1a-bf54-2a94d60a23a1",
  "name": "Contrato Aurora",
  "description": "Acuerdo para el desarrollo e implementación del sistema Aurora",
  "document_count": 7,
  "signed_documents_count": 3,
  "in_progress_documents_count": 2,
  "not_started_documents_count": 2,
  "created_at": "2024-10-08T11:32:45.000000Z",
  "updated_at": "2024-12-19T15:10:27.000000Z",
  "deleted": false,
  "parent": null
}

Campos devueltos

Nombre	Tipo	Descripción
external_id	string	Identificador asignado por el cliente. Permite al integrador mapear su propio ID al sistema de Firmeasy.
token	string	Identificador interno generado por Firmeasy. Se utiliza en todas las operaciones futuras sobre la carpeta.
name	string	Nombre de la carpeta.
description	string	Descripción de la carpeta.
document_count	integer	Cantidad total de documentos dentro de la carpeta.
signed_documents_count	integer	Cantidad de documentos firmados dentro de la carpeta.
in_progress_documents_count	integer	Documentos actualmente en proceso de firma.
not_started_documents_count	integer	Documentos que aún no han iniciado el proceso de firma.
created_at	datetime	Fecha de creación (formato UTC ISO 8601).
updated_at	datetime	Fecha de última modificación (formato UTC ISO 8601).
deleted	boolean	Indica si la carpeta está eliminada lógicamente.
parent	object	Información de la carpeta padre (null si es raíz).

Consideraciones importantes

El external_id es completamente opcional. Sirve como referencia cruzada para integradores que prefieren trabajar con sus propios IDs.
El token es obligatorio para toda operación de lectura, edición o eliminación posterior sobre la carpeta.
Se permite crear jerarquía de carpetas anidadas mediante el uso de parent_id.

Errores posibles

Código	Descripción
`400`	Request inválido (parámetros incorrectos o faltantes).
`401`	No autorizado (token inválido o ausente).
`409`	Ya existe una carpeta con el mismo `external_id`.
`500`	Error interno inesperado.