> ## Documentation Index
> Fetch the complete documentation index at: https://api.contractia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 🔲 Campos dinámicos

> Permite definir e integrar campos editables dentro de un documento. Mediante un único endpoint, podés configurar en un mismo llamado tanto los campos que debe completar cada participante como los campos con datos precargados por el creador. 

<Warning>
  **Incompatibilidad de funcionalidades:**<br />Los **Campos dinámicos** no pueden combinarse con la **Asignación de documentos a participantes** dentro de una misma tarea.

  Debés elegir un único esquema para tu flujo:

  * Usar **Campos dinámicos** para que los participantes completen valores sobre los documentos.
  * Usar **Asignación de documentos** si requerís limitar qué participantes ven o firman cada documento.
</Warning>

#### 🔄 ¿Cómo funciona?

1. **Requisitos previos:** El documento y el participante asignado ya deben estar creados en la tarea.
2. **Envío de datos:** Se envía la estructura JSON con los parámetros obligatorios del campo y la relación con el participante.
3. **Edición o eliminación (Reemplazo total):** Este endpoint opera por **reemplazo completo**. Cada llamada realizada pisa la configuración anterior. Si querés modificar o quitar un campo, debés enviar nuevamente la lista completa con los cambios deseados.

<Warning>
  Asegurate de incluir todos los campos vigentes en cada llamada a la API, ya que cualquier campo que omitas en el nuevo envío será eliminado automáticamente.
</Warning>

## <Badge color="yellow">POST</Badge>➜ /v2/documentos/documento\_id/form-fields

`https://api.contractia.app/v2/documentos/documento\_id/form-fields`

<Info>
  Reemplazar `{documento_id}` por el ID numérico del documento deseado.
</Info>

### **🧾 Parámetros del cuerpo (JSON)**

| Campo | Tipo | Descripción |
| - | - | - |
| `fields` | objeto | |
| `type` | string | `text`debe completarse con texto.<br />`number`debe completarse con números<br />`email`debe completarse con un correo electrónico <br />`signature`campo donde se realizará la firma. <br />`checkbox` |
| `page_index` | int | Número de página en donde ira el campo. Arranca desde el 1. |
| `x` | int | Coordenada en donde irá el campo. Tiene el (0) en la esquina superior izquierda. x>0 a la derecha<br />Se mueve en horizontal. |
| `y` | int | Coordenada en donde irá el campo.<br />Tiene el (0) en la esquina superior izquierda. y>0 hacia abajo<br />Se mueve en vertical. |
| `width` | int | Ancho del campo. |
| `heigh` | int | Altura del campo. |
| `pre_loaded_value` | Va a depender del `type` del campo. | Campo a completar por el remitente. |
| `participation_id` | int | ID del participante que va a completar ese campo. |

### ⚙️ Reglas de configuración

> ⚠️ **1. Exclusividad por campo:** En cada objeto de la lista `fields`, debés usar `participation_id `**O** `pre_loaded_value`, pero nunca ambos en el mismo objeto:
>
> * Usá `participation_id` si el campo lo debe completar un participante.
> * Usá `pre_loaded_value` si el valor ya viene precargado por el creador.

> ✍️ **2. Firma obligatoria por tarea:** Si la tarea cuenta con al menos un participante con rol **Firmante**, es obligatorio que exista **al menos un campo de tipo** `"type": "signature" `**asignado a él en todo el conjunto de la tarea**. No es necesario incluir una firma en cada documento; con que esté presente en al menos uno de los documentos, la condición estará cubierta.

> 🚫 **3. Restricción por rol (Validadores):** No se pueden asignar campos de tipo `"type": "signature"` a participantes con rol Validador. Si se intenta asignar una firma a un validador, la petición devolverá un error y no se creará ningún campo del listado enviado.

> ✍️ **4. Cantidad máxima de campos:** El máximo total de campos por DOCUMENTO es de 500.

> 👥 **5. Cobertura total de participantes: Todos los participantes de la tarea** (sin importar su rol, ya sea Firmante o Validador) deben contar obligatoriamente con al menos un campo asignado (`participation_id`).

> 📄 **6. Cobertura total de documentos: Todos los documentos de la tarea** deben incluir obligatoriamente al menos un campo. No pueden existir documentos sin campos configurados en la tarea.

### 💻 Ejemplo de implementación

<Tabs>
  <Tab title="cURL">
    ```bash theme={"dark"}
    curl --location --request POST 'https://api.contractia.app/v2/documentos/{{documento_id}/form-fields' \
    --header 'Authorization: Bearer {{api_key}}' \
    --header 'user_id: {{user_id}}' \
    --header 'Content-Type: application/json' \
    --data '{
      "fields": [
        {
          "type": "text",
          "page_index": 1,
          "x": 100,
          "y": 200,
          "width": 150,
          "height": 30,
          "pre_loaded_value": "Valor precargado por el creador"
        },
        {
          "type": "email",
          "page_index": 1,
          "x": 100,
          "y": 250,
          "width": 200,
          "height": 30,
          "participation_id": 4821
        },
        {
          "type": "checkbox",
          "page_index": 1,
          "x": 100,
          "y": 300,
          "width": 20,
          "height": 20,
          "participation_id": 4821
        },
        {
          "type": "signature",
          "page_index": 1,
          "x": 100,
          "y": 400,
          "width": 200,
          "height": 60,
          "participation_id": 4821
        }
      ]
    }'
    ```
  </Tab>

  <Tab title="Request JSON">
    ```json theme={"dark"}
    {
      "fields": [
        {
          "type": "text",
          "page_index": 1,
          "x": 100,
          "y": 200,
          "width": 150,
          "height": 30,
          "pre_loaded_value": "Valor precargado por el creador"
        },
        {
          "type": "email",
          "page_index": 1,
          "x": 100,
          "y": 250,
          "width": 200,
          "height": 30,
          "participation_id": 4821
        },
        {
          "type": "checkbox",
          "page_index": 1,
          "x": 100,
          "y": 300,
          "width": 20,
          "height": 20,
          "participation_id": 4821
        },
        {
          "type": "signature",
          "page_index": 1,
          "x": 100,
          "y": 400,
          "width": 200,
          "height": 60,
          "participation_id": 4821
        }
      ]
    }
     
    ```
  </Tab>

  <Tab title="Response JSON">
    ```json theme={"dark"}
    200 OK
    ```
  </Tab>
</Tabs>

## Preguntas frecuentes

* Cómo obtengo la [participacion\_id](/platform/detalle-de-tarea)
* Cómo obtengo el  [documento\_id](/platform/detalle-de-tarea)