Signers

The actions on this page are for those who deliver the invitation and the confirmation code through their own channel, as ChatISP does in the WhatsApp conversation. If your signers receive everything by email, Ravisign takes care of it on its own and you do not need them.

All of them require the envelopes.escrever scope, because they give access to another person's signature.

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

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

signatarios/link#

GET, scope envelopes.escrever. Parameter signatario_uuid. The signer's signing link, for those who deliver the invitation through their own channel (ChatISP sends it in the conversation). The link is personal: do not share it with anyone else.

curl -sS -G "$API/signatarios/link" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -d signatario_uuid=7eb90fca-1488-4a17-84c4-0b01f4acb9f1

{
    "ok": true,
    "signatario_uuid": "7eb90fca-1488-4a17-84c4-0b01f4acb9f1",
    "envelope_uuid": "157b650a-75e0-4eaa-a32c-b92b5a432ee4",
    "link": "https://ravisign.com.br/assinar.php?t=yEJ0y3ENQjLq3jTSy9Lx-obvgnQFa05o0mHtOP7C7m4",
    "situacao": "notificado",
    "envelope_situacao": "enviado"
}

Error 409 signatario_fora_da_vez when there is no link yet (draft, sequential order before the signer's turn, or observer).

signatarios/otp_gerar#

POST, scope envelopes.escrever. Only for signers on the conversa channel. Generates the 6-digit confirmation code (valid for 30 minutes) and returns it so that the integrator can deliver it in the conversation. Parameters signatario_uuid and, optionally, origem_conversa (object that identifies the conversation where the code will be delivered; it goes into the trail).

curl -sS "$API/signatarios/otp_gerar" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"signatario_uuid":"7eb90fca-1488-4a17-84c4-0b01f4acb9f1","origem_conversa":{"conversa_id":"8812"}}'

{
    "ok": true,
    "signatario_uuid": "7eb90fca-1488-4a17-84c4-0b01f4acb9f1",
    "codigo": "473334",
    "canal": "conversa",
    "validade_minutos": 30,
    "expira_em": "2026-10-09T20:58:25-03:00"
}

• A new code invalidates the previous one. At most 4 codes per hour for the same signer (429 otp_reenvio_limite); each code allows 5 attempts.
• Errors: 409 canal_indisponivel (signer on another channel), 409 envelope_encerrado, envelope_vencido, situacao_invalida (already signed or declined) and signatario_fora_da_vez.

signatarios/otp_pendente#

GET, scope envelopes.escrever. Parameter signatario_uuid. The conversation channel code that is still valid (generated through the API or requested by the signer on the page), for those who do not use webhooks.

curl -sS -G "$API/signatarios/otp_pendente" -H "Authorization: Bearer $RAVISIGN_CHAVE" \
  -d signatario_uuid=7eb90fca-1488-4a17-84c4-0b01f4acb9f1

{
    "ok": true,
    "signatario_uuid": "7eb90fca-1488-4a17-84c4-0b01f4acb9f1",
    "pendente": true,
    "codigo": "473334",
    "expira_em": "2026-10-09T20:58:25-03:00",
    "segundos_restantes": 1800
}

With no valid code: { "ok": true, "signatario_uuid": "...", "pendente": false }.

Warning the link and the code give access to the signer's signature. Deliver them only to that person, do not log them and do not keep the code after it has been delivered.