🗂️ Carga Masiva de Documentos

Este endpoint permite el envío masivo de documentos DOCX para firma electrónica vía WhatsApp, con soporte para:

• Reemplazo dinámico de variables por firmante
• Firma electrónica con validez legal
• Flujos con o sin validación de fotos / DNI

Endpoint: /api/sendCargaMasiva
Método: POST

---

Attributes

📄 Document Settings — Object

• document_type (string, required)
  Tipo de documento. Único valor permitido: docx.

• document (string, required)
  URL pública del documento o contenido en Base64 que se va a firmar.

• request_photos (boolean, optional)
  Solicita fotos durante el flujo de firma.
  Default: false

• validate_photos (boolean, optional)
  Si es true, se validará el DNI del firmante durante el proceso.
  Default: true

  ⚠️ Disponible solo para usuarios del plan PRO.

---

firmante — Object (required)

Define la posición visual de la firma dentro del documento. Los tres campos son numéricos y obligatorios.

• page (integer, required) — Página donde se aplica la firma. Usar 0 para firmar en todas las páginas.
• position_x (integer, required) — Coordenada X en píxeles
• position_y (integer, required) — Coordenada Y en píxeles

---

df — Array<Object> (required)

Arreglo de firmantes.
Cada objeto consume 1 crédito.

Validaciones:

• El dni y whatsapp deben ser únicos dentro del array (no se permiten duplicados).
• Si se omite id, se usa el whatsapp como identificador interno.

Campos por firmante:

• id (string, optional) — Identificador interno (fallback al whatsapp)
• nombre y apellido (string, required)
• dni (string, required)
• whatsapp (string, required) — Formato internacional (solo dígitos, p.ej. 5491122334455)

---

🔁 Reemplazo de Variables por Firmante

Cada objeto dentro de df puede incluir variables personalizadas en formato clave–valor.
Estas variables se usan para reemplazar automáticamente contenidos del documento DOCX.

¿Cómo funciona?

• En el documento DOCX, las variables deben escribirse entre llaves:

  {nombre_variable}

• En el objeto del firmante (df), se envía la variable con el mismo nombre.

• Cada firmante recibe su documento personalizado.

Ejemplo

Documento (DOCX)

Estado civil: {estado_civil}
Número de póliza: {poliza}

Body — df

{
  "df": [
    {
      "id": 123,
      "nombre y apellido": "Juan Pérez",
      "dni": "12345678",
      "whatsapp": "5491122334455",
      "estado_civil": "soltero",
      "poliza": "A-210"
    },
    {
      "id": 456,
      "nombre y apellido": "María Gómez",
      "dni": "87654321",
      "whatsapp": "5491166778899",
      "estado_civil": "casada",
      "poliza": "B-330"
    }
  ]
}

Resultado

• Juan recibe:

  Estado civil: soltero
  Número de póliza: A-210

• María recibe:

  Estado civil: casada
  Número de póliza: B-330

⚠️ Consideraciones

• No hay límite de variables por firmante.
• Los nombres deben coincidir exactamente (case-sensitive).
• Si una variable existe en el documento pero no en el df, no se reemplaza.

---

Communication — Object

• webhook_url (string, optional)
  URL para recibir notificaciones del proceso.

  Tipos:

  • alert — Documento firmado
  • report — Reporte generado
  • whatsapp — Error de entrega por WhatsApp

• webhook_key (object, optional)
  Par clave–valor adicional para el webhook.

El envío por WhatsApp es siempre automático en este endpoint — no requiere un parámetro adicional.

---

Headers

x-api-key: your-api-key-here
Content-Type: application/json

---

Body (ejemplo completo)

{
  "document_type": "docx",
  "document": "<base64-del-documento>",
  "request_photos": true,
  "validate_photos": true,
  "df": [
    {
      "id": 123,
      "nombre y apellido": "Juan Pérez",
      "dni": "12345678",
      "whatsapp": "5491122334455",
      "estado_civil": "soltero"
    }
  ],
  "firmante": {
    "page": 1,
    "position_x": 120,
    "position_y": 450
  },
  "webhook_url": "https://noApiKey.com",
  "webhook_key": { "key": "value" }
}

---

✅ Respuesta exitosa

[
  {
    "link": "https://midominio.wapifirma.com/rd/123",
    "name": "Juan Pérez",
    "dni": "12345678",
    "contact": "5491122334455",
    "method": "wpp",
    "id_custom": 123
  }
]

---

❌ Respuestas de error

400 — Bad Request

Algunas variantes:

{ "error": "document_type debe ser \"docx\"" }
{ "error": "campo document es requerido" }
{ "error": "campo df debe ser un array no vacío" }
{ "error": "campo firmante es requerido y debe ser un objeto" }
{ "error": "cada elemento de df debe contener al menos nombre y apellido, dni y whatsapp" }
{ "error": "DNI 12345678 duplicado" }
{ "error": "Teléfono 5491122334455 duplicado" }
{ "error": "firmante debe contener position_x, position_y y page como números" }

403 — Forbidden

{ "error": "Tu API Key se encuentra bloqueada. Por favor contacta a soporte." }

429 — Too Many Requests

{ "error": "No te quedan firmas disponibles." }