> ## Documentation Index > Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar preço > Cria um novo preço associado a um produto. - Para cobranças recorrentes, use `type: recurring` e inclua o objeto `recurring` - Para cobranças únicas, use `type: one_time` - O valor é em centavos (ex: 2990 = R$ 29,90) ## OpenAPI ````yaml /api-reference/openapi.yml post /api/v1/prices openapi: 3.1.0 info: title: API - Simplo version: 1.0.0 description: API para cobrança e assinaturas para contas Simplo contact: name: Simplo url: https://besimplo.com email: team@besimplo.com servers: - url: https://besimplo.com description: Produção security: - apiKeyAuth: [] tags: - name: Clientes description: Clientes são as pessoas que pagarão pelos produtos da sua conta - name: Produtos description: Produtos representam os bens ou serviços que você vende - name: Preços description: Preços definem quanto cobrar e a frequência de cobrança de um Produto - name: Assinaturas description: Assinaturas conectam clientes aos seus planos para cobrança recorrente - name: Checkout description: >- Sessões de checkout permitem que clientes completem pagamentos e assinaturas através de uma interface web - name: Faturas description: Faturas representam cobranças geradas para clientes - name: Reembolsos description: Reembolsos permitem devolver pagamentos já realizados aos clientes - name: Webhooks description: > Eventos enviados via HTTP POST para a URL configurada na sua conta. Responda com status 2xx rapidamente. Processe o evento de forma assincrona. Use o campo `event.id` para garantir idempotencia. paths: /api/v1/prices: post: tags: - Preços summary: Criar preço description: > Cria um novo preço associado a um produto. - Para cobranças recorrentes, use `type: recurring` e inclua o objeto `recurring` - Para cobranças únicas, use `type: one_time` - O valor é em centavos (ex: 2990 = R$ 29,90) operationId: createPrice requestBody: description: Dados do preço que será criado required: true content: application/json: schema: type: object unevaluatedProperties: false required: - price properties: price: type: object unevaluatedProperties: false required: - product_id - unit_amount - type properties: product_id: type: string pattern: ^prod_[0-9a-z]{26}$ description: >- ID do produto associado, no formato TypeID com prefixo `prod_`. example: prod_01h455vb4pex5vsknk084sn02q unit_amount: type: integer minimum: 0 maximum: 999999 description: Valor em centavos (máximo R$ 9.999,99). example: 2990 type: type: string description: Tipo de cobrança. enum: - one_time - recurring example: recurring recurring: type: object description: Obrigatório quando type=recurring. unevaluatedProperties: false properties: interval: type: string description: Intervalo de cobrança. enum: - day - week - month - year example: month interval_count: type: integer minimum: 1 maximum: 1095 description: > Número de intervalos entre cobranças. Regras adicionais para parcelamento: - `day` e `week` não permitem parcelamento - `month` só permite parcelamento a partir de `2` - `year` permite parcelamento até o limite global de `12` example: 1 description: type: - string - 'null' nullable: true description: Nome amigável do preço. maxLength: 250 example: Plano Mensal Premium card_installments_enabled: type: boolean description: | Permite parcelamento no cartão para este preço. Não permitido para recorrências `day` e `week`. Para recorrência `month`, exige `interval_count >= 2`. default: false example: false max_card_installments: type: integer minimum: 1 maximum: 12 description: > Máximo de parcelas aceitas no cartão. Use `1` quando não permitir parcelamento. Para preços recorrentes, não pode exceder a recorrência em meses, limitado a `12`. O valor mínimo por parcela é `R$ 5,00`. default: 1 example: 1 external_code: type: - string - 'null' nullable: true description: Código externo único por conta. maxLength: 250 example: price_premium_monthly active: type: boolean description: Se o preço está ativo (padrão true). default: true example: true examples: recurring: summary: Preço recorrente mensal value: price: product_id: prod_01h455vb4pex5vsknk084sn02q unit_amount: 2990 type: recurring recurring: interval: month interval_count: 1 description: Plano Mensal one_time: summary: Preço único value: price: product_id: prod_01h455vb4pex5vsknk084sn02q unit_amount: 9900 type: one_time description: Compra Única responses: '201': description: Preço criado com sucesso content: application/json: schema: type: object unevaluatedProperties: false required: - id - object - active - live_mode - created - currency - product - type - unit_amount - card_installments_enabled - max_card_installments properties: id: type: string pattern: ^price_[0-9a-z]{26}$ readOnly: true description: ID único do preço, no formato TypeID com prefixo `price_`. example: price_01h455vb4pex5vsknk084sn02q object: type: string description: Tipo do objeto. Sempre 'price'. enum: - price example: price active: type: boolean description: Se o preço está ativo para novas compras. example: true live_mode: type: boolean description: >- Indica ambiente de produção (true) ou sandbox (false). Dados de sandbox são limpos periodicamente. example: true created: type: integer format: int64 readOnly: true description: Timestamp Unix de quando o preço foi criado. example: 1704672000 currency: type: string description: Moeda do valor. Sempre 'brl' (Real brasileiro). enum: - brl example: brl description: type: - string - 'null' nullable: true description: Nome amigável do preço. example: Plano Mensal Premium product: type: string pattern: ^prod_[0-9a-z]{26}$ description: >- ID do produto associado, no formato TypeID com prefixo `prod_`. example: prod_01h455vb4pex5vsknk084sn02q type: type: string description: | Tipo de cobrança: - one_time: Cobrança única. - recurring: Cobrança recorrente. enum: - one_time - recurring example: recurring unit_amount: type: integer minimum: 0 maximum: 999999 description: Valor em centavos. R$ 29,90 = 2990. Máximo R$ 9.999,99. example: 2990 unit_amount_decimal: type: string description: Valor em centavos como string. example: '2990' recurring: oneOf: - type: object unevaluatedProperties: false required: - interval - interval_count properties: interval: type: string description: | Intervalo de cobrança: - day: Diário. - week: Semanal. - month: Mensal. - year: Anual. enum: - day - week - month - year example: month interval_count: type: integer minimum: 1 description: | Número de intervalos entre cobranças. Máximo de 3 anos: - day: máximo 1095 - week: máximo 156 - month: máximo 36 - year: máximo 3 example: 1 - type: 'null' nullable: true description: Configuração de recorrência (apenas para type=recurring). external_code: type: - string - 'null' nullable: true description: Código externo para idempotência. maxLength: 250 example: price_premium_monthly card_installments_enabled: type: boolean description: > Indica se este preço permite parcelamento no cartão de crédito. Regras: - preços avulsos podem permitir parcelamento - recorrências diárias e semanais não podem permitir parcelamento - recorrências mensais exigem pelo menos 2 meses para permitir parcelamento example: false max_card_installments: type: integer minimum: 1 maximum: 12 description: > Máximo de parcelas aceitas no cartão. Regras: - quando `card_installments_enabled=false`, o valor efetivo é `1` - preços recorrentes não podem exceder a recorrência em meses, com limite global de `12` - o valor mínimo por parcela é `R$ 5,00` example: 1 effective_max_card_installments: type: integer minimum: 1 maximum: 12 readOnly: true description: > Máximo efetivo de parcelas aceitas no cartão após aplicar as regras de recorrência e valor mínimo. example: 1 installment_selection_available: type: boolean readOnly: true description: >- Indica se a seleção de parcelas está disponível para o preço. example: false '404': description: Recurso não encontrado content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: not_found: summary: Recurso não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: The requested resource was not found code: NOT_FOUND product_not_found: summary: Produto não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: 'No such product: ''prod_01h455vb4pex5vsknk084sn02q''' code: RESOURCE_MISSING '422': description: Erro de validação content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: validation_error: summary: Erro de validação de campos value: type: https://problems-registry.smartbear.com/validation-error status: 422 title: Unprocessable Entity detail: The request payload contains validation errors code: VALIDATION_ERROR errors: - detail: Name can't be blank pointer: /customer/name components: securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: > A chave de API usada para autenticar a requisição e identificar a sua conta. **Exemplo:** `Authorization: ApiKey my-secure-key` ````