Envelopes in the API

This page describes the actions that create and follow envelopes: envelopes/criar, enviar, detalhe, listar, eventos, lembrar and cancelar. The concepts (roles, order, deadline, statuses) are in Concepts.

In the examples, the key is in the RAVISIGN_CHAVE environment variable and the responses were shortened where indicated:

BASH

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

envelopes/criar#

POST, scope envelopes.escrever. Creates an envelope and, with enviar: true, sends it to the signers right away. Each envelope created counts toward the plan's monthly limit (402 plano_limite when it is used up).

The document comes in ONE of these forms (none: 400 parametro_obrigatorio in the documento field; more than one: 400 parametro_invalido in the documento field):

Form	Fields
PDF in base64	`pdf_base64`: the PDF encoded in base64 (up to 20 MB of PDF, about 27 MB in base64)
File upload	`arquivo`: the PDF sent as `multipart/form-data` (up to 20 MB)
Template	`modelo_id` + `variaveis` (object `{ "chave": "valor" }`, only for templates of type `html`; for these, the PDF is generated right afterwards, in the background)

Other fields:

Field	Required	Description
`titulo`	yes	up to 190 characters; also names the document (for uploads, the name of the uploaded file applies)
`signatarios`	yes	list of 1 to 50 signers (table below); at least one who is not an observer
`mensagem`	no	invitation text, up to 2000 characters
`ordem`	no	`paralela` (default: everyone signs at the same time) or `sequencial` (one group at a time, by each signer's `ordem`; without `ordem`, the position in the list applies)
`nivel`	no	`avancada` (default) or `simples`
`idioma`	no	`pt`, `en` or `es`; default: account language
`expira_em`	no	deadline date and time (from 1 hour to 365 days from now)
`prazo_dias`	no	alternative to `expira_em`: days until expiration (1 to 365; account default: 30)
`lembrete_a_cada_horas`	no	automatic email reminder to those who have not signed yet (0 turns it off; up to 720; account default: 48)
`referencia_externa`	no	your identifier (order, contract, ticket), up to 190 characters; filterable in `listar`
`enviar`	no	`true` sends immediately; `false` (default) leaves it as a draft for `envelopes/enviar`

Each signer:

Field	Required	Description
`nome`	yes	full name, up to 190 characters
`email`	depending on the channel	required, except on the `conversa` channel
`telefone`	no	with area code (and country code, if outside Brazil); when provided, it must be valid
`cpf_cnpj`	no	validated by its check digits; recorded on the manifest, never returned by the API
`papel`	no	`signatario` (default), `testemunha`, `aprovador` or `observador` (follows along, does not sign)
`ordem`	no	position in the sequential order, from 1 to 50 (same number = they sign together)
`canal_otp`	no	confirmation code channel: `email` or `conversa` (default `conversa` in accounts that come from ChatISP; in the others, the default channel configured in the account, initially `email`)
`idioma`	no	language of the page and the emails for this signer
`origem_conversa`	no	object with up to 10 key and value pairs that identify the source conversation (example: `conversa_id`, `conexao`, `protocolo`); it goes into the trail without personal data fields

With 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 for accounts that come from ChatISP, api for the others.
hash_original: SHA-256 of the PDF sent. Keep it: it is the proof of which document was signed.
link_disponivel: the signer can now open the signing link (envelope sent and, in the sequential order, their turn).
On the email channel, the invitation goes out in the background right after sending; the signer becomes notificado (with notificado_em) when the email goes out. On the conversa channel, the integrator delivers the invitation, and the signer is already notificado when the envelope is sent.

With file upload (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

The response has the same format; the document name is the name of the uploaded file.

With a template:

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 }
        }
    }
}

(shortened response) With a template of type html, the PDF is generated right after the response: documento.pendente is true and the envelope remains rascunho until the PDF is ready. With enviar: true, sending happens automatically at that moment (the envelope.enviado webhook notifies you); with enviar: false, call envelopes/enviar after pendente becomes false. A template of type pdf behaves like sending the PDF: nothing is left pending.

Variable values are inserted as text (without HTML), up to 5000 characters each. Variable errors point to the variaveis.<chave> field: 400 modelo_variavel_faltando (required variable missing or empty) and 400 valor_invalido (value that is not text or is too long).

envelopes/enviar#

POST, scope envelopes.escrever. Parameter envelope_uuid. Sends a draft whose PDF is already ready. Returns the complete envelope (format of 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" } }

(shortened response) Errors: 409 situacao_invalida (not a draft), 409 documento_pendente (template PDF still being prepared), 400 prazo_invalido in the expira_em field (the draft expires in less than 1 hour: create another envelope).

envelopes/detalhe#

GET, scope envelopes.ler. Parameter envelope_uuid. Complete envelope (format of criar) plus summarized eventos (type, date and signer).

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 }
        ]
    }
}

(shortened response)

envelopes/listar#

GET, scope envelopes.ler. The account's envelopes, from newest to oldest, without signers or document (use detalhe for that). Optional filters:

Parameter	Description
`situacao`	one or more statuses separated by commas (`enviado,em_andamento`) or a JSON list
`referencia_externa`	exact match
`criado_de`, `criado_ate`	creation period; a date only in `criado_ate` covers the whole day
`pagina`, `limite`	pagination (limit from 1 to 100, default 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, scope envelopes.ler. Parameter envelope_uuid. The envelope's audit trail, in order, with the data of each event and the chaining hash (each event seals the previous one). Personal data, IP and browser are not returned here.

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"
        }
    ]
}

(shortened response; the event types are in the Reference)

envelopes/lembrar#

POST, scope envelopes.escrever. Parameter envelope_uuid. Resends the invitation by email to those whose turn it is and who have not responded yet. Anyone who received a reminder in the last hour is skipped (counted in ignorados); signers on the conversation channel do not receive email (the reminder in the conversation is up to the integrator).

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 }

Only for enviado or em_andamento envelopes (otherwise, 409 situacao_invalida; already expired, 409 envelope_vencido).

envelopes/cancelar#

POST, scope envelopes.escrever. Parameters envelope_uuid and motivo (required, up to 500 characters; it is recorded and not returned by the API). Cancels a draft, sent or in-progress envelope; a canceled envelope still counts toward the monthly limit. The envelope.cancelado webhook is only emitted for envelopes that had already been sent.

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"
    }
}

(shortened response) Errors: 400 motivo_obrigatorio (empty or longer than 500 characters), 409 situacao_invalida (already completed, declined, expired or canceled).

Tip instead of querying envelopes/detalhe repeatedly to find out whether an envelope was signed, register a webhook with the envelope.concluido event.

Did not find what you were looking for?

Contact Ravi Systems support at the e-mail below.

contato@ravisystems.com.br