API: visión general

La API pública de Ravisign permite que su sistema cree sobres, siga las firmas, descargue la copia final y reciba avisos por webhook, sin abrir el panel. Un ERP, un CRM o un sistema de atención puede, por ejemplo, generar el contrato de un cliente nuevo y enviarlo para firma en el mismo instante en que se registra la venta. ChatISP usa esta misma API.

Dirección y formato#

• Dirección base: https://ravisign.com.br/api/v1/<recurso>/<acao>, por ejemplo https://ravisign.com.br/api/v1/envelopes/criar.
• Solo HTTPS. Respuestas en JSON UTF-8, excepto la descarga de documento, que devuelve el PDF.
• Toda respuesta incluye el encabezado X-Ravisign-Api-Versao: 1.
• Las acciones de escritura aceptan solo POST. Las acciones de lectura aceptan GET (parámetros en la query string) o POST.
• Los sobres y los firmantes siempre se referencian por el uuid (campos envelope_uuid y signatario_uuid); las plantillas y los webhooks, por el id numérico.
• Los campos desconocidos en la entrada se ignoran.

Autenticación#

Cada solicitud lleva una clave de API en el encabezado Authorization:

Authorization: Bearer rsg_0123456789abcdef0123456789abcdef0123456789abcdef

• La clave comienza con rsg_ y se crea en el panel, en Configuración > Claves de API.
• Se muestra una única vez, al crearla. Ravisign guarda solo una huella irreversible de la clave: si se pierde, revóquela y cree otra.
• La clave pertenece a una cuenta. Todo lo que crea y ve es de esa cuenta; un sobre de otra cuenta responde 404, como si no existiera.
• La cuenta debe estar activa (o en un período de prueba válido) y con un plan válido.

Atención la clave da acceso a los documentos de su cuenta. Nunca la coloque en código que se ejecute en el navegador o en la aplicación del cliente, ni en un repositorio de código. Úsela solo en el servidor.

Sin la clave, la respuesta 401 incluye WWW-Authenticate: Bearer realm="Ravisign"; con una clave rechazada, también error="invalid_token".

Alcances#

Cada clave tiene alcances (scopes), elegidos al crearla. Una acción fuera de los alcances de la clave responde 403 escopo_insuficiente. Asigne a cada integración solo los alcances que necesita.

Las acciones de firmante (enlace y código) exigen envelopes.escrever porque dan acceso a la firma de otra persona.

Cómo enviar los parámetros#

• GET: parámetros en la query string (?envelope_uuid=...&limite=20). En un POST, la query string también vale; si el mismo campo viene en ambos, vale el del cuerpo.
• POST con Content-Type: application/json: objeto JSON en el cuerpo (recomendado). Un cuerpo que no sea un objeto JSON válido responde 400 json_invalido.
• POST como formulario (application/x-www-form-urlencoded) o multipart/form-data: las listas y los objetos (como signatarios, variaveis y eventos) van como texto JSON en el campo. El envío del PDF como archivo (campo arquivo) exige multipart/form-data.
• Verdadero o falso: true/false, 1/0, sim/nao (también yes/no, si/no).
• Fechas en la entrada: ISO 8601. Acepta solo la fecha (2026-10-31), fecha y hora (2026-10-31T18:00:00) y fecha y hora con zona horaria (2026-10-31T18:00:00-03:00 o 2026-10-31T21:00:00Z). Sin zona horaria, vale la zona horaria de la cuenta.
• uuid acepta mayúsculas o minúsculas.

Formato de las respuestas#

Éxito: HTTP 200 y "ok": true, con los datos al lado:

{ "ok": true, "envelope": { "uuid": "157b650a-75e0-4eaa-a32c-b92b5a432ee4", "situacao": "enviado" } }

• Fechas en ISO 8601 en la zona horaria de la cuenta (2026-10-09T20:28:25-03:00). Los eventos del registro de auditoría usan UTC con microsegundos (2026-10-09T23:28:25.619105Z), que es como se guarda el registro de auditoría.
• Las listas paginadas incluyen paginacao: { "pagina": 1, "limite": 50, "total": 3, "paginas": 1 }. Parámetros pagina (desde 1) y limite (1 a 100, 50 de forma predeterminada).
• Los datos personales salen enmascarados: correo electrónico m***@cliente.com.br, teléfono ***4321. El CPF y el CNPJ nunca salen. El motivo del rechazo y de la cancelación, la IP y el navegador de quien firmó tampoco salen por la API.

Los errores tienen un formato propio, descrito en Formato de errores.

Cuota por minuto#

Cada clave tiene una cuota de solicitudes por minuto: el valor predeterminado es 60, configurable en el panel hasta 600. El conteo es por minuto del reloj y comienza después de que la clave y la cuenta son aceptadas; a partir de ahí, toda respuesta, incluso de error, incluye:

Por encima de la cuota la respuesta es 429 cota_excedida, con el encabezado Retry-After en segundos. Las solicitudes rechazadas por la cuota no cuentan. Respete el Retry-After antes de repetir y prefiera los webhooks a las consultas repetidas.

Primera prueba: estado de la cuenta#

En los ejemplos de esta documentación, la clave está en la variable de entorno RAVISIGN_CHAVE:

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

La acción conta/situacao (GET, alcance conta.ler) devuelve el estado de la cuenta, el plan, el uso del mes y los datos de la clave usada. Es una buena primera prueba de la integración:

curl -sS "$API/conta/situacao" -H "Authorization: Bearer $RAVISIGN_CHAVE"

{
    "ok": true,
    "conta": {
        "nome": "Provedor Exemplo",
        "situacao": "teste",
        "teste_ate": "2026-10-19T20:28:25-03:00",
        "idioma": "pt",
        "fuso": "America/Sao_Paulo"
    },
    "plano": { "codigo": "teste", "nome": "Teste", "envelopes_mes": 20 },
    "uso": { "ano_mes": "2026-10", "envelopes_criados": 0, "envelopes_concluidos": 0, "envelopes_restantes": 20 },
    "chave": {
        "nome": "Integração ChatISP",
        "prefixo": "rsg_f81d",
        "escopos": ["envelopes.escrever", "envelopes.ler", "modelos.ler", "documentos.ler", "conta.ler"],
        "cota_minuto": 120
    }
}

situacao de la cuenta: teste o ativa (en los demás casos, las solicitudes se rechazan con 403). teste_ate solo viene en el período de prueba.

Próximos pasos#

• Sobres: crear, enviar, consultar, recordar y cancelar.
• Documentos y plantillas: descargar el original y la copia final, usar plantillas.
• Firmantes: enlace de firma y código de confirmación en su propio canal.
• Webhooks: avisos de eventos con firma HMAC.