Criação de uma sessão de jornada

Características Principais

• Criação de Sessão: Cria uma nova sessão de jornada ITP para sweeping accounts
• 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
• Integração com Sistema de Jornadas: Integra-se com o sistema de jornadas disponíveis através do endpoint GET /open-keys/itp/api/v2/journeys
• Agendamento de Expiração: Agenda automaticamente a expiração da jornada quando configurado

Endpoint

POST /open-keys/itp/api/v2/sweeping-accounts/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

Headers Obrigatórios

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

Estrutura da Requisição

Payload Completo

{
    "journeyId": "default",
    "redirectUrl": "http://localhost:8080/callback",
    "brandId": "6894f1db86d49fedbec6cd13",
    "externalId": "sweeping-account-session-123",
    "settings": [
        {
            "key": "PRIORITIES_BRANDS",
            "value": ["6894f1db86d49fedbec6cd13", "a1b2c3d4e5f6g7h8i9j0k1l2"]
        },
        {
            "key": "JOURNEY_RULES",
            "value": ["rule1", "rule2"]
        }
    ],
    "tags": {
        "environment": "production",
        "clientId": "client-123"
    }
}

Campos da Requisição

Nível Raiz

Array settings

Array de objetos contendo configurações da jornada.

Objeto tags

Objeto com chaves e valores customizados para identificação da sessão. Não há restrições de formato, mas recomenda-se usar valores simples (strings, números).

Exemplo:

{
    "environment": "production",
    "clientId": "client-123",
    "userId": "user-456"
}

Formato de Valores

journeyId

• Tipo: String
• Tamanho máximo: 36 caracteres
• Valores aceitos:
  • "default" - Utiliza a jornada padrão configurada
  • ID de jornada válido (UUID ou alias)
• Padrão: "default" se não informado

redirectUrl

• Tipo: String (URL)
• Formato: URL válida (RFC 3986)
• Validação: Deve estar cadastrada nas URLs de redirecionamento permitidas da aplicação
• Exemplos válidos:
  • "http://localhost:8080/callback"
  • "https://app.exemplo.com.br/callback"

brandId

• Tipo: String
• Tamanho máximo: 36 caracteres
• Formato: ID de brand válido (geralmente ObjectId do MongoDB)

externalId

• Tipo: String
• Tamanho máximo: 36 caracteres
• Unicidade: Deve ser único por aplicação
• Uso recomendado: Identificador externo da sessão no sistema da aplicação

Validações e Regras de Negócio

1. Application Client ID

• O applicationClientId é extraído automaticamente do token OAuth2 através do claim azp
• A aplicação deve existir no sistema
• Se a aplicação não for encontrada, será retornado erro 403 (Forbidden)

2. Journey ID

• Se journeyId for "default" ou não informado:
  1. Busca a setting JOURNEY_DEFAULT_ALIAS na aplicação
  2. Se não encontrada, utiliza a variável de ambiente JOURNEY_DEFAULT_ALIAS
  3. Se nenhuma das opções estiver configurada, retorna erro
• Se journeyId for especificado:
  1. Busca a jornada por ID (ObjectId) ou alias
  2. Se não encontrada, retorna erro 403 (Forbidden)

3. External ID

• Se informado, deve ser único para a aplicação
• Se já existir uma sessão com o mesmo externalId para a aplicação, retorna erro 409 (Conflict)
• Útil para evitar duplicação de sessões e rastreamento externo

4. Redirect URL

• Se informada, deve estar cadastrada nas URLs de redirecionamento permitidas da aplicação
• Validação é realizada através do serviço v2.open-keys.itp.application-redirect.verify
• Se não autorizada, retorna erro 403 (Forbidden)

5. Settings da Jornada

• Settings da jornada (PRIORITIES_BRANDS, JOURNEY_RULES) são aplicadas automaticamente se não especificadas na requisição
• Settings especificadas na requisição têm prioridade sobre as settings da jornada
• Permite customização por sessão sem modificar a jornada base

Fluxo de Implementação

Passo a Passo

1. Obtenção do Token OAuth2

   • Obtenha um token de acesso válido com permissão app
   • O token deve conter o claim azp com o clientId da aplicação

2. Preparação da Requisição

   • Defina o journeyId (ou use "default")
   • Configure a redirectUrl (se necessário)
   • Defina o externalId (recomendado para rastreamento)
   • 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/sweeping-accounts/v2/journeys-sessions/{id}
   • A sessão será atualizada conforme o progresso do fluxo

Resposta da API

Sucesso (200 OK)

{
    "id": "f362a873-c127-4122-b711-a37b24a36914",
    "journeyId": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "journeySessionUrl": "https://journey.openkeys.com.br/journey/a1b2c3d4e5f6g7h8i9j0k1l2m3?api=SWEEPING_ACCOUNTS_V2&id=f362a873-c127-4122-b711-a37b24a36914&token=opaque-token-123",
    "applicationClientId": "client-id-da-aplicacao",
    "applicationId": "app-uuid-123",
    "tokenId": "token-uuid-456",
    "status": "PENDING",
    "paymentInitiationApi": "SWEEPING_ACCOUNTS_V2",
    "redirectUrl": "http://localhost:8080/callback",
    "brandId": "6894f1db86d49fedbec6cd13",
    "externalId": "sweeping-account-session-123",
    "settings": [
        {
            "key": "PRIORITIES_BRANDS",
            "value": ["6894f1db86d49fedbec6cd13"]
        }
    ],
    "tags": {
        "environment": "production",
        "clientId": "client-123"
    },
    "statusHistory": [
        {
            "updatedAt": "2025-01-15T10:00:00.000Z",
            "status": "PENDING"
        }
    ],
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
}

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 'journeyId' inválido"
}

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 a permissão app

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

409 Conflict

Causa: externalId já existe para a aplicação.

{
    "error": "Conflict",
    "message": "Each Journey Session should have a unique externalId prop."
}

Solução: Utilize um externalId diferente ou remova o campo para gerar automaticamente.

422 Unprocessable Entity

Causa: Validação de schema falhou.

{
    "error": "Unprocessable Entity",
    "message": "Validation failed",
    "details": [
        {
            "field": "journeyId",
            "message": "Invalid format"
        }
    ]
}

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/sweeping-accounts/v2/journeys-sessions/{id}
2. Listar Sessões: GET /open-keys/itp/api/v2/sweeping-accounts/v2/journeys-sessions
3. Criar Payment Initiation: Após a autorização, utilize o endpoint de criação de payment initiation associado à sessão
4. Verificar Expiração: POST /open-keys/itp/api/v2/sweeping-accounts/v2/journeys-sessions/{id}/verify-expired