A documentação da ArcSign API

Quem sou eu

curl -X GET "https://app.arcsphera.com/api/v1/me" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/me", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 A chave vale.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Revogar esta chave

# A Idempotency-Key é estável por registro: a nova tentativa usa a MESMA; um pedido novo, outra.
curl -X POST "https://app.arcsphera.com/api/v1/me/revoke" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Idempotency-Key: revokeMe-exemplo-1"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde junto do seu registro

const resposta = await fetch("https://app.arcsphera.com/api/v1/me/revoke", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    // Estável por registro: a nova tentativa usa a MESMA chave e o MESMO corpo.
    "Idempotency-Key": idempotencyKey,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 A chave foi revogada. Daqui em diante, ela recebe 401.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Listar os envelopes

curl -X GET "https://app.arcsphera.com/api/v1/envelopes" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/envelopes", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 Uma página da lista.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Criar um envelope

O corpo

# A Idempotency-Key é estável por registro: a nova tentativa usa a MESMA; um pedido novo, outra.
curl -X POST "https://app.arcsphera.com/api/v1/envelopes" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Idempotency-Key: createEnvelope-exemplo-1" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Locação — Rua das Flores, 120, ap. 31",
  "documentType": "OTHER",
  "externalReference": "crm:contrato:ck9x2",
  "onBehalfOf": {
    "id": "imob_42",
    "name": "Imobiliária Sol Ltda.",
    "cnpj": "11.222.333/0001-81"
  },
  "status": "sent",
  "expiresInDays": 15,
  "documents": [
    {
      "name": "contrato.pdf",
      "contentBase64": "JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAxMTAKPj4Kc3RyZWFtCnicHYpBCsJQDAX37xRZF4r5aX7yC+JCaOnCjZALiNTSoouKeH5tGRhmMSvOAaaN94TDMD6/42e+32rntmhhLy0loXhAlOKCtK+JhCkzxQtHbay3ztXFkqv1wqaWhf+dvdl8olgQFbrAFT+/TBi+CmVuZHN0cmVhbQplbmRvYmoKCjYgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL09ialN0bQovTiA0Ci9GaXJzdCAyMAovTGVuZ3RoIDIzMgo+PgpzdHJlYW0KeJxVj91qAjEQhe/zFPMCZRK7siuIoNIfKMWihRZKL+LusKRIUsxs0bfvTLpFvAhkzjkzfMeBhQlUFdxC3UAFk2kN87nB1/M3Ab74nrLBp9Bl+JCIhS18GlynITI4s1iYS3bt2R9Sb/6WwGn4OqGG2kfS7eLjlnIajq0saO4+iaOfRzr8EIfW39R21lSNrZuZ0I0n8X2z/6K2RHW8O/HDjj3TKKj2TF3wq3QSbqsdrQUnT+iXMSbWPqVJZKHRaTq2u0JWIIO7Yc9lVNEZXPlMBfXCKRCxTV2IPeBbiMuYw7+gF38B7fhizAplbmRzdHJlYW0KZW5kb2JqCgo3IDAgb2JqCjw8Ci9TaXplIDgKL1Jvb3QgMiAwIFIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL1hSZWYKL0xlbmd0aCAzOAovVyBbIDEgMiAyIF0KL0luZGV4IFsgMCA4IF0KPj4Kc3RyZWFtCnicFcSxDQAgCACwgomzi/+fw1koHYrutJliymmFQ6hfXh5UAAMWCmVuZHN0cmVhbQplbmRvYmoKCnN0YXJ0eHJlZgo1MzMKJSVFT0Y="
    }
  ],
  "recipients": [
    {
      "type": "SIGNER",
      "order": 1,
      "name": "Ana Souza",
      "email": "ana@example.com",
      "expectedCpf": "529.982.247-25"
    },
    {
      "type": "SIGNER",
      "order": 1,
      "name": "Bruno Lima",
      "email": "bruno@example.com"
    },
    {
      "type": "SIGNER",
      "order": 2,
      "name": "Testemunha 1",
      "email": "t1@example.com"
    },
    {
      "type": "CARBON_COPY",
      "order": 3,
      "name": "Imobiliária Sol",
      "email": "contratos@example.com"
    }
  ]
}'

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde junto do seu registro

const resposta = await fetch("https://app.arcsphera.com/api/v1/envelopes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    // Estável por registro: a nova tentativa usa a MESMA chave e o MESMO corpo.
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Locação — Rua das Flores, 120, ap. 31",
    "documentType": "OTHER",
    "externalReference": "crm:contrato:ck9x2",
    "onBehalfOf": {
      "id": "imob_42",
      "name": "Imobiliária Sol Ltda.",
      "cnpj": "11.222.333/0001-81"
    },
    "status": "sent",
    "expiresInDays": 15,
    "documents": [
      {
        "name": "contrato.pdf",
        "contentBase64": "JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAxMTAKPj4Kc3RyZWFtCnicHYpBCsJQDAX37xRZF4r5aX7yC+JCaOnCjZALiNTSoouKeH5tGRhmMSvOAaaN94TDMD6/42e+32rntmhhLy0loXhAlOKCtK+JhCkzxQtHbay3ztXFkqv1wqaWhf+dvdl8olgQFbrAFT+/TBi+CmVuZHN0cmVhbQplbmRvYmoKCjYgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL09ialN0bQovTiA0Ci9GaXJzdCAyMAovTGVuZ3RoIDIzMgo+PgpzdHJlYW0KeJxVj91qAjEQhe/zFPMCZRK7siuIoNIfKMWihRZKL+LusKRIUsxs0bfvTLpFvAhkzjkzfMeBhQlUFdxC3UAFk2kN87nB1/M3Ab74nrLBp9Bl+JCIhS18GlynITI4s1iYS3bt2R9Sb/6WwGn4OqGG2kfS7eLjlnIajq0saO4+iaOfRzr8EIfW39R21lSNrZuZ0I0n8X2z/6K2RHW8O/HDjj3TKKj2TF3wq3QSbqsdrQUnT+iXMSbWPqVJZKHRaTq2u0JWIIO7Yc9lVNEZXPlMBfXCKRCxTV2IPeBbiMuYw7+gF38B7fhizAplbmRzdHJlYW0KZW5kb2JqCgo3IDAgb2JqCjw8Ci9TaXplIDgKL1Jvb3QgMiAwIFIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL1hSZWYKL0xlbmd0aCAzOAovVyBbIDEgMiAyIF0KL0luZGV4IFsgMCA4IF0KPj4Kc3RyZWFtCnicFcSxDQAgCACwgomzi/+fw1koHYrutJliymmFQ6hfXh5UAAMWCmVuZHN0cmVhbQplbmRvYmoKCnN0YXJ0eHJlZgo1MzMKJSVFT0Y="
      }
    ],
    "recipients": [
      {
        "type": "SIGNER",
        "order": 1,
        "name": "Ana Souza",
        "email": "ana@example.com",
        "expectedCpf": "529.982.247-25"
      },
      {
        "type": "SIGNER",
        "order": 1,
        "name": "Bruno Lima",
        "email": "bruno@example.com"
      },
      {
        "type": "SIGNER",
        "order": 2,
        "name": "Testemunha 1",
        "email": "t1@example.com"
      },
      {
        "type": "CARBON_COPY",
        "order": 3,
        "name": "Imobiliária Sol",
        "email": "contratos@example.com"
      }
    ]
  }),
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 201 O envelope nasceu (e, com `status sent`, saiu).
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Consultar um envelope

curl -X GET "https://app.arcsphera.com/api/v1/envelopes/<id>" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/envelopes/<id>", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O envelope.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Enviar o rascunho

O corpo

# A Idempotency-Key é estável por registro: a nova tentativa usa a MESMA; um pedido novo, outra.
curl -X POST "https://app.arcsphera.com/api/v1/envelopes/<id>/send" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Idempotency-Key: sendEnvelope-exemplo-1" \
  -H "Content-Type: application/json" \
  -d '{}'

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde junto do seu registro

const resposta = await fetch("https://app.arcsphera.com/api/v1/envelopes/<id>/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    // Estável por registro: a nova tentativa usa a MESMA chave e o MESMO corpo.
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O envelope, enviado.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Cancelar o envelope

O corpo

# A Idempotency-Key é estável por registro: a nova tentativa usa a MESMA; um pedido novo, outra.
curl -X POST "https://app.arcsphera.com/api/v1/envelopes/<id>/void" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Idempotency-Key: voidEnvelope-exemplo-1" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "O locatário desistiu da locação."
}'

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde junto do seu registro

const resposta = await fetch("https://app.arcsphera.com/api/v1/envelopes/<id>/void", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    // Estável por registro: a nova tentativa usa a MESMA chave e o MESMO corpo.
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "O locatário desistiu da locação."
  }),
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O envelope, cancelado.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Baixar o PDF concluído

curl -X GET "https://app.arcsphera.com/api/v1/envelopes/<id>/documents/completed" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/envelopes/<id>/documents/completed", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O PDF.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Baixar o certificado de conclusão

curl -X GET "https://app.arcsphera.com/api/v1/envelopes/<id>/documents/certificate" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/envelopes/<id>/documents/certificate", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O PDF do certificado.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Baixar um documento original

curl -X GET "https://app.arcsphera.com/api/v1/envelopes/<id>/documents/<docId>" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/envelopes/<id>/documents/<docId>", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O PDF original.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Listar os Modelos publicados

curl -X GET "https://app.arcsphera.com/api/v1/templates" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/templates", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 Os modelos.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Listar os webhooks

curl -X GET "https://app.arcsphera.com/api/v1/webhooks" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 A lista.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Cadastrar um webhook

O corpo

# A Idempotency-Key é estável por registro: a nova tentativa usa a MESMA; um pedido novo, outra.
curl -X POST "https://app.arcsphera.com/api/v1/webhooks" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Idempotency-Key: createWebhook-exemplo-1" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://crm.example.com/webhooks/arcsign",
  "events": [
    "envelope.completed",
    "envelope.declined",
    "envelope.voided",
    "envelope.expired",
    "recipient.signed"
  ],
  "description": "CRM Exemplo — produção"
}'

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde junto do seu registro

const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    // Estável por registro: a nova tentativa usa a MESMA chave e o MESMO corpo.
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://crm.example.com/webhooks/arcsign",
    "events": [
      "envelope.completed",
      "envelope.declined",
      "envelope.voided",
      "envelope.expired",
      "recipient.signed"
    ],
    "description": "CRM Exemplo — produção"
  }),
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 201 Cadastrado. O `secret` só aparece aqui.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Ler um webhook

curl -X GET "https://app.arcsphera.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks/<id>", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O webhook.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Mudar um webhook

O corpo

curl -X PATCH "https://app.arcsphera.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks/<id>", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "enabled": true
  }),
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O webhook, como ficou.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Apagar um webhook

curl -X DELETE "https://app.arcsphera.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks/<id>", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}

• 204 Apagado.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Trocar o segredo

# A Idempotency-Key é estável por registro: a nova tentativa usa a MESMA; um pedido novo, outra.
curl -X POST "https://app.arcsphera.com/api/v1/webhooks/<id>/rotate-secret" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Idempotency-Key: rotateWebhookSecret-exemplo-1"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde junto do seu registro

const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks/<id>/rotate-secret", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    // Estável por registro: a nova tentativa usa a MESMA chave e o MESMO corpo.
    "Idempotency-Key": idempotencyKey,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 O segredo novo.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Enviar um teste

# A Idempotency-Key é estável por registro: a nova tentativa usa a MESMA; um pedido novo, outra.
curl -X POST "https://app.arcsphera.com/api/v1/webhooks/<id>/test" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Idempotency-Key: testWebhook-exemplo-1"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde junto do seu registro

const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks/<id>/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    // Estável por registro: a nova tentativa usa a MESMA chave e o MESMO corpo.
    "Idempotency-Key": idempotencyKey,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 A entrega do teste, com o resultado.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

A fila de entrega

curl -X GET "https://app.arcsphera.com/api/v1/webhooks/<id>/deliveries" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks/<id>/deliveries", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 Uma página da fila.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

Reenviar agora

# A Idempotency-Key é estável por registro: a nova tentativa usa a MESMA; um pedido novo, outra.
curl -X POST "https://app.arcsphera.com/api/v1/webhooks/<id>/deliveries/<deliveryId>/retry" \
  -H "Authorization: Bearer $ARCSIGN_API_KEY" \
  -H "Idempotency-Key: retryWebhookDelivery-exemplo-1"

// Node 18 ou mais, como módulo ES (o await no topo): salve como exemplo.mjs e rode node exemplo.mjs.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // guarde junto do seu registro

const resposta = await fetch("https://app.arcsphera.com/api/v1/webhooks/<id>/deliveries/<deliveryId>/retry", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARCSIGN_API_KEY}`,
    // Estável por registro: a nova tentativa usa a MESMA chave e o MESMO corpo.
    "Idempotency-Key": idempotencyKey,
  },
});

if (!resposta.ok) {
  // RFC 9457: decida pelo `code`, mostre o `detail`, guarde o `requestId`.
  const problema = await resposta.json();
  throw new Error(`${problema.code}: ${problema.detail} (${problema.requestId})`);
}
const dados = await resposta.json();

• 200 A entrega, com o resultado desta tentativa.
• 400 Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).
• 401 Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.
• 403 A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).
• 404 Não existe, ou é de outra organização — as duas respostas são iguais.
• 409 A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.
• 413 O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.
• 422 Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/<nome>`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).
• 423 A licença está só de leitura (`license_read_only`) — a API lê, e não grava.
• 429 Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).
• 500 O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.
• 503 O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.

envelope.sent

Envelope enviado

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d",
  "type": "envelope.sent",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "envelope": {
      "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64",
      "status": "sent",
      "statusChangedAt": "2026-10-21T18:04:05.123Z",
      "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73",
      "onBehalfOf": {
        "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21"
      },
      "test": false
    },
    "recipient": null
  }
}

envelope.delivered

Envelope aberto

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d",
  "type": "envelope.delivered",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "envelope": {
      "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64",
      "status": "delivered",
      "statusChangedAt": "2026-10-21T18:04:05.123Z",
      "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73",
      "onBehalfOf": {
        "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21"
      },
      "test": false
    },
    "recipient": null
  }
}

recipient.signed

Alguém assinou

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d",
  "type": "recipient.signed",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "envelope": {
      "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64",
      "status": "delivered",
      "statusChangedAt": "2026-10-21T17:58:41.902Z",
      "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73",
      "onBehalfOf": {
        "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21"
      },
      "test": false
    },
    "recipient": {
      "id": "2d8f4b6a-1c3e-4f5a-9b7d-0e2c4a6f8b13",
      "type": "SIGNER",
      "order": 1,
      "status": "signed"
    }
  }
}

recipient.declined

Alguém recusou

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d",
  "type": "recipient.declined",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "envelope": {
      "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64",
      "status": "declined",
      "statusChangedAt": "2026-10-21T18:04:05.123Z",
      "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73",
      "onBehalfOf": {
        "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21"
      },
      "test": false
    },
    "recipient": {
      "id": "2d8f4b6a-1c3e-4f5a-9b7d-0e2c4a6f8b13",
      "type": "SIGNER",
      "order": 1,
      "status": "declined"
    }
  }
}

envelope.completed

Envelope concluído

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d",
  "type": "envelope.completed",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "envelope": {
      "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64",
      "status": "completed",
      "statusChangedAt": "2026-10-21T18:04:05.123Z",
      "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73",
      "onBehalfOf": {
        "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21"
      },
      "test": false
    },
    "recipient": null
  }
}

envelope.declined

Envelope recusado

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d",
  "type": "envelope.declined",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "envelope": {
      "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64",
      "status": "declined",
      "statusChangedAt": "2026-10-21T18:04:05.123Z",
      "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73",
      "onBehalfOf": {
        "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21"
      },
      "test": false
    },
    "recipient": null
  }
}

envelope.voided

Envelope cancelado

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d",
  "type": "envelope.voided",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "envelope": {
      "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64",
      "status": "voided",
      "statusChangedAt": "2026-10-21T18:04:05.123Z",
      "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73",
      "onBehalfOf": {
        "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21"
      },
      "test": false
    },
    "recipient": null
  }
}

envelope.expired

Envelope expirado

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d",
  "type": "envelope.expired",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "envelope": {
      "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64",
      "status": "expired",
      "statusChangedAt": "2026-10-21T18:04:05.123Z",
      "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73",
      "onBehalfOf": {
        "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21"
      },
      "test": false
    },
    "recipient": null
  }
}

webhook.test

O teste do webhook

• ArcSign-Signature — t=<unix>,v1=<hex>: HMAC-SHA256 de "{t}.{corpo bruto}" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.
• ArcSign-Event-Id — O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.
• ArcSign-Event-Type — O tipo do evento, o mesmo do `type` do corpo.
• ArcSign-Delivery-Id — A entrega — é o `deliveryId` do reenvio pela API.
• ArcSign-Delivery-Attempt — 1 na primeira tentativa, 2 na segunda…
• webhook-id — Standard Webhooks: o id do evento.
• webhook-timestamp — Standard Webhooks: o mesmo t, em segundos Unix.
• webhook-signature — Standard Webhooks: v1,<base64> — HMAC-SHA256 de "{id}.{t}.{corpo}" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.

{
  "id": "evt_9a2c4e6b8d0f1a3c5e7b9d1f",
  "type": "webhook.test",
  "timestamp": "2026-10-21T18:04:05.123Z",
  "data": {
    "webhook": {
      "id": "3e5a7c9b-1d2f-4a6c-8e0b-2d4f6a8c0e13"
    }
  }
}