> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usevext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar saldo

> Saldo, reservado, disponível e sacável do vendedor.

<Warning>
  `provider` e `withdrawable` vêm `null` quando a consulta ao provedor falha. **`null` não é zero**:
  zero diria que não há dinheiro, quando o que houve foi uma consulta que não respondeu.
  Ver [Saldo do vendedor](/essenciais/saldo).
</Warning>


## OpenAPI

````yaml api-reference/openapi.yaml GET /v1/balance
openapi: 3.1.0
info:
  title: Vext - API de pagamentos PIX com split
  version: 1.0.0
  summary: Cobranças PIX, estornos e saldo do vendedor.
  description: |
    API pública do gateway. Todo endpoint desta versão vive sob `/v1`.

    Quatro regras valem para toda chamada. Cada uma tem uma página própria
    nos guias, com exemplos nas quatro linguagens.

    - **Dinheiro é sempre centavos inteiros.** R$ 100,00 se envia como
      `10000`; um decimal devolve `422`. Ver
      [Valores em centavos](/essenciais/valores-em-centavos).
    - **A chave secreta vai no header e fica no servidor.** Cada chave
      carrega escopos; fora do escopo devolve `403`, e não `401`. Ver
      [Autenticação](/essenciais/autenticacao).
    - **Envie `Idempotency-Key` em todo `POST`.** Repetir com a mesma chave
      devolve a resposta gravada em vez de criar um segundo recurso. Ver
      [Idempotência](/essenciais/idempotencia).
    - **Trate os erros pelo `code`**, nunca pela `message` - o código é
      contrato, o texto pode ser reescrito a qualquer momento. Ver
      [Erros](/essenciais/erros).
  contact:
    name: Suporte Vext
    email: suporte@usevext.com
servers:
  - url: https://api.usevext.com
    description: Produção
security:
  - apiKey: []
tags:
  - name: Cobranças
    description: Criação, consulta e estorno de cobranças PIX.
  - name: Saldo
    description: Quanto o vendedor tem e quanto pode sacar.
paths:
  /v1/balance:
    get:
      tags:
        - Saldo
      summary: Consultar saldo
      description: |
        Quatro números, porque respondem perguntas diferentes:

        - `balance` - tudo que o vendedor ganhou e ainda não sacou.
        - `reserved` - a parte que a reserva rolante ainda segura.
        - `available` - o que já pode sair pelo nosso extrato.
        - `withdrawable` - o **menor** entre o nosso disponível e o do
          provedor. É este que vale para pedir saque: usar só o nosso
          permitiria pedir dinheiro que a adquirente ainda não liberou.

        `provider` e `withdrawable` vêm `null` quando a consulta ao provedor
        falha. `null` não é zero: zero diria que não há dinheiro, quando o
        que houve foi uma consulta que não respondeu. O resto do saldo, que
        é nosso, continua correto.
      operationId: getBalance
      responses:
        '200':
          description: Saldo da conta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
              examples:
                normal:
                  summary: Provedor respondeu
                  value:
                    object: balance
                    currency: BRL
                    balance: 92020
                    available: 82818
                    reserved: 9202
                    debt: 0
                    withdrawable: 50000
                    provider:
                      available: 50000
                      waiting_funds: 7000
                indisponivel:
                  summary: Provedor não respondeu
                  value:
                    object: balance
                    currency: BRL
                    balance: 92020
                    available: 82818
                    reserved: 9202
                    debt: 0
                    withdrawable: null
                    provider: null
                emDivida:
                  summary: Vendedor no vermelho
                  description: |
                    Acontece quando um estorno chega depois do saque. Não é
                    erro: as próximas vendas cobrem a dívida
                    automaticamente, e apenas o saque fica bloqueado até lá.
                  value:
                    object: balance
                    currency: BRL
                    balance: -9301
                    available: 0
                    reserved: 0
                    debt: 9301
                    withdrawable: 0
                    provider:
                      available: 0
                      waiting_funds: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKey:
            - balance:read
components:
  schemas:
    Balance:
      type: object
      required:
        - object
        - currency
        - balance
        - available
        - reserved
        - debt
      properties:
        object:
          type: string
          const: balance
        currency:
          type: string
          const: BRL
        balance:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            Saldo do extrato, em centavos inteiros. Pode ser NEGATIVO -
            acontece quando um estorno chega depois do saque.
        available:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            O que já pode sair pelo nosso extrato, em centavos inteiros.
            Nunca negativo: veja `debt`.
        reserved:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            Retido pela reserva rolante, em centavos inteiros. É dinheiro do
            vendedor que ainda não pode sair - sem este campo, a diferença
            entre `balance` e `available` pareceria erro do sistema.
        debt:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            Quanto o vendedor deve, em centavos inteiros. Estado próprio, e
            não "saldo zero": as próximas vendas cobrem automaticamente e só
            o saque fica bloqueado até lá.
        withdrawable:
          oneOf:
            - $ref: '#/components/schemas/Cents'
            - type: 'null'
          description: |
            O que dá para sacar AGORA, em centavos inteiros. `null` quando a
            consulta ao provedor falhou.
        provider:
          oneOf:
            - type: object
              required:
                - available
                - waiting_funds
              properties:
                available:
                  allOf:
                    - $ref: '#/components/schemas/Cents'
                  description: Disponível na adquirente, em centavos inteiros.
                waiting_funds:
                  allOf:
                    - $ref: '#/components/schemas/Cents'
                  description: |
                    A caminho na adquirente, em centavos inteiros.
            - type: 'null'
          description: |
            `null` quando a consulta ao provedor falhou. Diferente de zero.
    Cents:
      type: integer
      format: int64
      description: |
        Valor monetário em **centavos inteiros** de real. R$ 10,00 = `1000`.
        Nunca decimal, nunca string.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - details
          properties:
            type:
              type: string
              description: |
                Família do erro. Responde "de quem é o problema e o que
                fazer": `invalid_request_error` se corrige mudando a
                chamada, `authentication_error` trocando a chave, e
                `api_error` é nosso - repita, não reescreva.
              enum:
                - authentication_error
                - permission_error
                - invalid_request_error
                - idempotency_error
                - not_found_error
                - rate_limit_error
                - api_error
            code:
              type: string
              description: |
                Código estável do erro. **Trate por ele.** A `message` pode
                ser reescrita a qualquer momento; o código, não.
            message:
              type: string
              description: Explicação em português, para leitura humana.
            details:
              type: object
              description: |
                Sempre objeto, mesmo vazio. Em `validation_failed`, traz os
                campos recusados e suas mensagens.
              additionalProperties: true
  responses:
    Unauthorized:
      description: |
        Chave ausente, desconhecida, revogada ou expirada. A revogada é
        distinguida da inexistente na MENSAGEM, nunca no status: quem
        integra precisa saber que a chave existiu e foi desligada, e quem
        está adivinhando tokens não aprende nada com isso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ausente:
              summary: missing_api_key
              value:
                error:
                  type: authentication_error
                  code: missing_api_key
                  message: 'Envie a chave em Authorization: Bearer sk_live_...'
                  details: {}
            invalida:
              summary: invalid_api_key
              value:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: Chave de API inválida.
                  details: {}
            revogada:
              summary: revoked_api_key
              value:
                error:
                  type: authentication_error
                  code: revoked_api_key
                  message: >-
                    Esta chave de API foi revogada. Gere uma nova em
                    Desenvolvedores.
                  details: {}
            expirada:
              summary: expired_api_key
              value:
                error:
                  type: authentication_error
                  code: expired_api_key
                  message: Esta chave de API expirou. Gere uma nova em Desenvolvedores.
                  details: {}
    Forbidden:
      description: |
        A chave é válida, mas não tem o escopo do endpoint. `403` e não
        `401` de propósito: `401` diria "sua chave está errada" a quem tem
        a chave certa.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            escopo:
              summary: insufficient_scope
              value:
                error:
                  type: permission_error
                  code: insufficient_scope
                  message: Esta chave não tem o escopo [refunds:write].
                  details:
                    required_ability: refunds:write
                    abilities:
                      - charges:read
                      - charges:write
    RateLimited:
      description: |
        Requisições demais.

        Há três limites, por minuto: um por IP antes da autenticação, e
        depois um de leitura e um de escrita, ambos por CHAVE - o excesso
        de uma integração não consome a cota das outras do mesmo
        vendedor. A escrita é bem mais apertada porque cada cobrança
        criada vira uma chamada ao provedor.

        `Retry-After` diz em quantos segundos voltar. Os cabeçalhos
        `X-RateLimit-*` vêm em TODA resposta, não só nesta: são eles que
        permitem desacelerar antes de bater no limite.
      headers:
        Retry-After:
          description: Segundos até a cota ser reposta.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requisições permitidas por minuto neste balde.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Quantas ainda cabem no minuto corrente.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            cota:
              summary: too_many_requests
              value:
                error:
                  type: rate_limit_error
                  code: too_many_requests
                  message: Muitas requisições. Tente novamente em 42 segundos.
                  details:
                    retry_after: 42
            provedor:
              summary: provider_rate_limited
              value:
                error:
                  type: rate_limit_error
                  code: provider_rate_limited
                  message: >-
                    Limite de requisições do provedor atingido. Tente novamente
                    em instantes.
                  details: {}
    InternalError:
      description: |
        Erro inesperado do nosso lado. Repita com a mesma
        `Idempotency-Key` - ela é o que torna repetir seguro.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            interno:
              value:
                error:
                  type: api_error
                  code: internal_error
                  message: >-
                    Erro interno. Se persistir, informe o horário da chamada ao
                    suporte.
                  details: {}
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: sk_live_… | sk_test_…
      description: |
        Chave secreta do vendedor, criada no painel em **Desenvolvedores**.

        O valor em claro existe uma única vez, na criação. Guardamos só o
        hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto:
        um dump do nosso banco não permite cobrar em nome de ninguém.

        A chave vai no **servidor**. Colocá-la no navegador do comprador a
        entrega a qualquer pessoa que abra a página.

````