Ir al contenido
Ravisign
PT EN ES
Ingresar Crear cuenta

Sobres en la API

Esta página describe las acciones que crean y siguen sobres: envelopes/criar, enviar, detalhe, listar, eventos, lembrar y cancelar. Los conceptos (roles, orden, plazo, estados) están en Conceptos.

En los ejemplos, la clave está en la variable de entorno RAVISIGN_CHAVE y las respuestas se acortaron donde se indica:

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

envelopes/criar#

POST, alcance envelopes.escrever. Crea un sobre y, con enviar: true, lo envía de inmediato a los firmantes. Cada sobre creado cuenta en el límite mensual del plan (402 plano_limite cuando se agota).

El documento viene de UNA de estas formas (ninguna: 400 parametro_obrigatorio en el campo documento; más de una: 400 parametro_invalido en el campo documento):

Forma Campos
PDF en base64 pdf_base64: el PDF codificado en base64 (hasta 20 MB de PDF, cerca de 27 MB en base64)
Carga de archivo arquivo: el PDF enviado en multipart/form-data (hasta 20 MB)
Plantilla modelo_id + variaveis (objeto { "chave": "valor" }, solo en las plantillas del tipo html; en ellas, el PDF se genera a continuación, en segundo plano)

Demás campos:

Campo Obligatorio Descripción
titulo sí hasta 190 caracteres; también da nombre al documento (en la carga, vale el nombre del archivo enviado)
signatarios sí lista de 1 a 50 firmantes (tabla siguiente); al menos uno que no sea observador
mensagem no texto de la invitación, hasta 2000 caracteres
ordem no paralela (predeterminado: todos firman al mismo tiempo) o sequencial (un grupo a la vez, según el ordem de cada firmante; sin ordem, vale la posición en la lista)
nivel no avancada (predeterminado) o simples
idioma no pt, en o es; predeterminado: idioma de la cuenta
expira_em no fecha y hora límite (de 1 hora a 365 días a partir de ahora)
prazo_dias no alternativa a expira_em: días hasta expirar (1 a 365; predeterminado de la cuenta: 30)
lembrete_a_cada_horas no recordatorio automático por correo electrónico a quien falta firmar (0 lo desactiva; hasta 720; predeterminado de la cuenta: 48)
referencia_externa no su identificador (pedido, contrato, protocolo), hasta 190 caracteres; filtrable en listar
enviar no true lo envía de inmediato; false (predeterminado) lo deja en borrador para envelopes/enviar

Cada firmante:

Campo Obligatorio Descripción
nome sí nombre completo, hasta 190 caracteres
email según el canal obligatorio, excepto en el canal conversa
telefone no con código de área (y código de país, si es de fuera de Brasil); cuando se informa, debe ser válido
cpf_cnpj no validado por los dígitos verificadores; registrado en el manifiesto, nunca devuelto por la API
papel no signatario (predeterminado), testemunha, aprovador u observador (acompaña, no firma)
ordem no posición en el orden secuencial, de 1 a 50 (mismo número = firman juntos)
canal_otp no canal del código de confirmación: email o conversa (predeterminado conversa en cuentas provenientes de ChatISP; en las demás, el canal predeterminado configurado en la cuenta, que inicialmente es email)
idioma no idioma de la página y de los correos de ese firmante
origem_conversa no objeto con hasta 10 pares de clave y valor que identifican la conversación de origen (ejemplo: conversa_id, conexao, protocolo); va al registro de auditoría sin campos de datos personales

Con 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 cuentas provenientes de ChatISP, api para las demás.
  • hash_original: SHA-256 del PDF enviado. Guárdelo: es la prueba de qué documento se firmó.
  • link_disponivel: el firmante ya puede abrir el enlace de firma (sobre enviado y, en el orden secuencial, su turno).
  • En el canal email, la invitación sale en segundo plano justo después del envío; el firmante pasa a notificado (con notificado_em) cuando sale el correo. En el canal conversa, quien entrega la invitación es el integrador, y el firmante ya queda notificado en el envío.

Con carga de archivo (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

La respuesta tiene el mismo formato; el nombre del documento es el nombre del archivo enviado.

Con plantilla:

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

(respuesta acortada) Con una plantilla del tipo html, el PDF se genera justo después de la respuesta: documento.pendente queda true y el sobre sigue en rascunho hasta que el PDF esté listo. Con enviar: true, el envío ocurre por sí solo en ese momento (el webhook envelope.enviado lo avisa); con enviar: false, llame a envelopes/enviar después de que pendente pase a false. Una plantilla del tipo pdf se comporta como el envío del PDF: nada queda pendiente.

Los valores de las variables se insertan como texto (sin HTML), hasta 5000 caracteres cada uno. Los errores en las variables señalan el campo variaveis.<chave>: 400 modelo_variavel_faltando (obligatoria ausente o vacía) y 400 valor_invalido (valor que no es texto o demasiado largo).

envelopes/enviar#

POST, alcance envelopes.escrever. Parámetro envelope_uuid. Envía un borrador cuyo PDF ya está listo. Devuelve el sobre completo (formato de 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" } }

(respuesta acortada) Errores: 409 situacao_invalida (no es un borrador), 409 documento_pendente (PDF de la plantilla todavía en preparación), 400 prazo_invalido en el campo expira_em (el borrador vence en menos de 1 hora: cree otro sobre).

envelopes/detalhe#

GET, alcance envelopes.ler. Parámetro envelope_uuid. Sobre completo (formato de criar) más eventos resumidos (tipo, fecha y firmante).

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

(respuesta acortada)

envelopes/listar#

GET, alcance envelopes.ler. Sobres de la cuenta, del más reciente al más antiguo, sin firmantes ni documento (use detalhe para eso). Filtros opcionales:

Parámetro Descripción
situacao uno o más estados separados por comas (enviado,em_andamento) o lista JSON
referencia_externa igualdad exacta
criado_de, criado_ate período de creación; solo la fecha en criado_ate vale por el día entero
pagina, limite paginación (límite de 1 a 100, 50 de forma predeterminada)
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, alcance envelopes.ler. Parámetro envelope_uuid. El registro de auditoría del sobre, en orden, con los datos de cada evento y el hash del encadenamiento (cada evento sella el anterior). Los datos personales, la IP y el navegador no salen por aquí.

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

(respuesta acortada; los tipos de evento están en la Referencia)

envelopes/lembrar#

POST, alcance envelopes.escrever. Parámetro envelope_uuid. Reenvía la invitación por correo electrónico a quien tiene el turno y todavía no respondió. Quien recibió un recordatorio en la última hora queda excluido (cuenta en ignorados); los firmantes del canal de conversación no reciben correo (el recordatorio en la conversación lo hace el 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 }

Solo para sobres enviado o em_andamento (fuera de eso, 409 situacao_invalida; ya vencido, 409 envelope_vencido).

envelopes/cancelar#

POST, alcance envelopes.escrever. Parámetros envelope_uuid y motivo (obligatorio, hasta 500 caracteres; queda registrado, no vuelve por la API). Cancela un borrador, enviado o en curso; el sobre cancelado sigue contando en el límite del mes. El webhook envelope.cancelado solo se emite para sobres que ya habían 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"
    }
}

(respuesta acortada) Errores: 400 motivo_obrigatorio (vacío o con más de 500 caracteres), 409 situacao_invalida (ya concluido, rechazado, expirado o cancelado).

Consejo en lugar de consultar envelopes/detalhe repetidamente para saber si un sobre fue firmado, registre un webhook con el evento envelope.concluido.

¿No encontró lo que buscaba?

Escriba al soporte de Ravi Systems al correo de abajo.

contato@ravisystems.com.br