Crear Carpeta

POST {{base_url}}/v1/folders

curl -X POST {{base_url}}/v1/folders \
-H "Authorization: Bearer TU_TOKEN_AQUI" \
-H "Content-Type: application/json" \
-d '{
  "name": "Contratos Laborales 2026",
  "external_id": "CL-2026-001",
  "description": "Documentos del área laboral"
}'

Sin ejecutar·latencia ~ 412 ms

Demo pública · no guarda datos · firma con sandbox PKI

Crear Carpeta

Este endpoint permite crear una nueva carpeta dentro de tu cuenta. Las carpetas son estructuras organizativas fundamentales que te permiten agrupar documentos por categorías, departamentos o cualquier lógica de negocio definida por tu sistema.

Autorización

Para consumir este recurso, debes incluir tu token de acceso en el encabezado de la petición utilizando el esquema Bearer.

Parámetro	Tipo	Descripción	Límites
`Authorization*`	string	Token de acceso obtenido en el proceso de login, precedido por la palabra 'Bearer'.	Obligatorio
`Content-Type*`	string	Especifica el formato del cuerpo de la petición.	application/json

Parámetros de la Petición

Campos Obligatorios

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

A continuación, se detallan los parámetros que puedes enviar en el cuerpo (body) de tu petición en formato JSON.

Parámetro	Tipo	Descripción	Límites
`name*`	string	Nombre visible que tendrá la carpeta en la plataforma.	Máx: 100 caracteres
`external_id`	string	Identificador personalizado. Útil para enlazar la carpeta creada con el ID interno de la base de datos de tu propio sistema.	Máx: 255 caracteres
`description`	string	Detalle adicional o notas sobre el propósito de la carpeta.	Entre 5 y 255 caracteres
`parent_id`	string	Token (UUID) de otra carpeta existente. Utiliza este campo únicamente si deseas que la nueva carpeta se cree como una subcarpeta.	Formato UUID válido

Ejemplos de Implementación

Aquí tienes ejemplos listos para copiar y probar la integración de forma inmediata.

cURL

curl -X POST {{base_url}}/v1/folders \
  -H "Authorization: Bearer TU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contratos Laborales 2026",
    "external_id": "CL-2026-001",
    "description": "Carpeta destinada a los nuevos ingresos de este año."
  }'

Node.js (Fetch)

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer TU_TOKEN_AQUI");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
  "name": "Contratos Laborales 2026",
  "external_id": "CL-2026-001",
  "description": "Carpeta destinada a los nuevos ingresos de este año."
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("{{base_url}}/v1/folders", requestOptions)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Estructura de Respuesta

Una vez procesada la solicitud, la API devolverá un objeto JSON con los detalles de la carpeta recién creada junto con su token único.

Respuesta Exitosa (200 OK)

{
  "external_id": "CL-2026-001",
  "token": "8d17c3b4-71f0-4c1a-bf54-2a94d60a23a1",
  "name": "Contratos Laborales 2026",
  "description": "Carpeta destinada a los nuevos ingresos de este año.",
  "document_count": 0,
  "signed_documents_count": 0,
  "in_progress_documents_count": 0,
  "not_started_documents_count": 0,
  "created_at": "2026-06-15T10:30:00.000000Z",
  "updated_at": "2026-06-15T10:30:00.000000Z",
  "deleted": false,
  "parent": null
}

Nombre	Tipo	Descripción
`token`	string	Identificador único y definitivo generado por Firmeasy. Guárdalo en tu base de datos, ya que lo necesitarás para operaciones futuras (como agregarle documentos).
`external_id`	string	El mismo ID que enviaste en la petición original para validación de tu sistema.
`name`	string	Nombre asignado a la carpeta.
`document_count`	integer	Total de documentos alojados (iniciará en 0).
`created_at`	datetime	Fecha y hora exacta de la creación en formato UTC ISO 8601.

Consideraciones de Integración

Almacenamiento de Tokens: Es crucial que almacenes el token devuelto en tu base de datos, ya que es la llave principal para interactuar con esta carpeta en el futuro.
Jerarquías: Puedes crear subcarpetas enviando el token de la carpeta padre en el parámetro parent_id.

Códigos de Estado

Código	Estado	Descripción
`200`	OK	La carpeta se creó correctamente.
`400`	Bad Request	Sintaxis inválida o falta el campo obligatorio `name`.
`401`	Unauthorized	El token Bearer no fue enviado, ha expirado o es incorrecto.
`409`	Conflict	Ya existe una carpeta en tu cuenta utilizando ese mismo `external_id`.
`500`	Server Error	Falla interna en los servidores de Firmeasy.