openapi.yaml

openapi: 3.1.0
info:
  title: API AbacatePay
  description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
  version: 1.0.0
servers:
  - url: 'https://api.abacatepay.com/v2'
    description: Único servidor para os ambientes de produção e sandbox.
paths:
  /customers/create:
    post:
      summary: Criar um cliente
      description: >
        Permite que você crie um cliente para a sua loja.


        **Campo obrigatório**: Apenas o `email` é obrigatório para criar um
        cliente.


        **Recomendado**: Embora os demais campos sejam opcionais, é altamente
        recomendado fornecer `name`, `cellphone`, `taxId` e `zipCode` quando
        disponíveis, pois essas informações melhoram a experiência do cliente no
        checkout e facilitam a identificação.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >
                Os dados do seu cliente.


                **Obrigatório**: Apenas `email` é obrigatório.


                **Opcional mas recomendado**: `name`, `cellphone`, `taxId`,
                `zipCode` e `metadata` são opcionais, mas recomendados para
                melhor experiência do cliente.
              required:
                - email
              additionalProperties: false
              example:
                email: daniel_lima@abacatepay.com
              properties:
                email:
                  type: string
                  description: E-mail do cliente (obrigatório)
                  example: daniel_lima@abacatepay.com
                name:
                  type: string
                  description: Nome completo do seu cliente (opcional)
                  example: Daniel Lima
                  x-mint:
                    hidden: true
                cellphone:
                  type: string
                  description: Celular do cliente (opcional)
                  example: (11) 4002-8922
                  x-mint:
                    hidden: true
                taxId:
                  type: string
                  description: CPF ou CNPJ válido do cliente (opcional)
                  example: 123.456.789-01
                  x-mint:
                    hidden: true
                zipCode:
                  type: string
                  description: CEP do cliente (opcional)
                  example: 01310-100
                  x-mint:
                    hidden: true
                metadata:
                  type: object
                  description: >-
                    Metadados adicionais do cliente. Campo livre para a sua
                    aplicação (opcional)
                  additionalProperties: true
                  example:
                    source: landing-page
                    campaign: black-friday-2025
                  x-mint:
                    hidden: true
      responses:
        '200':
          description: Cliente criado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /customers/list:
    get:
      summary: Listar clientes
      description: >
        Retorna todos os clientes que você cadastrou com suporte a paginação.


        Você pode usar essa rota para visualizar todos os seus clientes e suas
        informações.


        **Alternativa**: Você também pode visualizar e gerenciar seus clientes
        pelo [Dashboard da AbacatePay](https://app.abacatepay.com/clientes).
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único do cliente
          required: false
          schema:
            type: string
            example: cust_aebxkhDZNaMmJeKsy0AHS0FQ
        - name: email
          in: query
          description: Filtrar por e-mail do cliente
          required: false
          schema:
            type: string
            example: daniel_lima@abacatepay.com
        - name: taxId
          in: query
          description: Filtrar por CPF ou CNPJ do cliente
          required: false
          schema:
            type: string
            example: 123.456.789-01
      responses:
        '200':
          description: Lista de clientes retornada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de clientes.
                    items:
                      $ref: '#/components/schemas/Customer'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    example: null
                    nullable: true
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /customers/get:
    get:
      summary: Buscar um cliente
      description: >
        Retorna os dados de um cliente específico baseado em filtros.


        Você pode usar essa rota para buscar um cliente por ID ou outros
        critérios.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Identificador único público do cliente
          required: false
          schema:
            type: string
            example: cust_aebxkhDZNaMmJeKsy0AHS0FQ
      responses:
        '200':
          description: Cliente encontrado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
                  error:
                    type: string
                    example: null
                    nullable: true
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Cliente não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro indicando que o cliente não foi
                      encontrado.
                    example: Cliente não encontrado.
  /customers/delete:
    post:
      summary: Deletar um cliente
      description: |
        Remove um cliente da sua loja.

        Esta operação é irreversível. Use com cuidado.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          required: true
          description: Identificador único público do cliente a ser deletado
          schema:
            type: string
            example: cust_aebxkhDZNaMmJeKsy0AHS0FQ
      responses:
        '200':
          description: Cliente deletado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
                  error:
                    type: string
                    example: null
                    nullable: true
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Cliente não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro indicando que o cliente não foi
                      encontrado.
                    example: Cliente não encontrado.
  /coupons/create:
    post:
      summary: Criar um cupom
      description: >
        Permite que você crie um novo cupom que pode ser usado por seus clientes
        para aplicar descontos.


        **Alternativa**: Você também pode criar e gerenciar seus cupons pelo
        [Dashboard da AbacatePay](https://app.abacatepay.com/cupons).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Coupon'
      responses:
        '200':
          description: Cupom criado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CouponResponse'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /coupons/list:
    get:
      summary: Listar cupons
      description: >
        Retorna todos os cupons que você criou com suporte a paginação.


        Você pode usar essa rota para visualizar todos os seus cupons, incluindo
        seus status (ativos, inativos ou expirados), descontos aplicados e
        quantas vezes foram utilizados.


        **Alternativa**: Você também pode visualizar e gerenciar seus cupons
        pelo [Dashboard da AbacatePay](https://app.abacatepay.com/cupons).
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único do cupom
          required: false
          schema:
            type: string
            example: DEYVIN_20
        - name: status
          in: query
          description: Filtrar por status do cupom
          required: false
          schema:
            type: string
            enum:
              - ACTIVE
              - INACTIVE
              - EXPIRED
      responses:
        '200':
          description: Lista de cupons retornada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de cupons.
                    items:
                      $ref: '#/components/schemas/CouponResponse'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /coupons/get:
    get:
      summary: Buscar um cupom
      description: >
        Retorna os dados de um cupom específico baseado em filtros.


        Você pode usar essa rota para buscar um cupom por ID ou outros
        critérios.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Identificador único do cupom
          required: false
          schema:
            type: string
            example: MY_COUPON
      responses:
        '200':
          description: Cupom encontrado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CouponResponse'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Cupom não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Mensagem de erro indicando que o cupom não foi encontrado.
                    example: Cupom não encontrado.
  /coupons/delete:
    post:
      summary: Deletar um cupom
      description: |
        Remove um cupom da sua loja.

        Esta operação é irreversível. Use com cuidado.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          required: true
          description: Identificador único do cupom a ser deletado
          schema:
            type: string
            example: MY_COUPON
      responses:
        '200':
          description: Cupom deletado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CouponResponse'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Cupom não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Mensagem de erro indicando que o cupom não foi encontrado.
                    example: Cupom não encontrado.
  /coupons/toggle:
    post:
      summary: Alternar status de um cupom
      description: |
        Alterna o status de um cupom entre ativo e inativo.

        Use essa rota para ativar ou desativar um cupom sem precisar deletá-lo.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          required: true
          description: Identificador único do cupom
          schema:
            type: string
            example: MY_COUPON
      responses:
        '200':
          description: Status do cupom alternado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CouponResponse'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Cupom não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Mensagem de erro indicando que o cupom não foi encontrado.
                    example: Cupom não encontrado.
  /products/create:
    post:
      summary: Criar um produto
      description: >
        Permite que você crie um novo produto que pode ser usado em cobranças.

        Produtos podem ser avulsos (pagamento único) ou de assinatura; use o
        campo opcional `cycle` para definir a recorrência (`WEEKLY`, `MONTHLY`,
        `SEMIANNUALLY`, `ANNUALLY`). Quando `cycle` é omitido ou `null`, o
        produto é avulso.


        **Alternativa**: Você também pode criar e gerenciar seus produtos pelo
        [Dashboard da AbacatePay](https://app.abacatepay.com/produtos).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Dados necessários para criar um produto.
              required:
                - externalId
                - name
                - price
                - currency
              additionalProperties: false
              example:
                externalId: prod-123
                name: Produto Exemplo
                price: 10000
                currency: BRL
              properties:
                externalId:
                  type: string
                  description: Identificador único do produto no seu sistema.
                  example: prod-123
                name:
                  type: string
                  description: Nome do produto.
                  example: Produto Exemplo
                price:
                  type: number
                  description: Preço do produto em centavos.
                  minimum: 1
                  example: 10000
                currency:
                  type: string
                  description: Moeda do produto.
                  default: BRL
                  example: BRL
                description:
                  type: string
                  description: Descrição opcional do produto.
                  example: Descrição do produto
                  x-mint:
                    hidden: true
                imageUrl:
                  type: string
                  format: uri
                  nullable: true
                  description: URL da imagem do produto. Opcional.
                  example: null
                cycle:
                  type: string
                  nullable: true
                  description: >
                    Opcional. Indica se o produto é uma assinatura. Quando omitido
                    ou `null`, o produto é avulso (pagamento único).

                    Valores possíveis: `WEEKLY`, `MONTHLY`, `SEMIANNUALLY`,
                    `ANNUALLY`.
                  enum:
                    - WEEKLY
                    - MONTHLY
                    - SEMIANNUALLY
                    - ANNUALLY
                  example: null
      responses:
        '200':
          description: Produto criado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /products/list:
    get:
      summary: Listar produtos
      description: >
        Retorna todos os produtos que você criou com suporte a paginação.


        Você pode usar essa rota para visualizar todos os seus produtos,
        incluindo status, preços, ciclo de assinatura (quando aplicável) e
        demais informações.


        **Alternativa**: Você também pode visualizar e gerenciar seus produtos
        pelo [Dashboard da AbacatePay](https://app.abacatepay.com/produtos).
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único do produto
          required: false
          schema:
            type: string
            example: prod_abc123xyz
        - name: externalId
          in: query
          description: Filtrar por identificador do produto no seu sistema
          required: false
          schema:
            type: string
            example: prod-123
        - name: status
          in: query
          description: Filtrar por status do produto
          required: false
          schema:
            type: string
            enum:
              - ACTIVE
              - INACTIVE
      responses:
        '200':
          description: Lista de produtos retornada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de produtos.
                    items:
                      $ref: '#/components/schemas/Product'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /products/get:
    get:
      summary: Buscar um produto
      description: >
        Retorna os dados de um produto específico baseado em filtros, incluindo
        o campo `cycle` (assinatura ou avulso).


        Você pode usar essa rota para buscar um produto por ID ou externalId.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Identificador único público do produto
          required: false
          schema:
            type: string
            example: prod_abc123xyz
        - name: externalId
          in: query
          description: Identificador único do produto no seu sistema
          required: false
          schema:
            type: string
            example: prod-123
      responses:
        '200':
          description: Produto encontrado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Produto não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro indicando que o produto não foi
                      encontrado.
                    example: Produto não encontrado.
  /products/delete:
    post:
      summary: Deletar um produto
      description: |
        Remove um produto da sua loja (avulso ou de assinatura).

        Esta operação é irreversível. Use com cuidado.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          required: true
          description: Identificador único público do produto a ser deletado
          schema:
            type: string
            example: prod_abc123xyz
      responses:
        '200':
          description: Produto deletado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Product'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Produto não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro indicando que o produto não foi
                      encontrado.
                    example: Produto não encontrado.
  /checkouts/create:
    post:
      summary: Criar um Checkout
      description: Cria um Checkout para o cliente realizar o pagamento.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              additionalProperties: false
              example:
                items:
                  - id: prod-1234
                    quantity: 2
                methods: ["PIX", "CARD"]
              properties:
                items:
                  type: array
                  description: >
                    Lista de itens incluídos na cobrança.

                    Este é o único campo obrigatório — o valor total é calculado
                    a partir destes itens.
                  minItems: 1
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - id
                      - quantity
                    properties:
                      id:
                        type: string
                        description: ID público do produto na sua loja.
                        example: prod-1234
                      quantity:
                        type: integer
                        description: Quantidade deste item.
                        minimum: 1
                        example: 2
                methods:
                  type: array
                  description: Métodos de pagamento disponíveis. Padrão ["PIX", "CARD"].
                  items:
                    type: string
                    enum:
                      - PIX
                      - CARD
                  minItems: 1
                  default: ["PIX", "CARD"]
                  x-mint:
                    hidden: true
                returnUrl:
                  type: string
                  format: uri
                  description: >-
                    URL para onde o cliente será redirecionado ao clicar em
                    "Voltar" no checkout.
                  x-mint:
                    hidden: true
                completionUrl:
                  type: string
                  format: uri
                  description: >-
                    URL para onde o cliente será redirecionado após o pagamento
                    ser concluído.
                  x-mint:
                    hidden: true
                customerId:
                  type: string
                  description: >
                    ID de um cliente já cadastrado na sua loja.

                    Se informado, o checkout será pré-preenchido com os dados
                    deste cliente.


                    **Exemplo**: `"cust_abcdefghij"`
                  x-mint:
                    hidden: true
                coupons:
                  type: array
                  description: |
                    Lista de cupons que podem ser utilizados nesta cobrança.

                    **Exemplo**: `["ABKT10", "ABKT5", "PROMO10"]`
                  items:
                    type: string
                  maxItems: 50
                  x-mint:
                    hidden: true
                externalId:
                  type: string
                  description: >
                    ID da cobrança no seu sistema, caso queira manter uma
                    referência própria.


                    **Exemplo**: `"seu_id_123"`
                  x-mint:
                    hidden: true
                upSellProductId:
                  type: string
                  description: >
                    ID de um produto avulso (sem `cycle`) a ser ofertado como
                    upsell após a conclusão do pagamento.


                    O produto deve estar com `status: ACTIVE` e **não pode ter
                    `cycle`** — apenas produtos de pagamento único são aceitos.


                    **Exemplo**: `"prod_bump456xyz"`
                  x-mint:
                    hidden: true
                interest:
                  description: >-
                    Juros por atraso, aplicados apenas quando
                    `methods` inclui `BOLETO`. Ignorado para PIX/CARD.
                  allOf:
                    - $ref: '#/components/schemas/BoletoInterest'
                  x-mint:
                    hidden: true
                fine:
                  description: >-
                    Multa por atraso, aplicada apenas quando
                    `methods` inclui `BOLETO`. Ignorado para PIX/CARD.
                  allOf:
                    - $ref: '#/components/schemas/BoletoFine'
                  x-mint:
                    hidden: true
                metadata:
                  type: object
                  description: >
                    Metadados adicionais da cobrança. Campo livre para a sua
                    aplicação.


                    **Exemplo**:

                    ```json

                    {
                      "source": "landing-page-black-friday",
                      "campaign": "BF-2025"
                    }

                    ```
                  additionalProperties: true
                  x-mint:
                    hidden: true
      responses:
        '200':
          description: Cobrança criada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Billing'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Motivo da falha na autenticação.
                    example: Token de autenticação inválido ou ausente.
  /checkouts/get:
    get:
      summary: Buscar um Checkout
      description: >
        Retorna os dados de um Checkout específico usando o ID.


        Você pode usar essa rota para buscar um Checkout por ID e visualizar
        seus detalhes, status e informações relacionadas.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Identificador único do Checkout
          required: true
          schema:
            type: string
            example: bill_abc123xyz
      responses:
        '200':
          description: Cobrança encontrada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Billing'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Cobrança não encontrada.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro indicando que a cobrança não foi
                      encontrada.
                    example: Cobrança não encontrada.
  /payment-links/create:
    post:
      summary: Criar um link de pagamento
      description: >
        Cria um link de pagamento (checkout com frequency MULTIPLE_PAYMENTS).
        Vários clientes podem pagar o mesmo link; não suporta customerId.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              additionalProperties: false
              example:
                frequency: MULTIPLE_PAYMENTS
                items:
                  - id: prod-1234
                    quantity: 2
                methods: ["PIX", "CARD"]
              properties:
                frequency:
                  type: string
                  description: Tipo de cobrança fixo para links de pagamento.
                  enum:
                    - MULTIPLE_PAYMENTS
                  default: MULTIPLE_PAYMENTS
                  example: MULTIPLE_PAYMENTS
                items:
                  type: array
                  description: >
                    Lista de itens incluídos na cobrança.

                    Este é o único campo obrigatório — o valor total é calculado
                    a partir destes itens.
                  minItems: 1
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - id
                      - quantity
                    properties:
                      id:
                        type: string
                        description: ID público do produto na sua loja.
                        example: prod-1234
                      quantity:
                        type: integer
                        description: Quantidade deste item.
                        minimum: 1
                        example: 2
                methods:
                  type: array
                  description: Métodos de pagamento disponíveis. Padrão ["PIX", "CARD"].
                  items:
                    type: string
                    enum:
                      - PIX
                      - CARD
                  minItems: 1
                  default: ["PIX", "CARD"]
                  x-mint:
                    hidden: true
                returnUrl:
                  type: string
                  format: uri
                  description: >-
                    URL para onde o cliente será redirecionado ao clicar em
                    "Voltar" no checkout.
                  x-mint:
                    hidden: true
                completionUrl:
                  type: string
                  format: uri
                  description: >-
                    URL para onde o cliente será redirecionado após o pagamento
                    ser concluído.
                  x-mint:
                    hidden: true
                coupons:
                  type: array
                  description: |
                    Lista de cupons que podem ser utilizados nesta cobrança.

                    **Exemplo**: `["ABKT10", "ABKT5", "PROMO10"]`
                  items:
                    type: string
                  maxItems: 50
                  x-mint:
                    hidden: true
                externalId:
                  type: string
                  description: >
                    ID da cobrança no seu sistema, caso queira manter uma
                    referência própria.


                    **Exemplo**: `"seu_id_123"`
                  x-mint:
                    hidden: true
                interest:
                  description: >-
                    Juros por atraso, aplicados apenas quando
                    `methods` inclui `BOLETO`. Ignorado para PIX/CARD.
                  allOf:
                    - $ref: '#/components/schemas/BoletoInterest'
                  x-mint:
                    hidden: true
                fine:
                  description: >-
                    Multa por atraso, aplicada apenas quando
                    `methods` inclui `BOLETO`. Ignorado para PIX/CARD.
                  allOf:
                    - $ref: '#/components/schemas/BoletoFine'
                  x-mint:
                    hidden: true
                metadata:
                  type: object
                  description: >
                    Metadados adicionais da cobrança. Campo livre para a sua
                    aplicação.


                    **Exemplo**:

                    ```json

                    {
                      "source": "landing-page-black-friday",
                      "campaign": "BF-2025"
                    }

                    ```
                  additionalProperties: true
                  x-mint:
                    hidden: true
      responses:
        '200':
          description: Link de pagamento criado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Billing'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /checkouts/list:
    get:
      summary: Listar Checkouts
      description: >
        Retorna todos os Checkouts que você criou.


        Você pode usar essa rota para listar todos seus Checkouts e visualizar
        seus status, valores e informações relacionadas.
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único do Checkout
          required: false
          schema:
            type: string
            example: bill_abc123xyz
        - name: externalId
          in: query
          description: Filtrar por identificador do Checkout no seu sistema
          required: false
          schema:
            type: string
            example: pedido-123
        - name: status
          in: query
          description: Filtrar por status do Checkout
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - EXPIRED
              - CANCELLED
              - PAID
              - REFUNDED
        - name: email
          in: query
          description: Filtrar por e-mail do cliente associado
          required: false
          schema:
            type: string
            example: daniel_lima@abacatepay.com
        - name: taxId
          in: query
          description: Filtrar por CPF ou CNPJ do cliente associado
          required: false
          schema:
            type: string
            example: 123.456.789-01
      responses:
        '200':
          description: Checkouts listados com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de Checkouts.
                    items:
                      $ref: '#/components/schemas/Billing'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Token de autenticação inválido ou ausente.
  /payment-links/list:
    get:
      summary: Listar links de pagamento
      description: >
        Lista apenas links de pagamento (checkouts com frequency MULTIPLE_PAYMENTS).
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único do link de pagamento
          required: false
          schema:
            type: string
            example: bill_abc123xyz
        - name: externalId
          in: query
          description: Filtrar por identificador do link no seu sistema
          required: false
          schema:
            type: string
            example: pedido-123
        - name: status
          in: query
          description: Filtrar por status do link de pagamento
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - EXPIRED
              - CANCELLED
              - PAID
              - REFUNDED
      responses:
        '200':
          description: Links de pagamento listados com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de links de pagamento.
                    items:
                      $ref: '#/components/schemas/Billing'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Token de autenticação inválido ou ausente.
  /payment-links/get:
    get:
      summary: Buscar um link de pagamento
      description: >
        Retorna os dados de um link de pagamento específico (checkout com
        frequency MULTIPLE_PAYMENTS) usando o ID.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Identificador único do link de pagamento
          required: true
          schema:
            type: string
            example: bill_abc123xyz
      responses:
        '200':
          description: Link de pagamento encontrado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Billing'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Link de pagamento não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro indicando que o link de pagamento não foi
                      encontrado.
                    example: Link de pagamento não encontrado.
  /transparents/create:
    post:
      summary: Criar Checkout Transparente
      description: >-
        Cria um checkout transparente. Use `"method": "PIX"` para gerar um QR
        Code ou `"method": "BOLETO"` para emitir um boleto com PIX alternativo
        incluído.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                method:
                  type: string
                  description: Método de pagamento.
                  enum:
                    - PIX
                    - BOLETO
                  default: PIX
                  example: PIX
                data:
                  type: object
                  description: Dados da cobrança.
                  properties:
                    amount:
                      type: number
                      description: Valor da cobrança em centavos.
                    expiresIn:
                      type: number
                      description: PIX — expiração em segundos.
                      x-mint:
                        hidden: true
                    description:
                      type: string
                      maxLength: 500
                      description: Descrição da cobrança.
                      x-mint:
                        hidden: true
                    customer:
                      type: object
                      description: >
                        Dados do pagador. Obrigatório para BOLETO (`name` e
                        `taxId` sempre exigidos). Para PIX, se informado, todos
                        os campos são obrigatórios.
                      required:
                        - name
                        - taxId
                      additionalProperties: false
                      x-mint:
                        hidden: true
                      properties:
                        name:
                          type: string
                          example: Daniel Lima
                        taxId:
                          type: string
                          example: 123.456.789-01
                        email:
                          type: string
                          example: daniel_lima@abacatepay.com
                        cellphone:
                          type: string
                          example: (11) 4002-8922
                    externalId:
                      type: string
                      description: ID no seu sistema para idempotência.
                      x-mint:
                        hidden: true
                    interest:
                      description: >-
                        BOLETO — juros por atraso. Ignorado quando
                        `method` é `PIX`.
                      allOf:
                        - $ref: '#/components/schemas/BoletoInterest'
                      x-mint:
                        hidden: true
                    fine:
                      description: >-
                        BOLETO — multa por atraso. Ignorado quando
                        `method` é `PIX`.
                      allOf:
                        - $ref: '#/components/schemas/BoletoFine'
                      x-mint:
                        hidden: true
                    metadata:
                      type: object
                      additionalProperties: true
                      x-mint:
                        hidden: true
                  required:
                    - amount
                  additionalProperties: false
              required:
                - method
                - data
              additionalProperties: false
      responses:
        '200':
          description: Checkout transparente criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TransparentCharge'
                  error:
                    type: string
                    example: null
                    nullable: true
                  success:
                    $ref: '#/components/schemas/Success'
              example:
                data:
                  id: bole_k8pqr2mnvx
                  amount: 25000
                  status: PENDING
                  devMode: false
                  barCode: 23793.38128 60007.827263 37000.963779 4 10010000025000
                  url: https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto
                  brCode: 00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5914Mariana Costa6009SAO PAULO62070503***6304F1C2
                  brCodeBase64: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
                  platformFee: 250
                  expiresAt: '2024-11-07T03:00:00.000Z'
                  createdAt: '2024-11-04T14:22:10.381Z'
                  updatedAt: '2024-11-04T14:22:10.381Z'
                  metadata:
                    faturaId: fatura-456
                    plano: pro
                error: null
                success:
                  message: Checkout transparente criado com sucesso
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Token de autenticação inválido ou ausente.
  /transparents/check:
    get:
      summary: Checar Status
      description: Checar status do pagamento do QRCode Pix.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Status retornado
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Identificador único do Checkout Transparente.
                        example: pix_char_z2rSk6042t1mCKgGgeBpJe1u
                      status:
                        type: string
                        description: Informação sobre o andamento do QRCode Pix.
                        enum:
                          - PENDING
                          - EXPIRED
                          - CANCELLED
                          - PAID
                          - UNDER_DISPUTE
                          - REFUNDED
                          - REDEEMED
                          - APPROVED
                          - FAILED
                        example: PENDING
                      expiresAt:
                        type: string
                        description: Data de expiração do QRCode Pix
                        example: '2026-03-04T15:48:59.876Z'
                  error:
                    type: string
                    example: null
                    nullable: true
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
      parameters:
        - name: id
          in: query
          description: Identificador único do Checkout Transparente
          required: true
          schema:
            type: string
  /transparents/simulate-payment:
    post:
      summary: Simular Pagamento
      description: Simula o pagamento de um QRCode Pix criado no modo de desenvolvimento.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  description: Metadados opcionais para a requisição
                  default: {}
      responses:
        '200':
          description: Pagamento ralizado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PixQRCode'
                  error:
                    type: string
                    example: null
                    nullable: true
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
      parameters:
        - name: id
          in: query
          description: Identificador único do Checkout Transparente
          required: true
          schema:
            type: string
  /transparents/list:
    get:
      summary: Listar Checkouts Transparentes
      description: >
        Retorna todos os Checkouts Transparentes (QRCodes PIX) que você criou.


        Você pode usar essa rota para listar todos os seus checkouts
        transparentes e visualizar seus status, valores e informações
        relacionadas.
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único do QRCode Pix
          required: false
          schema:
            type: string
            example: pix_char_123456
        - name: status
          in: query
          description: Filtrar por status do QRCode Pix
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - EXPIRED
              - CANCELLED
              - PAID
              - REFUNDED
      responses:
        '200':
          description: Checkouts transparentes listados com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de Checkouts Transparentes (QRCodes PIX).
                    items:
                      $ref: '#/components/schemas/PixQRCode'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /payouts/create:
    post:
      summary: Criar um payout
      description: >
        Permite que você crie um novo payout para transferir valores da sua
        conta AbacatePay.


        Você pode usar esta rota para:

        - **Realizar saques** da sua conta para sua própria chave PIX

        - **Enviar dinheiro** para outras contas

        - **Realizar pagamentos** diretamente pela API

        - **Efetuar transferências** para fornecedores, parceiros ou terceiros


        **Importante**: A chave PIX de destino não precisa ter a mesma
        titularidade do CNPJ da sua conta. Você pode realizar payouts para
        qualquer chave PIX válida.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Dados necessários para criar um payout.
              required:
                - amount
                - externalId
              additionalProperties: false
              example:
                amount: 10000
                externalId: saque-123
              properties:
                amount:
                  type: number
                  description: Valor do payout em centavos.
                  minimum: 350
                  example: 10000
                description:
                  type: string
                  description: Descrição opcional do payout.
                  example: Saque para conta bancária
                  x-mint:
                    hidden: true
                externalId:
                  type: string
                  description: Identificador único do payout em seu sistema.
                  example: saque-123
      responses:
        '200':
          description: Payout criado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Dados da transação de payout criada.
                    properties:
                      id:
                        type: string
                        description: Identificador único da transação.
                        example: txn_abc123xyz
                      status:
                        type: string
                        description: Status atual da transação.
                        enum:
                          - PENDING
                          - EXPIRED
                          - CANCELLED
                          - COMPLETE
                          - REFUNDED
                        example: PENDING
                      devMode:
                        type: boolean
                        description: >-
                          Indica se a transação foi criada em ambiente de
                          testes.
                        example: false
                      receiptUrl:
                        type: string
                        format: uri
                        nullable: true
                        description: URL do comprovante da transação.
                        example: null
                      amount:
                        type: number
                        description: Valor da transação em centavos.
                        example: 10000
                      platformFee:
                        type: number
                        description: Taxa da plataforma em centavos.
                        example: 100
                      externalId:
                        type: string
                        description: Identificador externo da transação.
                        example: saque-123
                      createdAt:
                        type: string
                        format: date-time
                        description: Data de criação da transação.
                        example: '2024-11-04T18:38:28.573Z'
                      updatedAt:
                        type: string
                        format: date-time
                        description: Data de atualização da transação.
                        example: '2024-11-04T18:38:28.573Z'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /payouts/get:
    get:
      summary: Buscar payout
      description: >-
        Permite que você recupere os detalhes de um payout específico usando o
        externalId.
      security:
        - bearerAuth: []
      parameters:
        - name: externalId
          in: query
          description: Identificador único do payout em seu sistema.
          required: true
          schema:
            type: string
            example: saque-123
      responses:
        '200':
          description: Detalhes do payout retornados com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Dados da transação de payout.
                    properties:
                      id:
                        type: string
                        description: Identificador único da transação.
                        example: txn_abc123xyz
                      status:
                        type: string
                        description: Status atual da transação.
                        enum:
                          - PENDING
                          - EXPIRED
                          - CANCELLED
                          - COMPLETE
                          - REFUNDED
                        example: COMPLETE
                      devMode:
                        type: boolean
                        description: >-
                          Indica se a transação foi criada em ambiente de
                          testes.
                        example: false
                      receiptUrl:
                        type: string
                        format: uri
                        nullable: true
                        description: URL do comprovante da transação.
                        example: 'https://app.abacatepay.com/receipt/txn_abc123xyz'
                      amount:
                        type: number
                        description: Valor da transação em centavos.
                        example: 10000
                      platformFee:
                        type: number
                        description: Taxa da plataforma em centavos.
                        example: 100
                      externalId:
                        type: string
                        description: Identificador externo da transação.
                        example: saque-123
                      createdAt:
                        type: string
                        format: date-time
                        description: Data de criação da transação.
                        example: '2024-11-04T18:38:28.573Z'
                      updatedAt:
                        type: string
                        format: date-time
                        description: Data de atualização da transação.
                        example: '2024-11-04T19:15:42.123Z'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Saque não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                    nullable: true
                    example: null
                  error:
                    type: string
                    description: Mensagem de erro indicando que o saque não foi encontrado.
                    example: Saque não encontrado com o externalId fornecido.
  /payouts/list:
    get:
      summary: Listar payouts
      description: >
        Permite que você recupere uma lista de todos os payouts criados com
        suporte a paginação.
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único da transação
          required: false
          schema:
            type: string
            example: tran_123456
        - name: externalId
          in: query
          description: Filtrar por identificador do payout no seu sistema
          required: false
          schema:
            type: string
            example: saque-123
        - name: status
          in: query
          description: Filtrar por status da transação
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - EXPIRED
              - CANCELLED
              - COMPLETE
              - REFUNDED
      responses:
        '200':
          description: Lista de payouts retornada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de saques criados.
                    items:
                      $ref: '#/components/schemas/Transaction'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /pix/send:
    post:
      summary: Enviar PIX
      description: >
        Permite que você envie dinheiro via PIX para qualquer chave PIX que não
        seja do titular da conta.


        Você pode usar esta rota para:

        - **Enviar pagamentos** para fornecedores, parceiros ou terceiros

        - **Realizar transferências** para contas de outras pessoas ou empresas

        - **Efetuar pagamentos** diretamente pela API


        **Importante**: Esta funcionalidade é diferente dos payouts, pois
        permite enviar dinheiro para chaves PIX que não pertencem ao titular da
        conta. Use payouts quando quiser enviar para sua própria chave PIX.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Dados necessários para enviar um PIX.
              required:
                - amount
                - externalId
                - pix
              additionalProperties: false
              example:
                amount: 10000
                externalId: pix-123
                description: Pagamento para fornecedor
                pix:
                  key: '11987654321'
                  type: PHONE
              properties:
                amount:
                  type: number
                  description: Valor do PIX em centavos.
                  minimum: 1
                  example: 10000
                externalId:
                  type: string
                  description: Identificador único do PIX em seu sistema.
                  example: pix-123
                description:
                  type: string
                  description: Descrição opcional do PIX.
                  example: Pagamento para fornecedor
                  x-mint:
                    hidden: true
                pix:
                  type: object
                  description: Dados da chave PIX de destino.
                  required:
                    - key
                    - type
                  additionalProperties: false
                  properties:
                    key:
                      type: string
                      description: Chave PIX de destino.
                      example: '11987654321'
                    type:
                      type: string
                      description: Tipo da chave PIX.
                      enum:
                        - CPF
                        - CNPJ
                        - PHONE
                        - EMAIL
                        - RANDOM
                        - BR_CODE
                      example: PHONE
      responses:
        '200':
          description: PIX enviado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PixTransaction'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /pix/get:
    get:
      summary: Buscar PIX
      description: >
        Permite que você recupere os detalhes de uma transação PIX específica
        usando o ID ou externalId.


        Você pode buscar usando:

        - `id`: Identificador único da transação PIX na AbacatePay

        - `externalId`: Identificador único do PIX em seu sistema


        **Importante**: Você deve fornecer pelo menos um dos parâmetros (`id` ou
        `externalId`).
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Identificador único da transação PIX na AbacatePay.
          required: false
          schema:
            type: string
            example: txn_abc123xyz
        - name: externalId
          in: query
          description: Identificador único do PIX em seu sistema.
          required: false
          schema:
            type: string
            example: pix-123
      responses:
        '200':
          description: Detalhes do PIX retornados com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PixTransaction'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: PIX não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                    nullable: true
                    example: null
                  error:
                    type: string
                    description: Mensagem de erro indicando que o PIX não foi encontrado.
                    example: PIX não encontrado com o ID ou externalId fornecido.
  /pix/list:
    get:
      summary: Listar PIX
      description: |
        Permite que você recupere uma lista de transações PIX criadas.

        Você pode filtrar usando:
        - `id`: Identificador único da transação PIX na AbacatePay
        - `externalId`: Identificador único do PIX em seu sistema
        - `status`: Status da transação
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único da transação PIX na AbacatePay
          required: false
          schema:
            type: string
            example: txn_abc123xyz
        - name: externalId
          in: query
          description: Filtrar por identificador do PIX em seu sistema
          required: false
          schema:
            type: string
            example: pix-123
        - name: status
          in: query
          description: Filtrar por status da transação
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - EXPIRED
              - CANCELLED
              - COMPLETE
              - REFUNDED
      responses:
        '200':
          description: Lista de PIX retornada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de transações PIX criadas.
                    items:
                      $ref: '#/components/schemas/PixTransaction'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /subscriptions/create:
    post:
      summary: Criar uma nova assinatura (Checkout de assinatura)
      description: >
        Cria um Checkout de assinatura — uma página de pagamento igual ao
        Checkout comum, mas para cobrança recorrente.


        Aceita os mesmos parâmetros do Checkout (`returnUrl`, `completionUrl`,
        `customerId`, `externalId`, `metadata`, `coupons`, `methods`). O Checkout
        de assinatura aceita **apenas um produto**; o ciclo (frequência) já deve
        estar definido no produto ao criá-lo na loja — não é enviado no
        checkout.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >
                Mesmos parâmetros do Checkout, com `items` contendo exatamente
                um item (`id` e `quantity`).

                O produto referenciado deve ter sido criado com ciclo de
                assinatura (frequency) na loja.
              required:
                - items
              additionalProperties: false
              example:
                items:
                  - id: prod-1234
                    quantity: 1
                customerId: cust_abc123xyz
                methods: ["CARD"]
              properties:
                items:
                  type: array
                  description: >
                    Lista com **exatamente um** item. O produto deve ter sido
                    criado com ciclo de assinatura (frequency).

                    O valor total é calculado a partir do produto.
                  minItems: 1
                  maxItems: 1
                  items:
                    type: object
                    required:
                      - id
                      - quantity
                    additionalProperties: false
                    properties:
                      id:
                        type: string
                        description: >-
                          ID público do produto na sua loja (produto criado com
                          ciclo de assinatura).
                        example: prod-1234
                      quantity:
                        type: integer
                        description: Quantidade (geralmente 1 para assinatura).
                        minimum: 1
                        example: 1
                methods:
                  type: array
                  description: Métodos de pagamento disponíveis. Assinaturas suportam apenas CARD. Padrão ["CARD"].
                  items:
                    type: string
                    enum:
                      - PIX
                      - CARD
                  minItems: 1
                  default: ["CARD"]
                returnUrl:
                  type: string
                  format: uri
                  description: >-
                    URL para onde o cliente será redirecionado ao clicar em
                    "Voltar" no checkout.
                completionUrl:
                  type: string
                  format: uri
                  description: >-
                    URL para onde o cliente será redirecionado após o pagamento
                    ser concluído.
                customerId:
                  type: string
                  description: >
                    ID de um cliente já cadastrado na sua loja.

                    Se informado, o checkout será pré-preenchido com os dados
                    deste cliente.
                coupons:
                  type: array
                  description: Lista de cupons que podem ser utilizados nesta cobrança.
                  items:
                    type: string
                  maxItems: 50
                externalId:
                  type: string
                  description: >-
                    ID da assinatura no seu sistema, caso queira manter uma
                    referência própria.
                metadata:
                  type: object
                  description: Metadados adicionais. Campo livre para a sua aplicação.
                  additionalProperties: true
      responses:
        '200':
          description: >-
            Checkout de assinatura criado com sucesso. Use a `url` retornada
            para redirecionar o cliente.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Billing'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /subscriptions/list:
    get:
      summary: Listar assinaturas (Checkouts de assinatura)
      description: >
        Retorna todos os Checkouts de assinatura que você criou, com suporte a
        paginação baseada em cursor.

        Cada item possui o mesmo formato de um Checkout: `id`, `url`,
        `amount`, `items`, `status`, etc.
      security:
        - bearerAuth: []
      parameters:
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único do Checkout de assinatura
          required: false
          schema:
            type: string
            example: bill_abc123xyz
        - name: externalId
          in: query
          description: Filtrar por identificador da assinatura no seu sistema
          required: false
          schema:
            type: string
            example: subs-123
        - name: status
          in: query
          description: Filtrar por status do Checkout de assinatura
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - EXPIRED
              - CANCELLED
              - PAID
              - REFUNDED
        - name: email
          in: query
          description: Filtrar por e-mail do cliente associado
          required: false
          schema:
            type: string
            example: daniel_lima@abacatepay.com
        - name: taxId
          in: query
          description: Filtrar por CPF ou CNPJ do cliente associado
          required: false
          schema:
            type: string
            example: 123.456.789-01
      responses:
        '200':
          description: Lista de Checkouts de assinatura retornada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: >-
                      Lista de Checkouts de assinatura (mesmo payload de
                      Checkout).
                    items:
                      $ref: '#/components/schemas/Billing'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /subscriptions/cancel:
    post:
      summary: Cancelar uma assinatura
      description: |
        Cancela imediatamente uma assinatura ativa.

        A assinatura passa para o status `CANCELLED` e nenhuma cobrança futura será gerada. Esta operação é irreversível.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              additionalProperties: false
              properties:
                id:
                  type: string
                  description: Identificador único da assinatura a ser cancelada
                  example: subs_abc123xyz
      responses:
        '200':
          description: Assinatura cancelada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Subscription'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Assinatura não encontrada.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Mensagem de erro indicando que a assinatura não foi encontrada.
                    example: Subscription not found
  /subscriptions/change-plan:
    post:
      summary: Alterar plano da assinatura
      description: |
        Altera o produto principal de uma assinatura ativa.

        A mudança é agendada como `PENDING` e aplicada automaticamente no início do próximo ciclo de cobrança. Só pode existir uma alteração pendente por assinatura — uma nova chamada substitui a anterior ainda não aplicada.

        O produto informado em `productId` deve ter um ciclo de cobrança definido. Produtos avulsos (sem ciclo) retornam erro.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - productId
                - quantity
              additionalProperties: false
              properties:
                id:
                  type: string
                  description: Identificador único da assinatura a ser alterada.
                  example: subs_abc123xyz
                productId:
                  type: string
                  description: Identificador do novo produto. Deve ter ciclo de cobrança definido.
                  example: prod_plano_pro
                quantity:
                  type: integer
                  minimum: 1
                  description: Quantidade do novo produto.
                  example: 1
      responses:
        '200':
          description: Alteração de plano agendada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionUpdate'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Assinatura ou produto não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Subscription not found or not active
        '422':
          description: "Dados inválidos (ex: produto sem ciclo)."
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Product must have a billing cycle
  /subscriptions/record-usage:
    post:
      summary: Registrar uso
      description: |
        Registra unidades de uso de um produto avulso (pay-as-you-go) em uma assinatura ativa.

        O registro é vinculado à próxima parcela pendente da assinatura e incluído na cobrança do ciclo atual. Use `action: "add"` para acrescentar unidades e `action: "subtract"` para estornar unidades já registradas.

        O produto informado em `productId` **não** deve ter ciclo de cobrança. Produtos de assinatura (com ciclo) retornam erro.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - productId
                - units
                - action
              additionalProperties: false
              properties:
                id:
                  type: string
                  description: Identificador único da assinatura.
                  example: subs_abc123xyz
                productId:
                  type: string
                  description: Identificador do produto de uso. Não deve ter ciclo de cobrança.
                  example: prod_api_calls
                units:
                  type: integer
                  minimum: 1
                  description: Quantidade de unidades a registrar.
                  example: 50
                action:
                  type: string
                  enum:
                    - add
                    - subtract
                  description: >-
                    `add` para acrescentar unidades à próxima cobrança;
                    `subtract` para estornar unidades já registradas no ciclo.
                  example: add
      responses:
        '200':
          description: Uso registrado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubscriptionUsageRecord'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Assinatura ou produto não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Subscription not found or not active
        '422':
          description: "Dados inválidos (ex: produto com ciclo enviado em vez de produto avulso)."
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Product must not have a billing cycle
  /store/get:
    get:
      summary: Obter detalhes da loja
      description: >-
        Permite que você recupere os detalhes da sua conta/loja, incluindo
        informações de saldo.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Detalhes da loja retornados com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Store'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /public-mrr/merchant-info:
    get:
      summary: Obter informações do merchant
      description: >-
        Retorna informações básicas da loja (ID, nome, website e data de
        criação).
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Informações do merchant retornadas com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Identificador único da loja
                        example: store_abc123xyz
                      name:
                        type: string
                        description: Nome da loja
                        example: Example Tech
                      website:
                        type: string
                        description: Website da loja
                        example: 'https://www.example.com'
                      createdAt:
                        type: string
                        format: date-time
                        description: Data de criação da loja
                        example: '2024-12-06T18:53:31.756Z'
                    required:
                      - id
                      - name
                      - website
                      - createdAt
                    additionalProperties: false
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /public-mrr/mrr:
    get:
      summary: Obter MRR (Monthly Recurring Revenue)
      description: >-
        Retorna o MRR (receita recorrente mensal) e o total de assinaturas
        ativas da loja.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Dados de MRR retornados com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      mrr:
                        type: number
                        description: >-
                          Receita recorrente mensal em centavos. Valor 0 indica
                          que não há receita recorrente no momento.
                        example: 0
                      totalActiveSubscriptions:
                        type: integer
                        description: >-
                          Total de assinaturas ativas. Valor 0 indica que não há
                          assinaturas ativas no momento.
                        example: 0
                    required:
                      - mrr
                      - totalActiveSubscriptions
                    additionalProperties: false
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /public-mrr/revenue:
    get:
      summary: Obter receita por período
      description: >-
        Retorna a receita total, total de transações e transações por dia em um
        período específico. Os dados são cacheados por 1 hora (3600 segundos)
        para melhor performance. A data de fim deve ser posterior à data de
        início.
      security:
        - bearerAuth: []
      parameters:
        - name: startDate
          in: query
          required: true
          description: Data de início do período (formato YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: '2024-01-01'
        - name: endDate
          in: query
          required: true
          description: Data de fim do período (formato YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: '2024-01-31'
      responses:
        '200':
          description: Dados de receita retornados com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      totalRevenue:
                        type: number
                        description: Receita total do período em centavos
                        example: 150000
                      totalTransactions:
                        type: integer
                        description: Total de transações no período
                        example: 45
                      transactionsPerDay:
                        type: object
                        description: >-
                          Objeto com transações agrupadas por dia (chave é a
                          data no formato YYYY-MM-DD)
                        additionalProperties:
                          type: object
                          properties:
                            amount:
                              type: number
                              description: Valor total das transações do dia em centavos
                              example: 5000
                            count:
                              type: integer
                              description: Quantidade de transações do dia
                              example: 3
                          required:
                            - amount
                            - count
                          additionalProperties: false
                        example:
                          '2024-01-15':
                            amount: 5000
                            count: 3
                          '2024-01-16':
                            amount: 3000
                            count: 2
                    required:
                      - totalRevenue
                      - totalTransactions
                      - transactionsPerDay
                    additionalProperties: false
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '400':
          description: Erro de validação. Parâmetros inválidos ou ausentes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Mensagem de erro descrevendo o problema de validação.
                    example: Start date and end date are required
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /webhooks/create:
    post:
      summary: Criar um webhook
      description: >
        Cria um novo webhook para receber notificações automáticas de eventos da
        sua loja.


        O `endpoint` deve ser uma URL HTTPS válida e não pode apontar para
        endereços locais ou IPs privados.


        **Alternativa**: Você também pode criar e gerenciar seus webhooks pelo
        [Dashboard da AbacatePay](https://app.abacatepay.com/webhooks).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateInput'
      responses:
        '200':
          description: Webhook criado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookResponse'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /webhooks/list:
    get:
      summary: Listar webhooks
      description: >
        Retorna todos os webhooks da sua loja com suporte a paginação e busca.


        **Alternativa**: Você também pode visualizar e gerenciar seus webhooks
        pelo [Dashboard da AbacatePay](https://app.abacatepay.com/webhooks).
      security:
        - bearerAuth: []
      parameters:
        - name: search
          in: query
          description: Busca por nome, ID ou endpoint do webhook
          required: false
          schema:
            type: string
            example: pagamentos
        - name: after
          in: query
          description: Cursor para buscar itens após este ponto
          required: false
          schema:
            type: string
        - name: before
          in: query
          description: Cursor para buscar itens antes deste ponto
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Quantidade de itens por página (1-100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            example: 100
        - name: id
          in: query
          description: Filtrar por identificador único do webhook
          required: false
          schema:
            type: string
            example: webh_abc123xyz
      responses:
        '200':
          description: Lista de webhooks retornada com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Lista de webhooks.
                    items:
                      $ref: '#/components/schemas/WebhookResponse'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
  /webhooks/get:
    get:
      summary: Buscar um webhook
      description: Retorna os dados de um webhook específico pelo seu identificador.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          description: Identificador único do webhook
          required: true
          schema:
            type: string
            example: webh_abc123xyz
      responses:
        '200':
          description: Webhook encontrado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookResponse'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Webhook não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Mensagem de erro indicando que o webhook não foi encontrado.
                    example: Webhook não encontrado.
  /webhooks/delete:
    post:
      summary: Deletar um webhook
      description: |
        Remove um webhook da sua loja.

        Esta operação é irreversível. Use com cuidado.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              additionalProperties: false
              properties:
                id:
                  type: string
                  description: Identificador único do webhook a ser deletado
                  example: webh_abc123xyz
      responses:
        '200':
          description: Webhook deletado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookResponse'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
        '404':
          description: Webhook não encontrado.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Mensagem de erro indicando que o webhook não foi encontrado.
                    example: Webhook não encontrado.
components:
  schemas:
    Success:
      type: boolean
      description: Se a requisição obteve sucesso ou não.
      example: true
    PaginationCursor:
      type: object
      description: Informações de paginação baseada em cursor.
      required:
        - hasMore
        - next
        - before
      additionalProperties: false
      properties:
        hasMore:
          type: boolean
          description: Indica se existe mais itens para carregar.
        next:
          type: string
          nullable: true
          description: Cursor para próxima página (usar em after).
        before:
          type: string
          nullable: true
          description: Cursor para página anterior (usar em before).
    BoletoInterest:
      type: object
      description: >-
        Juros por atraso aplicados ao boleto após o vencimento. Late interest
        applied to the boleto after the due date. Aplica-se apenas a
        `method: "BOLETO"`; ignorado nos demais métodos.
      additionalProperties: false
      required:
        - value
      properties:
        value:
          type: integer
          minimum: 0
          description: >-
            Percentual de juros ao mês em centésimos de percentual
            (`100` = 1% ao mês, `250` = 2,5% ao mês). Quando `0` ou omitido,
            sem juros. Calculado pro rata die após o vencimento.

            EN: Monthly late-interest rate in hundredths of a percent
            (`100` = 1%/month). Accrues pro rata die after the due date;
            `0` or omitted disables interest.
          example: 100
    BoletoFine:
      type: object
      description: >-
        Multa por atraso aplicada uma única vez após o vencimento do boleto.
        One-time late fine applied after the due date. Aplica-se apenas a
        `method: "BOLETO"`; ignorado nos demais métodos.
      additionalProperties: false
      required:
        - value
        - type
      properties:
        value:
          type: integer
          minimum: 0
          description: >-
            Quando `type = "PERCENTAGE"`: centésimos de percentual sobre o
            valor do boleto (`200` = 2%). Quando `type = "FIXED"`: valor fixo
            em centavos (`1000` = R$ 10,00). Quando `0` ou omitido, sem multa.

            EN: With `type: "PERCENTAGE"`, value is in hundredths of a percent
            (`200` = 2%). With `type: "FIXED"`, value is in cents
            (`1000` = R$ 10.00). `0` or omitted disables the fine.
          example: 200
        type:
          type: string
          description: >-
            Tipo da multa. `PERCENTAGE` aplica percentual sobre o valor do
            boleto; `FIXED` aplica um valor fixo em centavos.

            EN: Fine type. `PERCENTAGE` applies a percent of the boleto
            amount; `FIXED` applies a fixed amount in cents.
          enum:
            - PERCENTAGE
            - FIXED
          example: PERCENTAGE
    Customer:
      type: object
      description: Os dados do seu cliente.
      required:
        - id
        - devMode
        - name
        - cellphone
        - email
        - taxId
      additionalProperties: false
      properties:
        id:
          type: string
          description: Identificador único público do cliente
          example: cust_aebxkhDZNaMmJeKsy0AHS0FQ
        devMode:
          type: boolean
          description: Indica se o cliente foi criado em ambiente de testes.
          example: true
        name:
          type: string
          description: Nome completo do cliente
          example: Daniel Lima
        cellphone:
          type: string
          description: Celular do cliente
          example: (11) 4002-8922
        email:
          type: string
          description: E-mail do cliente
          example: daniel_lima@abacatepay.com
        taxId:
          type: string
          description: CPF ou CNPJ do cliente
          example: 123.456.789-01
        country:
          type: string
          description: País do cliente
          example: BR
        zipCode:
          type: string
          description: CEP do cliente
          example: 01310-100
        metadata:
          type: object
          description: Metadados adicionais do cliente
          additionalProperties: true
          example:
            source: landing-page
            campaign: black-friday-2025
    Coupon:
      type: object
      description: Os dados do seu cupom.
      required:
        - code
        - discount
        - discountKind
      additionalProperties: false
      properties:
        code:
          type: string
          description: Identificador único do cupom
          example: DEYVIN_20
        notes:
          type: string
          description: Descrição sbre o cupom
          example: Cupom de desconto pro meu público
        maxRedeems:
          type: number
          description: >-
            Quantidade de vezes em que o cupom pode ser resgatado. -1 Significa
            que esse cupom pode ser resgatado sem limites
          example: 10
          default: -1
        discountKind:
          type: string
          description: 'Tipo de desconto aplicado, porcentagem ou fixo'
          enum:
            - PERCENTAGE
            - FIXED
        discount:
          type: number
          description: Valor de desconto a ser aplicado
        metadata:
          type: object
          description: Objeto chave valor para metadados do cupom
          default: {}
    CouponResponse:
      type: object
      description: Os dados do seu cupom.
      required:
        - id
        - discount
        - discountKind
        - status
        - createdAt
        - updatedAt
      additionalProperties: false
      properties:
        id:
          type: string
          description: Identificador único do cupom
          example: DEYVIN_20
        notes:
          type: string
          description: Descrição sobre o cupom
          example: Cupom de desconto pro meu público
        maxRedeems:
          type: integer
          description: >-
            Quantidade de vezes em que o cupom pode ser resgatado. -1 significa
            ilimitado.
          example: -1
          default: 10
        redeemsCount:
          type: integer
          description: Quantidade de vezes que o cupom já foi resgatado.
          example: 0
        discountKind:
          type: string
          description: 'Tipo de desconto aplicado, porcentagem ou fixo'
          enum:
            - PERCENTAGE
            - FIXED
          example: PERCENTAGE
        discount:
          type: number
          description: Valor de desconto a ser aplicado
          example: 123
        devMode:
          type: boolean
          description: Indica se o cupom foi criado em ambiente de testes.
          example: true
        status:
          type: string
          description: Status atual do cupom.
          enum:
            - ACTIVE
            - INACTIVE
            - EXPIRED
          example: ACTIVE
        createdAt:
          type: string
          format: date-time
          description: Data de criação do cupom.
          example: '2025-05-25T23:43:25.250Z'
        updatedAt:
          type: string
          format: date-time
          description: Data de atualização do cupom.
          example: '2025-05-25T23:43:25.250Z'
        metadata:
          type: object
          description: Objeto chave valor para metadados do cupom
          default: {}
    Product:
      type: object
      description: >
        Os dados do seu produto.

        O campo `cycle` indica se o produto é uma assinatura (subscription).
        Quando `null`, o produto é avulso (pagamento único). Valores possíveis
        definem a recorrência da assinatura.

        A moeda (`currency`) é sempre `BRL`.
      required:
        - externalId
        - name
        - description
        - price
        - devMode
        - currency
        - createdAt
        - updatedAt
        - status
        - id
      additionalProperties: false
      properties:
        externalId:
          type: string
          description: Identificador único do produto no seu sistema
          example: prod-123
        name:
          type: string
          description: Nome do produto
          example: Produto Exemplo
        description:
          type: string
          description: Descrição do produto
          example: Descrição do produto
        imageUrl:
          type: string
          format: uri
          nullable: true
          description: URL da imagem do produto
          example: null
        price:
          type: number
          description: Preço do produto em centavos
          example: 10000
        devMode:
          type: boolean
          description: Indica se o produto foi criado em ambiente de testes
          example: false
        currency:
          type: string
          description: Moeda do produto (sempre BRL)
          enum:
            - BRL
          example: BRL
        createdAt:
          type: string
          format: date-time
          description: Data de criação do produto
          example: '2024-11-04T18:38:28.573Z'
        updatedAt:
          type: string
          format: date-time
          description: Data de atualização do produto
          example: '2024-11-04T18:38:28.573Z'
        status:
          type: string
          description: Status atual do produto (ProductStatus)
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        id:
          type: string
          description: Identificador único público do produto
          example: prod_abc123xyz
        cycle:
          type: string
          nullable: true
          description: >
            Indica se o produto é uma assinatura (ProductCycle). Quando `null`,
            o produto é avulso (pagamento único).

            Valores possíveis definem a recorrência da assinatura.
          enum:
            - WEEKLY
            - MONTHLY
            - SEMIANNUALLY
            - ANNUALLY
          example: null
    Billing:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do Checkout.
          example: bill_abc123xyz
        externalId:
          type: string
          nullable: true
          description: ID do Checkout no seu sistema.
          example: pedido-123
        url:
          type: string
          format: uri
          description: URL onde o usuário pode concluir o pagamento.
          example: 'https://app.abacatepay.com/pay/bill_abc123xyz'
        amount:
          type: number
          description: Valor total a ser pago em centavos.
          example: 10000
        paidAmount:
          type: number
          nullable: true
          description: Valor já pago em centavos. Null se ainda não foi pago.
          example: null
        items:
          type: array
          description: Lista de itens no Checkout.
          items:
            type: object
            properties:
              id:
                type: string
                description: ID do produto.
                example: prod_456
              quantity:
                type: integer
                description: Quantidade do item.
                example: 2
        status:
          type: string
          description: Status atual do Checkout.
          enum:
            - PENDING
            - EXPIRED
            - CANCELLED
            - PAID
            - REFUNDED
          example: PENDING
        coupons:
          type: array
          description: Lista de cupons aplicados no Checkout.
          items:
            type: string
          example: []
        devMode:
          type: boolean
          description: Indica se a cobrança foi criada em ambiente de testes.
          example: false
        customerId:
          type: string
          nullable: true
          description: ID do cliente associado ao Checkout.
          example: null
        returnUrl:
          type: string
          format: uri
          nullable: true
          description: URL para onde o cliente será redirecionado ao clicar em "Voltar".
          example: null
        completionUrl:
          type: string
          format: uri
          nullable: true
          description: URL para onde o cliente será redirecionado após o pagamento.
          example: null
        receiptUrl:
          type: string
          format: uri
          nullable: true
          description: URL do comprovante de pagamento.
          example: null
        upSellProductId:
          type: string
          nullable: true
          description: >-
            ID do produto de upsell vinculado ao Checkout. Null se
            nenhum produto de upsell foi informado na criação.
          example: prod_bump456xyz
        interest:
          nullable: true
          description: >-
            Juros por atraso configurados para o boleto. `null` quando não
            foi configurado ou quando o método de pagamento não é BOLETO.
          allOf:
            - $ref: '#/components/schemas/BoletoInterest'
        fine:
          nullable: true
          description: >-
            Multa por atraso configurada para o boleto. `null` quando não
            foi configurada ou quando o método de pagamento não é BOLETO.
          allOf:
            - $ref: '#/components/schemas/BoletoFine'
        metadata:
          type: object
          description: Metadados adicionais do Checkout.
          additionalProperties: true
          example: {}
        createdAt:
          type: string
          format: date-time
          description: Data e hora de criação do Checkout.
          example: '2024-11-04T18:38:28.573Z'
        updatedAt:
          type: string
          format: date-time
          description: Data e hora da última atualização do Checkout.
          example: '2024-11-04T18:38:28.573Z'
    PixQRCode:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do QRCode Pix.
          example: pix_char_123456
        amount:
          type: number
          description: Valor a ser pago.
          example: 100
        status:
          type: string
          description: Informação sobre o andamento do QRCode Pix.
          enum:
            - PENDING
            - EXPIRED
            - CANCELLED
            - PAID
            - UNDER_DISPUTE
            - REFUNDED
            - REDEEMED
            - APPROVED
            - FAILED
          example: PENDING
        devMode:
          type: boolean
          description: Ambiente no qual o QRCode Pix foi criado.
          example: true
        brCode:
          type: string
          description: Código copia-e-cola do QRCode Pix.
          example: 00020101021226950014br.gov.bcb.pix
        brCodeBase64:
          type: string
          description: Imagem em Base64 do QRCode Pix.
          example: 'data:image/png;base64,iVBORw0KGgoAAA'
        platformFee:
          type: number
          description: Taxas da plataforma
          example: 80
        createdAt:
          type: string
          description: Data de criação do QRCode Pix.
          example: '2025-03-24T21:50:20.772Z'
        updatedAt:
          type: string
          description: Data de atualização do QRCode Pix.
          example: '2025-03-24T21:50:20.772Z'
        expiresAt:
          type: string
          description: Data de expiração do QRCode Pix
          example: '2025-03-25T21:50:20.772Z'
        metadata:
          type: object
          description: Metadados opcionais da cobrança.
          additionalProperties: true
    TransparentCharge:
      type: object
      description: >-
        Dados da cobrança retornados pelo checkout transparente. Os campos
        `brCode` e `brCodeBase64` são sempre retornados (PIX direto ou PIX
        alternativo do boleto). Para boleto também retornam `barCode` e
        `url`.
      properties:
        id:
          type: string
          description: Identificador único da cobrança.
          example: bole_k8pqr2mnvx
        amount:
          type: number
          description: Valor a ser pago em centavos.
          example: 25000
        status:
          type: string
          description: Status atual da cobrança.
          enum:
            - PENDING
            - EXPIRED
            - CANCELLED
            - PAID
            - UNDER_DISPUTE
            - REFUNDED
            - REDEEMED
            - APPROVED
            - FAILED
          example: PENDING
        devMode:
          type: boolean
          description: Indica se a cobrança foi criada em ambiente sandbox.
          example: false
        brCode:
          type: string
          description: >-
            Código copia-e-cola do QR Code PIX. Para `method: "BOLETO"`,
            representa o PIX alternativo da mesma cobrança.
          example: 00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5913Daniel Lima6009SAO PAULO62070503***6304F1C2
        brCodeBase64:
          type: string
          description: >-
            Imagem em Base64 do QR Code PIX. Para `method: "BOLETO"`,
            representa o PIX alternativo da mesma cobrança.
          example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
        barCode:
          type: string
          description: >-
            Linha digitável do boleto para pagamento no app do banco.
            Retornado quando `method` é `"BOLETO"`.
          example: 23793.38128 60007.827263 37000.963779 4 10010000025000
        url:
          type: string
          description: >-
            URL para visualização e impressão do boleto. Retornado quando
            `method` é `"BOLETO"`.
          example: https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto
        platformFee:
          type: number
          description: Taxa da plataforma em centavos.
          example: 250
        interest:
          nullable: true
          description: >-
            Juros por atraso configurados para o boleto. `null` para `method:
            "PIX"` ou quando não foi configurado.
          allOf:
            - $ref: '#/components/schemas/BoletoInterest'
        fine:
          nullable: true
          description: >-
            Multa por atraso configurada para o boleto. `null` para `method:
            "PIX"` ou quando não foi configurada.
          allOf:
            - $ref: '#/components/schemas/BoletoFine'
        expiresAt:
          type: string
          description: >-
            Data de expiração da cobrança (ISO 8601). Para boleto, representa
            a data de vencimento.
          example: '2024-11-07T03:00:00.000Z'
        createdAt:
          type: string
          description: Data de criação.
          example: '2024-11-04T14:22:10.381Z'
        updatedAt:
          type: string
          description: Data da última atualização.
          example: '2024-11-04T14:22:10.381Z'
        metadata:
          type: object
          description: Campos livres enviados na requisição.
          additionalProperties: true
    BoletoTransparent:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do boleto.
          example: bole_k8pqr2mnvx
        amount:
          type: number
          description: Valor a ser pago em centavos.
          example: 25000
        status:
          type: string
          description: Status atual da cobrança.
          enum:
            - PENDING
            - EXPIRED
            - CANCELLED
            - PAID
            - UNDER_DISPUTE
            - REFUNDED
          example: PENDING
        devMode:
          type: boolean
          description: Indica se a cobrança foi criada em ambiente sandbox.
          example: false
        barCode:
          type: string
          description: Linha digitável do boleto para pagamento no app do banco.
          example: 23793.38128 60007.827263 37000.963779 4 10010000025000
        url:
          type: string
          description: URL para visualização e impressão do boleto.
          example: https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto
        brCode:
          type: string
          description: Código PIX copia e cola alternativo vinculado à mesma cobrança.
          example: 00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5913Mariana Costa6009SAO PAULO62070503***6304F1C2
        brCodeBase64:
          type: string
          description: QR Code PIX alternativo em base64.
          example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
        platformFee:
          type: number
          description: Taxa da plataforma em centavos.
          example: 250
        interest:
          nullable: true
          description: >-
            Juros por atraso configurados para o boleto. `null` quando não
            foi configurado.
          allOf:
            - $ref: '#/components/schemas/BoletoInterest'
        fine:
          nullable: true
          description: >-
            Multa por atraso configurada para o boleto. `null` quando não
            foi configurada.
          allOf:
            - $ref: '#/components/schemas/BoletoFine'
        expiresAt:
          type: string
          description: Data de vencimento do boleto (ISO 8601).
          example: '2024-11-07T03:00:00.000Z'
        createdAt:
          type: string
          description: Data de criação.
          example: '2024-11-04T14:22:10.381Z'
        updatedAt:
          type: string
          description: Data da última atualização.
          example: '2024-11-04T14:22:10.381Z'
        metadata:
          type: object
          description: Campos livres enviados na requisição.
          additionalProperties: true
    Transaction:
      type: object
      description: Dados de uma transação (pagamento ou saque).
      properties:
        id:
          type: string
          description: Identificador único da transação.
          example: tran_123456
        status:
          type: string
          description: Status atual da transação.
          enum:
            - PENDING
            - EXPIRED
            - CANCELLED
            - COMPLETE
            - REFUNDED
          example: PENDING
        devMode:
          type: boolean
          description: Indica se a transação foi criada em ambiente de testes.
          example: true
        receiptUrl:
          type: string
          format: uri
          description: URL do comprovante da transação.
          example: 'https://abacatepay.com/receipt/tran_123456'
        kind:
          type: string
          description: Tipo da transação.
          enum:
            - PAYMENT
            - WITHDRAW
          example: WITHDRAW
          default: WITHDRAW
        amount:
          type: number
          description: Valor da transação em centavos.
          example: 5000
        platformFee:
          type: number
          description: Taxa da plataforma em centavos.
          example: 80
        externalId:
          type: string
          description: Identificador externo da transação.
          example: withdraw-1234
        createdAt:
          type: string
          format: date-time
          description: Data de criação da transação.
          example: '2025-03-24T21:50:20.772Z'
        updatedAt:
          type: string
          format: date-time
          description: Data de atualização da transação.
          example: '2025-03-24T21:50:20.772Z'
      required:
        - id
        - status
        - devMode
        - receiptUrl
        - kind
        - amount
        - platformFee
        - createdAt
        - updatedAt
    PixTransaction:
      type: object
      description: Dados de uma transação PIX.
      properties:
        id:
          type: string
          description: Identificador único da transação PIX.
          example: txn_abc123xyz
        status:
          type: string
          description: Status atual da transação.
          enum:
            - PENDING
            - EXPIRED
            - CANCELLED
            - COMPLETE
            - REFUNDED
          example: PENDING
        devMode:
          type: boolean
          description: Indica se a transação foi criada em ambiente de testes.
          example: false
        receiptUrl:
          type: string
          format: uri
          description: URL do comprovante da transação.
          example: 'https://app.abacatepay.com/receipt/txn_abc123xyz'
        amount:
          type: number
          description: Valor da transação em centavos.
          example: 10000
        platformFee:
          type: number
          description: Taxa da plataforma em centavos.
          example: 100
        externalId:
          type: string
          nullable: true
          description: Identificador externo da transação.
          example: pix-123
        createdAt:
          type: string
          format: date-time
          description: Data de criação da transação.
          example: '2024-11-04T18:38:28.573Z'
        updatedAt:
          type: string
          format: date-time
          description: Data de atualização da transação.
          example: '2024-11-04T18:38:28.573Z'
      required:
        - id
        - status
        - devMode
        - receiptUrl
        - amount
        - platformFee
        - createdAt
        - updatedAt
    Store:
      type: object
      description: Dados da loja/conta do usuário.
      required:
        - id
        - name
        - balance
      additionalProperties: false
      properties:
        id:
          type: string
          description: Identificador único da loja.
          example: store_abc123xyz
        name:
          type: string
          description: Nome da loja.
          example: Minha Loja
        balance:
          type: object
          description: Informações de saldo da loja.
          required:
            - available
            - pending
            - blocked
          additionalProperties: false
          properties:
            available:
              type: number
              description: Saldo disponível para saque em centavos.
              example: 50000
            pending:
              type: number
              description: Saldo pendente de confirmação em centavos.
              example: 10000
            blocked:
              type: number
              description: Saldo bloqueado em disputas em centavos.
              example: 0
    Subscription:
      type: object
      description: Dados de uma assinatura (subscription).
      required:
        - id
        - name
        - description
        - amount
        - currency
        - method
        - status
        - customerId
        - devMode
        - events
        - createdAt
        - updatedAt
      additionalProperties: false
      properties:
        id:
          type: string
          description: Identificador único da assinatura.
          example: subs_abc123xyz
        name:
          type: string
          description: Nome da assinatura.
          example: Plano Premium Mensal
        description:
          type: string
          description: Descrição da assinatura.
          example: Assinatura mensal do plano premium
        amount:
          type: number
          description: Valor da assinatura em centavos.
          example: 10000
        currency:
          type: string
          description: Moeda da assinatura.
          example: BRL
        method:
          type: string
          description: Método de pagamento da assinatura.
          enum:
            - PIX
            - CARD
          example: PIX
        status:
          type: string
          description: Status atual da assinatura.
          enum:
            - PENDING
            - ACTIVE
            - CANCELLED
            - EXPIRED
            - FAILED
          example: PENDING
        customerId:
          type: string
          description: Identificador do cliente que possui a assinatura.
          example: cust_abc123xyz
        devMode:
          type: boolean
          description: Indica se a assinatura foi criada em ambiente de testes.
          example: false
        createdAt:
          type: string
          format: date-time
          description: Data de criação da assinatura.
          example: '2024-11-04T18:38:28.573Z'
        updatedAt:
          type: string
          format: date-time
          description: Data de atualização da assinatura.
          example: '2024-11-04T18:38:28.573Z'
    SubscriptionUpdate:
      type: object
      description: Atualização de plano pendente de uma assinatura.
      required:
        - id
        - subscriptionId
        - status
        - productId
        - quantity
        - newAmount
        - requestedAt
      additionalProperties: false
      properties:
        id:
          type: string
          description: Identificador único da atualização de plano.
          example: subu_abc123xyz
        subscriptionId:
          type: string
          description: Identificador da assinatura associada.
          example: subs_abc123xyz
        status:
          type: string
          description: Status da atualização.
          enum:
            - PENDING
            - APPLIED
            - CANCELLED
          example: PENDING
        productId:
          type: string
          description: Identificador do novo produto.
          example: prod_plano_pro
        quantity:
          type: integer
          description: Quantidade do novo produto.
          example: 1
        newAmount:
          type: integer
          description: Novo valor a ser cobrado por ciclo, em centavos (preço × quantidade).
          example: 4990
        requestedAt:
          type: string
          format: date-time
          description: Data e hora em que a alteração foi solicitada.
          example: '2024-12-06T20:05:00.000Z'
    SubscriptionUsageRecord:
      type: object
      description: Registro de uso de um produto avulso em uma assinatura.
      required:
        - id
        - subscriptionId
        - productId
        - units
        - unitPrice
        - action
        - installmentNumber
        - recordedAt
      additionalProperties: false
      properties:
        id:
          type: string
          description: Identificador único do registro de uso.
          example: usgr_abc123xyz
        subscriptionId:
          type: string
          description: Identificador da assinatura associada.
          example: subs_abc123xyz
        productId:
          type: string
          description: Identificador do produto de uso.
          example: prod_api_calls
        units:
          type: integer
          description: Quantidade de unidades registradas.
          example: 50
        unitPrice:
          type: integer
          description: Preço unitário em centavos no momento do registro.
          example: 100
        action:
          type: string
          description: Tipo de ação aplicada ao uso.
          enum:
            - add
            - subtract
          example: add
        installmentNumber:
          type: integer
          description: Número da parcela em que este uso será cobrado.
          example: 2
        recordedAt:
          type: string
          format: date-time
          description: Data e hora do registro.
          example: '2024-12-06T20:10:00.000Z'
    WebhookCreateInput:
      type: object
      description: Dados para criação de um webhook.
      required:
        - name
        - endpoint
        - secret
        - events
      additionalProperties: false
      properties:
        name:
          type: string
          description: Nome identificador do webhook
          example: Webhook de Pagamentos
        endpoint:
          type: string
          description: URL HTTPS que receberá as notificações de eventos
          example: 'https://meusite.com/webhooks/abacatepay'
        secret:
          type: string
          description: Sua chave usada para autenticar nosso webhook
          example: meu-secret-seguro
        events:
          type: array
          description: Lista de eventos que este webhook deve receber
          items:
            type: string
            enum:
              - checkout.completed
              - checkout.refunded
              - checkout.disputed
              - checkout.lost
              - transparent.completed
              - transparent.refunded
              - transparent.disputed
              - transparent.lost
              - subscription.completed
              - subscription.trial_started
              - subscription.cancelled
              - subscription.renewed
              - payout.completed
              - payout.failed
              - transfer.completed
              - transfer.failed
          example:
            - checkout.completed
            - subscription.renewed
    WebhookResponse:
      type: object
      description: Os dados do webhook.
      required:
        - id
        - name
        - endpoint
        - events
        - devMode
        - v2
        - createdAt
        - updatedAt
      additionalProperties: false
      properties:
        id:
          type: string
          description: Identificador único do webhook
          example: webh_abc123xyz
        name:
          type: string
          description: Nome identificador do webhook
          example: Webhook de Pagamentos
        endpoint:
          type: string
          description: URL HTTPS que recebe as notificações de eventos
          example: 'https://meusite.com/webhooks/abacatepay'
        events:
          type: array
          description: Lista de eventos subscritos
          items:
            type: string
          example:
            - checkout.completed
            - subscription.renewed
        devMode:
          type: boolean
          description: Indica se o webhook foi criado em ambiente de testes
          example: false
        v2:
          type: boolean
          description: Indica se o webhook usa o formato de payload v2
          example: true
        createdAt:
          type: string
          format: date-time
          description: Data de criação do webhook
          example: '2025-01-01T00:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Data da última atualização do webhook
          example: '2025-01-01T00:00:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Todas as requisições devem incluir sua chave de API no header
        Authorization usando o formato `Bearer <abacatepay-api-key>`. Sem esse
        header a requisição será rejeitada.


        Saiba mais sobre como criar e usar chaves de API na [documentação de
        autenticação](/pages/authentication).