API
Listar campos do envelope
Lista os campos dinâmicos de um envelope baseado em template, com seus valores, origem e estado.
GET
/
v1
/
envelopes
/
:uuid
/
fields
Listar campos do envelope
curl --request GET \
--url https://api.valid.com/v1/envelopes/:uuid/fields \
--header 'x-api-key: <api-key>'import requests
url = "https://api.valid.com/v1/envelopes/:uuid/fields"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.valid.com/v1/envelopes/:uuid/fields', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.valid.com/v1/envelopes/:uuid/fields",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.valid.com/v1/envelopes/:uuid/fields"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.valid.com/v1/envelopes/:uuid/fields")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.valid.com/v1/envelopes/:uuid/fields")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_bodyHTTP/1.1 200 OK
Content-Type: application/json
{
"fields": [
{
"key": "nome_cliente",
"fieldUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"type": "text",
"label": "Nome do Cliente",
"required": true,
"pageIndex": 0,
"x": 0.1,
"y": 0.2,
"width": 0.8,
"height": 0.05,
"value": "Empresa XYZ Ltda.",
"origin": "api",
"status": "filled",
"displayState": "filled_by_api",
"assignedSignerId": null,
"editableBySigner": false
},
{
"key": "data_assinatura",
"fieldUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
"type": "date",
"label": "Data de Assinatura",
"required": true,
"pageIndex": 0,
"x": 0.1,
"y": 0.3,
"width": 0.4,
"height": 0.05,
"value": null,
"origin": null,
"status": "pending",
"displayState": "pending",
"assignedSignerId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
"editableBySigner": true
},
{
"key": "termos_aceitos",
"fieldUuid": "6ba7b813-9dad-11d1-80b4-00c04fd430c8",
"type": "checkbox",
"label": "Aceito os termos e condições",
"required": true,
"pageIndex": 1,
"x": 0.1,
"y": 0.8,
"width": 0.8,
"height": 0.1,
"value": ["opcao_a", "opcao_c"],
"origin": "signer",
"status": "filled",
"displayState": "filled_by_signer",
"assignedSignerId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
"editableBySigner": true,
"options": [
{ "label": "Opção A", "value": "opcao_a" },
{ "label": "Opção B", "value": "opcao_b" },
{ "label": "Opção C", "value": "opcao_c" }
]
}
]
}
Retorna todos os campos dinâmicos de um envelope (quando criado a partir de um template), incluindo valores preenchidos, origem (API, operador, signatário) e estado (pendente, preenchido, bloqueado).
Parâmetros
string
required
UUID do envelope.
Respostas
array
Lista de campos do template (cada um é um
EnvelopeFieldBlock).Show Propriedades de fields[]
Show Propriedades de fields[]
string
Identificador único do campo (ex:
"nome_cliente"). Imutável, define a integração.string
UUID interno do campo (para compatibilidade com endpoints que aceitam UUID).
string
Tipo do campo:
text, signature, checkbox, radio, date, select.string
Rótulo do campo (ex:
"Nome do Cliente").boolean
Se é obrigatório.
integer
Página do PDF onde o campo aparece (0-indexado).
number
Coordenada X normalizada (0 a 1, origem no topo-esquerdo).
number
Coordenada Y normalizada (0 a 1).
number
Largura normalizada (0 a 1).
number
Altura normalizada (0 a 1).
string | string[] | boolean
Valor atual do campo. Para
checkbox, array de strings selecionadas. Para radio/select, string única. Para booleanos, true/false.string
Origem do valor:
api (vindo da API), operator (preenchido por operador), signer (preenchido por signatário), default (valor padrão do template), null (pendente).string
Estado do campo:
pending (sem valor), filled (preenchido), locked (preenchido e não editável), invalid (valor inválido).string
Estado para exibição:
pending, filled_by_api, filled_by_operator, filled_by_signer, default, locked, invalid.string
UUID do signatário responsável por preencher este campo (se for um campo de dados atribuído a alguém).
boolean
Se o signatário pode editar este campo (mesmo que já tenha valor pré-preenchido).
array
Para
radio/select, lista de opções disponíveis ({ label, value }).Erros
Veja Autenticação e erros.- 400: Envelope não baseado em template (sem campos).
- 401: API key inválido.
- 404: Envelope não encontrado.
HTTP/1.1 200 OK
Content-Type: application/json
{
"fields": [
{
"key": "nome_cliente",
"fieldUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"type": "text",
"label": "Nome do Cliente",
"required": true,
"pageIndex": 0,
"x": 0.1,
"y": 0.2,
"width": 0.8,
"height": 0.05,
"value": "Empresa XYZ Ltda.",
"origin": "api",
"status": "filled",
"displayState": "filled_by_api",
"assignedSignerId": null,
"editableBySigner": false
},
{
"key": "data_assinatura",
"fieldUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
"type": "date",
"label": "Data de Assinatura",
"required": true,
"pageIndex": 0,
"x": 0.1,
"y": 0.3,
"width": 0.4,
"height": 0.05,
"value": null,
"origin": null,
"status": "pending",
"displayState": "pending",
"assignedSignerId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
"editableBySigner": true
},
{
"key": "termos_aceitos",
"fieldUuid": "6ba7b813-9dad-11d1-80b4-00c04fd430c8",
"type": "checkbox",
"label": "Aceito os termos e condições",
"required": true,
"pageIndex": 1,
"x": 0.1,
"y": 0.8,
"width": 0.8,
"height": 0.1,
"value": ["opcao_a", "opcao_c"],
"origin": "signer",
"status": "filled",
"displayState": "filled_by_signer",
"assignedSignerId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
"editableBySigner": true,
"options": [
{ "label": "Opção A", "value": "opcao_a" },
{ "label": "Opção B", "value": "opcao_b" },
{ "label": "Opção C", "value": "opcao_c" }
]
}
]
}
Exemplo
curl -X GET "https://signer.vcc-service.com/v1/envelopes/550e8400-e29b-41d4-a716-446655440000/fields" \
-H "x-api-key: YOUR_API_KEY"
Relacionado
PATCH /v1/envelopes/:uuid/fields— operador preenche/edita camposPATCH /v1/sign/:sessionToken/fields— signatário preenche campos
⌘I
Listar campos do envelope
curl --request GET \
--url https://api.valid.com/v1/envelopes/:uuid/fields \
--header 'x-api-key: <api-key>'import requests
url = "https://api.valid.com/v1/envelopes/:uuid/fields"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.valid.com/v1/envelopes/:uuid/fields', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.valid.com/v1/envelopes/:uuid/fields",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.valid.com/v1/envelopes/:uuid/fields"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.valid.com/v1/envelopes/:uuid/fields")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.valid.com/v1/envelopes/:uuid/fields")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_bodyHTTP/1.1 200 OK
Content-Type: application/json
{
"fields": [
{
"key": "nome_cliente",
"fieldUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"type": "text",
"label": "Nome do Cliente",
"required": true,
"pageIndex": 0,
"x": 0.1,
"y": 0.2,
"width": 0.8,
"height": 0.05,
"value": "Empresa XYZ Ltda.",
"origin": "api",
"status": "filled",
"displayState": "filled_by_api",
"assignedSignerId": null,
"editableBySigner": false
},
{
"key": "data_assinatura",
"fieldUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
"type": "date",
"label": "Data de Assinatura",
"required": true,
"pageIndex": 0,
"x": 0.1,
"y": 0.3,
"width": 0.4,
"height": 0.05,
"value": null,
"origin": null,
"status": "pending",
"displayState": "pending",
"assignedSignerId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
"editableBySigner": true
},
{
"key": "termos_aceitos",
"fieldUuid": "6ba7b813-9dad-11d1-80b4-00c04fd430c8",
"type": "checkbox",
"label": "Aceito os termos e condições",
"required": true,
"pageIndex": 1,
"x": 0.1,
"y": 0.8,
"width": 0.8,
"height": 0.1,
"value": ["opcao_a", "opcao_c"],
"origin": "signer",
"status": "filled",
"displayState": "filled_by_signer",
"assignedSignerId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
"editableBySigner": true,
"options": [
{ "label": "Opção A", "value": "opcao_a" },
{ "label": "Opção B", "value": "opcao_b" },
{ "label": "Opção C", "value": "opcao_c" }
]
}
]
}