Documentos e modelos

Esta página reúne as ações que trabalham com arquivos: listar e detalhar os modelos da conta (para criar envelopes a partir deles) e baixar o original ou a via final assinada de um envelope. Como os modelos são criados e versionados no painel, veja Modelos.

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

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

modelos/listar#

GET, escopo modelos.ler. Modelos de documento da conta (sem o conteúdo). tipo é html (texto com variáveis {{chave}}, preenchidas na criação do envelope) ou pdf (PDF fixo, sem variáveis). Parâmetros opcionais: busca (no nome ou na descrição), ativo (true padrão, false ou todos), pagina, limite.

curl -sS -G "$API/modelos/listar" -H "Authorization: Bearer $RAVISIGN_CHAVE" -d limite=20

{
    "ok": true,
    "modelos": [
        {
            "id": 1,
            "nome": "Contrato de adesão",
            "descricao": "",
            "tipo": "html",
            "variaveis": [
                { "chave": "cliente", "rotulo": "Nome do cliente", "obrigatoria": true },
                { "chave": "plano", "rotulo": "Plano", "obrigatoria": false }
            ],
            "versao": 1,
            "ativo": true,
            "criado_em": "2026-10-09T20:28:25-03:00",
            "atualizado_em": "2026-10-09T20:28:25-03:00"
        }
    ],
    "paginacao": { "pagina": 1, "limite": 20, "total": 1, "paginas": 1 }
}

modelos/detalhe#

GET, escopo modelos.ler. Parâmetro id. Mesmo formato do item da lista, mais o conteúdo html (nos modelos do tipo html).

curl -sS -G "$API/modelos/detalhe" -H "Authorization: Bearer $RAVISIGN_CHAVE" -d id=1

{
    "ok": true,
    "modelo": {
        "id": 1,
        "nome": "Contrato de adesão",
        "tipo": "html",
        "variaveis": [ { "chave": "cliente", "rotulo": "Nome do cliente", "obrigatoria": true } ],
        "versao": 1,
        "ativo": true,
        "html": "<p>Cliente: {{cliente}} | Plano: {{plano}}</p>"
    }
}

(resposta encurtada)

documentos/baixar#

GET, escopo documentos.ler. Parâmetros envelope_uuid e tipo: final (padrão: a via assinada, com o manifesto de assinaturas incorporado) ou original (o PDF como foi enviado). A resposta de sucesso é o próprio PDF (Content-Type: application/pdf, Content-Disposition: attachment com o nome do arquivo); erro continua em JSON.

curl -sS -G "$API/documentos/baixar" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -d envelope_uuid=157b650a-75e0-4eaa-a32c-b92b5a432ee4 -d tipo=final \
  -o "contrato-assinado.pdf" -w "%{http_code}\n"

200

Nome do arquivo: o nome do documento (documento.nome, que vem do título ou, no upload, do nome do arquivo enviado), com - assinado antes do .pdf na via final ("signed" e "firmado" em contas em inglês e espanhol). Erros: 409 arquivo_indisponivel (via final antes da conclusão), 409 documento_pendente (original de modelo ainda em preparação), 400 parametro_invalido no campo tipo. O manifesto de assinaturas vai dentro da via final, por isso documento.disponivel.manifesto vem false e tipo=manifesto responde 409 arquivo_indisponivel. Para conferir a integridade, compare o SHA-256 do arquivo baixado com hash_final ou hash_original do detalhe.

Criar um envelope a partir de um modelo#

Use modelo_id e variaveis em envelopes/criar. As chaves de variaveis são as mesmas devolvidas em modelos/detalhe. O exemplo completo está em Envelopes na API.

Nota a gestão de modelos pela API (criar e editar) está reservada para uma versão futura, com o escopo modelos.escrever. Hoje os modelos são criados no painel.