Malga Client-token API

openapi: 3.1.0
info:
  version: '0.5'
  title: Documentação Malga 3DS2 Malga Client-token API
  description: "# Authentication\n\nOs serviços de API da Malga são protegidos através de chaves de acesso. Você pode gerenciar suas chaves de acesso através do seu dashboard.\n\nÉ importante armazenar suas chaves de maneira privada e segura uma vez que elas possuem privilégios de alteração na sua conta. Não compartilhe suas chaves, não deixe elas fixadas no seu código e nem armazene elas no seu servidor de controle de versão. Recomendamos utilizar variáveis de ambiente secretas para deixar a chave disponível para sua aplicação.\n\nA Autenticação para todos os chamadas da API é feita através de headers HTTP, sendo necessário informar seu identificador de cliente na Malga e a chave secreta de acesso.\n\n## X-Client-ID\n\nIdentificador única da sua conta na Malga. Deve ser enviado no header obrigatóriamente em todas as requisições feitas a API.\n\n| Security Scheme Type | API Key |\n|-----------------------|-----------|\n| Header parameter name | `X-Client-ID` |\n\n## X-Api-Key\n\nSua chave de acesso a API. Funciona em par com o client-id devendo ser enviado no header obrigatóriamente em todas as requisições feitas a API.\n\n| Security Scheme Type | API Key |\n|-----------------------|-----------|\n| Header parameter name | `X-Api-Key` |\n\n## Exemplo de requisicão autenticada\n\n```bash\n  curl --location --request GET 'https://api.malga.io/v1/' \\\n    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \\\n    --header 'X-Api-Key: <YOUR_SECRET_KEY>'\n```\n"
servers:
- url: https://api.malga.io
  description: Production
security:
- X-Client-ID: []
  X-Api-Key: []
tags:
- name: Client-token
  description: 'É possível criar chaves públicas de acesso temporária a API com escopo e tempo de expiração limitados.


    Recomendamos o uso deste tipo de chave quando você tiver que expor a chave em uma aplicação client side.


    **Detalhe dos parâmetros da chamada de criação da chave pública:**


    <SchemaDefinition schemaRef="#/components/schemas/AuthRequest" />


    **Retorno da chamada de criação da chave pública:**


    <SchemaDefinition schemaRef="#/components/schemas/AuthResponse" />

    '
paths:
  /v1/auth:
    post:
      tags:
      - Client-token
      summary: Criar nova chave pública para uso no client-side
      operationId: create_auth_token
      requestBody:
        description: Creat authentication token
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
            examples:
              AuthRequest:
                $ref: '#/components/examples/AuthRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              examples:
                AuthResponse:
                  $ref: '#/components/examples/AuthResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorItem:
      properties:
        type:
          type: string
          enum:
          - api_error
          - bad_request
          - invalid_request_error
          - card_declined
        code:
          type: integer
          description: Código HTTP do erro (por exemplo, `422` em erros de regra de negócio).
        declinedCode:
          type: string
          description: Código de retorno da transação em caso de falha na autorização
        key:
          type: string
          description: 'Chave estável que identifica o erro de negócio (ex.: `bank_identifier_required`). Útil para tratar o erro programaticamente, independente da mensagem traduzida.'
        businessCode:
          type: string
          description: 'Chave estável de regra de negócio retornada em `422`. Permite tratar o erro programaticamente independente da mensagem traduzida. Exemplos em sessões: `pix_boleto_multiple_payments_not_allowed`, `pix_boleto_one_to_one_reactivation_blocked`, `platform_fee_exceeds_link_amount`, `session_disabled`, `multiple_payments_limit_reached`.

            '
        message:
          type: string
          description: Descrição breve do erro
        details:
          type: array
          description: Lista contendo objetos que detalham o erro de validação
    AuthResponse:
      properties:
        scope:
          type: string
          description: Determina o escopo de endpoints que a chave terá acesso
          enum:
          - customers
          - cards
          - tokens
          - charges
          - webhooks
          - sessions
          - auth
          - reports
          - flows
          - sellers
          - providers
          - subscriptions
        expires:
          type: number
          description: Prazo de validade da chave em segundos a partir da criação, zero para não expirar
        clientId:
          type: string
          format: uuid
          description: Identificador do cliente na Malga
        publicKey:
          type: string
          format: uuid
          description: Chave pública criada
    AuthRequest:
      properties:
        scope:
          type: string
          description: Determina o escopo de endpoints que a chave terá acesso
          enum:
          - customers
          - cards
          - tokens
          - charges
          - webhooks
          - sessions
          - auth
          - flows
          - sellers
          - providers
          - subscriptions
        expires:
          type: number
          description: Prazo de validade da chave em segundos a partir da criação, zero para não expirar
          default: 0
    ErrorResponse:
      properties:
        error:
          type: object
          allOf:
          - $ref: '#/components/schemas/ErrorItem'
  examples:
    AuthResponse:
      value:
        clientId: cc0b1e41-2936-45c5-947f-93995ffcdc00
        publicKey: <YOUR_PUBLIC_KEY>
        scope:
        - tokens
        expires: 31104000
        createdAt: 20200110 00:00:00
    AuthRequest:
      value:
        scope:
        - tokens
        expires: 31104000
  securitySchemes:
    X-Client-ID:
      type: apiKey
      in: header
      name: X-Client-Id
    X-Api-Key:
      type: apiKey
      in: header
      name: X-Api-Key
x-tagGroups:
- name: API Key
  tags:
  - Client-token
- name: Cartões
  tags:
  - Tokens
  - Cards
- name: Pagamentos
  tags:
  - Customers
  - Charges
  - Sessions
  - Sellers
  - Vendors
  - Split
  - 3DSecure2
  - Settings
- name: Notificação e eventos
  tags:
  - Webhooks
- name: Provedores
  tags:
  - Merchants
  - Providers
- name: Gestão de pagamentos
  tags:
  - Flows
- name: Exportar Dados
  tags:
  - Reports
- name: Apêndice
  tags:
  - Tabelas de tipos