API
Listar envelopes
Lista todos os envelopes do seu projeto com filtros e paginação.
GET
/
v1
/
envelopes
Listar envelopes
curl --request GET \
--url https://api.valid.com/v1/envelopes \
--header 'x-api-key: <api-key>'import requests
url = "https://api.valid.com/v1/envelopes"
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', 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",
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"
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")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.valid.com/v1/envelopes")
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
{
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"externalCode": "CONT-2025-001",
"title": "Contrato de Serviços",
"state": "FINISHED",
"dueDate": "2025-12-31T23:59:59Z",
"createdAt": "2025-07-27T10:30:00.000Z",
"finishedAt": "2025-07-27T15:45:30.000Z"
},
{
"uuid": "660e8400-e29b-41d4-a716-446655440001",
"externalCode": "CONT-2025-002",
"title": "Contrato de Parceria",
"state": "AWAITING_SIGNATURE",
"dueDate": "2025-08-15T23:59:59Z",
"createdAt": "2025-07-27T11:00:00.000Z"
}
],
"total": 2,
"page": 1,
"perPage": 10
}
Lista envelopes com suporte a filtros (estado, CPF de signatário, código externo) e paginação.
Parâmetros de query
enum
Filtrar por estado:
CREATED, AWAITING_SIGNATURE, SIGNING_IN_PROGRESS, FINISHED, CANCELLED, EXPIRED, REFUSED.string
Filtrar por código externo do seu sistema.
string
Filtrar por CPF de um signatário (formato sem dígitos, ex:
"12345678901").integer
Número da página (começa em 1). Padrão: 1.
integer
Itens por página. Padrão: 10. Máximo: 100.
Respostas
array
Lista de envelopes.
Show Propriedades de data[]
Show Propriedades de data[]
string
UUID do envelope.
string
Código externo do seu sistema (se fornecido).
string
Título do envelope.
string
Estado atual:
CREATED, AWAITING_SIGNATURE, SIGNING_IN_PROGRESS, FINISHED, CANCELLED, EXPIRED, REFUSED.string
Data limite de assinatura (ISO 8601).
string
Timestamp de criação (ISO 8601).
string
Timestamp de finalização (ISO 8601), presente apenas se
state for FINISHED.string
Timestamp de recusa (ISO 8601), presente apenas se
state for REFUSED.integer
Total de envelopes que correspondem ao filtro.
integer
Página atual.
integer
Itens por página.
Erros
Veja Autenticação e erros para detalhes.- 400: Parâmetros de query inválidos (ex:
statecom valor desconhecido). - 401: API key/Bearer token inválido.
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"externalCode": "CONT-2025-001",
"title": "Contrato de Serviços",
"state": "FINISHED",
"dueDate": "2025-12-31T23:59:59Z",
"createdAt": "2025-07-27T10:30:00.000Z",
"finishedAt": "2025-07-27T15:45:30.000Z"
},
{
"uuid": "660e8400-e29b-41d4-a716-446655440001",
"externalCode": "CONT-2025-002",
"title": "Contrato de Parceria",
"state": "AWAITING_SIGNATURE",
"dueDate": "2025-08-15T23:59:59Z",
"createdAt": "2025-07-27T11:00:00.000Z"
}
],
"total": 2,
"page": 1,
"perPage": 10
}
Exemplo
# Listar envelopes finalizados da página 1
curl -X GET "https://signer.vcc-service.com/v1/envelopes?state=FINISHED&page=1&perPage=10" \
-H "x-api-key: YOUR_API_KEY"
# Filtrar por CPF
curl -X GET "https://signer.vcc-service.com/v1/envelopes?signerCpf=12345678901" \
-H "x-api-key: YOUR_API_KEY"
# Filtrar por código externo
curl -X GET "https://signer.vcc-service.com/v1/envelopes?externalCode=CONT-2025-001" \
-H "x-api-key: YOUR_API_KEY"
Relacionado
GET /v1/envelopes/:uuid— detalhe completo de um envelopeGET /v1/envelopes/:uuid/history— histórico de ações
⌘I
Listar envelopes
curl --request GET \
--url https://api.valid.com/v1/envelopes \
--header 'x-api-key: <api-key>'import requests
url = "https://api.valid.com/v1/envelopes"
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', 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",
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"
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")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.valid.com/v1/envelopes")
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
{
"data": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"externalCode": "CONT-2025-001",
"title": "Contrato de Serviços",
"state": "FINISHED",
"dueDate": "2025-12-31T23:59:59Z",
"createdAt": "2025-07-27T10:30:00.000Z",
"finishedAt": "2025-07-27T15:45:30.000Z"
},
{
"uuid": "660e8400-e29b-41d4-a716-446655440001",
"externalCode": "CONT-2025-002",
"title": "Contrato de Parceria",
"state": "AWAITING_SIGNATURE",
"dueDate": "2025-08-15T23:59:59Z",
"createdAt": "2025-07-27T11:00:00.000Z"
}
],
"total": 2,
"page": 1,
"perPage": 10
}