Criar Jornada de Vínculo

Características Principais

• Criação de Sessão: Cria uma nova sessão de jornada ITP para enrollments
• Seleção de Jornada: Suporta especificação de jornada customizada ou uso da jornada padrão configurada
• URL de Redirecionamento: Gera uma URL única contendo todos os parâmetros necessários para iniciar a jornada

Endpoint

POST /open-keys/itp/api/v2/enrollments/v2/journeys-sessions

Autenticação

A API requer autenticação OAuth2 utilizando o fluxo de Client Credentials

Permissões Requeridas

• app: Permissão para integrações diretas via API
• journey: Permissão para acessar jornadas
• end_user: Permissão para usuários finais

Headers Obrigatórios

Authorization: Bearer {access_token}
Content-Type: application/json

Estrutura da Requisição

Payload Completo

{
    "journeyId": "enrollments-redirect",
    "paymentInitiationData": {
        "loggedUser": {
            "document": {
                "identification": "{CPF}",
                "rel": "CPF"
            }
        },
        "permissions": [
            "PAYMENTS_INITIATE"
        ]
    },
    "directoryCallback": true,
    "redirectUrl": "{redirectUrl}",
    "resumetUrl": "{resumetUrl}",
    "settings": [
        {
            "key": "JOURNEY_RULES",
            "value": [
                {
                    "key": "returnToManagement",
                    "value": true
                },
                {
                    "key": "openManagementOnSelf",
                    "value": true
                },
                {
                    "key": "goToPayment",
                    "value": true
                }
            ]
        }
    ],
    "tags": {
        "environment": "production",
        "clientId": "client-123"
    }
}

Campos da Requisição

Nível Raiz

Objeto paymentInitiationData

Array settings

Array de objetos contendo configurações da jornada.

Fluxo de Implementação

Passo a Passo

1. Obtenção do Token OAuth2

   • Obtenha um token de acesso válido com permissões app, journey e end_user
   • O token deve conter o claim azp com o clientId da aplicação

2. Preparação da Requisição

   • Defina o journeyId
   • Configure paymentInitiationData com usuário e permissões
   • Configure redirectUrl e resumetUrl (se necessário)
   • Adicione settings e tags conforme necessário

3. Envio da Requisição

   • Envie a requisição POST para o endpoint
   • Inclua o token no header Authorization

4. Processamento da Resposta

   • A sessão será criada com status PENDING
   • A resposta contém a journeySessionUrl para redirecionamento
   • Armazene o id da sessão para consultas futuras

5. Redirecionamento do Usuário

   • Utilize a journeySessionUrl retornada para redirecionar o usuário
   • O usuário será direcionado para a jornada de autorização

6. Monitoramento da Sessão

   • Monitore o status da sessão através do endpoint GET /open-keys/itp/api/v2/enrollments/v2/journeys-sessions/{id}
   • A sessão será atualizada conforme o progresso do fluxo

Resposta da API

Sucesso (200 OK)

{
    "journeyId": "{journeyId}",
    "paymentInitiationApi": "ENROLLMENTS_V2",
    "tokenId": "{tokenId}",
    "journeySessionStageId": "{journeySessionStageId}",
    "journeySessionUrl": "{url}",
    "status": "PENDING",
    "id": "{id}",
    "..."
}

Campos Importantes da Resposta

Tratamento de Erros

400 Bad Request

Causa: Dados da requisição inválidos ou mal formatados.

{
    "error": "Validation Error",
    "message": "Campo obrigatório ausente"
}

Solução: Verifique o formato dos dados enviados e os requisitos de validação.

401 Unauthorized

Causa: Token de acesso inválido, expirado ou ausente.

{
    "error": "Unauthorized",
    "message": "Token inválido ou expirado"
}

Solução:

• Verifique se o token está presente no header Authorization
• Obtenha um novo token se o atual estiver expirado
• Verifique se o token possui as permissões necessárias

403 Forbidden

Causa: Aplicação não encontrada, jornada não encontrada ou redirectUrl não autorizada.

{
    "error": "Forbidden",
    "message": "application not found"
}

ou

{
    "error": "Forbidden",
    "message": "journey not found"
}

ou

{
    "error": "Forbidden",
    "message": "this redirectUrl is not allowed for this application."
}

Solução:

• Verifique se a aplicação existe e está ativa
• Verifique se o journeyId informado existe e está disponível
• Verifique se a redirectUrl está cadastrada nas URLs permitidas da aplicação

422 Unprocessable Entity

Causa: Validação de schema falhou ou CPF/CNPJ não corresponde ao token opaco.

{
    "error": "Unprocessable Entity",
    "message": "the cpf is not equal"
}

Solução: Verifique os detalhes do erro e corrija os campos indicados.

500 Internal Server Error

Causa: Erro interno do servidor.

{
    "error": "Internal Server Error",
    "message": "An unexpected error occurred"
}

Solução: Tente novamente mais tarde. Se o problema persistir, entre em contato com o suporte.

Status da Sessão

• PENDING: Sessão criada, aguardando início do fluxo
• AWAITING_AUTHORISATION: Aguardando autorização do usuário na detentora
• AUTHORISED: Consentimento autorizado pelo usuário
• REJECTED: Consentimento rejeitado pelo usuário
• CANCELLED: Sessão cancelada
• EXPIRED: Sessão expirada
• FINISHED: Fluxo concluído com sucesso

Integração com Outros Endpoints

Após criar a sessão de jornada, você pode:

1. Consultar a Sessão: GET /open-keys/itp/api/v2/enrollments/v2/journeys-sessions/{id}
2. Listar Sessões: GET /open-keys/itp/api/v2/enrollments/v2/journeys-sessions