openapi: 3.0.0
info:
  title: API Webhook - Core-Banking - CIBA
  description: >-
    Notificação de pedido de autenticação CIBA entregue ao núcleo financeiro e
    rotas internas para registrar a decisão do usuário (aprovar/rejeitar).
  version: 1.0.0
servers:
  - url: https://seu-dominio-core-banking
components:
  schemas: {}
  parameters: {}
paths:
  /backchannel:
    post:
      description: >-
        Esta rota deve ser disponibilizada do lado do núcleo financeiro para
        receber a notificação de que um TPP iniciou uma autenticação CIBA
        (Client Initiated Backchannel Authentication) para o usuário. Ao
        recebê-la, a instituição deve solicitar a aprovação do usuário no seu
        próprio canal (ex.: push no aplicativo) e, com a decisão, chamar
        `/internal/backchannel/{authReqId}` antes de `expiresAt`. Em sandbox,
        com a opção "mock do backchannel" ligada no portal, este webhook não é
        chamado e a decisão é tomada diretamente na tela "Login CIBA (Mock)" do
        portal.
      tags:
        - Webhook CIBA
      summary: Notificação de pedido de autenticação CIBA
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - CIBA_AUTHENTICATION_REQUESTED
                  description: Tipo da notificação.
                authReqId:
                  type: string
                  example: orYQeB_OUt1lSAIsrPUc6-iw86oUxGVVa58Jeq0qjf1
                consentId:
                  type: string
                  example: urn:bancoex:C1DD33123
                document:
                  type: string
                  description: CPF do usuário que deve aprovar a autenticação.
                  example: '76109277673'
                clientId:
                  type: string
                  description: client_id do TPP no authorization server.
                  example: g7Xqlt_L3JuTyqgKRiMt9
                clientName:
                  type: string
                  description: Nome do TPP, para exibição ao usuário.
                  example: TPP Exemplo
                bindingMessage:
                  type: string
                  description: >-
                    Mensagem enviada pelo TPP para ser exibida ao usuário,
                    quando houver.
                expiresAt:
                  type: string
                  nullable: true
                  description: >-
                    Prazo para a decisão do usuário; após esse horário o pedido
                    expira.
                resources:
                  type: array
                  items:
                    type: object
                    properties:
                      resourceId:
                        type: string
                        example: 25cac914-d8ae-6789-b215-650a6215a0e5
                      resourceName:
                        type: string
                        description: Nome do recurso, para exibição ao usuário.
                        example: Conta corrente 1234-5
                      resourceType:
                        type: string
                        enum:
                          - ACCOUNT
                          - CREDIT_CARD_ACCOUNT
                    required:
                      - resourceId
                      - resourceType
                  description: >-
                    Contas e cartões do usuário vinculados ao consentimento,
                    para o usuário escolher quais compartilhar; os `resourceId`
                    escolhidos são enviados na decisão. Operações de crédito não
                    entram na seleção: são compartilhadas por modalidade,
                    conforme as permissões do consentimento. Lista vazia quando
                    o consentimento não pede `ACCOUNTS_READ` nem
                    `CREDIT_CARDS_ACCOUNTS_READ`.
              required:
                - type
                - authReqId
                - consentId
                - document
                - clientId
                - expiresAt
                - resources
      responses:
        '204':
          description: Notificação recebida com sucesso.
  /internal/backchannel/{authReqId}:
    post:
      description: >-
        Chamada pela instituição na plataforma SaaS com a decisão do usuário.
        `AUTHORISED` autoriza o consentimento somente com as contas e cartões
        escolhidos pelo usuário em `resources` (operações de crédito são sempre
        compartilhadas por modalidade) e libera o TPP para obter o token. Quando
        o consentimento pede `ACCOUNTS_READ`, é obrigatório escolher ao menos
        uma conta (`ACCOUNT`); quando pede `CREDIT_CARDS_ACCOUNTS_READ`, ao
        menos um cartão (`CREDIT_CARD_ACCOUNT`); `REJECTED` rejeita o
        consentimento e o TPP recebe `access_denied` ao solicitar o token.
      tags:
        - CIBA
      summary: Registra a decisão do usuário em uma requisição de autenticação CIBA
      parameters:
        - schema:
            type: string
            description: >-
              Identificador da requisição de autenticação CIBA, recebido no
              webhook.
            example: orYQeB_OUt1lSAIsrPUc6-iw86oUxGVVa58Jeq0qjf1
          required: true
          name: authReqId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - AUTHORISED
                    - REJECTED
                  description: Decisão do usuário.
                resources:
                  type: array
                  items:
                    type: object
                    properties:
                      resourceId:
                        type: string
                        example: 25cac914-d8ae-6789-b215-650a6215a0e5
                    required:
                      - resourceId
                  description: >-
                    Contas e cartões escolhidos pelo usuário, dentre os
                    recebidos no webhook. Com `AUTHORISED`, só as contas e
                    cartões enviados são compartilhados; ignorado com
                    `REJECTED`.
              required:
                - status
      responses:
        '200':
          description: Decisão registrada.
          content:
            application/json:
              schema:
                type: object
                properties:
                  authReqId:
                    type: string
                  consentId:
                    type: string
                  status:
                    type: string
                    enum:
                      - AUTHORISED
                      - REJECTED
                    description: Status do consentimento após a decisão.
                required:
                  - authReqId
                  - consentId
                  - status
        '400':
          description: >-
            `status` ou `resources` inválidos, authReqId inexistente, já
            decidido ou expirado, recursos escolhidos que não estão entre os
            recebidos no webhook ou que não atendem às permissões do
            consentimento (`access_denied`), ou falha ao atualizar o
            consentimento.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - invalid_request
                      - expired_token
                      - access_denied
                      - server_error
                  error_description:
                    type: string
                required:
                  - error