> ## Documentation Index > Fetch the complete documentation index at: https://docs.beinfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Consultar estado do cliente > Numa só leitura: a inscrição, os saldos de cada meter, as assinaturas ativas (com seus itens) e o uso do período atual. Serve para montar o painel do cliente ou decidir, antes de atender uma requisição, se ele ainda tem saldo. `customerID` aqui é o id da inscrição, não o id do cliente. ## OpenAPI ````yaml /api-reference/openapi.pt-BR.json get /customers/{customerID}/state openapi: 3.1.0 info: title: Infi API version: 0.0.1 description: > A API REST do Infi: catálogo, clientes, medição de uso, assinaturas, faturas, pagamentos e checkout. **Autenticação.** Envie a chave secreta em `Authorization: Bearer sk_test_…` (sandbox) ou `sk_live_…` (produção). O prefixo da chave decide o ambiente. As rotas de checkout (`/pay/*`) e `/public/*` não levam chave: rodam no navegador de quem paga. **Idempotência.** Toda requisição que altera dados exige o header `Idempotency-Key`. Uma repetição com a mesma chave devolve a resposta original em vez de executar de novo. **Valores.** Dinheiro e quantidades trafegam como texto decimal (`"150.00"`, `"0.0001"`), nunca como número de ponto flutuante. **Erros.** O corpo traz `error_code` (estável, use para decidir), `message` (para pessoas) e `tracer_id` (envie ao suporte). Erros de limite de requisições e de idempotência vêm aninhados em `error`, com `code` e `request_id`. servers: - url: https://api-sandbox.beinfi.com description: Sandbox - url: https://api.beinfi.com description: Produção security: - bearerAuth: [] tags: - name: Catálogo - name: Clientes - name: Medição de uso - name: Assinaturas - name: Faturas - name: Pagamentos - name: Checkout - name: Cupons - name: Cobrança - name: Conta - name: Webhooks - name: Conta de teste - name: Rail - name: Lojas paths: /customers/{customerID}/state: parameters: - $ref: '#/components/parameters/EnrollmentIDInPath' get: tags: - Clientes summary: Consultar estado do cliente description: > Numa só leitura: a inscrição, os saldos de cada meter, as assinaturas ativas (com seus itens) e o uso do período atual. Serve para montar o painel do cliente ou decidir, antes de atender uma requisição, se ele ainda tem saldo. `customerID` aqui é o id da inscrição, não o id do cliente. operationId: getCustomerState responses: '200': content: application/json: schema: $ref: '#/components/schemas/CustomerState' description: Estado do cliente. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: EnrollmentIDInPath: name: customerID in: path required: true schema: type: string format: uuid description: ID da inscrição do cliente no produto (não o ID do cliente). schemas: CustomerState: type: object required: - customer - balances - subscriptions - usage properties: customer: $ref: '#/components/schemas/ProductCustomer' description: A inscrição. balances: type: array items: $ref: '#/components/schemas/WalletBalance' description: Um saldo por meter. subscriptions: type: array items: $ref: '#/components/schemas/Subscription' description: Assinaturas ativas, com seus itens. usage: $ref: '#/components/schemas/UsageReport' description: Uso do período atual. description: >- O estado do cliente numa só leitura: a inscrição, o saldo de cada meter, as assinaturas ativas e o uso do período atual. ProductCustomer: type: object properties: id: type: string format: uuid description: >- Id da inscrição. É este que as chamadas de cobrança e de uso esperam. customerId: type: string format: uuid description: Id do cliente. Não use nas chamadas de cobrança e de uso; use `id`. productId: type: string format: uuid externalId: type: string description: O id do cliente no seu sistema. name: type: - string - 'null' email: type: - string - 'null' taxId: type: - string - 'null' description: CPF ou CNPJ. pspRef: type: - string - 'null' description: Referência do cliente no meio de pagamento, quando existe. metadata: type: object additionalProperties: true description: Os dados livres enviados na inscrição. creditAlertSent: type: boolean description: Se o aviso de saldo baixo já foi enviado para esta inscrição. createdAt: type: string format: date-time description: >- Uma inscrição: este cliente neste produto. O `id` é o id da inscrição, que assinaturas, faturas, uso e saldos referenciam. WalletBalance: type: object properties: meter: type: string description: Chave do meter. balance: type: string description: Saldo atual, em texto decimal. Pode ser negativo. total: type: string description: Total já creditado neste meter desde o início. Subscription: type: object properties: id: type: string format: uuid customerId: type: string format: uuid description: Id da inscrição. productVersionId: type: string format: uuid description: >- A versão do produto assinada. Define o preço cobrado, mesmo se o produto mudar depois. status: type: string enum: - trialing - active - past_due - paused - canceled billingCycle: type: string enum: - weekly - monthly - annual collectionMethod: type: string enum: - charge_automatically - send_invoice description: >- `charge_automatically` cobra sozinho; `send_invoice` envia a fatura para o cliente pagar. billingMode: type: string enum: - arrears - advance description: '`advance` cobra no início do período; `arrears`, no fim.' anchor: type: string format: date-time description: Data de referência a partir da qual os períodos são contados. nextBillingDate: type: - string - 'null' format: date-time description: Próxima cobrança. startedAt: type: string format: date-time canceledAt: type: - string - 'null' format: date-time items: type: array items: $ref: '#/components/schemas/SubscriptionItem' description: O que a assinatura cobra ou concede. UsageReport: type: object required: - customerId - from - to - meters properties: customerId: type: string format: uuid description: Id da inscrição. from: type: string format: date-time description: Início da janela. to: type: string format: date-time description: Fim da janela. meters: type: array items: $ref: '#/components/schemas/MeterUsage' description: Um total por meter. description: Total de uso por meter de uma inscrição numa janela de tempo. Error: type: object required: - message - error_code - tracer_id properties: message: type: string description: Frase legível para pessoas. error_code: $ref: '#/components/schemas/ErrorCode' description: Código estável do erro. Use-o para decidir o que fazer. tracer_id: type: string description: Identificador da requisição. Informe-o ao falar com o suporte. description: >- O corpo de erro padrão. É plano (sem o envelope `error`) e o identificador de rastreio é `tracer_id`. NotFoundError: type: object required: - message - error_code - tracer_id - resource properties: message: type: string error_code: $ref: '#/components/schemas/ErrorCode' tracer_id: type: string resource: type: string SubscriptionItem: type: object properties: id: type: string format: uuid kind: type: string enum: - recurring_fee - credit_grant - metered_usage - prepaid_usage description: >- `recurring_fee` é a mensalidade fixa; `credit_grant`, créditos concedidos a cada ciclo; `metered_usage`, uso cobrado depois; `prepaid_usage`, uso pago antes. timing: type: - string - 'null' enum: - advance - arrears - null description: '`advance` cobra no início do período; `arrears`, no fim.' productVersionId: type: string format: uuid description: A versão do produto de onde o item vem. createdAt: type: string format: date-time canceledAt: type: - string - 'null' format: date-time MeterUsage: type: object required: - meterId - meter - unit - totalValue - eventCount properties: meterId: type: string format: uuid meter: type: string description: Chave do meter. unit: type: string description: Unidade do meter. totalValue: type: string description: Quantidade somada no período, em texto decimal. eventCount: type: integer description: Quantos eventos foram registrados. totalAmount: type: - string - 'null' description: >- Valor em dinheiro dessa quantidade pelo preço aplicável. Nulo quando o meter não tem preço. currency: type: - string - 'null' description: Moeda de `totalAmount`. ErrorCode: type: string examples: - internal_error - validation_failed - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited description: >- Código estável do erro. A lista não é fechada: além dos códigos genéricos, cada área tem os seus (`coupon_expired`, `insufficient_balance`, `version_not_draft`, `idempotency_key_reused`…). Um código que você não conhece deve ser tratado pelo status HTTP, mostrando `message`; não falhe ao ler a resposta. responses: Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Chave ausente ou inválida. NotFound: content: application/json: schema: $ref: '#/components/schemas/NotFoundError' description: Recurso não encontrado. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chave secreta da conta: `Authorization: Bearer sk_test_…` ou `sk_live_…`. Use só no servidor. ````