Skip to content
Firmeasy Logo Firmeasy API Documentation

Crear Documento

Este endpoint permite registrar un nuevo documento dentro del sistema de firma electrónica avanzada de Firmeasy, especificando el archivo, los firmantes y las configuraciones asociadas.

Endpoint

POST 
https://app.firmeasy.legal/api/v1/documents

Autenticación

El token de acceso obtenido en el proceso de login debe enviarse en cada solicitud:

Nombre Tipo Descripción Límites
Authorization * string Token de acceso obtenido en el login, con el prefijo 'Bearer'. Obligatorio
Content-Type string Especifica el tipo de contenido del cuerpo de la solicitud HTTP. Para las peticiones que incluyen datos JSON 'application/json'

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

Nombre Tipo Descripción Límites
name * string Nombre del documento con su extensión (por ejemplo: 'Contrato2025.pdf'). Máx: 100 caracteres,
document_pdf_base64 string Recomendado, archivo PDF codificado en base64. Requerido si no se usa `document_pdf_url`. Tamaño del archivo soportado hasta 50 MB
document_pdf_url string Alternativa a document_pdf_base64: URL pública desde donde el sistema descargará el archivo PDF. Alternativa a `document_pdf_base64`. Requerido si no se proporciona base64
folder_token string Token de la carpeta donde se almacenará el documento. Si se omite, quedará sin carpeta asignada. Debe ser un UUID
external_id string Identificador externo asignado por el integrador para control interno. Máx: 255 caracteres
signature_deadline datetime Fecha y hora límite para la firma (UTC ISO 8601). En formato UTC y tiene que estar después de la hora
disable_owner_notifications boolean Desactiva notificaciones automáticas al propietario del documento. Por defecto: false
disable_signer_notifications boolean Desactiva notificaciones automáticas a los firmantes. Por defecto: false
send_automatic_invitations boolean Envía automáticamente las solicitudes de firma al crear el documento. Por defecto: true
is_signature_order_active boolean Define si la firma es secuencial o simultánea. Por defecto: false
is_rejection_allowed boolean Permite a los firmantes rechazar la solicitud de firma. Por defecto: false
redirect_link string URL a la que será redirigido el firmante al finalizar su firma. Máx 255 y tiene que ser una URL
observers array<string> Lista de emails que recibirán copia del documento firmado como observadores (máx. 6 correos). Array de emails y máx 20 observers
metadata object Datos adicionales personalizados enviados por el integrador para integración con sistemas internos.

Campos Obligatorios

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

Reglas de los firmantes

Nombre Tipo Descripción Límites
signers * array Lista de firmantes asignados al documento. Debe incluir al menos un firmante. Mínimo 1 elemento
signers[].name * string Nombre completo del firmante. Máx: 100 caracteres
signers[].country_code * string Código de país del firmante (ej.: '+51'). Formato: +XXX, máx: 4 caracteres
signers[].phone * string Número de teléfono del firmante. Entre 9 y 20 caracteres, solo números
signers[].email * string Correo electrónico del firmante. Máx: 150 caracteres
signers[].standard_flow array Flujos estándar de firma. Valores: holographic_signature, otp_email, otp_sms, otp_whatsapp
signers[].advanced_flow array Flujos avanzados de firma. Valores: selfie, identity_document_verification, doc_identidad, live_video_authentication
signers[].external_id string Identificador externo del firmante definido por el integrador. Máx: 255
signers[].position_x float Coordenada horizontal de la firma (opcional, para firma posicionada). Valor en puntos
signers[].position_y float Coordenada vertical de la firma (opcional, para firma posicionada). Valor en puntos
signers[].page integer Página donde se incrustará la firma (opcional). Requerido, mín: 1
signers[].redirect_link string Redirección personalizada al finalizar la firma (opcional). Tiene que ser una URL y máx: 255 caracteres
signers[].geo_latitude string Latitud geográfica al firmar (si aplica). Máx: 255 caracteres
signers[].geo_longitude string Longitud geográfica al firmar (si aplica). Máx: 255 caracteres

Ejemplo de solicitud mínima

{
  "name": "Acuerdo Comercial 2025.pdf",
  "document_pdf_base64": "{{pdf_base64_aqui}}",
  "signers": [
    {
      "name": "Carlos Andrade",
      "country_code": "+51",
      "phone": "926481357",
      "email": "[email protected]"
    }
  ]
}

Respuesta exitosa

{
  "external_id": null,
  "token": "8a6d2f41-93b2-4f1a-8d6a-4f92c93a2f77",
  "name": "Contrato Servicios 2025_02_015432.pdf",
  "folder": null,
  "status": "pending",
  "lang": "es",
  "size": "105328",
  "original_file": "https://docs.empresaglobal.com/files/contratos/8a6d2f41-93b2-4f1a-8d6a-4f92c93a2f77",
  "signed_file": null,
  "signatures_made": 0,
  "signature_deadline": null,
  "signers": [
    {
      "external_id": null,
      "token": "de41f735-89b7-4a18-bb4c-351a43bcf293",
      "status": "new",
      "rejection_reason": null,
      "order": 1,
      "name": "María Fernanda López",
      "email": "[email protected]",
      "phone": "981245673",
      "country_code": "+51",
      "role": "signer",
      "identifier": "G7HkLpQ2mZn5xR8",
      "link": "https://docs.empresaglobal.com/firmantes/de41f735-89b7-4a18-bb4c-351a43bcf293",
      "signed_at_hour": null,
      "signed_at": null,
      "position_x": null,
      "position_y": null,
      "page": null,
      "standard_flow": [
        {
          "state": "P",
          "flow_name": "Firma Holográfica",
          "flow_key": "firma_biometrica"
        }
      ],
      "advanced_flow": [],
      "created_through": "api",
      "send_automatic_invitations": false,
      "send_signed_document_by_whatsapp": false,
      "geo_latitude": null,
      "geo_longitude": null,
      "lang": "es",
      "created_at": "2024-10-15T14:22:48.000000Z",
      "updated_at": "2024-10-15T14:22:48.000000Z"
    }
  ],
  "created_through": "api",
  "reminder_every_n_days": 0,
  "send_automatic_invitations": false,
  "is_rejection_allowed": false,
  "is_signature_order_active": false,
  "redirect_link": null,
  "observers": null,
  "metadata": null,
  "created_at": "2024-10-15T13:58:19.000000Z",
  "updated_at": "2024-10-15T13:58:19.000000Z"
}

Errores posibles

CódigoDescripción
400Request inválido (parámetros incorrectos o faltantes).
401No autorizado (token inválido o ausente).
500Error interno inesperado.