API: visão geral

A API pública do Ravisign permite que o seu sistema crie envelopes, acompanhe as assinaturas, baixe a via final e receba avisos por webhook, sem abrir o painel. Um ERP, um CRM ou um sistema de atendimento pode, por exemplo, gerar o contrato de um cliente novo e mandá-lo para assinatura no mesmo instante em que a venda é registrada. O ChatISP usa esta mesma API.

Endereço e formato#

• Endereço base: https://ravisign.com.br/api/v1/<recurso>/<acao>, por exemplo https://ravisign.com.br/api/v1/envelopes/criar.
• Somente HTTPS. Respostas em JSON UTF-8, exceto o download de documento, que devolve o PDF.
• Toda resposta traz o cabeçalho X-Ravisign-Api-Versao: 1.
• Ações de escrita aceitam só POST. Ações de leitura aceitam GET (parâmetros na query string) ou POST.
• Envelopes e signatários são sempre referenciados pelo uuid (campos envelope_uuid e signatario_uuid); modelos e webhooks, pelo id numérico.
• Campos desconhecidos na entrada são ignorados.

Autenticação#

Cada requisição leva uma chave de API no cabeçalho Authorization:

Authorization: Bearer rsg_0123456789abcdef0123456789abcdef0123456789abcdef

• A chave começa com rsg_ e é criada no painel, em Configurações > Chaves de API.
• Ela é mostrada uma única vez, na criação. O Ravisign guarda só uma impressão irreversível da chave: se ela se perder, revogue e crie outra.
• A chave pertence a uma conta. Tudo o que ela cria e enxerga é dessa conta; um envelope de outra conta responde 404, como se não existisse.
• A conta precisa estar ativa (ou em período de teste válido) e com plano válido.

Atenção a chave dá acesso aos documentos da sua conta. Nunca a coloque em código que roda no navegador ou no aplicativo do cliente, nem em repositório de código. Use-a só no servidor.

Sem a chave, a resposta 401 traz WWW-Authenticate: Bearer realm="Ravisign"; com chave recusada, também error="invalid_token".

Escopos#

Cada chave tem escopos, escolhidos na criação. Uma ação fora dos escopos da chave responde 403 escopo_insuficiente. Dê a cada integração só os escopos de que ela precisa.

As ações de signatário (link e código) exigem envelopes.escrever porque dão acesso à assinatura de outra pessoa.

Como enviar os parâmetros#

• GET: parâmetros na query string (?envelope_uuid=...&limite=20). Num POST, a query string também vale; se o mesmo campo vier nos dois, vale o do corpo.
• POST com Content-Type: application/json: objeto JSON no corpo (recomendado). Corpo que não é um objeto JSON válido responde 400 json_invalido.
• POST como formulário (application/x-www-form-urlencoded) ou multipart/form-data: listas e objetos (como signatarios, variaveis e eventos) vão como texto JSON no campo. O envio do PDF como arquivo (campo arquivo) exige multipart/form-data.
• Verdadeiro ou falso: true/false, 1/0, sim/nao (também yes/no, si/no).
• Datas na entrada: ISO 8601. Aceita só a data (2026-10-31), data e hora (2026-10-31T18:00:00) e data e hora com fuso (2026-10-31T18:00:00-03:00 ou 2026-10-31T21:00:00Z). Sem fuso, vale o fuso da conta.
• uuid aceita maiúsculas ou minúsculas.

Formato das respostas#

Sucesso: HTTP 200 e "ok": true, com os dados ao lado:

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

• Datas em ISO 8601 no fuso da conta (2026-10-09T20:28:25-03:00). Os eventos da trilha de auditoria usam UTC com microssegundos (2026-10-09T23:28:25.619105Z), que é como a trilha é registrada.
• Listas paginadas trazem paginacao: { "pagina": 1, "limite": 50, "total": 3, "paginas": 1 }. Parâmetros pagina (1 em diante) e limite (1 a 100, padrão 50).
• Dados pessoais saem mascarados: e-mail m***@cliente.com.br, telefone ***4321. CPF e CNPJ nunca saem. Motivo de recusa e de cancelamento, IP e navegador de quem assinou também não saem pela API.

Erros têm formato próprio, descrito em Formato de erros.

Cota por minuto#

Cada chave tem uma cota de requisições por minuto: o padrão é 60, configurável no painel até 600. A contagem é por minuto do relógio e começa depois que a chave e a conta são aceitas; dali em diante toda resposta, inclusive de erro, traz:

Acima da cota a resposta é 429 cota_excedida, com o cabeçalho Retry-After em segundos. Requisições recusadas pela cota não contam. Respeite o Retry-After antes de repetir e prefira webhooks a consultas repetidas.

Primeiro teste: situação da conta#

Nos exemplos desta documentação, a chave está na variável de ambiente RAVISIGN_CHAVE:

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

A ação conta/situacao (GET, escopo conta.ler) devolve a situação da conta, o plano, o uso do mês e os dados da chave usada. É um bom primeiro teste da integração:

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 da conta: teste ou ativa (nas demais, as requisições são recusadas com 403). teste_ate só vem no período de teste.

Próximos passos#

• Envelopes: criar, enviar, consultar, lembrar e cancelar.
• Documentos e modelos: baixar o original e a via final, usar modelos.
• Signatários: link de assinatura e código de confirmação no seu próprio canal.
• Webhooks: avisos de eventos com assinatura HMAC.