openapi: 3.0.0 info: title: Integração - API de Enriquecimento de Conta description: >- Documentação referente ao endpoint de Enriquecimento de Conta que deve ser implementado pelo parceiro. O OpenX chama este endpoint passando o CPF do usuário e os dados do consentimento em andamento. O parceiro deve retornar a lista de contas bancárias disponíveis no formato `PaymentAccountEnrichment`. **Configuração:** Configure a URL deste endpoint na propriedade `accountsEnrichmentApi` da brand no Portal SaaS. **Tipos de Conta (AccountType):** | Código | Descrição | |--------|-----------| | `CACC` | Conta Corrente | | `SVGS` | Conta Poupança | | `TRAN` | Conta de Pagamento (Transacional) | | `SLRY` | Conta Salário | version: 1.0.0 servers: - url: https://{partner-domain} description: URL configurada na propriedade accountsEnrichmentApi da brand variables: partner-domain: default: api.parceiro.com.br description: Domínio da API do parceiro tags: - name: Enriquecimento de Conta description: >- Endpoint responsável por retornar as contas bancárias disponíveis do usuário para exibição durante o fluxo de confirmação de consentimento. components: schemas: {} parameters: {} paths: /payments/accounts/enrichment: post: description: >- Endpoint de **Enriquecimento de Conta** que deve ser implementado pelo parceiro e configurado na propriedade `accountsEnrichmentApi` da brand no Portal SaaS. O OpenX chama este endpoint durante o fluxo de confirmação de consentimento para buscar as contas bancárias disponíveis do usuário e exibi-las na interface. **Importante:** - O retorno deve seguir estritamente o contrato `PaymentAccountEnrichment` - As contas retornadas serão exibidas na tela de seleção durante o fluxo de consentimento - Utilize o campo `enabled` para indicar se a conta pode ser selecionada - Utilize `reasonCode` e `messages` para comunicar ao usuário por que uma conta está indisponível tags: - Enriquecimento de Conta requestBody: required: true content: application/json: schema: type: object properties: document: type: string description: CPF do usuário (somente números) example: '12345678900' consent: type: object properties: document: type: string description: CPF do usuário presente no consentimento example: '12345678900' consent: type: object properties: consentId: type: string description: Identificador único do consentimento example: urn:banco:abc-123 status: type: string description: Status atual do consentimento example: AWAITING_AUTHORISATION payment: type: object properties: amount: type: string description: Valor do pagamento example: '150.00' currency: type: string description: Moeda do pagamento (ISO 4217) example: BRL required: - amount - currency description: Dados do pagamento associado ao consentimento riskSignals: type: object properties: deviceId: type: string description: Identificador único do dispositivo do usuário example: uuid-device-001 isRootedDevice: type: boolean description: Indica se o dispositivo está com root/jailbreak example: false required: - deviceId - isRootedDevice description: Sinais de risco do dispositivo (opcional) required: - consentId - status - payment description: Dados internos do consentimento required: - document - consent description: Objeto de consentimento completo encaminhado pelo OpenX required: - document - consent description: Corpo da requisição recebido pelo endpoint de enriquecimento responses: '200': description: >- Enriquecimento realizado com sucesso. Retorna as contas disponíveis do usuário. content: application/json: schema: type: object properties: userId: type: string description: Identificador único do usuário no sistema do parceiro example: user-abc-12345 name: type: string description: Nome completo do usuário example: João da Silva cpf: type: string description: CPF do usuário (somente números) example: '12345678900' accounts: type: array items: type: object properties: ispb: type: string description: Código ISPB da instituição financeira (8 dígitos) example: '60701190' issuer: type: string description: Código da agência bancária (opcional) example: '0001' number: type: string description: Número da conta bancária example: 123456-7 balance: type: string description: >- Saldo disponível na conta, formatado como string numérica example: '1500.00' accountType: type: string enum: - CACC - SVGS - TRAN - SLRY description: |- Tipo da conta bancária: - `CACC`: Conta Corrente - `SVGS`: Conta Poupança - `TRAN`: Conta de Pagamento (Transacional) - `SLRY`: Conta Salário example: CACC partners: type: array items: type: object properties: document: type: string description: CPF ou CNPJ do sócio/parceiro da conta example: '12345678900' name: type: string description: Nome do sócio/parceiro da conta example: João da Silva status: type: string description: Status do sócio/parceiro (opcional) example: ACTIVE required: - document - name description: >- Informações de um sócio ou parceiro vinculado à conta description: Lista de sócios/parceiros da conta (opcional) enabled: type: boolean description: >- Indica se a conta está habilitada para ser selecionada pelo usuário no fluxo de consentimento example: true reasonCode: type: string description: >- Código de motivo caso a conta esteja desabilitada (opcional). Corresponde ao EnumConsentRejectionReasonTypeV3. example: ACCOUNT_DOES_NOT_ALLOW_PAYMENT messages: type: array items: type: string description: >- Mensagens informativas ou de erro associadas à conta (opcional) example: - Conta sem saldo suficiente required: - ispb - number - balance - accountType - enabled description: >- Dados de uma conta bancária disponível para seleção no consentimento description: >- Lista de contas bancárias disponíveis do usuário para o fluxo de consentimento required: - userId - name - cpf - accounts description: >- Objeto obrigatório de retorno da API de Enriquecimento de Conta '400': description: 'Requisição inválida (ex: CPF ausente ou malformado)' content: application/json: schema: type: object properties: error: type: string description: Código ou mensagem de erro example: USER_NOT_FOUND message: type: string description: Descrição detalhada do erro example: Usuário com CPF informado não foi encontrado required: - error description: Resposta de erro '404': description: Usuário não encontrado content: application/json: schema: type: object properties: error: type: string description: Código ou mensagem de erro example: USER_NOT_FOUND message: type: string description: Descrição detalhada do erro example: Usuário com CPF informado não foi encontrado required: - error description: Resposta de erro '500': description: Erro interno no servidor do parceiro content: application/json: schema: type: object properties: error: type: string description: Código ou mensagem de erro example: USER_NOT_FOUND message: type: string description: Descrição detalhada do erro example: Usuário com CPF informado não foi encontrado required: - error description: Resposta de erro