> ## 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. # Criar produto > Cria o produto junto com a versão 1 em `draft`. Para vender, publique essa versão com `POST /products/{productID}/versions/{versionID}/publish`. Com `key`, a chamada é idempotente: se a chave já existe, você recebe o produto que ela identifica (com `name` e `description` atualizados para o que enviou) em vez de um erro. O preço não entra nessa atualização: se `basePrice` ou `billingCycle` diferirem da versão atual, a resposta é `422 pricing_immutable`. Para mudar o preço, crie uma nova versão com `POST /products/{productID}/versions`. Uma requisição sem preço não mexe no preço. ## OpenAPI ````yaml /api-reference/openapi.pt-BR.json post /products 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: /products: post: tags: - Catálogo summary: Criar produto description: > Cria o produto junto com a versão 1 em `draft`. Para vender, publique essa versão com `POST /products/{productID}/versions/{versionID}/publish`. Com `key`, a chamada é idempotente: se a chave já existe, você recebe o produto que ela identifica (com `name` e `description` atualizados para o que enviou) em vez de um erro. O preço não entra nessa atualização: se `basePrice` ou `billingCycle` diferirem da versão atual, a resposta é `422 pricing_immutable`. Para mudar o preço, crie uma nova versão com `POST /products/{productID}/versions`. Uma requisição sem preço não mexe no preço. operationId: createProduct parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateProductRequest' responses: '201': content: application/json: schema: type: object properties: product: $ref: '#/components/schemas/Product' version: $ref: '#/components/schemas/Version' description: Produto criado (ou o produto existente com a mesma `key`). '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string description: >- Chave única por operação (um UUID serve). Repetir com a mesma chave devolve a resposta original. schemas: CreateProductRequest: type: object required: - name - pricingModel properties: key: type: - string - 'null' description: >- Chave estável do produto, única na sua conta. Criar duas vezes com a mesma chave devolve o mesmo produto; um preço diferente do da versão atual é recusado com `422 pricing_immutable`. name: type: string type: type: string enum: - agent - item description: '`item` (padrão) ou `agent`.' description: type: - string - 'null' pricingModel: type: string enum: - subscription - one_time - usage - prepaid description: '`subscription`, `one_time`, `usage` ou `prepaid`.' currency: type: string example: BRL description: 'Código ISO 4217 de 3 letras. Padrão: `BRL`.' billingCycle: type: - string - 'null' enum: - weekly - monthly - annual - null description: >- `weekly`, `monthly` ou `annual`. Obrigatório para `subscription` e `prepaid`; não envie nos outros modelos. basePrice: type: - string - 'null' description: Preço base da versão 1, em texto decimal (`"49.90"`). Product: type: object properties: id: type: string format: uuid key: type: - string - 'null' description: >- Chave estável que você escolhe para o produto, única na sua conta. Permite criar o mesmo produto de novo sem duplicar. name: type: string type: type: string enum: - agent - item description: '`item` (padrão) ou `agent`.' description: type: - string - 'null' pricingModel: type: string enum: - subscription - one_time - usage - prepaid description: >- Como o produto é cobrado: `subscription`, `one_time`, `usage` ou `prepaid`. currency: type: string example: BRL description: Código ISO 4217 de 3 letras, como `BRL`. status: type: string example: active description: '`active` ou `archived`.' imageUrl: type: - string - 'null' description: Endereço público da foto do produto. requiresShipping: type: boolean description: >- Se a compra exige entrega física; quando `true`, o checkout pede endereço. createdAt: type: string format: date-time updatedAt: type: string format: date-time description: Um item do catálogo. O preço fica nas versões do produto. Version: type: object properties: id: type: string format: uuid productId: type: string format: uuid version: type: integer description: Número sequencial da versão (1, 2, 3…). billingCycle: type: - string - 'null' enum: - weekly - monthly - annual - null description: '`weekly`, `monthly` ou `annual`; `null` em produtos sem recorrência.' basePrice: type: - string - 'null' description: Preço base em texto decimal; `null` em produto só de uso. status: type: string enum: - draft - published - archived description: >- `draft` (editável), `published` (vendável, preço fixo) ou `archived`. isDefault: type: boolean description: >- Se esta é a versão que o comprador recebe quando nada indica outra. Uma versão publicada com `isDefault: false` é uma oferta: só é vendida por um link de pagamento criado com `productVersionId`. publishedAt: type: - string - 'null' format: date-time commitmentAmount: type: - string - 'null' description: Mínimo cobrado por ciclo, em texto decimal; `null` sem mínimo. commitmentResets: type: boolean description: >- `true`: o mínimo não usado se perde no fim do ciclo. `false`: passa para o seguinte. consumptionFloor: type: - string - 'null' description: >- Saldo abaixo do qual o registro de uso é recusado. Veja `VersionConsumption.floor`. grants: type: array items: $ref: '#/components/schemas/VersionGrant' description: Créditos de uso que a versão concede. description: >- Uma versão do produto: o retrato do preço. Uma versão publicada nunca muda; para mudar o preço, crie outra. VersionGrant: type: object required: - meter - amount - 'on' properties: meter: type: string description: >- O `name` do medidor que recebe o crédito (por exemplo, `tokens`). `credits` é o saldo geral de créditos. amount: type: string description: Quantidade a creditar, em texto decimal. 'on': type: string enum: - cycle - payment description: >- `cycle`: a cada novo período da assinatura. `payment`: quando o pagamento confirma. description: Um crédito de uso concedido pela versão. 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`. ConflictError: type: object required: - message - error_code - tracer_id - resource - metadata properties: message: type: string description: Explicação para pessoas. error_code: $ref: '#/components/schemas/ErrorCode' description: Código estável do erro. Use este campo para decidir o que fazer. tracer_id: type: string description: Identificador da requisição. Envie ao suporte. resource: type: string description: O tipo de recurso em conflito. Texto vazio quando não se aplica. metadata: type: - object - 'null' additionalProperties: type: string description: Detalhes do conflito, em pares chave-valor. `null` quando não há. description: >- Corpo de um erro 409: o recurso está num estado que não permite a operação. RequestError: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string request_id: type: string ValidationError: type: object required: - message - error_code - tracer_id - errors properties: message: type: string error_code: $ref: '#/components/schemas/ErrorCode' tracer_id: type: string errors: type: array items: type: object required: - field - value - constraint - description properties: field: type: string value: type: string constraint: type: string description: type: string description: >- Detalhe por campo (`field`, `description`). Sempre presente num `422`; pode vir vazio. description: >- Corpo de um `422`. Mesmo formato de `Error`, mais `errors[]` com o detalhe por campo. É ali que está a frase que diz o que corrigir (por exemplo, "product has no published version"). 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. Conflict: content: application/json: schema: oneOf: - $ref: '#/components/schemas/ConflictError' - $ref: '#/components/schemas/RequestError' description: >- O recurso está num estado que não permite a operação, ou a `Idempotency-Key` já foi usada com outro corpo. ValidationFailed: content: application/json: schema: $ref: '#/components/schemas/ValidationError' description: >- Um ou mais campos são inválidos. O detalhe de cada campo está em `errors[]`. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chave secreta da conta: `Authorization: Bearer sk_test_…` ou `sk_live_…`. Use só no servidor. ````