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

# Quantidade de certificados disponíveis

> Retorna quantos certificados o parceiro pode emitir.



## OpenAPI

````yaml GET /api/v1/partners/{partnerId}/balance
openapi: 3.1.0
info:
  title: Certificados ZapSign Partner API
  version: 4.2.0
  description: >-
    API REST para parceiros (revendedores) emitirem vouchers de certificado
    digital e-CPF e e-CNPJ. Cada criação desconta 1 certificado do saldo da
    carteira do parceiro. Autenticação por Bearer token com prefixo `czk_live_`
    gerado em
    [https://certificados.zapsign.com.br/reseller/api-keys](https://certificados.zapsign.com.br/reseller/api-keys).
  contact:
    name: Suporte Certificados ZapSign
    url: https://wa.me/5511952135263
servers:
  - url: https://certificados.zapsign.com.br
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Vouchers
    description: Criação e consulta de vouchers de certificado digital.
  - name: Carteira
    description: Saldo disponível do parceiro.
paths:
  /api/v1/partners/{partnerId}/balance:
    get:
      tags:
        - Carteira
      summary: Consulta do saldo disponível do parceiro.
      description: Retorna quantos certificados o parceiro pode emitir.
      operationId: getPartnerBalance
      parameters:
        - $ref: '#/components/parameters/PartnerIdParam'
      responses:
        '200':
          description: Saldo atual.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
              examples:
                saldo:
                  value:
                    certificates_available: 42
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >-
            curl
            'https://certificados.zapsign.com.br/api/v1/partners/PRT_ABC123/balance'
            \
              -H 'Authorization: Bearer czk_live_SUA_CHAVE'
components:
  parameters:
    PartnerIdParam:
      name: partnerId
      in: path
      required: true
      description: Identificador público do parceiro (Partner ID), exibido no portal.
      schema:
        type: string
        minLength: 1
        maxLength: 64
  schemas:
    BalanceResponse:
      type: object
      required:
        - certificates_available
      properties:
        certificates_available:
          type: integer
          minimum: 0
          description: Certificados disponíveis para emitir.
    VoucherErrorEnvelope:
      type: object
      description: >-
        Envelope de erro dos endpoints de voucher: `error`, `message` e
        `details` (opcional).
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: >-
            Código curto e estável do catálogo fechado. Use para fazer branching
            no seu cliente.
          example: validation_error
        message:
          type: string
          description: Mensagem em pt-BR, segura para mostrar a operadores internos.
        details:
          description: Estrutura adicional dependente do código. Veja a tabela de erros.
  responses:
    Unauthorized:
      description: Não autenticado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            missing_or_invalid_authorization:
              $ref: '#/components/examples/MissingOrInvalidAuthorizationExample'
            invalid_api_key:
              $ref: '#/components/examples/InvalidApiKeyExample'
            api_key_revoked:
              $ref: '#/components/examples/ApiKeyRevokedExample'
    Forbidden:
      description: Acesso negado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            partner_not_approved:
              $ref: '#/components/examples/PartnerNotApprovedExample'
            tenant_mismatch:
              $ref: '#/components/examples/TenantMismatchExample'
    RateLimitExceeded:
      description: >-
        Limite de requisições excedido para a chave. Aguarde a janela e respeite
        os headers `RateLimit-*`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            rate_limit_exceeded:
              $ref: '#/components/examples/RateLimitExceededExample'
      headers:
        RateLimit-Limit:
          description: Limite máximo na janela atual.
          schema:
            type: integer
        RateLimit-Remaining:
          description: Quantas requisições ainda cabem na janela.
          schema:
            type: integer
            example: 0
        RateLimit-Reset:
          description: Segundos até a janela reabrir.
          schema:
            type: integer
            example: 42
    InternalError:
      description: >-
        Falha inesperada do servidor. Reenvie com backoff exponencial; o
        `reference_id` garante idempotência.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VoucherErrorEnvelope'
          examples:
            internal_error:
              $ref: '#/components/examples/InternalErrorExample'
  examples:
    MissingOrInvalidAuthorizationExample:
      summary: Header `Authorization` ausente ou fora do formato `Bearer <token>`
      x-resolution: Envie o header `Authorization` no formato `Bearer czk_live_...`.
      value:
        error: missing_or_invalid_authorization
        message: Header Authorization ausente ou malformado.
    InvalidApiKeyExample:
      summary: Token Bearer não bate com nenhuma chave válida
      x-resolution: >-
        Gere uma nova chave em
        https://certificados.zapsign.com.br/reseller/api-keys e atualize seus
        secrets.
      value:
        error: invalid_api_key
        message: API key inválida.
    ApiKeyRevokedExample:
      summary: Chave existe mas foi revogada no portal
      x-resolution: >-
        Gere uma nova chave em
        https://certificados.zapsign.com.br/reseller/api-keys e atualize seus
        secrets.
      value:
        error: api_key_revoked
        message: API key revogada.
    PartnerNotApprovedExample:
      summary: Parceiro existe mas o status não está em `approved`
      x-resolution: Aguarde a aprovação do cadastro. Você recebe email quando for liberado.
      value:
        error: partner_not_approved
        message: Parceiro não aprovado.
    TenantMismatchExample:
      summary: O `partnerId` da URL não bate com o dono da chave
      x-resolution: Use a chave do parceiro dono daquele `partnerId`.
      value:
        error: tenant_mismatch
        message: partnerId do path não corresponde ao dono da API key.
    RateLimitExceededExample:
      summary: Limite de requisições excedido para a chave.
      x-resolution: >-
        Reduza a frequência das chamadas e use backoff exponencial antes de
        tentar novamente.
      value:
        error: rate_limit_exceeded
        message: Limite de requisições excedido.
    InternalErrorExample:
      summary: Falha não esperada do servidor
      x-resolution: >-
        Reenvie com backoff exponencial. O mesmo `reference_id` garante
        idempotência.
      value:
        error: internal_error
        message: Erro interno do servidor.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: czk_live_*
      description: >-
        Token Bearer com prefixo `czk_live_`. Gere a chave no portal em
        [https://certificados.zapsign.com.br/reseller/api-keys](https://certificados.zapsign.com.br/reseller/api-keys).

````