API: overview

The Ravisign public API lets your system create envelopes, follow signatures, download the final copy and receive webhook notifications, without opening the panel. An ERP, a CRM or a customer service system can, for example, generate the contract for a new customer and send it for signature at the very moment the sale is recorded. ChatISP uses this same API.

Address and format#

• Base address: https://ravisign.com.br/api/v1/<recurso>/<acao>, for example https://ravisign.com.br/api/v1/envelopes/criar.
• HTTPS only. Responses in UTF-8 JSON, except document download, which returns the PDF.
• Every response includes the X-Ravisign-Api-Versao: 1 header.
• Write actions accept only POST. Read actions accept GET (parameters in the query string) or POST.
• Envelopes and signers are always referenced by uuid (fields envelope_uuid and signatario_uuid); templates and webhooks, by numeric id.
• Unknown input fields are ignored.

Authentication#

Each request carries an API key in the Authorization header:

Authorization: Bearer rsg_0123456789abcdef0123456789abcdef0123456789abcdef

• The key starts with rsg_ and is created in the panel, in Settings > API keys.
• It is shown only once, at creation. Ravisign stores only an irreversible fingerprint of the key: if it is lost, revoke it and create another one.
• The key belongs to one account. Everything it creates and sees belongs to that account; an envelope from another account responds 404, as if it did not exist.
• The account must be active (or in a valid trial period) and have a valid plan.

Warning the key gives access to your account's documents. Never put it in code that runs in the browser or in the customer's app, or in a code repository. Use it only on the server.

Without the key, the 401 response includes WWW-Authenticate: Bearer realm="Ravisign"; with a rejected key, also error="invalid_token".

Scopes#

Each key has scopes, chosen at creation. An action outside the key's scopes responds 403 escopo_insuficiente. Give each integration only the scopes it needs.

Signer actions (link and code) require envelopes.escrever because they give access to another person's signature.

How to send parameters#

• GET: parameters in the query string (?envelope_uuid=...&limite=20). In a POST, the query string also works; if the same field comes in both, the one in the body prevails.
• POST with Content-Type: application/json: JSON object in the body (recommended). A body that is not a valid JSON object responds 400 json_invalido.
• POST as a form (application/x-www-form-urlencoded) or multipart/form-data: lists and objects (such as signatarios, variaveis and eventos) go as JSON text in the field. Sending the PDF as a file (field arquivo) requires multipart/form-data.
• True or false: true/false, 1/0, sim/nao (also yes/no, si/no).
• Input dates: ISO 8601. Accepts date only (2026-10-31), date and time (2026-10-31T18:00:00) and date and time with time zone (2026-10-31T18:00:00-03:00 or 2026-10-31T21:00:00Z). Without a time zone, the account time zone applies.
• uuid accepts uppercase or lowercase.

Response format#

Success: HTTP 200 and "ok": true, with the data alongside:

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

• Dates in ISO 8601 in the account time zone (2026-10-09T20:28:25-03:00). Audit trail events use UTC with microseconds (2026-10-09T23:28:25.619105Z), which is how the trail is recorded.
• Paginated lists include paginacao: { "pagina": 1, "limite": 50, "total": 3, "paginas": 1 }. Parameters pagina (1 onward) and limite (1 to 100, default 50).
• Personal data is returned masked: email m***@cliente.com.br, phone ***4321. CPF and CNPJ are never returned. The reason for refusal and cancellation, and the IP and browser of the person who signed, are not returned through the API either.

Errors have their own format, described in Error format.

Rate limit per minute#

Each key has a rate limit of requests per minute: the default is 60, configurable in the panel up to 600. Counting is per clock minute and starts after the key and the account are accepted; from then on every response, including errors, includes:

Above the limit the response is 429 cota_excedida, with the Retry-After header in seconds. Requests rejected by the rate limit do not count. Respect the Retry-After before retrying and prefer webhooks to repeated queries.

First test: account status#

In the examples in this documentation, the key is in the RAVISIGN_CHAVE environment variable:

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

The conta/situacao action (GET, scope conta.ler) returns the account status, the plan, the usage for the month and the details of the key used. It is a good first test of the integration:

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

Account situacao: teste or ativa (in any other status, requests are rejected with 403). teste_ate is only returned during the trial period.

Next steps#

• Envelopes: create, send, query, remind and cancel.
• Documents and templates: download the original and the final copy, use templates.
• Signers: signing link and confirmation code through your own channel.
• Webhooks: event notifications with HMAC signature.