Skip to main content

Jornadas (journeys)

Rota base v5/journeys.

A jornada é uma página guiada, em etapas, que o cliente final abre por um link para concluir uma ação que depende dele: ler e aceitar um termo de autorização, conferir o resumo de um empréstimo, aceitar os documentos e seguir para a assinatura eletrônica. O integrador gera a jornada pela API, recebe o link e o entrega ao cliente (a plataforma também pode enviar o convite por e-mail ou SMS). Tudo o que o cliente faz no link (aberturas, etapas, aceites, geolocalização, dispositivo) fica registrado na jornada e pode ser consultado depois como trilha de evidências.

O integrador não chama as rotas do link

A página do link é servida pela plataforma Semear e usa rotas públicas próprias, autenticadas apenas pelo token embutido no link. Essas rotas não fazem parte da API de integração e não estão documentadas aqui. Para o integrador, a jornada se resume a: gerar, entregar o link, acompanhar (consulta ou webhook do recurso de origem) e, se necessário, cancelar.

Autenticação​

Todos os endpoints exigem API Key (X-Api-Key) (ver Autenticação). Permissões do recurso "Jornada":

PermissãoEndpoints
AcessarGET /{id}, GET /current, GET /{id}/events, POST /search
GerarPOST /
CancelarPOST /{id}/cancel

A jornada de assinatura do empréstimo (POST /v5/loans/{loanId}/signature-requests/current/journeys) exige a permissão de edição de empréstimos. Ver Autenticação.

Rotas implementadas​

RotaVerboResumo
/v5/journeysPOSTGera uma jornada para um registro de origem e devolve o link.
/v5/journeys/{id}GETBusca a jornada, com etapas, documentos, respostas e acessos.
/v5/journeys/currentGETBusca a jornada mais recente de um tipo para um registro de origem.
/v5/journeys/{id}/eventsGETLista a trilha de eventos da jornada.
/v5/journeys/{id}/cancelPOSTCancela uma jornada em aberto.
/v5/journeys/searchPOSTBusca paginada com filtros.
/v5/journeys/filtersGETCampos disponíveis para filtro.
/v5/loans/{loanId}/signature-requests/current/journeysPOSTGera uma nova jornada de formalização para a assinatura em andamento do empréstimo.

Convenções reutilizadas nesta página: Tratamento de erros, Objeto de domínio, Campo de status, Referências organizacionais, Log de auditoria. Valores fixos em Domínios › Jornadas.

Tipos de jornada​

O tipo define de qual registro a jornada nasce (sourceId), o que o cliente vê por padrão e o que acontece quando ele conclui ou desiste.

typeOrigem (sourceId)O que o cliente fazAo concluirSe o cliente cancelar
authorization_term_acceptanceid do termo de autorizaçãoLê o texto integral do termo e clica em "Li e aceito o termo".O aceite é registrado como assinatura eletrônica do termo, com IP, navegador, sessão e, se autorizada, geolocalização. O evento authorization_term.accepted é publicado. Se o termo depende de autorização no provedor (Dataprev), ela segue em segundo plano e, quando concluída, o termo passa a active (authorization_term.activated).O termo ainda pendente passa a rejected, com o motivo em status.note, e o evento authorization_term.rejected é publicado.
loan_formalizationid do empréstimoConfere o resumo da operação, abre e aceita cada documento e é redirecionado ao provedor de assinatura (identidade, documento e assinatura). Ao final, volta para a jornada.A jornada é concluída quando a assinatura eletrônica é concluída no provedor. O resultado da assinatura segue o fluxo do empréstimo (eventos signature.completed e loan.signed).Só a jornada é cancelada. O empréstimo e a assinatura não mudam.

A jornada loan_formalization é criada automaticamente quando o empréstimo é enviado para assinatura (POST /v5/loans/{loanId}/signature-requests). Use POST /v5/loans/{loanId}/signature-requests/current/journeys para gerar um novo link para a mesma assinatura (por exemplo, depois de cancelar ou expirar a jornada anterior).

Ciclo de vida​

POST /v5/journeys ─────────► pending       (link gerado, convite enviado se houver contato)
   │
   ├─ cliente abre o link ─► in_progress
   │     ├─ etapa externa ─► external      (ex.: assinatura no provedor)
   │     │     └─ retorno / assinatura concluída ─► in_progress ou completed
   │     └─ última etapa ──► completed
   │
   ├─ POST /{id}/cancel, cliente desiste ou nova jornada gerada ─► canceled
   └─ link aberto depois de expiresAt ─────────────────────────► expired
StatusAberta?Significado
pendingSimGerada, o cliente ainda não abriu o link.
in_progressSimO cliente abriu o link e está nas etapas.
externalSimO cliente foi redirecionado para uma etapa fora da jornada (assinatura no provedor) e ainda não voltou.
completedNãoTodas as etapas concluídas. completedAt preenchido.
canceledNãoCancelada pelo operador, pelo cliente ou substituída por uma nova jornada. canceledAt e cancelReason preenchidos.
expiredNãoO prazo de expiresAt passou.

Expiração​

Cada jornada tem um prazo (expiresAt), definido na geração: 72 horas por padrão, ou o prazo configurado no modelo da jornada (até 30 dias). Se o registro de origem vencer antes (validade do termo, validade do link de assinatura), vale o prazo menor.

expiresAt é a fonte da verdade

A jornada passa a expired quando o link é aberto depois do prazo. Até alguém abrir o link, o status pode continuar pending ou in_progress mesmo com expiresAt no passado. Para decidir se o link ainda vale, compare expiresAt com a hora atual.

Substituição​

Ao gerar uma jornada, as jornadas em aberto do mesmo tipo, para o mesmo registro de origem e o mesmo destinatário, são canceladas com o motivo "Substituída por uma nova jornada". Só o link mais recente funciona.

Convite e mensagem de conclusão​

Se o modelo da jornada tiver mensagens configuradas, a plataforma envia o convite (com o link) ao gerar e, opcionalmente, uma mensagem ao concluir, pelos canais e-mail, SMS ou WhatsApp, usando o contato de recipient. O resultado de cada envio aparece na trilha de eventos (invitation_sent, invitation_failed, completion_message_sent). Sem e-mail ou telefone no destinatário, nada é enviado: entregue o link pelo seu próprio canal.

Acompanhamento​

A jornada não publica eventos de webhook próprios. Acompanhe pelo resultado no registro de origem:

TipoEventos de webhook
authorization_term_acceptanceauthorization_term.accepted (1705) no aceite, authorization_term.rejected (1703) na recusa e authorization_term.activated (1700) quando o provedor autoriza o termo.
loan_formalizationsignature.completed (1601), signature.rejected (1602) e loan.signed (1007).

O andamento dentro da jornada (etapa atual, documentos aceitos, acessos) é consultado por GET /{id}, GET /current e GET /{id}/events.

Campos da entidade​

Identificação e situação​

CampoTipoDescrição
id / codestring (uuid) / integerIdentificadores da jornada.
typeobject (code/key/name)Tipo. Ver JourneyType.
statusobject (Status)Ver JourneyStatus. Em cancelamento, note traz o motivo.
templateobject (Referência)Modelo usado para montar a jornada. "Modelo padrão" (code = 0) quando a empresa não publicou modelo próprio para o tipo.
templateVersionintegerVersão do modelo usada. 0 para o modelo padrão.
featureobject (code/key/name)Recurso de origem: authorization_term ou loan.
parentIdstring (uuid)id do registro de origem (termo ou empréstimo).
parentNidintegerIdentificador interno do registro de origem. Use parentId.
linkstringLink que o cliente final abre. Contém o token de acesso: trate como dado sensível e entregue só ao destinatário.
expiresAtstring (date-time)Prazo do link.

Destinatário (recipient)​

CampoTipoDescrição
namestringNome do cliente.
documentNumberstringCPF, somente dígitos.
emailstring | nullE-mail para o convite.
phonestring | nullTelefone com DDD, somente dígitos, para SMS/WhatsApp.
firstNamestringPrimeiro nome, derivado de name. Somente leitura.

Progresso​

CampoTipoDescrição
currentStepstringkey da etapa em que o cliente está.
completedSteps / totalStepsintegerEtapas concluídas e total de etapas.
revisionintegerContador de alterações. Aumenta a cada ação do cliente ou do operador.
startedAtstring (date-time) | nullPrimeira abertura do link.
lastAccessAtstring (date-time) | nullÚltima interação do cliente.
completedAtstring (date-time) | nullConclusão.
canceledAt / cancelReasonstring (date-time) | null / string | nullCancelamento e motivo.

Conteúdo e evidências​

CampoTipoDescrição
contentobjectConteúdo exibido ao cliente, já preenchido com os dados do registro de origem: settings (prazo, navegação, cancelamento), theme (cores, fonte, logo), steps[] (cada etapa com key, title e blocks[]) e messages[] (convite e conclusão). É uma cópia congelada: alterações posteriores no modelo não afetam jornadas já geradas.
contentHashstringHash do conteúdo exibido, para provar o que o cliente viu.
steps[]arrayUma linha por etapa: key, title, order, status (JourneyStepStatus), allowBack, irreversible, action (ação que concluiu a etapa: next, go_to_step, finish ou a ação do tipo, como accept_term e start_signature), accessId, ip, geolocation, contentHash, completionCount, startedAt, firstCompletedAt, lastCompletedAt.
documents[]arrayDocumentos apresentados: key, type, title, order, fileId (PDF, quando há arquivo), fileName, contentType, hash (SHA-256 do conteúdo apresentado).
data[]arrayRespostas e aceites registrados pelo cliente: stepKey, key, label, value, accessId, answeredAt. Aceite de documento aparece com value no formato accepted:{hash}.
accesses[]arrayCada dispositivo/sessão que abriu o link: id, ip, ipForwardedFor, userAgent, browser, browserVersion, operatingSystem, operatingSystemVersion, deviceType, deviceModel, language, timeZone, screen, geolocation, openedAt, lastSeenAt. Preenchido só em GET /{id} e GET /current.

geolocation (em steps[] e accesses[]): status (JourneyGeolocationStatus), latitude, longitude, accuracy, capturedAt.

Mais unit, partner, branch, agent, user, company (Referência, copiados do registro de origem) e log (Log de auditoria).

POST /v5/journeys​

Gera uma jornada para um registro de origem e devolve o link.

Autenticação: API Key (X-Api-Key). Exige a permissão "Gerar" de Jornada.

Comportamento​

  1. Valida o type (1174003) e o sourceId (1174004).
  2. Carrega o registro de origem (1174004 se não existir) e monta o destinatário a partir dele: no termo, o subject; no empréstimo, o signatário da assinatura em andamento ou o tomador. Os campos informados em recipient substituem os da origem.
  3. Escolhe o modelo publicado pela empresa para o tipo (considerando unidade e produto do registro); sem modelo publicado, usa o modelo padrão do tipo.
  4. Monta o conteúdo com os dados do registro, calcula o prazo e grava a jornada como pending. A empresa precisa ter o endereço da página de jornadas configurado (1174005).
  5. Cancela as jornadas em aberto do mesmo tipo, origem e destinatário (ver Substituição).
  6. Envia o convite, se o modelo tiver mensagens e o destinatário tiver contato, e responde 201 com a jornada.

Payload de entrada​

Visualizar parâmetros
CampoTipoObrigatórioDescrição
typestringSimkey do tipo: authorization_term_acceptance ou loan_formalization. Ausente ou inválido → 1174003.
sourceIdstring (uuid)Simid do termo de autorização ou do empréstimo. Ausente ou não encontrado → 1174004.
recipientobjectNãoSobrescreve os dados do destinatário vindos da origem. Campos em branco são ignorados.
recipient.namestringNãoNome.
recipient.documentNumberstringNãoCPF. Pontuação é removida.
recipient.emailstringNãoE-mail para o convite. Informe para o termo de autorização, cuja origem não traz contato.
recipient.phonestringNãoTelefone com DDD, para SMS/WhatsApp. Pontuação é removida.
Jornada de assinatura do empréstimo

Para loan_formalization, prefira POST /v5/loans/{loanId}/signature-requests/current/journeys, que valida a assinatura em andamento e devolve a jornada junto com os dados da assinatura. Pelo POST /v5/journeys, a jornada usa a assinatura mais recente não cancelada do empréstimo.

Exemplo de Requisição e Resposta​

Visualizar Body
{
  "type": "authorization_term_acceptance",
  "sourceId": "00000000-0000-7000-8000-000000000101",
  "recipient": {
    "email": "cliente@exemplo.com",
    "phone": "11999990000"
  }
}

GET /v5/journeys/{id}​

Busca a jornada completa, incluindo accesses[].

Autenticação: API Key (X-Api-Key). Exige a permissão "Acessar" de Jornada.

Parâmetros de rota​

ParâmetroTipoDescrição
idstring (uuid)id da jornada. Não encontrada → 1174001.

Exemplo de Requisição e Resposta​

curl --request GET \
  --url 'https://{base-url}/v5/journeys/00000000-0000-7000-8000-000000000701' \
  --header 'X-Api-Key: {api_key}'

GET /v5/journeys/current​

Busca a jornada mais recente de um tipo para um registro de origem, em qualquer status. Útil quando você guardou só o id do termo ou do empréstimo e precisa recuperar o link atual.

Autenticação: API Key (X-Api-Key). Exige a permissão "Acessar" de Jornada.

Parâmetros de consulta​

ParâmetroTipoObrigatórioDescrição
typestringSimkey do tipo. Inválido → 1174003.
sourceIdstring (uuid)Simid do termo ou do empréstimo. Sem jornada → 1174001.

Exemplo de Requisição​

curl --request GET \
  --url 'https://{base-url}/v5/journeys/current?type=loan_formalization&sourceId=00000000-0000-7000-8000-000000000501' \
  --header 'X-Api-Key: {api_key}'

A resposta (200) tem o mesmo formato de GET /{id}. Verifique status e expiresAt antes de reenviar o link: se a jornada não estiver aberta, gere uma nova.

GET /v5/journeys/{id}/events​

Lista a trilha de eventos da jornada, em ordem cronológica. É a evidência do que aconteceu no link: geração, convites, aberturas, etapas exibidas e concluídas, documentos visualizados e aceitos, geolocalização, redirecionamento e retorno da etapa externa, conclusão, cancelamento e expiração.

Autenticação: API Key (X-Api-Key). Exige a permissão "Acessar" de Jornada.

Estes eventos ficam só na jornada: não são enviados por webhook.

Campos de cada evento​

CampoTipoDescrição
idstring (uuid)Identificador do evento.
typeobject (code/key/name)Ver JourneyEventType.
stepKey / blockKeystring | nullEtapa e bloco (botão, documento) envolvidos.
accessIdstring (uuid) | nullAcesso (dispositivo/sessão) que gerou o evento. null para eventos da plataforma ou do operador.
ipstring | nullIP do cliente.
latitude / longitudedecimal | nullPosição, quando autorizada.
contentHashstring | nullHash do conteúdo exibido naquele momento.
payloadstring | nullDetalhes do evento em JSON serializado como texto (ex.: respostas da etapa, motivo do cancelamento, canal do convite).
occurredAtstring (date-time)Momento do evento.

Exemplo de Requisição e Resposta​

curl --request GET \
  --url 'https://{base-url}/v5/journeys/00000000-0000-7000-8000-000000000701/events' \
  --header 'X-Api-Key: {api_key}'

POST /v5/journeys/{id}/cancel​

Cancela uma jornada em aberto (pending, in_progress ou external). O link deixa de funcionar e o cliente passa a ver a mensagem de jornada encerrada.

Autenticação: API Key (X-Api-Key). Exige a permissão "Cancelar" de Jornada.

O cancelamento pelo operador não altera o registro de origem: o termo continua no status em que estava e o empréstimo e a assinatura seguem inalterados. Para encerrar o processo, trate também o termo ou o empréstimo pelas rotas deles.

Parâmetros de rota​

ParâmetroTipoDescrição
idstring (uuid)id da jornada. Não encontrada → 1174001.

Payload de entrada​

CampoTipoObrigatórioDescrição
reasonstringNãoMotivo, até 800 caracteres. Se omitido, grava "Cancelada pelo operador".

Exemplo de Requisição e Resposta​

curl --request POST \
  --url 'https://{base-url}/v5/journeys/00000000-0000-7000-8000-000000000701/cancel' \
  --header 'X-Api-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{ "reason": "Cliente pediu novo link por outro e-mail" }'

POST /v5/journeys/search​

Busca paginada de jornadas. Sem corpo, devolve as 100 mais recentes.

Autenticação: API Key (X-Api-Key). Exige a permissão "Acessar" de Jornada.

Payload de entrada​

CampoTipoDescrição
offset / limitintegerPaginação.
sortarray de stringOrdenação.
searchTextstringTexto livre (código, nome e documento do destinatário, modelo).
idobject{ "eq": "<uuid>" }.
codeobject{ "eq": 12 }.
typeobject{ "code": { "in": [1, 2] } } ou { "key": { "eq": "loan_formalization" } }.
statusobject{ "code": { "in": [1, 2, 3] } } para jornadas em aberto.
recipientNameobject{ "regex": "maria" }.
recipientDocumentNumberobject{ "eq": "00000000000" }.
expiresAt / completedAtobject{ "gte": "2026-10-01T00:00Z", "lt": "2026-11-01T00:00Z" }.
filtersarrayFiltros dinâmicos no formato devolvido por GET /filters.

Resposta (200)​

{ count, offset, limit, items[] }. Cada item traz id, code, template, templateVersion, type, status, feature, parentNid, recipientName, recipientDocumentNumber, currentStep, completedSteps, totalSteps, expiresAt, lastAccessAt, completedAt e log. O link não vem na busca: use GET /{id}.

curl --request POST \
  --url 'https://{base-url}/v5/journeys/search' \
  --header 'X-Api-Key: {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{ "limit": 20, "status": { "code": { "in": [1, 2, 3] } }, "recipientDocumentNumber": { "eq": "00000000000" } }'

GET /v5/journeys/filters​

Lista os campos aceitos em filters da busca: id, code, type_code, status_code, recipient_name, recipient_document_number, expires_at, completed_at e created_at. Cada item traz key, name, label, type (guid, int, string, datetime, select_list), operator (eq, in, regex, btw), sourceType, source e active.

Autenticação: API Key (X-Api-Key).

POST /v5/loans/{loanId}/signature-requests/current/journeys​

Gera uma nova jornada de formalização (loan_formalization) para a assinatura eletrônica em andamento do empréstimo e devolve a assinatura com o link da jornada. A jornada anterior em aberto do mesmo empréstimo e destinatário é cancelada.

Use quando o cliente perdeu o link, ele expirou ou a jornada foi cancelada, mas a assinatura no provedor continua válida. Se a assinatura também expirou ou foi recusada, envie o empréstimo para assinatura de novo com POST /v5/loans/{loanId}/signature-requests, que gera nova CCB, nova assinatura e nova jornada.

Autenticação: API Key (X-Api-Key). Exige permissão de edição de empréstimos.

Parâmetros de rota​

ParâmetroTipoDescrição
loanIdstring (uuid)id do empréstimo. Não encontrado ou fora do nível de acesso → 1010001.

Sem corpo.

Validações​

CódigoQuando
1010001Empréstimo não encontrado.
1010029O empréstimo nunca foi enviado para assinatura.
1010033A assinatura mais recente não está aguardando assinatura (concluída, recusada, cancelada ou expirada). Gere uma nova assinatura.
1010028Nenhum signatário pendente com link de assinatura do provedor.
1174005Endereço da página de jornadas não configurado para a empresa.

Resposta​

CampoTipoDescrição
signatureId / codestring (uuid) / integerAssinatura eletrônica do empréstimo.
providerobject (code/key/name)Provedor de assinatura.
statusobject (Status)Status da assinatura. Ver Domínios › Assinatura Eletrônica.
completedAtstring (date-time) | nullConclusão da assinatura.
ccbFileId / ccbFileUrlstring (uuid) / stringCCB gerada para assinatura.
signers[]arrayid, name, documentNumber, email, signUrl, status, expiresAt, signedAt, refusedAt, refusalReason, verification, identityDocuments.
documents[]arrayDocumentos devolvidos pelo provedor: id, title, role, origin, fileId, fileName, fileExtension.
journeyIdstring (uuid)id da jornada gerada. Use em GET /v5/journeys/{id}.
journeyUrlstringLink da jornada para o cliente.
journeyStatusobject (Status)Status da jornada (pending na geração).

Exemplo de Requisição e Resposta​

curl --request POST \
  --url 'https://{base-url}/v5/loans/00000000-0000-7000-8000-000000000501/signature-requests/current/journeys' \
  --header 'X-Api-Key: {api_key}'

Erros do módulo​

codetextOnde
1174001Jornada não encontradaGET /{id}, GET /current, GET /{id}/events, POST /{id}/cancel
1174003Tipo da Jornada inválidoPOST /, GET /current
1174004Registro de origem da jornada é obrigatórioPOST / (ausente ou não encontrado)
1174005Endereço da página de aceite não configuradoGeração (POST / e rotas do empréstimo)
1174010A jornada foi alterada em outra aba ou dispositivo, recarregue a páginaPOST /{id}/cancel
1174022Esta jornada não pode ser canceladaPOST /{id}/cancel
1173010A jornada precisa de pelo menos uma etapaGeração, modelo inválido
1173036Falha ao montar o conteúdo da jornadaGeração, modelo inválido

Os demais códigos 1174xxx (link inválido, expirado, encerrado, etapa, documento, geolocalização) são devolvidos à página do link, não às rotas de integração.