Ir para o conteúdo
Ravisign
PT EN ES
Entrar Criar conta

Envelopes na API

Esta página descreve as ações que criam e acompanham envelopes: envelopes/criar, enviar, detalhe, listar, eventos, lembrar e cancelar. Os conceitos (papéis, ordem, prazo, situações) estão em Conceitos.

Nos exemplos, a chave está na variável de ambiente RAVISIGN_CHAVE e as respostas foram encurtadas onde indicado:

BASH
export RAVISIGN_CHAVE="rsg_..."
API="https://ravisign.com.br/api/v1"

envelopes/criar#

POST, escopo envelopes.escrever. Cria um envelope e, com enviar: true, já o envia aos signatários. Cada envelope criado conta no limite mensal do plano (402 plano_limite quando esgotado).

O documento vem de UMA destas formas (nenhuma: 400 parametro_obrigatorio no campo documento; mais de uma: 400 parametro_invalido no campo documento):

Forma Campos
PDF em base64 pdf_base64: o PDF codificado em base64 (até 20 MB de PDF, cerca de 27 MB em base64)
Upload de arquivo arquivo: o PDF enviado em multipart/form-data (até 20 MB)
Modelo modelo_id + variaveis (objeto { "chave": "valor" }, só nos modelos do tipo html; nesses, o PDF é gerado em seguida, em segundo plano)

Demais campos:

Campo Obrigatório Descrição
titulo sim até 190 caracteres; também dá nome ao documento (no upload, vale o nome do arquivo enviado)
signatarios sim lista de 1 a 50 signatários (tabela abaixo); ao menos um que não seja observador
mensagem não texto do convite, até 2000 caracteres
ordem não paralela (padrão: todos assinam ao mesmo tempo) ou sequencial (um grupo por vez, pela ordem de cada signatário; sem ordem, vale a posição na lista)
nivel não avancada (padrão) ou simples
idioma não pt, en ou es; padrão: idioma da conta
expira_em não data e hora limite (de 1 hora a 365 dias a partir de agora)
prazo_dias não alternativa ao expira_em: dias até expirar (1 a 365; padrão da conta: 30)
lembrete_a_cada_horas não lembrete automático por e-mail a quem falta assinar (0 desliga; até 720; padrão da conta: 48)
referencia_externa não seu identificador (pedido, contrato, protocolo), até 190 caracteres; filtrável no listar
enviar não true envia já; false (padrão) deixa em rascunho para envelopes/enviar

Cada signatário:

Campo Obrigatório Descrição
nome sim nome completo, até 190 caracteres
email conforme o canal obrigatório, exceto no canal conversa
telefone não com DDD (e código do país, se for de fora do Brasil); quando informado, precisa ser válido
cpf_cnpj não validado pelos dígitos verificadores; registrado no manifesto, nunca devolvido pela API
papel não signatario (padrão), testemunha, aprovador ou observador (acompanha, não assina)
ordem não posição na ordem sequencial, de 1 a 50 (mesmo número = assinam juntos)
canal_otp não canal do código de confirmação: email ou conversa (padrão conversa em contas vindas do ChatISP; nas demais, o canal padrão configurado na conta, que de início é email)
idioma não idioma da página e dos e-mails desse signatário
origem_conversa não objeto com até 10 pares chave e valor que identificam a conversa de origem (exemplo: conversa_id, conexao, protocolo); vai para a trilha sem campos de dado pessoal

Com pdf_base64 (JSON):

BASH
curl -sS "$API/envelopes/criar" \
  -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "titulo": "Contrato de Fibra",
  "mensagem": "Assine, por favor.",
  "pdf_base64": "$(base64 -w0 contrato.pdf)",
  "signatarios": [
    { "nome": "Maria Souza", "telefone": "+55 11 98765-4321", "canal_otp": "conversa",
      "cpf_cnpj": "529.982.247-25", "origem_conversa": { "conversa_id": "8812" } },
    { "nome": "Carlos Lima", "email": "carlos@provedor.com.br", "papel": "testemunha", "canal_otp": "email" }
  ],
  "referencia_externa": "PEDIDO-1042",
  "prazo_dias": 7,
  "lembrete_a_cada_horas": 24,
  "enviar": true
}
EOF
JSON
{
    "ok": true,
    "envelope": {
        "uuid": "157b650a-75e0-4eaa-a32c-b92b5a432ee4",
        "titulo": "Contrato de Fibra",
        "mensagem": "Assine, por favor.",
        "situacao": "enviado",
        "ordem": "paralela",
        "nivel": "avancada",
        "idioma": "pt",
        "origem": "chatisp",
        "referencia_externa": "PEDIDO-1042",
        "expira_em": "2026-10-16T20:28:25-03:00",
        "lembrete_a_cada_horas": 24,
        "criado_em": "2026-10-09T20:28:25-03:00",
        "atualizado_em": "2026-10-09T20:28:25-03:00",
        "concluido_em": null,
        "cancelado_em": null,
        "total_signatarios": 2,
        "assinados": 0,
        "documento": {
            "nome": "Contrato de Fibra.pdf",
            "paginas": 1,
            "tamanho": 48213,
            "pendente": false,
            "hash_original": "2bcde2cdcc9404896632750d862110efa678490d6dcebea450fd5e66ff9e8089",
            "hash_final": null,
            "disponivel": { "original": true, "final": false, "manifesto": false }
        },
        "signatarios": [
            {
                "uuid": "7eb90fca-1488-4a17-84c4-0b01f4acb9f1",
                "nome": "Maria Souza",
                "email": null,
                "telefone": "***4321",
                "papel": "signatario",
                "ordem": 1,
                "canal_otp": "conversa",
                "situacao": "notificado",
                "link_disponivel": true,
                "notificado_em": "2026-10-09T20:28:25-03:00",
                "assinado_em": null,
                "recusado_em": null
            },
            {
                "uuid": "3d04a71b-34e1-4b22-95b7-b45caae80322",
                "nome": "Carlos Lima",
                "email": "c***@provedor.com.br",
                "telefone": null,
                "papel": "testemunha",
                "ordem": 1,
                "canal_otp": "email",
                "situacao": "pendente",
                "link_disponivel": true,
                "notificado_em": null,
                "assinado_em": null,
                "recusado_em": null
            }
        ]
    }
}
  • origem: chatisp para contas vindas do ChatISP, api para as demais.
  • hash_original: SHA-256 do PDF enviado. Guarde-o: é a prova de qual documento foi assinado.
  • link_disponivel: o signatário já pode abrir o link de assinatura (envelope enviado e, na ordem sequencial, a vez dele).
  • No canal email, o convite sai em segundo plano logo após o envio; o signatário passa a notificado (com notificado_em) quando o e-mail sai. No canal conversa, quem entrega o convite é o integrador, e o signatário já fica notificado no envio.

Com upload de arquivo (multipart):

BASH
curl -sS "$API/envelopes/criar" \
  -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -F titulo="Contrato de Fibra" \
  -F arquivo=@contrato.pdf \
  -F 'signatarios=[{"nome":"Maria Souza","email":"maria@cliente.com.br"}]' \
  -F enviar=true

A resposta tem o mesmo formato; o nome do documento é o nome do arquivo enviado.

Com modelo:

BASH
curl -sS "$API/envelopes/criar" \
  -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Adesão Fibra 500",
    "modelo_id": 1,
    "variaveis": { "cliente": "Ana Pereira", "plano": "Fibra 500" },
    "signatarios": [ { "nome": "Ana Pereira", "email": "ana@cliente.com.br" } ],
    "enviar": true
  }'
JSON
{
    "ok": true,
    "envelope": {
        "uuid": "46076565-92bc-4605-99e4-7d47464373f1",
        "titulo": "Adesão Fibra 500",
        "situacao": "rascunho",
        "documento": {
            "nome": "Adesão Fibra 500.pdf",
            "paginas": null,
            "tamanho": null,
            "pendente": true,
            "hash_original": null,
            "hash_final": null,
            "disponivel": { "original": false, "final": false, "manifesto": false }
        }
    }
}

(resposta encurtada) Com modelo do tipo html, o PDF é gerado logo depois da resposta: documento.pendente fica true e o envelope continua rascunho até o PDF ficar pronto. Com enviar: true, o envio acontece sozinho nesse momento (o webhook envelope.enviado avisa); com enviar: false, chame envelopes/enviar depois que pendente virar false. Modelo do tipo pdf se comporta como o envio do PDF: nada fica pendente.

Os valores das variáveis são inseridos como texto (sem HTML), até 5000 caracteres cada. Erros nas variáveis apontam o campo variaveis.<chave>: 400 modelo_variavel_faltando (obrigatória ausente ou vazia) e 400 valor_invalido (valor que não é texto ou longo demais).

envelopes/enviar#

POST, escopo envelopes.escrever. Parâmetro envelope_uuid. Envia um rascunho cujo PDF já está pronto. Devolve o envelope completo (formato do criar).

BASH
curl -sS "$API/envelopes/enviar" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -H "Content-Type: application/json" -d '{"envelope_uuid":"b0c9ce2f-e6b2-4395-af6e-336be8e320c1"}'
JSON
{ "ok": true, "envelope": { "uuid": "b0c9ce2f-e6b2-4395-af6e-336be8e320c1", "situacao": "enviado" } }

(resposta encurtada) Erros: 409 situacao_invalida (não é rascunho), 409 documento_pendente (PDF do modelo ainda em preparação), 400 prazo_invalido no campo expira_em (o rascunho vence em menos de 1 hora: crie outro envelope).

envelopes/detalhe#

GET, escopo envelopes.ler. Parâmetro envelope_uuid. Envelope completo (formato do criar) mais eventos resumidos (tipo, data e signatário).

BASH
curl -sS -G "$API/envelopes/detalhe" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -d envelope_uuid=157b650a-75e0-4eaa-a32c-b92b5a432ee4
JSON
{
    "ok": true,
    "envelope": {
        "uuid": "157b650a-75e0-4eaa-a32c-b92b5a432ee4",
        "situacao": "concluido",
        "concluido_em": "2026-10-09T20:31:02-03:00",
        "total_signatarios": 2,
        "assinados": 2,
        "documento": {
            "nome": "Contrato de Fibra.pdf",
            "hash_original": "2bcde2cdcc9404896632750d862110efa678490d6dcebea450fd5e66ff9e8089",
            "hash_final": "7ced225baf8e20d34cb09a713c4454a632f749ecf31645aa3a640e1660e2a880",
            "disponivel": { "original": true, "final": true, "manifesto": false }
        },
        "signatarios": [
            { "uuid": "7eb90fca-1488-4a17-84c4-0b01f4acb9f1", "nome": "Maria Souza", "situacao": "assinado",
              "assinado_em": "2026-10-09T20:30:11-03:00" }
        ],
        "eventos": [
            { "tipo": "envelope_criado", "ocorrido_em": "2026-10-09T23:28:25.619105Z", "signatario_uuid": null },
            { "tipo": "envelope_enviado", "ocorrido_em": "2026-10-09T23:28:25.619651Z", "signatario_uuid": null },
            { "tipo": "assinado", "ocorrido_em": "2026-10-09T23:30:11.648572Z", "signatario_uuid": "7eb90fca-1488-4a17-84c4-0b01f4acb9f1" },
            { "tipo": "concluido", "ocorrido_em": "2026-10-09T23:31:02.676083Z", "signatario_uuid": null }
        ]
    }
}

(resposta encurtada)

envelopes/listar#

GET, escopo envelopes.ler. Envelopes da conta, do mais recente para o mais antigo, sem signatários nem documento (use detalhe para isso). Filtros opcionais:

Parâmetro Descrição
situacao uma ou mais situações separadas por vírgula (enviado,em_andamento) ou lista JSON
referencia_externa igualdade exata
criado_de, criado_ate período de criação; só a data no criado_ate vale o dia inteiro
pagina, limite paginação (limite de 1 a 100, padrão 50)
BASH
curl -sS -G "$API/envelopes/listar" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  --data-urlencode "situacao=enviado,em_andamento" -d criado_de=2026-10-01 -d limite=20
JSON
{
    "ok": true,
    "envelopes": [
        {
            "uuid": "157b650a-75e0-4eaa-a32c-b92b5a432ee4",
            "titulo": "Contrato de Fibra",
            "mensagem": "Assine, por favor.",
            "situacao": "em_andamento",
            "ordem": "paralela",
            "nivel": "avancada",
            "idioma": "pt",
            "origem": "chatisp",
            "referencia_externa": "PEDIDO-1042",
            "expira_em": "2026-10-16T20:28:25-03:00",
            "lembrete_a_cada_horas": 24,
            "criado_em": "2026-10-09T20:28:25-03:00",
            "atualizado_em": "2026-10-09T20:30:11-03:00",
            "concluido_em": null,
            "cancelado_em": null,
            "total_signatarios": 2,
            "assinados": 1
        }
    ],
    "paginacao": { "pagina": 1, "limite": 20, "total": 1, "paginas": 1 }
}

envelopes/eventos#

GET, escopo envelopes.ler. Parâmetro envelope_uuid. A trilha de auditoria do envelope, em ordem, com os dados de cada evento e o hash do encadeamento (cada evento sela o anterior). Dados pessoais, IP e navegador não saem por aqui.

BASH
curl -sS -G "$API/envelopes/eventos" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -d envelope_uuid=157b650a-75e0-4eaa-a32c-b92b5a432ee4
JSON
{
    "ok": true,
    "envelope_uuid": "157b650a-75e0-4eaa-a32c-b92b5a432ee4",
    "eventos": [
        {
            "tipo": "otp_enviado",
            "ocorrido_em": "2026-10-09T23:28:25.627905Z",
            "signatario_uuid": "7eb90fca-1488-4a17-84c4-0b01f4acb9f1",
            "dados": {
                "canal": "conversa",
                "conversa": { "conversa_id": "8812" },
                "origem": "integrador",
                "validade_minutos": 30
            },
            "hash": "97d980c7d800fa02ddbc2362f9f03eb29612b8bde7f3e21707423ef6a409b508"
        },
        {
            "tipo": "concluido",
            "ocorrido_em": "2026-10-09T23:31:02.676083Z",
            "signatario_uuid": null,
            "dados": {
                "hash_final": "7ced225baf8e20d34cb09a713c4454a632f749ecf31645aa3a640e1660e2a880",
                "total_assinaturas": 2
            },
            "hash": "5b2832551f5e07897051330d6c2101526ad37151b3119327f4552a0c846a9bba"
        }
    ]
}

(resposta encurtada; os tipos de evento estão na Referência)

envelopes/lembrar#

POST, escopo envelopes.escrever. Parâmetro envelope_uuid. Reenvia o convite por e-mail a quem está na vez e ainda não respondeu. Quem recebeu lembrete na última hora fica de fora (conta em ignorados); signatários do canal conversa não recebem e-mail (o lembrete na conversa é do integrador).

BASH
curl -sS "$API/envelopes/lembrar" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -H "Content-Type: application/json" -d '{"envelope_uuid":"157b650a-75e0-4eaa-a32c-b92b5a432ee4"}'
JSON
{ "ok": true, "envelope_uuid": "157b650a-75e0-4eaa-a32c-b92b5a432ee4", "enfileirados": 1, "ignorados": 0 }

Só para envelopes enviado ou em_andamento (fora disso, 409 situacao_invalida; já vencido, 409 envelope_vencido).

envelopes/cancelar#

POST, escopo envelopes.escrever. Parâmetros envelope_uuid e motivo (obrigatório, até 500 caracteres; fica registrado, não volta pela API). Cancela rascunho, enviado ou em andamento; o envelope cancelado continua contando no limite do mês. O webhook envelope.cancelado só é emitido para envelopes que já tinham sido enviados.

BASH
curl -sS "$API/envelopes/cancelar" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"envelope_uuid":"b0c9ce2f-e6b2-4395-af6e-336be8e320c1","motivo":"Cliente desistiu da instalação"}'
JSON
{
    "ok": true,
    "envelope": {
        "uuid": "b0c9ce2f-e6b2-4395-af6e-336be8e320c1",
        "situacao": "cancelado",
        "cancelado_em": "2026-10-09T20:40:00-03:00"
    }
}

(resposta encurtada) Erros: 400 motivo_obrigatorio (vazio ou com mais de 500 caracteres), 409 situacao_invalida (já concluído, recusado, expirado ou cancelado).

Dica em vez de consultar envelopes/detalhe repetidamente para saber se um envelope foi assinado, cadastre um webhook com o evento envelope.concluido.

Não encontrou o que procurava?

Fale com o suporte da Ravi Systems pelo e-mail abaixo.

contato@ravisystems.com.br