Campos y posiciones

Un campo relaciona un PDF, un destinatario y una zona de página. Antes de añadirlo, consulta el sobre y conserva un envelopeItems[].id de texto y un recipients[].id numérico.

Coordenadas e identificadoresCopiar link al encabezado

Posiciones y dimensiones admiten valores entre 0 y 100. Verifica además que la suma de posición y dimensión no salga de la zona de página que deseas utilizar.

Al crear campos dentro de /envelope/create, identifier selecciona el PDF de la carga. En operaciones posteriores, utiliza envelopeItemId.

Añade una firma y un nombreCopiar link al encabezado

Este ejemplo añade dos campos al mismo PDF y destinatario en un borrador. Sustituye los tres IDs por los obtenidos al consultar el sobre.

curl --fail-with-body \
  'https://business.digito.do/api/v2/envelope/field/create-many' \
  -H "Authorization: $DIGITO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
  "envelopeId": "envelope_ejemplo",
  "data": [
    {
      "type": "SIGNATURE",
      "envelopeItemId": "item_ejemplo",
      "recipientId": 123,
      "page": 1,
      "positionX": 10,
      "positionY": 75,
      "width": 30,
      "height": 8
    },
    {
      "type": "NAME",
      "envelopeItemId": "item_ejemplo",
      "recipientId": 123,
      "page": 1,
      "positionX": 10,
      "positionY": 85,
      "width": 40,
      "height": 5
    }
  ]
}'

La respuesta contiene data con los campos creados. Guarda sus IDs numéricos para posteriores cambios. Comprueba que ambos campos pertenezcan al PDF y al destinatario correctos.

Configura un campo de textoCopiar link al encabezado

El tipo principal usa mayúsculas (TEXT) y la variante de fieldMeta usa minúsculas (text). Esta configuración solicita una referencia de contrato y limita su longitud visual:

curl --fail-with-body \
  'https://business.digito.do/api/v2/envelope/field/create-many' \
  -H "Authorization: $DIGITO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
  "envelopeId": "envelope_ejemplo",
  "data": [
    {
      "type": "TEXT",
      "envelopeItemId": "item_ejemplo",
      "recipientId": 123,
      "page": 1,
      "positionX": 10,
      "positionY": 60,
      "width": 45,
      "height": 6,
      "fieldMeta": {
        "type": "text",
        "label": "Referencia del contrato",
        "placeholder": "Contrato 001",
        "required": true,
        "fontSize": 12,
        "characterLimit": 30,
        "textAlign": "left"
      }
    }
  ]
}'

La misma estructura no sirve para todos los tipos. fieldMeta es una unión de variantes; propiedades de text no deben enviarse como si pertenecieran a checkbox o dropdown.

Por ejemplo, esta variante de fieldMeta configura opciones de un campo DROPDOWN:

{
  "type": "dropdown",
  "label": "Tipo de servicio",
  "required": true,
  "values": [
    {
      "value": "Consultoría"
    },
    {
      "value": "Soporte"
    }
  ],
  "defaultValue": "Consultoría"
}

Es solo el objeto fieldMeta; añade el tipo principal, los IDs y las coordenadas para crear un campo. Consulta los esquemas de creación para cada variante.

Actualiza y revisaCopiar link al encabezado

POST /envelope/field/update-many actualiza campos existentes y POST /envelope/field/delete utiliza un fieldId numérico. No crees un campo nuevo para corregir otro sin retirar o actualizar la configuración anterior.

Después de cambiar un PDF, su orden o sus páginas, revisa cada campo nuevamente. El servidor puede aceptar unas coordenadas que resulten poco legibles en el documento.

Firma visible y autorizaciónCopiar link al encabezado

La representación visible no es el certificado de firma electrónica cualificada ni confirma por sí sola una firma completada. El firmante se autentica de nuevo con Digito ID antes de cada acción de firma. La sesión, la clave de API y los tokens técnicos no sustituyen esa autenticación.

Preparar un documento completo · Actualizar campos.