openapi: 3.1.0 info: title: Hubfy API version: 1.0.0 description: API pública da Hubfy para produtos, preços, arquivos, clientes, pedidos e links de pagamento. Autenticação por chave da conta. GET consulta; POST cria, atualiza ou executa ações; DELETE remove ou desativa. O ambiente usa dados reais, sem sandbox separado. Consulte os fundamentos, os objetos e os eventos em https://docs.hubfy.io/api-reference/introduction. servers: - url: https://api.hubfy.io tags: - name: Produtos description: Objeto Product. Campos e relacionamentos na visão geral. - name: Preços description: Objeto Price. Campos e relacionamentos na visão geral. - name: Arquivos description: Objeto Asset. Campos e relacionamentos na visão geral. - name: Clientes description: Objeto Customer. Campos e relacionamentos na visão geral. - name: Pedidos description: Objeto Order. Campos e relacionamentos na visão geral. - name: Links de pagamento description: Objeto PaymentLink. Campos e relacionamentos na visão geral. - name: Fundamentos da API description: Conexão e identificação da API. paths: /v1/assets/files: post: operationId: createFile tags: - Arquivos summary: Iniciar upload de arquivo description: |- Siga o fluxo de upload e download e utilize apenas a credencial temporária retornada para transferir conteúdo. Permissão: `assets:write` ou `write`. Consulte a [visão geral](/api-reference/assets/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Upload" example: id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z description: null file: checksum: null filename: material.pdf metadata: {} mime_type: application/pdf object: asset size_bytes: null status: uploading title: Material de apoio type: file updated_at: 2030-01-01T00:00:00.000Z upload: expires_at: 2030-01-01T00:00:00.000Z method: PUT url: https://uploads.example.com/temporary-credential video: null "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FileCreate" example: filename: material.pdf mime_type: application/pdf title: Material de apoio /v1/assets/videos: post: operationId: createVideo tags: - Arquivos summary: Iniciar upload de vídeo description: |- Siga o fluxo de upload e download e utilize apenas a credencial temporária retornada para transferir conteúdo. Permissão: `assets:write` ou `write`. Consulte a [visão geral](/api-reference/assets/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Upload" example: id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z description: null file: null metadata: {} mime_type: null object: asset size_bytes: null status: uploading title: Material de apoio type: video updated_at: 2030-01-01T00:00:00.000Z upload: expires_at: 2030-01-01T00:00:00.000Z method: PUT url: https://uploads.example.com/temporary-credential video: duration_seconds: null height: null progress: null width: null "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VideoCreate" example: title: Aula de exemplo /v1/assets/{id}/confirm: post: operationId: confirmAssetUpload tags: - Arquivos summary: Confirmar upload description: |- Siga o fluxo de upload e download e utilize apenas a credencial temporária retornada para transferir conteúdo. Permissão: `assets:write` ou `write`. Consulte a [visão geral](/api-reference/assets/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^ast_[a-z0-9]{16}$ description: ID público do arquivo na conta. - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Asset" example: id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z description: null file: checksum: null filename: material.pdf metadata: {} mime_type: application/pdf object: asset size_bytes: null status: uploading title: Material de apoio type: file updated_at: 2030-01-01T00:00:00.000Z video: null "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Empty" example: {} /v1/assets/{id}/download: get: operationId: getAssetDownload tags: - Arquivos summary: Obter URL de download description: |- Siga o fluxo de upload e download e utilize apenas a credencial temporária retornada para transferir conteúdo. Permissão: `assets:read` ou `read`. Consulte a [visão geral](/api-reference/assets/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^ast_[a-z0-9]{16}$ description: ID público do arquivo na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Download" example: asset: ast_1234567890abcdef expires_at: 2030-01-01T00:00:00.000Z object: download url: https://downloads.example.com/temporary-credential "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1/products: get: operationId: listProduct tags: - Produtos summary: Listar produtos description: |- Lista os registros da conta, com paginação por cursor. Permissão: `products:read` ou `read`. Consulte a [visão geral](/api-reference/products/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: benefit in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: ending_before in: query schema: type: string description: ID para percorrer a lista na direção anterior. Não combine com starting_after. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Número de itens, de 1 a 100; padrão 50. - name: starting_after in: query schema: type: string description: ID do último item da página anterior. Não combine com ending_before. - name: status in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: type: object additionalProperties: false required: - data - has_more - object - url properties: data: type: array items: $ref: "#/components/schemas/Product" has_more: type: boolean object: type: string const: list url: type: string example: data: - id: pro_1234567890abcdef benefit: null cover_url: null created_at: 2030-01-01T00:00:00.000Z description: null metadata: {} name: Curso de exemplo object: product prices: - prc_1234567890abcdef status: draft updated_at: 2030-01-01T00:00:00.000Z has_more: false object: list url: /v1/products "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: createProduct tags: - Produtos summary: Criar um produto description: |- Na criação, envie `name` e `initial_price`. O preço inicial segue as mesmas regras de [Preços](/api-reference/prices/object), sem o campo `product`. A atualização aceita `name`, `description`, `status`, `benefit` e `metadata`. A capa é definida no painel; `cover_url` é somente leitura. Se o produto estiver vinculado a pedido, checkout ou conteúdo, a exclusão o arquiva e retorna o produto com `status: "archived"`. Sem esses vínculos, retorna a confirmação de exclusão. Configurar `benefit` não cadastra cursos nem vínculos de entrega pela API. Permissão: `products:write` ou `write`. Consulte a [visão geral](/api-reference/products/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Product" example: id: pro_1234567890abcdef benefit: null cover_url: null created_at: 2030-01-01T00:00:00.000Z description: null metadata: {} name: Curso de exemplo object: product prices: - prc_1234567890abcdef status: draft updated_at: 2030-01-01T00:00:00.000Z "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ProductCreate" example: initial_price: currency: BRL unit_amount: 4990 name: Curso de exemplo /v1/products/{id}: get: operationId: getProduct tags: - Produtos summary: Obter um produto description: |- Retorna o objeto completo quando ele pertence à conta da chave. Permissão: `products:read` ou `read`. Consulte a [visão geral](/api-reference/products/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^pro_[a-z0-9]{16}$ description: ID público do produto na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Product" example: id: pro_1234567890abcdef benefit: null cover_url: null created_at: 2030-01-01T00:00:00.000Z description: null metadata: {} name: Curso de exemplo object: product prices: - prc_1234567890abcdef status: draft updated_at: 2030-01-01T00:00:00.000Z "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: updateProduct tags: - Produtos summary: Atualizar um produto description: |- Na criação, envie `name` e `initial_price`. O preço inicial segue as mesmas regras de [Preços](/api-reference/prices/object), sem o campo `product`. A atualização aceita `name`, `description`, `status`, `benefit` e `metadata`. A capa é definida no painel; `cover_url` é somente leitura. Se o produto estiver vinculado a pedido, checkout ou conteúdo, a exclusão o arquiva e retorna o produto com `status: "archived"`. Sem esses vínculos, retorna a confirmação de exclusão. Configurar `benefit` não cadastra cursos nem vínculos de entrega pela API. Permissão: `products:write` ou `write`. Consulte a [visão geral](/api-reference/products/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^pro_[a-z0-9]{16}$ description: ID público do produto na conta. - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Product" example: id: pro_1234567890abcdef benefit: null cover_url: null created_at: 2030-01-01T00:00:00.000Z description: null metadata: {} name: Curso de exemplo object: product prices: - prc_1234567890abcdef status: draft updated_at: 2030-01-01T00:00:00.000Z "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ProductUpdate" example: metadata: reference: exemplo delete: operationId: deleteProduct tags: - Produtos summary: Excluir um produto description: |- Na criação, envie `name` e `initial_price`. O preço inicial segue as mesmas regras de [Preços](/api-reference/prices/object), sem o campo `product`. A atualização aceita `name`, `description`, `status`, `benefit` e `metadata`. A capa é definida no painel; `cover_url` é somente leitura. Se o produto estiver vinculado a pedido, checkout ou conteúdo, a exclusão o arquiva e retorna o produto com `status: "archived"`. Sem esses vínculos, retorna a confirmação de exclusão. Configurar `benefit` não cadastra cursos nem vínculos de entrega pela API. Permissão: `products:write` ou `write`. Consulte a [visão geral](/api-reference/products/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^pro_[a-z0-9]{16}$ description: ID público do produto na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: oneOf: - $ref: "#/components/schemas/Product" - $ref: "#/components/schemas/Deleted" example: id: pro_1234567890abcdef deleted: true object: product "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1/prices: get: operationId: listPrice tags: - Preços summary: Listar preços description: |- Lista os registros da conta, com paginação por cursor. Permissão: `prices:read` ou `read`. Consulte a [visão geral](/api-reference/prices/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: category in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: ending_before in: query schema: type: string description: ID para percorrer a lista na direção anterior. Não combine com starting_after. - name: is_active in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: boolean - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Número de itens, de 1 a 100; padrão 50. - name: product in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: starting_after in: query schema: type: string description: ID do último item da página anterior. Não combine com ending_before. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: type: object additionalProperties: false required: - data - has_more - object - url properties: data: type: array items: $ref: "#/components/schemas/Price" has_more: type: boolean object: type: string const: list url: type: string example: data: - id: prc_1234567890abcdef category: one_time created_at: 2030-01-01T00:00:00.000Z currency: BRL is_active: true metadata: {} min_price: null name: Oferta principal object: price package_size: 1 product: pro_1234567890abcdef renewal_interval_quantity: null renewal_interval_unit: null scheme: standard setup_fee: null setup_fee_enabled: false suggested_price: null tiers: [] trial_interval_quantity: null trial_interval_unit: null unit_amount: 4990 unit_amount_decimal: null updated_at: 2030-01-01T00:00:00.000Z usage_aggregation: null used: false has_more: false object: list url: /v1/prices "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: createPrice tags: - Preços summary: Criar um preço description: |- Na criação, `product` é obrigatório e precisa pertencer à mesma conta. Esse vínculo é imutável. Depois do primeiro uso em checkout ou pedido (`used: true`), apenas `name`, `metadata` e `is_active` podem mudar. Para alterar valor ou recorrência de um preço usado, crie outro preço. Excluir um preço usado o desativa; um preço sem uso pode ser excluído. - `subscription`: exige `renewal_interval_unit` e `renewal_interval_quantity` positiva. O período de teste deve ter unidade e quantidade juntas. Taxa inicial habilitada exige `setup_fee`. - `lead_magnet`: exige `unit_amount: 0`. - `pwyw`: exige `min_price`; se houver `suggested_price`, ele deve ser maior ou igual ao mínimo. - `graduated` e `volume`: exigem faixas não vazias, com limites crescentes e última faixa `up_to: null`. - Valores inteiros recebidos não podem exceder `2147483647`. `package_size` deve ser pelo menos 1. Estas são condições do cadastro. Este recurso não cobra um cliente, cria assinaturas ou registra consumo. Permissão: `prices:write` ou `write`. Consulte a [visão geral](/api-reference/prices/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Price" example: id: prc_1234567890abcdef category: one_time created_at: 2030-01-01T00:00:00.000Z currency: BRL is_active: true metadata: {} min_price: null name: Oferta principal object: price package_size: 1 product: pro_1234567890abcdef renewal_interval_quantity: null renewal_interval_unit: null scheme: standard setup_fee: null setup_fee_enabled: false suggested_price: null tiers: [] trial_interval_quantity: null trial_interval_unit: null unit_amount: 4990 unit_amount_decimal: null updated_at: 2030-01-01T00:00:00.000Z usage_aggregation: null used: false "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PriceCreate" example: currency: BRL name: Oferta principal product: pro_1234567890abcdef unit_amount: 4990 /v1/prices/{id}: get: operationId: getPrice tags: - Preços summary: Obter um preço description: |- Retorna o objeto completo quando ele pertence à conta da chave. Permissão: `prices:read` ou `read`. Consulte a [visão geral](/api-reference/prices/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^prc_[a-z0-9]{16}$ description: ID público do preço na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Price" example: id: prc_1234567890abcdef category: one_time created_at: 2030-01-01T00:00:00.000Z currency: BRL is_active: true metadata: {} min_price: null name: Oferta principal object: price package_size: 1 product: pro_1234567890abcdef renewal_interval_quantity: null renewal_interval_unit: null scheme: standard setup_fee: null setup_fee_enabled: false suggested_price: null tiers: [] trial_interval_quantity: null trial_interval_unit: null unit_amount: 4990 unit_amount_decimal: null updated_at: 2030-01-01T00:00:00.000Z usage_aggregation: null used: false "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: updatePrice tags: - Preços summary: Atualizar um preço description: |- Na criação, `product` é obrigatório e precisa pertencer à mesma conta. Esse vínculo é imutável. Depois do primeiro uso em checkout ou pedido (`used: true`), apenas `name`, `metadata` e `is_active` podem mudar. Para alterar valor ou recorrência de um preço usado, crie outro preço. Excluir um preço usado o desativa; um preço sem uso pode ser excluído. - `subscription`: exige `renewal_interval_unit` e `renewal_interval_quantity` positiva. O período de teste deve ter unidade e quantidade juntas. Taxa inicial habilitada exige `setup_fee`. - `lead_magnet`: exige `unit_amount: 0`. - `pwyw`: exige `min_price`; se houver `suggested_price`, ele deve ser maior ou igual ao mínimo. - `graduated` e `volume`: exigem faixas não vazias, com limites crescentes e última faixa `up_to: null`. - Valores inteiros recebidos não podem exceder `2147483647`. `package_size` deve ser pelo menos 1. Estas são condições do cadastro. Este recurso não cobra um cliente, cria assinaturas ou registra consumo. Permissão: `prices:write` ou `write`. Consulte a [visão geral](/api-reference/prices/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^prc_[a-z0-9]{16}$ description: ID público do preço na conta. - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Price" example: id: prc_1234567890abcdef category: one_time created_at: 2030-01-01T00:00:00.000Z currency: BRL is_active: true metadata: {} min_price: null name: Oferta principal object: price package_size: 1 product: pro_1234567890abcdef renewal_interval_quantity: null renewal_interval_unit: null scheme: standard setup_fee: null setup_fee_enabled: false suggested_price: null tiers: [] trial_interval_quantity: null trial_interval_unit: null unit_amount: 4990 unit_amount_decimal: null updated_at: 2030-01-01T00:00:00.000Z usage_aggregation: null used: false "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PriceUpdate" example: metadata: reference: exemplo delete: operationId: deletePrice tags: - Preços summary: Excluir um preço description: |- Na criação, `product` é obrigatório e precisa pertencer à mesma conta. Esse vínculo é imutável. Depois do primeiro uso em checkout ou pedido (`used: true`), apenas `name`, `metadata` e `is_active` podem mudar. Para alterar valor ou recorrência de um preço usado, crie outro preço. Excluir um preço usado o desativa; um preço sem uso pode ser excluído. - `subscription`: exige `renewal_interval_unit` e `renewal_interval_quantity` positiva. O período de teste deve ter unidade e quantidade juntas. Taxa inicial habilitada exige `setup_fee`. - `lead_magnet`: exige `unit_amount: 0`. - `pwyw`: exige `min_price`; se houver `suggested_price`, ele deve ser maior ou igual ao mínimo. - `graduated` e `volume`: exigem faixas não vazias, com limites crescentes e última faixa `up_to: null`. - Valores inteiros recebidos não podem exceder `2147483647`. `package_size` deve ser pelo menos 1. Estas são condições do cadastro. Este recurso não cobra um cliente, cria assinaturas ou registra consumo. Permissão: `prices:write` ou `write`. Consulte a [visão geral](/api-reference/prices/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^prc_[a-z0-9]{16}$ description: ID público do preço na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: oneOf: - $ref: "#/components/schemas/Price" - $ref: "#/components/schemas/Deleted" example: id: prc_1234567890abcdef deleted: true object: price "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1/assets: get: operationId: listAsset tags: - Arquivos summary: Listar arquivos description: |- Lista os registros da conta, com paginação por cursor. Permissão: `assets:read` ou `read`. Consulte a [visão geral](/api-reference/assets/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: ending_before in: query schema: type: string description: ID para percorrer a lista na direção anterior. Não combine com starting_after. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Número de itens, de 1 a 100; padrão 50. - name: starting_after in: query schema: type: string description: ID do último item da página anterior. Não combine com ending_before. - name: status in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: type in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: type: object additionalProperties: false required: - data - has_more - object - url properties: data: type: array items: $ref: "#/components/schemas/Asset" has_more: type: boolean object: type: string const: list url: type: string example: data: - id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z description: null file: checksum: null filename: material.pdf metadata: {} mime_type: application/pdf object: asset size_bytes: null status: uploading title: Material de apoio type: file updated_at: 2030-01-01T00:00:00.000Z video: null has_more: false object: list url: /v1/assets "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1/assets/{id}: get: operationId: getAsset tags: - Arquivos summary: Obter um arquivo description: |- Retorna o objeto completo quando ele pertence à conta da chave. Permissão: `assets:read` ou `read`. Consulte a [visão geral](/api-reference/assets/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^ast_[a-z0-9]{16}$ description: ID público do arquivo na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Asset" example: id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z description: null file: checksum: null filename: material.pdf metadata: {} mime_type: application/pdf object: asset size_bytes: null status: uploading title: Material de apoio type: file updated_at: 2030-01-01T00:00:00.000Z video: null "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: updateAsset tags: - Arquivos summary: Atualizar um arquivo description: |- Use [Iniciar upload de arquivo](/api-reference/assets/create-file) com `title` e `filename`, ou [Iniciar upload de vídeo](/api-reference/assets/create-video) com `title`. A resposta inclui `asset` e uma credencial de envio em `upload`. Siga o [fluxo de upload e download](/api-reference/assets/uploads). Depois de criado, apenas `description`, `metadata` e `title` são editáveis. O tipo e os dados de processamento são preenchidos pela Hubfy. Downloads privados exigem um arquivo pronto e devolvem uma URL válida por uma hora. Excluir marca o item como removido e agenda a limpeza do conteúdo. Permissão: `assets:write` ou `write`. Consulte a [visão geral](/api-reference/assets/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^ast_[a-z0-9]{16}$ description: ID público do arquivo na conta. - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Asset" example: id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z description: null file: checksum: null filename: material.pdf metadata: {} mime_type: application/pdf object: asset size_bytes: null status: uploading title: Material de apoio type: file updated_at: 2030-01-01T00:00:00.000Z video: null "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AssetUpdate" example: title: Material atualizado delete: operationId: deleteAsset tags: - Arquivos summary: Excluir um arquivo description: |- Use [Iniciar upload de arquivo](/api-reference/assets/create-file) com `title` e `filename`, ou [Iniciar upload de vídeo](/api-reference/assets/create-video) com `title`. A resposta inclui `asset` e uma credencial de envio em `upload`. Siga o [fluxo de upload e download](/api-reference/assets/uploads). Depois de criado, apenas `description`, `metadata` e `title` são editáveis. O tipo e os dados de processamento são preenchidos pela Hubfy. Downloads privados exigem um arquivo pronto e devolvem uma URL válida por uma hora. Excluir marca o item como removido e agenda a limpeza do conteúdo. Permissão: `assets:write` ou `write`. Consulte a [visão geral](/api-reference/assets/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^ast_[a-z0-9]{16}$ description: ID público do arquivo na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: oneOf: - $ref: "#/components/schemas/Asset" - $ref: "#/components/schemas/Deleted" example: id: ast_1234567890abcdef deleted: true object: asset "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1/customers: get: operationId: listCustomer tags: - Clientes summary: Listar clientes description: |- Lista os registros da conta, com paginação por cursor. Permissão: `customers:read` ou `read`. Consulte a [visão geral](/api-reference/customers/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: email in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: email_marketing_status in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: ending_before in: query schema: type: string description: ID para percorrer a lista na direção anterior. Não combine com starting_after. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Número de itens, de 1 a 100; padrão 50. - name: starting_after in: query schema: type: string description: ID do último item da página anterior. Não combine com ending_before. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: type: object additionalProperties: false required: - data - has_more - object - url properties: data: type: array items: $ref: "#/components/schemas/Customer" has_more: type: boolean object: type: string const: list url: type: string example: data: - id: cus_1234567890abcdef city: null country: null created_at: 2030-01-01T00:00:00.000Z currency: BRL document: null document_type: null email: cliente@example.com email_marketing_status: subscribed external_id: null first_name: null last_name: null metadata: {} mrr_cents: 0 name: Cliente Exemplo object: customer phone: null region: null total_revenue_cents: 0 updated_at: 2030-01-01T00:00:00.000Z has_more: false object: list url: /v1/customers "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: createCustomer tags: - Clientes summary: Criar um cliente description: |- Na criação, envie `email` e `name`, ambos não vazios. O email é convertido para minúsculas. Se já existir um cliente com esse email na conta, a criação retorna esse cadastro e preenche somente valores ausentes; não sobrescreve os dados existentes. Para alterar valores preenchidos, use a atualização. A atualização aceita os dados de contato, identificação, preferências, `external_id` e `metadata`. Os indicadores financeiros e `currency` são somente leitura. Excluir um cliente não é uma operação de estorno ou cancelamento; vínculos que impeçam a remoção retornam erro. Permissão: `customers:write` ou `write`. Consulte a [visão geral](/api-reference/customers/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Customer" example: id: cus_1234567890abcdef city: null country: null created_at: 2030-01-01T00:00:00.000Z currency: BRL document: null document_type: null email: cliente@example.com email_marketing_status: subscribed external_id: null first_name: null last_name: null metadata: {} mrr_cents: 0 name: Cliente Exemplo object: customer phone: null region: null total_revenue_cents: 0 updated_at: 2030-01-01T00:00:00.000Z "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CustomerCreate" example: email: cliente@example.com name: Cliente Exemplo /v1/customers/{id}: get: operationId: getCustomer tags: - Clientes summary: Obter um cliente description: |- Retorna o objeto completo quando ele pertence à conta da chave. Permissão: `customers:read` ou `read`. Consulte a [visão geral](/api-reference/customers/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^cus_[a-z0-9]{16}$ description: ID público do cliente na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Customer" example: id: cus_1234567890abcdef city: null country: null created_at: 2030-01-01T00:00:00.000Z currency: BRL document: null document_type: null email: cliente@example.com email_marketing_status: subscribed external_id: null first_name: null last_name: null metadata: {} mrr_cents: 0 name: Cliente Exemplo object: customer phone: null region: null total_revenue_cents: 0 updated_at: 2030-01-01T00:00:00.000Z "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: updateCustomer tags: - Clientes summary: Atualizar um cliente description: |- Na criação, envie `email` e `name`, ambos não vazios. O email é convertido para minúsculas. Se já existir um cliente com esse email na conta, a criação retorna esse cadastro e preenche somente valores ausentes; não sobrescreve os dados existentes. Para alterar valores preenchidos, use a atualização. A atualização aceita os dados de contato, identificação, preferências, `external_id` e `metadata`. Os indicadores financeiros e `currency` são somente leitura. Excluir um cliente não é uma operação de estorno ou cancelamento; vínculos que impeçam a remoção retornam erro. Permissão: `customers:write` ou `write`. Consulte a [visão geral](/api-reference/customers/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^cus_[a-z0-9]{16}$ description: ID público do cliente na conta. - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Customer" example: id: cus_1234567890abcdef city: null country: null created_at: 2030-01-01T00:00:00.000Z currency: BRL document: null document_type: null email: cliente@example.com email_marketing_status: subscribed external_id: null first_name: null last_name: null metadata: {} mrr_cents: 0 name: Cliente Exemplo object: customer phone: null region: null total_revenue_cents: 0 updated_at: 2030-01-01T00:00:00.000Z "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CustomerUpdate" example: metadata: reference: exemplo delete: operationId: deleteCustomer tags: - Clientes summary: Excluir um cliente description: |- Na criação, envie `email` e `name`, ambos não vazios. O email é convertido para minúsculas. Se já existir um cliente com esse email na conta, a criação retorna esse cadastro e preenche somente valores ausentes; não sobrescreve os dados existentes. Para alterar valores preenchidos, use a atualização. A atualização aceita os dados de contato, identificação, preferências, `external_id` e `metadata`. Os indicadores financeiros e `currency` são somente leitura. Excluir um cliente não é uma operação de estorno ou cancelamento; vínculos que impeçam a remoção retornam erro. Permissão: `customers:write` ou `write`. Consulte a [visão geral](/api-reference/customers/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^cus_[a-z0-9]{16}$ description: ID público do cliente na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: oneOf: - $ref: "#/components/schemas/Customer" - $ref: "#/components/schemas/Deleted" example: id: cus_1234567890abcdef deleted: true object: customer "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1/orders: get: operationId: listOrder tags: - Pedidos summary: Listar pedidos description: |- Lista os registros da conta, com paginação por cursor. Permissão: `orders:read` ou `read`. Consulte a [visão geral](/api-reference/orders/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: customer in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: ending_before in: query schema: type: string description: ID para percorrer a lista na direção anterior. Não combine com starting_after. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Número de itens, de 1 a 100; padrão 50. - name: price in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: product in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string - name: starting_after in: query schema: type: string description: ID do último item da página anterior. Não combine com ending_before. - name: status in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: type: object additionalProperties: false required: - data - has_more - object - url properties: data: type: array items: $ref: "#/components/schemas/Order" has_more: type: boolean object: type: string const: list url: type: string example: data: - id: ord_1234567890abcdef access_expires_at: null created_at: 2030-01-01T00:00:00.000Z currency: BRL customer: cus_1234567890abcdef effective_order_at: 2030-01-01T00:00:00.000Z metadata: {} object: order order_number: 1001 payment_method: credit_card price: prc_1234567890abcdef product: pro_1234567890abcdef status: approved subscription_status: null type: one_time unit_amount: 4990 updated_at: 2030-01-01T00:00:00.000Z has_more: false object: list url: /v1/orders "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1/orders/{id}: get: operationId: getOrder tags: - Pedidos summary: Obter um pedido description: |- Retorna o objeto completo quando ele pertence à conta da chave. Permissão: `orders:read` ou `read`. Consulte a [visão geral](/api-reference/orders/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^ord_[a-z0-9]{16}$ description: ID público do pedido na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Order" example: id: ord_1234567890abcdef access_expires_at: null created_at: 2030-01-01T00:00:00.000Z currency: BRL customer: cus_1234567890abcdef effective_order_at: 2030-01-01T00:00:00.000Z metadata: {} object: order order_number: 1001 payment_method: credit_card price: prc_1234567890abcdef product: pro_1234567890abcdef status: approved subscription_status: null type: one_time unit_amount: 4990 updated_at: 2030-01-01T00:00:00.000Z "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: updateOrder tags: - Pedidos summary: Atualizar um pedido description: |- A atualização aceita exclusivamente `access_expires_at` e `metadata`. Alterar a validade de acesso não muda o pagamento, não cancela a assinatura e não provoca uma cobrança. Assinaturas com pedido `approved` ou `completed` não aceitam validade de acesso nula. Não há criação, exclusão, estorno ou cancelamento de pedidos por este recurso. Consulte [Erros](/api-reference/errors) para tratar campos não editáveis e recursos indisponíveis. Permissão: `orders:write` ou `write`. Consulte a [visão geral](/api-reference/orders/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^ord_[a-z0-9]{16}$ description: ID público do pedido na conta. - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/Order" example: id: ord_1234567890abcdef access_expires_at: null created_at: 2030-01-01T00:00:00.000Z currency: BRL customer: cus_1234567890abcdef effective_order_at: 2030-01-01T00:00:00.000Z metadata: {} object: order order_number: 1001 payment_method: credit_card price: prc_1234567890abcdef product: pro_1234567890abcdef status: approved subscription_status: null type: one_time unit_amount: 4990 updated_at: 2030-01-01T00:00:00.000Z "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrderUpdate" example: metadata: reference: exemplo /v1/payment_links: get: operationId: listPaymentLink tags: - Links de pagamento summary: Listar links de pagamento description: |- Lista os links da conta, inclusive os checkouts criados no painel, com paginação por cursor. Permissão: `payment_links:read` ou `read`. Consulte a [visão geral](/api-reference/payment-links/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: ending_before in: query schema: type: string description: ID para percorrer a lista na direção anterior. Não combine com starting_after. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Número de itens, de 1 a 100; padrão 50. - name: starting_after in: query schema: type: string description: ID do último item da página anterior. Não combine com ending_before. - name: status in: query description: Filtra por igualdade; deve ser mantido ao usar um cursor. schema: type: string enum: - draft - active - inactive responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: type: object additionalProperties: false required: - data - has_more - object - url properties: data: type: array items: $ref: "#/components/schemas/PaymentLink" has_more: type: boolean object: type: string const: list url: type: string example: data: - id: chk_1234567890abcdef allow_discount_codes: false amount: 4990 cancel_url: null checkout_experience: banner: null confirmation_message: Sua compra foi confirmada. Enviaremos as instruções de acesso por email. footer_expanded: false header_shows_logo: null installment_teaser_mode: null order_summary_mode: null product_description_mode: null product_image_mode: null require_billing_address: null require_document: null require_phone: null summary_style: null created_at: 2030-01-01T00:00:00.000Z currency: BRL discount: null has_surcharge: false interest_payer: buyer line_items: - adjustable_quantity: null price: prc_1234567890abcdef product: pro_1234567890abcdef quantity: 1 unit_amount: 4990 max_installments: 1 metadata: {} object: payment_link optional_items: [] payment_method_collection: always payment_methods: - credit_card - pix recurring: null status: active subscription_data: null success_url: null template: null title: Curso de exemplo total_orders: 0 updated_at: 2030-01-01T00:00:00.000Z url: https://checkout.example.com/pay/link-example has_more: false object: list url: /v1/payment_links "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: createPaymentLink tags: - Links de pagamento summary: Criar um link de pagamento description: |- Envie `title` e `line_items`. O link nasce publicado (`status: active`) e a resposta traz `url`; use `status: draft` para revisar no painel antes de publicar. Um link vende de 1 a 20 preços de produtos distintos, todos avulsos ou todos assinaturas com o mesmo período. Publicar (`status: active`) exige conta aprovada para receber pagamentos e valida os itens: preços ativos, fixos, em reais, sem cobrança por uso, período grátis ou taxa de adesão, com total entre R$ 5,00 e R$ 999.999,99. Assinaturas exigem `payment_methods: ["credit_card"]` e `max_installments: 1`. `line_items` substitui a lista inteira; `metadata` substitui o objeto inteiro. Cada abertura de `url` cria uma sessão de compra com as condições vigentes. Permissão: `payment_links:write` ou `write`. Consulte a [visão geral](/api-reference/payment-links/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. required: true requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PaymentLinkCreate" example: line_items: - price: prc_1234567890abcdef quantity: 1 title: Curso de exemplo responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/PaymentLink" example: id: chk_1234567890abcdef allow_discount_codes: false amount: 4990 cancel_url: null checkout_experience: banner: null confirmation_message: Sua compra foi confirmada. Enviaremos as instruções de acesso por email. footer_expanded: false header_shows_logo: null installment_teaser_mode: null order_summary_mode: null product_description_mode: null product_image_mode: null require_billing_address: null require_document: null require_phone: null summary_style: null created_at: 2030-01-01T00:00:00.000Z currency: BRL discount: null has_surcharge: false interest_payer: buyer line_items: - adjustable_quantity: null price: prc_1234567890abcdef product: pro_1234567890abcdef quantity: 1 unit_amount: 4990 max_installments: 1 metadata: {} object: payment_link optional_items: [] payment_method_collection: always payment_methods: - credit_card - pix recurring: null status: active subscription_data: null success_url: null template: null title: Curso de exemplo total_orders: 0 updated_at: 2030-01-01T00:00:00.000Z url: https://checkout.example.com/pay/link-example "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1/payment_links/{id}: get: operationId: getPaymentLink tags: - Links de pagamento summary: Obter um link de pagamento description: |- Retorna o objeto completo quando ele pertence à conta da chave. `amount` e `unit_amount` refletem os preços atuais. Permissão: `payment_links:read` ou `read`. Consulte a [visão geral](/api-reference/payment-links/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^chk_[a-z0-9]{16}$ description: ID público do link de pagamento na conta. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/PaymentLink" example: id: chk_1234567890abcdef allow_discount_codes: false amount: 4990 cancel_url: null checkout_experience: banner: null confirmation_message: Sua compra foi confirmada. Enviaremos as instruções de acesso por email. footer_expanded: false header_shows_logo: null installment_teaser_mode: null order_summary_mode: null product_description_mode: null product_image_mode: null require_billing_address: null require_document: null require_phone: null summary_style: null created_at: 2030-01-01T00:00:00.000Z currency: BRL discount: null has_surcharge: false interest_payer: buyer line_items: - adjustable_quantity: null price: prc_1234567890abcdef product: pro_1234567890abcdef quantity: 1 unit_amount: 4990 max_installments: 1 metadata: {} object: payment_link optional_items: [] payment_method_collection: always payment_methods: - credit_card - pix recurring: null status: active subscription_data: null success_url: null template: null title: Curso de exemplo total_orders: 0 updated_at: 2030-01-01T00:00:00.000Z url: https://checkout.example.com/pay/link-example "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" post: operationId: updatePaymentLink tags: - Links de pagamento summary: Atualizar um link de pagamento description: |- Campos omitidos são preservados. Mudar `status` publica, despublica ou devolve o link a rascunho. Sessões de compra já abertas mantêm as condições anteriores. Uma edição concorrente no painel responde `409`. Um link vende de 1 a 20 preços de produtos distintos, todos avulsos ou todos assinaturas com o mesmo período. Publicar (`status: active`) exige conta aprovada para receber pagamentos e valida os itens: preços ativos, fixos, em reais, sem cobrança por uso, período grátis ou taxa de adesão, com total entre R$ 5,00 e R$ 999.999,99. Assinaturas exigem `payment_methods: ["credit_card"]` e `max_installments: 1`. `line_items` substitui a lista inteira; `metadata` substitui o objeto inteiro. Cada abertura de `url` cria uma sessão de compra com as condições vigentes. Permissão: `payment_links:write` ou `write`. Consulte a [visão geral](/api-reference/payment-links/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^chk_[a-z0-9]{16}$ description: ID público do link de pagamento na conta. - name: Idempotency-Key in: header schema: type: string minLength: 1 maxLength: 255 description: Chave única por operação lógica, de 1 a 255 caracteres ASCII imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma operação. required: true requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PaymentLinkUpdate" example: status: inactive responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/PaymentLink" example: id: chk_1234567890abcdef allow_discount_codes: false amount: 4990 cancel_url: null checkout_experience: banner: null confirmation_message: Sua compra foi confirmada. Enviaremos as instruções de acesso por email. footer_expanded: false header_shows_logo: null installment_teaser_mode: null order_summary_mode: null product_description_mode: null product_image_mode: null require_billing_address: null require_document: null require_phone: null summary_style: null created_at: 2030-01-01T00:00:00.000Z currency: BRL discount: null has_surcharge: false interest_payer: buyer line_items: - adjustable_quantity: null price: prc_1234567890abcdef product: pro_1234567890abcdef quantity: 1 unit_amount: 4990 max_installments: 1 metadata: {} object: payment_link optional_items: [] payment_method_collection: always payment_methods: - credit_card - pix recurring: null status: inactive subscription_data: null success_url: null template: null title: Curso de exemplo total_orders: 0 updated_at: 2030-01-01T00:00:00.000Z url: https://checkout.example.com/pay/link-example "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" delete: operationId: deletePaymentLink tags: - Links de pagamento summary: Excluir um link de pagamento description: |- Um rascunho nunca publicado e sem compras é removido, com `deleted: true`. Um link publicado ou usado passa a `inactive`, interrompendo novas compras, e a resposta retorna o objeto completo. Permissão: `payment_links:write` ou `write`. Consulte a [visão geral](/api-reference/payment-links/object) para campos e relacionamentos. security: - apiKeyAuth: [] parameters: - name: id in: path required: true schema: type: string pattern: ^chk_[a-z0-9]{16}$ description: ID público do link de pagamento na conta. - name: Idempotency-Key in: header required: true schema: type: string description: Chave única desta solicitação; reutilize somente para repetir a mesma operação. responses: "200": description: Operação concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: oneOf: - $ref: "#/components/schemas/PaymentLink" - $ref: "#/components/schemas/Deleted" example: id: chk_1234567890abcdef deleted: true object: payment_link "400": $ref: "#/components/responses/ApiFailure" "401": $ref: "#/components/responses/ApiFailure" "403": $ref: "#/components/responses/ApiFailure" "404": $ref: "#/components/responses/ApiFailure" "409": $ref: "#/components/responses/ApiFailure" "429": $ref: "#/components/responses/ApiFailure" "500": $ref: "#/components/responses/ApiFailure" "502": $ref: "#/components/responses/ApiFailure" "503": $ref: "#/components/responses/ApiFailure" /v1: get: operationId: getApiHealth tags: - Fundamentos da API summary: Verificar a API security: [] responses: "200": description: API disponível headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: type: object additionalProperties: false required: - name - version properties: name: type: string version: type: string example: name: Hubfy API version: v1 components: securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: API key schemas: ApiError: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - doc_url - message - param - type properties: code: type: string doc_url: type: - string - "null" message: type: string param: type: - string - "null" type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - api_error example: error: code: invalid_parameter doc_url: null message: The request contains invalid parameters param: null type: invalid_request_error Product: type: object additionalProperties: false required: - id - benefit - cover_url - created_at - description - metadata - name - object - prices - status - updated_at properties: id: type: string pattern: ^pro_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. benefit: type: - string - "null" enum: - files - courses - links - null description: "Tipo de conteúdo entregue: files (arquivos), courses (cursos) ou links (links). Pode ser null. Definir o tipo não vincula conteúdos ao produto." cover_url: type: - string - "null" description: URL pública da capa do produto; null quando ausente. Somente leitura, definida no painel. created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. description: type: - string - "null" description: Descrição do produto; null quando não informada. Envie null para limpar. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. name: type: string description: Nome do produto. Obrigatório e não vazio na criação. object: const: product type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. prices: type: array items: type: string pattern: ^prc_[a-z0-9]{16}$ description: IDs dos preços vinculados, ordenados por criação e ID. Consulte cada preço em /v1/prices/{id}. Somente leitura. status: type: string enum: - draft - published - archived description: "Estado do produto: draft (rascunho), published (publicado) ou archived (arquivado)." updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. example: id: pro_1234567890abcdef benefit: null cover_url: null created_at: 2030-01-01T00:00:00.000Z description: null metadata: {} name: Curso de exemplo object: product prices: - prc_1234567890abcdef status: draft updated_at: 2030-01-01T00:00:00.000Z Price: type: object additionalProperties: false required: - id - category - created_at - currency - is_active - metadata - min_price - name - object - package_size - product - renewal_interval_quantity - renewal_interval_unit - scheme - setup_fee - setup_fee_enabled - suggested_price - tiers - trial_interval_quantity - trial_interval_unit - unit_amount - unit_amount_decimal - updated_at - usage_aggregation - used properties: id: type: string pattern: ^prc_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. category: type: string enum: - one_time - subscription - lead_magnet - pwyw description: "Categoria: one_time (compra única), subscription (assinatura), lead_magnet (gratuito) ou pwyw (cliente escolhe o valor)." created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. currency: type: string enum: - BRL - USD description: "Moeda do preço: BRL ou USD, sempre em maiúsculas. Valores monetários são expressos em centavos dessa moeda." is_active: type: boolean description: Indica se a oferta está ativa. Desativar preserva o histórico dos pedidos que a utilizaram. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. min_price: type: - integer - "null" description: Valor mínimo em centavos, não negativo. Obrigatório para pwyw; pode ser null nas outras categorias. name: type: string description: Nome da oferta exibido no painel. Pode vir vazio quando não informado; se enviado, deve ser não vazio. object: const: price type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. package_size: type: integer description: Quantidade de unidades por pacote. Inteiro maior ou igual a 1. product: type: string pattern: ^pro_[a-z0-9]{16}$ description: ID do produto ao qual o preço pertence, na mesma conta. Obrigatório na criação; não pode ser alterado. renewal_interval_quantity: type: - integer - "null" description: Número de unidades entre renovações. Inteiro positivo para subscription; pode ser null nas outras categorias. renewal_interval_unit: type: - string - "null" description: "Unidade da renovação: day, week, month ou year. Obrigatória para subscription, junto da quantidade." enum: - day - week - month - year - null scheme: type: string enum: - standard - package - graduated - volume description: "Modelo do preço: standard (unitário), package (pacote), graduated (faixas progressivas) ou volume (faixa pelo volume total)." setup_fee: type: - integer - "null" description: Valor da taxa inicial, em centavos e não negativo. Pode ser null quando não configurado. setup_fee_enabled: type: - boolean - "null" description: Indica se há taxa inicial configurada. Pode ser null. Se true em uma assinatura, setup_fee é obrigatório. suggested_price: type: - integer - "null" description: Valor sugerido em centavos. Em pwyw, quando informado, deve ser maior ou igual a min_price. Pode ser null. tiers: type: array items: type: object additionalProperties: false required: - unit_amount - up_to properties: flat_amount: type: integer description: Valor fixo da faixa, em centavos; inteiro não negativo quando informado. É opcional. unit_amount: type: integer description: Valor por unidade nesta faixa, em centavos; inteiro não negativo. up_to: type: - integer - "null" description: Limite superior inclusivo da faixa. Inteiro positivo; os limites crescem e a última faixa deve usar null (sem limite). description: "Faixas para graduated e volume. Nesses modelos, envie uma lista não vazia, com limites crescentes e a última faixa sem limite (up_to: null)." trial_interval_quantity: type: - integer - "null" description: Quantidade de unidades do período de teste. Inteiro positivo quando configurado; null sem teste. trial_interval_unit: type: - string - "null" description: "Unidade do período de teste: day, week, month ou year. Pode ser null. Para subscription, envie unidade e quantidade juntas." enum: - day - week - month - year - null unit_amount: type: integer description: "Valor unitário inteiro, em centavos: 4990 representa R$ 49,90 em BRL. Deve ser não negativo; lead_magnet exige zero." unit_amount_decimal: type: - string - "null" description: Valor unitário decimal em centavos, como string com ponto e até 12 casas decimais. Pode ser null. Máximo 2147483647. updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. usage_aggregation: type: - string - "null" description: "Agregação de uso: sum (soma), last_during_period (último no período), last_ever (último conhecido) ou max (máximo). Null quando não configurada." enum: - sum - last_during_period - last_ever - max - null used: type: boolean description: Indica se o preço já foi vinculado a checkout ou pedido. Quando true, somente name, metadata e is_active podem ser editados pela API. Somente leitura. example: id: prc_1234567890abcdef category: one_time created_at: 2030-01-01T00:00:00.000Z currency: BRL is_active: true metadata: {} min_price: null name: Oferta principal object: price package_size: 1 product: pro_1234567890abcdef renewal_interval_quantity: null renewal_interval_unit: null scheme: standard setup_fee: null setup_fee_enabled: false suggested_price: null tiers: [] trial_interval_quantity: null trial_interval_unit: null unit_amount: 4990 unit_amount_decimal: null updated_at: 2030-01-01T00:00:00.000Z usage_aggregation: null used: false Asset: type: object additionalProperties: false required: - id - created_at - description - file - metadata - mime_type - object - size_bytes - status - title - type - updated_at - video properties: id: type: string pattern: ^ast_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. description: type: - string - "null" description: Descrição do item. Pode ser null; envie null para limpar. file: oneOf: - type: object additionalProperties: false required: - checksum - filename properties: checksum: type: - string - "null" description: Checksum do arquivo, quando disponível; null quando não informado. filename: type: string description: Nome original do arquivo, incluindo a extensão. - type: "null" description: Detalhes do arquivo quando type é file. Null para vídeos. Somente leitura. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. mime_type: type: - string - "null" description: Tipo MIME do arquivo, como application/pdf. Pode ser null. Informado no início do upload de arquivo; não é editável depois. object: const: asset type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. size_bytes: type: - integer - "null" description: Tamanho do conteúdo em bytes, preenchido pela verificação/processamento. Pode ser null enquanto desconhecido. Somente leitura. status: type: string enum: - uploading - processing - ready - failed - deleted description: "Estado do envio: uploading, processing, ready ou failed. deleted indica exclusão; itens excluídos não aparecem nas consultas normais. Somente leitura." title: type: string description: Título do item na biblioteca. Obrigatório na criação, não vazio e com até 300 caracteres no início do upload. type: type: string enum: - file - video description: "Variante do conteúdo: file ou video. Definida pela operação de criação e não editável." updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. video: oneOf: - type: object additionalProperties: false required: - duration_seconds - height - progress - width properties: duration_seconds: type: - integer - "null" description: Duração do vídeo em segundos; null enquanto desconhecida. height: type: - integer - "null" description: Altura do vídeo em pixels; null enquanto desconhecida. progress: type: - number - "null" description: Percentual de processamento informado, de 0 a 100; pode ser null. width: type: - integer - "null" description: Largura do vídeo em pixels; null enquanto desconhecida. - type: "null" description: Detalhes do vídeo quando type é video. Null para arquivos. Somente leitura. example: id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z description: null file: checksum: null filename: material.pdf metadata: {} mime_type: application/pdf object: asset size_bytes: null status: uploading title: Material de apoio type: file updated_at: 2030-01-01T00:00:00.000Z video: null Order: type: object additionalProperties: false required: - id - access_expires_at - created_at - currency - customer - effective_order_at - metadata - object - order_number - payment_method - price - product - status - subscription_status - type - unit_amount - updated_at properties: id: type: string pattern: ^ord_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. access_expires_at: type: - string - "null" format: date-time description: Fim da validade de acesso, em ISO 8601 com fuso. Editável. Null representa ausência de prazo; assinaturas approved ou completed exigem uma data. created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. currency: type: string description: Moeda do pedido, BRL ou USD. Somente leitura. customer: type: - string - "null" pattern: ^cus_[a-z0-9]{16}$ description: ID do cliente vinculado; pode ser null. Somente leitura. effective_order_at: type: - string - "null" format: date-time description: Data efetiva da compra em ISO 8601 com fuso. Pode ser null. Somente leitura. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. object: const: order type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. order_number: type: integer description: Número do pedido para exibição. Para chamadas da API, use id. Somente leitura. payment_method: type: - string - "null" description: Método de pagamento registrado, como credit_card ou pix. Pode ser null. Somente leitura. price: type: - string - "null" pattern: ^prc_[a-z0-9]{16}$ description: ID do preço vinculado; pode ser null. Somente leitura. product: type: - string - "null" pattern: ^pro_[a-z0-9]{16}$ description: ID do produto vinculado; pode ser null. Somente leitura. status: type: string description: "Estado registrado: pending, approved, completed, refunded, cancelled, chargeback ou disputed. Somente leitura." subscription_status: type: - string - "null" description: "Situação da assinatura vinculada: trialing, active, past_due, paused, cancelled ou expired. Pode ser null. Somente leitura." type: type: string description: "Tipo do pedido: one_time (compra única) ou subscription (assinatura). Somente leitura." unit_amount: type: integer description: Valor do pedido em centavos da moeda indicada em currency. Somente leitura. updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. example: id: ord_1234567890abcdef access_expires_at: null created_at: 2030-01-01T00:00:00.000Z currency: BRL customer: cus_1234567890abcdef effective_order_at: 2030-01-01T00:00:00.000Z metadata: {} object: order order_number: 1001 payment_method: credit_card price: prc_1234567890abcdef product: pro_1234567890abcdef status: approved subscription_status: null type: one_time unit_amount: 4990 updated_at: 2030-01-01T00:00:00.000Z Customer: type: object additionalProperties: false required: - id - city - country - created_at - currency - document - document_type - email - email_marketing_status - external_id - first_name - last_name - metadata - mrr_cents - name - object - phone - region - total_revenue_cents - updated_at properties: id: type: string pattern: ^cus_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. city: type: - string - "null" description: Cidade do cliente; null quando ausente. country: type: - string - "null" description: País informado no cadastro; null quando ausente. created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. currency: type: - string - "null" description: Moeda dos indicadores do cliente. Pode ser null. Somente leitura. document: type: - string - "null" description: Documento do cliente como string, preservando zeros à esquerda; null quando ausente. document_type: type: - string - "null" description: Tipo do documento informado, como cpf ou cnpj; null quando ausente. email: type: - string - "null" description: Email do cliente. Obrigatório e não vazio na criação; convertido para minúsculas ao criar. email_marketing_status: type: - string - "null" description: "Situação de email marketing: subscribed, unsubscribed, archived, requires_verification, invalid_email ou bounced." external_id: type: - string - "null" description: Identificador do cliente no seu sistema. Pode ser null. Não substitui o id da Hubfy. first_name: type: - string - "null" description: Primeiro nome; null quando ausente. last_name: type: - string - "null" description: Sobrenome; null quando ausente. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. mrr_cents: type: integer description: Receita recorrente mensal registrada para o cliente, em centavos. Somente leitura. name: type: - string - "null" description: Nome do cliente. Obrigatório e não vazio na criação. object: const: customer type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. phone: type: - string - "null" description: Telefone do cliente como string; null quando ausente. region: type: - string - "null" description: Estado ou região do cliente; null quando ausente. total_revenue_cents: type: integer description: Receita acumulada registrada para o cliente, em centavos. Não deve ser enviada em criação ou atualização. updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. example: id: cus_1234567890abcdef city: null country: null created_at: 2030-01-01T00:00:00.000Z currency: BRL document: null document_type: null email: cliente@example.com email_marketing_status: subscribed external_id: null first_name: null last_name: null metadata: {} mrr_cents: 0 name: Cliente Exemplo object: customer phone: null region: null total_revenue_cents: 0 updated_at: 2030-01-01T00:00:00.000Z Deleted: type: object additionalProperties: false required: - id - deleted - object properties: id: type: string deleted: type: boolean const: true object: type: string enum: - product - price - asset - customer - payment_link example: id: pro_1234567890abcdef deleted: true object: product Download: type: object additionalProperties: false required: - asset - expires_at - object - url properties: asset: type: string pattern: ^ast_[a-z0-9]{16}$ expires_at: type: string format: date-time object: type: string const: download url: type: string format: uri example: asset: ast_1234567890abcdef expires_at: 2030-01-01T00:00:00.000Z object: download url: https://downloads.example.com/temporary-credential ProductDeletedEvent: type: object additionalProperties: false required: - id - benefit - cover_url - created_at - deleted - description - metadata - name - object - prices - status - updated_at properties: id: type: string pattern: ^pro_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. benefit: type: - string - "null" enum: - files - courses - links - null description: "Tipo de conteúdo entregue: files (arquivos), courses (cursos) ou links (links). Pode ser null. Definir o tipo não vincula conteúdos ao produto." cover_url: type: - string - "null" description: URL pública da capa do produto; null quando ausente. Somente leitura, definida no painel. created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. deleted: type: boolean const: true description: Confirma a exclusão; o evento conserva os atributos anteriores. description: type: - string - "null" description: Descrição do produto; null quando não informada. Envie null para limpar. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. name: type: string description: Nome do produto. Obrigatório e não vazio na criação. object: const: product type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. prices: type: array items: type: string pattern: ^prc_[a-z0-9]{16}$ description: IDs dos preços vinculados, ordenados por criação e ID. Consulte cada preço em /v1/prices/{id}. Somente leitura. status: type: string enum: - draft - published - archived description: "Estado do produto: draft (rascunho), published (publicado) ou archived (arquivado)." updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. example: id: pro_1234567890abcdef benefit: null cover_url: null created_at: 2030-01-01T00:00:00.000Z deleted: true description: null metadata: {} name: Curso de exemplo object: product prices: - prc_1234567890abcdef status: draft updated_at: 2030-01-01T00:00:00.000Z PriceDeletedEvent: type: object additionalProperties: false required: - id - category - created_at - currency - deleted - is_active - metadata - min_price - name - object - package_size - product - renewal_interval_quantity - renewal_interval_unit - scheme - setup_fee - setup_fee_enabled - suggested_price - tiers - trial_interval_quantity - trial_interval_unit - unit_amount - unit_amount_decimal - updated_at - usage_aggregation - used properties: id: type: string pattern: ^prc_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. category: type: string enum: - one_time - subscription - lead_magnet - pwyw description: "Categoria: one_time (compra única), subscription (assinatura), lead_magnet (gratuito) ou pwyw (cliente escolhe o valor)." created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. currency: type: string enum: - BRL - USD description: "Moeda do preço: BRL ou USD, sempre em maiúsculas. Valores monetários são expressos em centavos dessa moeda." deleted: type: boolean const: true description: Confirma a exclusão; o evento conserva os atributos anteriores. is_active: type: boolean description: Indica se a oferta está ativa. Desativar preserva o histórico dos pedidos que a utilizaram. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. min_price: type: - integer - "null" description: Valor mínimo em centavos, não negativo. Obrigatório para pwyw; pode ser null nas outras categorias. name: type: string description: Nome da oferta exibido no painel. Pode vir vazio quando não informado; se enviado, deve ser não vazio. object: const: price type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. package_size: type: integer description: Quantidade de unidades por pacote. Inteiro maior ou igual a 1. product: type: string pattern: ^pro_[a-z0-9]{16}$ description: ID do produto ao qual o preço pertence, na mesma conta. Obrigatório na criação; não pode ser alterado. renewal_interval_quantity: type: - integer - "null" description: Número de unidades entre renovações. Inteiro positivo para subscription; pode ser null nas outras categorias. renewal_interval_unit: type: - string - "null" description: "Unidade da renovação: day, week, month ou year. Obrigatória para subscription, junto da quantidade." enum: - day - week - month - year - null scheme: type: string enum: - standard - package - graduated - volume description: "Modelo do preço: standard (unitário), package (pacote), graduated (faixas progressivas) ou volume (faixa pelo volume total)." setup_fee: type: - integer - "null" description: Valor da taxa inicial, em centavos e não negativo. Pode ser null quando não configurado. setup_fee_enabled: type: - boolean - "null" description: Indica se há taxa inicial configurada. Pode ser null. Se true em uma assinatura, setup_fee é obrigatório. suggested_price: type: - integer - "null" description: Valor sugerido em centavos. Em pwyw, quando informado, deve ser maior ou igual a min_price. Pode ser null. tiers: type: array items: type: object additionalProperties: false required: - unit_amount - up_to properties: flat_amount: type: integer description: Valor fixo da faixa, em centavos; inteiro não negativo quando informado. É opcional. unit_amount: type: integer description: Valor por unidade nesta faixa, em centavos; inteiro não negativo. up_to: type: - integer - "null" description: Limite superior inclusivo da faixa. Inteiro positivo; os limites crescem e a última faixa deve usar null (sem limite). description: "Faixas para graduated e volume. Nesses modelos, envie uma lista não vazia, com limites crescentes e a última faixa sem limite (up_to: null)." trial_interval_quantity: type: - integer - "null" description: Quantidade de unidades do período de teste. Inteiro positivo quando configurado; null sem teste. trial_interval_unit: type: - string - "null" description: "Unidade do período de teste: day, week, month ou year. Pode ser null. Para subscription, envie unidade e quantidade juntas." enum: - day - week - month - year - null unit_amount: type: integer description: "Valor unitário inteiro, em centavos: 4990 representa R$ 49,90 em BRL. Deve ser não negativo; lead_magnet exige zero." unit_amount_decimal: type: - string - "null" description: Valor unitário decimal em centavos, como string com ponto e até 12 casas decimais. Pode ser null. Máximo 2147483647. updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. usage_aggregation: type: - string - "null" description: "Agregação de uso: sum (soma), last_during_period (último no período), last_ever (último conhecido) ou max (máximo). Null quando não configurada." enum: - sum - last_during_period - last_ever - max - null used: type: boolean description: Indica se o preço já foi vinculado a checkout ou pedido. Quando true, somente name, metadata e is_active podem ser editados pela API. Somente leitura. example: id: prc_1234567890abcdef category: one_time created_at: 2030-01-01T00:00:00.000Z currency: BRL deleted: true is_active: true metadata: {} min_price: null name: Oferta principal object: price package_size: 1 product: pro_1234567890abcdef renewal_interval_quantity: null renewal_interval_unit: null scheme: standard setup_fee: null setup_fee_enabled: false suggested_price: null tiers: [] trial_interval_quantity: null trial_interval_unit: null unit_amount: 4990 unit_amount_decimal: null updated_at: 2030-01-01T00:00:00.000Z usage_aggregation: null used: false AssetDeletedEvent: type: object additionalProperties: false required: - id - created_at - deleted - description - file - metadata - mime_type - object - size_bytes - status - title - type - updated_at - video properties: id: type: string pattern: ^ast_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. deleted: type: boolean const: true description: Confirma a exclusão; o evento conserva os atributos anteriores. description: type: - string - "null" description: Descrição do item. Pode ser null; envie null para limpar. file: oneOf: - type: object additionalProperties: false required: - checksum - filename properties: checksum: type: - string - "null" description: Checksum do arquivo, quando disponível; null quando não informado. filename: type: string description: Nome original do arquivo, incluindo a extensão. - type: "null" description: Detalhes do arquivo quando type é file. Null para vídeos. Somente leitura. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. mime_type: type: - string - "null" description: Tipo MIME do arquivo, como application/pdf. Pode ser null. Informado no início do upload de arquivo; não é editável depois. object: const: asset type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. size_bytes: type: - integer - "null" description: Tamanho do conteúdo em bytes, preenchido pela verificação/processamento. Pode ser null enquanto desconhecido. Somente leitura. status: type: string enum: - uploading - processing - ready - failed - deleted description: "Estado do envio: uploading, processing, ready ou failed. deleted indica exclusão; itens excluídos não aparecem nas consultas normais. Somente leitura." title: type: string description: Título do item na biblioteca. Obrigatório na criação, não vazio e com até 300 caracteres no início do upload. type: type: string enum: - file - video description: "Variante do conteúdo: file ou video. Definida pela operação de criação e não editável." updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. video: oneOf: - type: object additionalProperties: false required: - duration_seconds - height - progress - width properties: duration_seconds: type: - integer - "null" description: Duração do vídeo em segundos; null enquanto desconhecida. height: type: - integer - "null" description: Altura do vídeo em pixels; null enquanto desconhecida. progress: type: - number - "null" description: Percentual de processamento informado, de 0 a 100; pode ser null. width: type: - integer - "null" description: Largura do vídeo em pixels; null enquanto desconhecida. - type: "null" description: Detalhes do vídeo quando type é video. Null para arquivos. Somente leitura. example: id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z deleted: true description: null file: checksum: null filename: material.pdf metadata: {} mime_type: application/pdf object: asset size_bytes: null status: uploading title: Material de apoio type: file updated_at: 2030-01-01T00:00:00.000Z video: null Event: type: object additionalProperties: false required: - id - created_at - data - object - request - type properties: id: type: string pattern: ^evt_[a-z0-9]{16}$ created_at: type: string format: date-time data: type: object additionalProperties: false required: - object - previous_attributes properties: object: oneOf: - $ref: "#/components/schemas/Product" - $ref: "#/components/schemas/Price" - $ref: "#/components/schemas/Asset" - $ref: "#/components/schemas/Order" - $ref: "#/components/schemas/ProductDeletedEvent" - $ref: "#/components/schemas/PriceDeletedEvent" - $ref: "#/components/schemas/AssetDeletedEvent" - $ref: "#/components/schemas/PaymentLink" - $ref: "#/components/schemas/PaymentLinkDeletedEvent" previous_attributes: type: object additionalProperties: true object: type: string const: event request: type: object additionalProperties: false required: - id properties: id: type: - string - "null" type: type: string enum: - product.created - product.updated - product.deleted - price.created - price.updated - price.deleted - asset.created - asset.updated - asset.deleted - order.updated - payment_link.created - payment_link.updated - payment_link.deleted example: id: evt_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z data: object: id: pro_1234567890abcdef benefit: null cover_url: null created_at: 2030-01-01T00:00:00.000Z description: null metadata: {} name: Curso de exemplo object: product prices: - prc_1234567890abcdef status: draft updated_at: 2030-01-01T00:00:00.000Z previous_attributes: {} object: event request: id: req_example type: product.created Upload: type: object additionalProperties: false required: - id - created_at - description - file - metadata - mime_type - object - size_bytes - status - title - type - updated_at - upload - video properties: id: type: string pattern: ^ast_[a-z0-9]{16}$ description: Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes. created_at: type: string format: date-time description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. description: type: - string - "null" description: Descrição do item. Pode ser null; envie null para limpar. file: oneOf: - type: object additionalProperties: false required: - checksum - filename properties: checksum: type: - string - "null" description: Checksum do arquivo, quando disponível; null quando não informado. filename: type: string description: Nome original do arquivo, incluindo a extensão. - type: "null" description: Detalhes do arquivo quando type é file. Null para vídeos. Somente leitura. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. mime_type: type: - string - "null" description: Tipo MIME do arquivo, como application/pdf. Pode ser null. Informado no início do upload de arquivo; não é editável depois. object: const: asset type: string description: Tipo do objeto retornado. O valor é fixo para este recurso. size_bytes: type: - integer - "null" description: Tamanho do conteúdo em bytes, preenchido pela verificação/processamento. Pode ser null enquanto desconhecido. Somente leitura. status: type: string enum: - uploading - processing - ready - failed - deleted description: "Estado do envio: uploading, processing, ready ou failed. deleted indica exclusão; itens excluídos não aparecem nas consultas normais. Somente leitura." title: type: string description: Título do item na biblioteca. Obrigatório na criação, não vazio e com até 300 caracteres no início do upload. type: type: string enum: - file - video description: "Variante do conteúdo: file ou video. Definida pela operação de criação e não editável." updated_at: type: string format: date-time description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. upload: type: object additionalProperties: false required: - expires_at - method - url properties: expires_at: type: - string - "null" format: date-time description: Validade da credencial em ISO 8601, ou null quando o serviço não informa um prazo. method: type: string const: PUT description: "Método HTTP do envio direto: PUT." url: type: string format: uri description: URL assinada para enviar os bytes. Trate como segredo temporário. description: Credencial temporária incluída somente na resposta de criação do upload. Os campos do asset permanecem na raiz da resposta. video: oneOf: - type: object additionalProperties: false required: - duration_seconds - height - progress - width properties: duration_seconds: type: - integer - "null" description: Duração do vídeo em segundos; null enquanto desconhecida. height: type: - integer - "null" description: Altura do vídeo em pixels; null enquanto desconhecida. progress: type: - number - "null" description: Percentual de processamento informado, de 0 a 100; pode ser null. width: type: - integer - "null" description: Largura do vídeo em pixels; null enquanto desconhecida. - type: "null" description: Detalhes do vídeo quando type é video. Null para arquivos. Somente leitura. example: id: ast_1234567890abcdef created_at: 2030-01-01T00:00:00.000Z description: null file: checksum: null filename: material.pdf metadata: {} mime_type: application/pdf object: asset size_bytes: null status: uploading title: Material de apoio type: file updated_at: 2030-01-01T00:00:00.000Z upload: expires_at: 2030-01-01T00:00:00.000Z method: PUT url: https://uploads.example.com/temporary-credential video: null ProductUpdate: type: object additionalProperties: false minProperties: 1 properties: benefit: type: - string - "null" enum: - files - courses - links - null description: "Tipo de conteúdo entregue: files (arquivos), courses (cursos) ou links (links). Pode ser null. Definir o tipo não vincula conteúdos ao produto." maxLength: 10000 description: type: - string - "null" description: Descrição do produto; null quando não informada. Envie null para limpar. maxLength: 10000 metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. name: type: string description: Nome do produto. Obrigatório e não vazio na criação. minLength: 1 maxLength: 10000 status: type: string enum: - draft - published - archived description: "Estado do produto: draft (rascunho), published (publicado) ou archived (arquivado)." maxLength: 10000 ProductCreate: type: object additionalProperties: false required: - initial_price - name properties: benefit: type: - string - "null" enum: - files - courses - links - null description: "Tipo de conteúdo entregue: files (arquivos), courses (cursos) ou links (links). Pode ser null. Definir o tipo não vincula conteúdos ao produto." maxLength: 10000 description: type: - string - "null" description: Descrição do produto; null quando não informada. Envie null para limpar. maxLength: 10000 initial_price: $ref: "#/components/schemas/InitialPrice" description: Preço inicial criado na mesma operação do produto. Obrigatório; usa os parâmetros de preço sem product, pois o vínculo é preenchido automaticamente. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. name: type: string description: Nome do produto. Obrigatório e não vazio na criação. minLength: 1 maxLength: 10000 status: type: string enum: - draft - published - archived description: "Estado do produto: draft (rascunho), published (publicado) ou archived (arquivado)." maxLength: 10000 example: initial_price: currency: BRL unit_amount: 4990 name: Curso de exemplo PriceUpdate: type: object additionalProperties: false minProperties: 1 properties: category: type: string enum: - one_time - subscription - lead_magnet - pwyw description: "Categoria: one_time (compra única), subscription (assinatura), lead_magnet (gratuito) ou pwyw (cliente escolhe o valor)." maxLength: 10000 currency: type: string enum: - BRL - USD description: "Moeda do preço: BRL ou USD, sempre em maiúsculas. Valores monetários são expressos em centavos dessa moeda." maxLength: 10000 is_active: type: boolean description: Indica se a oferta está ativa. Desativar preserva o histórico dos pedidos que a utilizaram. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. min_price: type: - integer - "null" description: Valor mínimo em centavos, não negativo. Obrigatório para pwyw; pode ser null nas outras categorias. minimum: 0 maximum: 2147483647 name: type: string description: Nome da oferta exibido no painel. Pode vir vazio quando não informado; se enviado, deve ser não vazio. maxLength: 10000 minLength: 1 package_size: type: integer description: Quantidade de unidades por pacote. Inteiro maior ou igual a 1. minimum: 1 maximum: 2147483647 renewal_interval_quantity: type: - integer - "null" description: Número de unidades entre renovações. Inteiro positivo para subscription; pode ser null nas outras categorias. minimum: 0 maximum: 2147483647 renewal_interval_unit: type: - string - "null" description: "Unidade da renovação: day, week, month ou year. Obrigatória para subscription, junto da quantidade." enum: - day - week - month - year - null maxLength: 10000 scheme: type: string enum: - standard - package - graduated - volume description: "Modelo do preço: standard (unitário), package (pacote), graduated (faixas progressivas) ou volume (faixa pelo volume total)." maxLength: 10000 setup_fee: type: - integer - "null" description: Valor da taxa inicial, em centavos e não negativo. Pode ser null quando não configurado. minimum: 0 maximum: 2147483647 setup_fee_enabled: type: - boolean - "null" description: Indica se há taxa inicial configurada. Pode ser null. Se true em uma assinatura, setup_fee é obrigatório. suggested_price: type: - integer - "null" description: Valor sugerido em centavos. Em pwyw, quando informado, deve ser maior ou igual a min_price. Pode ser null. minimum: 0 maximum: 2147483647 tiers: type: array items: type: object additionalProperties: false required: - unit_amount - up_to properties: flat_amount: type: integer description: Valor fixo da faixa, em centavos; inteiro não negativo quando informado. É opcional. unit_amount: type: integer description: Valor por unidade nesta faixa, em centavos; inteiro não negativo. up_to: type: - integer - "null" description: Limite superior inclusivo da faixa. Inteiro positivo; os limites crescem e a última faixa deve usar null (sem limite). description: "Faixas para graduated e volume. Nesses modelos, envie uma lista não vazia, com limites crescentes e a última faixa sem limite (up_to: null)." trial_interval_quantity: type: - integer - "null" description: Quantidade de unidades do período de teste. Inteiro positivo quando configurado; null sem teste. minimum: 0 maximum: 2147483647 trial_interval_unit: type: - string - "null" description: "Unidade do período de teste: day, week, month ou year. Pode ser null. Para subscription, envie unidade e quantidade juntas." enum: - day - week - month - year - null maxLength: 10000 unit_amount: type: integer description: "Valor unitário inteiro, em centavos: 4990 representa R$ 49,90 em BRL. Deve ser não negativo; lead_magnet exige zero." minimum: 0 maximum: 2147483647 unit_amount_decimal: type: - string - "null" description: Valor unitário decimal em centavos, como string com ponto e até 12 casas decimais. Pode ser null. Máximo 2147483647. maxLength: 10000 usage_aggregation: type: - string - "null" description: "Agregação de uso: sum (soma), last_during_period (último no período), last_ever (último conhecido) ou max (máximo). Null quando não configurada." enum: - sum - last_during_period - last_ever - max - null maxLength: 10000 PriceCreate: type: object additionalProperties: false required: - product properties: category: type: string enum: - one_time - subscription - lead_magnet - pwyw description: "Categoria: one_time (compra única), subscription (assinatura), lead_magnet (gratuito) ou pwyw (cliente escolhe o valor)." maxLength: 10000 currency: type: string enum: - BRL - USD description: "Moeda do preço: BRL ou USD, sempre em maiúsculas. Valores monetários são expressos em centavos dessa moeda." maxLength: 10000 is_active: type: boolean description: Indica se a oferta está ativa. Desativar preserva o histórico dos pedidos que a utilizaram. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. min_price: type: - integer - "null" description: Valor mínimo em centavos, não negativo. Obrigatório para pwyw; pode ser null nas outras categorias. minimum: 0 maximum: 2147483647 name: type: string description: Nome da oferta exibido no painel. Pode vir vazio quando não informado; se enviado, deve ser não vazio. maxLength: 10000 minLength: 1 package_size: type: integer description: Quantidade de unidades por pacote. Inteiro maior ou igual a 1. minimum: 1 maximum: 2147483647 product: type: string pattern: ^pro_[a-z0-9]{16}$ description: ID do produto ao qual o preço pertence, na mesma conta. Obrigatório na criação; não pode ser alterado. maxLength: 10000 renewal_interval_quantity: type: - integer - "null" description: Número de unidades entre renovações. Inteiro positivo para subscription; pode ser null nas outras categorias. minimum: 0 maximum: 2147483647 renewal_interval_unit: type: - string - "null" description: "Unidade da renovação: day, week, month ou year. Obrigatória para subscription, junto da quantidade." enum: - day - week - month - year - null maxLength: 10000 scheme: type: string enum: - standard - package - graduated - volume description: "Modelo do preço: standard (unitário), package (pacote), graduated (faixas progressivas) ou volume (faixa pelo volume total)." maxLength: 10000 setup_fee: type: - integer - "null" description: Valor da taxa inicial, em centavos e não negativo. Pode ser null quando não configurado. minimum: 0 maximum: 2147483647 setup_fee_enabled: type: - boolean - "null" description: Indica se há taxa inicial configurada. Pode ser null. Se true em uma assinatura, setup_fee é obrigatório. suggested_price: type: - integer - "null" description: Valor sugerido em centavos. Em pwyw, quando informado, deve ser maior ou igual a min_price. Pode ser null. minimum: 0 maximum: 2147483647 tiers: type: array items: type: object additionalProperties: false required: - unit_amount - up_to properties: flat_amount: type: integer description: Valor fixo da faixa, em centavos; inteiro não negativo quando informado. É opcional. unit_amount: type: integer description: Valor por unidade nesta faixa, em centavos; inteiro não negativo. up_to: type: - integer - "null" description: Limite superior inclusivo da faixa. Inteiro positivo; os limites crescem e a última faixa deve usar null (sem limite). description: "Faixas para graduated e volume. Nesses modelos, envie uma lista não vazia, com limites crescentes e a última faixa sem limite (up_to: null)." trial_interval_quantity: type: - integer - "null" description: Quantidade de unidades do período de teste. Inteiro positivo quando configurado; null sem teste. minimum: 0 maximum: 2147483647 trial_interval_unit: type: - string - "null" description: "Unidade do período de teste: day, week, month ou year. Pode ser null. Para subscription, envie unidade e quantidade juntas." enum: - day - week - month - year - null maxLength: 10000 unit_amount: type: integer description: "Valor unitário inteiro, em centavos: 4990 representa R$ 49,90 em BRL. Deve ser não negativo; lead_magnet exige zero." minimum: 0 maximum: 2147483647 unit_amount_decimal: type: - string - "null" description: Valor unitário decimal em centavos, como string com ponto e até 12 casas decimais. Pode ser null. Máximo 2147483647. maxLength: 10000 usage_aggregation: type: - string - "null" description: "Agregação de uso: sum (soma), last_during_period (último no período), last_ever (último conhecido) ou max (máximo). Null quando não configurada." enum: - sum - last_during_period - last_ever - max - null maxLength: 10000 example: currency: BRL name: Oferta principal product: pro_1234567890abcdef unit_amount: 4990 AssetUpdate: type: object additionalProperties: false minProperties: 1 properties: description: type: - string - "null" description: Descrição do item. Pode ser null; envie null para limpar. maxLength: 10000 metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. title: type: string description: Título do item na biblioteca. Obrigatório na criação, não vazio e com até 300 caracteres no início do upload. maxLength: 10000 minLength: 1 OrderUpdate: type: object additionalProperties: false minProperties: 1 properties: access_expires_at: type: - string - "null" format: date-time description: Fim da validade de acesso, em ISO 8601 com fuso. Editável. Null representa ausência de prazo; assinaturas approved ou completed exigem uma data. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. CustomerUpdate: type: object additionalProperties: false minProperties: 1 properties: city: type: - string - "null" description: Cidade do cliente; null quando ausente. maxLength: 10000 country: type: - string - "null" description: País informado no cadastro; null quando ausente. maxLength: 10000 document: type: - string - "null" description: Documento do cliente como string, preservando zeros à esquerda; null quando ausente. maxLength: 10000 document_type: type: - string - "null" description: Tipo do documento informado, como cpf ou cnpj; null quando ausente. maxLength: 10000 email: type: string description: Email do cliente. Obrigatório e não vazio na criação; convertido para minúsculas ao criar. minLength: 1 maxLength: 10000 email_marketing_status: type: - string - "null" description: "Situação de email marketing: subscribed, unsubscribed, archived, requires_verification, invalid_email ou bounced." maxLength: 10000 external_id: type: - string - "null" description: Identificador do cliente no seu sistema. Pode ser null. Não substitui o id da Hubfy. maxLength: 10000 first_name: type: - string - "null" description: Primeiro nome; null quando ausente. maxLength: 10000 last_name: type: - string - "null" description: Sobrenome; null quando ausente. maxLength: 10000 metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. name: type: string description: Nome do cliente. Obrigatório e não vazio na criação. minLength: 1 maxLength: 10000 phone: type: - string - "null" description: Telefone do cliente como string; null quando ausente. maxLength: 10000 region: type: - string - "null" description: Estado ou região do cliente; null quando ausente. maxLength: 10000 CustomerCreate: type: object additionalProperties: false required: - email - name properties: city: type: - string - "null" description: Cidade do cliente; null quando ausente. maxLength: 10000 country: type: - string - "null" description: País informado no cadastro; null quando ausente. maxLength: 10000 document: type: - string - "null" description: Documento do cliente como string, preservando zeros à esquerda; null quando ausente. maxLength: 10000 document_type: type: - string - "null" description: Tipo do documento informado, como cpf ou cnpj; null quando ausente. maxLength: 10000 email: type: string description: Email do cliente. Obrigatório e não vazio na criação; convertido para minúsculas ao criar. minLength: 1 maxLength: 10000 email_marketing_status: type: - string - "null" description: "Situação de email marketing: subscribed, unsubscribed, archived, requires_verification, invalid_email ou bounced." maxLength: 10000 external_id: type: - string - "null" description: Identificador do cliente no seu sistema. Pode ser null. Não substitui o id da Hubfy. maxLength: 10000 first_name: type: - string - "null" description: Primeiro nome; null quando ausente. maxLength: 10000 last_name: type: - string - "null" description: Sobrenome; null quando ausente. maxLength: 10000 metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. name: type: string description: Nome do cliente. Obrigatório e não vazio na criação. minLength: 1 maxLength: 10000 phone: type: - string - "null" description: Telefone do cliente como string; null quando ausente. maxLength: 10000 region: type: - string - "null" description: Estado ou região do cliente; null quando ausente. maxLength: 10000 example: email: cliente@example.com name: Cliente Exemplo InitialPrice: type: object additionalProperties: false minProperties: 0 properties: category: type: string enum: - one_time - subscription - lead_magnet - pwyw description: "Categoria: one_time (compra única), subscription (assinatura), lead_magnet (gratuito) ou pwyw (cliente escolhe o valor)." maxLength: 10000 currency: type: string enum: - BRL - USD description: "Moeda do preço: BRL ou USD, sempre em maiúsculas. Valores monetários são expressos em centavos dessa moeda." maxLength: 10000 is_active: type: boolean description: Indica se a oferta está ativa. Desativar preserva o histórico dos pedidos que a utilizaram. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. min_price: type: - integer - "null" description: Valor mínimo em centavos, não negativo. Obrigatório para pwyw; pode ser null nas outras categorias. minimum: 0 maximum: 2147483647 name: type: string description: Nome da oferta exibido no painel. Pode vir vazio quando não informado; se enviado, deve ser não vazio. maxLength: 10000 minLength: 1 package_size: type: integer description: Quantidade de unidades por pacote. Inteiro maior ou igual a 1. minimum: 1 maximum: 2147483647 renewal_interval_quantity: type: - integer - "null" description: Número de unidades entre renovações. Inteiro positivo para subscription; pode ser null nas outras categorias. minimum: 0 maximum: 2147483647 renewal_interval_unit: type: - string - "null" description: "Unidade da renovação: day, week, month ou year. Obrigatória para subscription, junto da quantidade." enum: - day - week - month - year - null maxLength: 10000 scheme: type: string enum: - standard - package - graduated - volume description: "Modelo do preço: standard (unitário), package (pacote), graduated (faixas progressivas) ou volume (faixa pelo volume total)." maxLength: 10000 setup_fee: type: - integer - "null" description: Valor da taxa inicial, em centavos e não negativo. Pode ser null quando não configurado. minimum: 0 maximum: 2147483647 setup_fee_enabled: type: - boolean - "null" description: Indica se há taxa inicial configurada. Pode ser null. Se true em uma assinatura, setup_fee é obrigatório. suggested_price: type: - integer - "null" description: Valor sugerido em centavos. Em pwyw, quando informado, deve ser maior ou igual a min_price. Pode ser null. minimum: 0 maximum: 2147483647 tiers: type: array items: type: object additionalProperties: false required: - unit_amount - up_to properties: flat_amount: type: integer description: Valor fixo da faixa, em centavos; inteiro não negativo quando informado. É opcional. unit_amount: type: integer description: Valor por unidade nesta faixa, em centavos; inteiro não negativo. up_to: type: - integer - "null" description: Limite superior inclusivo da faixa. Inteiro positivo; os limites crescem e a última faixa deve usar null (sem limite). description: "Faixas para graduated e volume. Nesses modelos, envie uma lista não vazia, com limites crescentes e a última faixa sem limite (up_to: null)." trial_interval_quantity: type: - integer - "null" description: Quantidade de unidades do período de teste. Inteiro positivo quando configurado; null sem teste. minimum: 0 maximum: 2147483647 trial_interval_unit: type: - string - "null" description: "Unidade do período de teste: day, week, month ou year. Pode ser null. Para subscription, envie unidade e quantidade juntas." enum: - day - week - month - year - null maxLength: 10000 unit_amount: type: integer description: "Valor unitário inteiro, em centavos: 4990 representa R$ 49,90 em BRL. Deve ser não negativo; lead_magnet exige zero." minimum: 0 maximum: 2147483647 unit_amount_decimal: type: - string - "null" description: Valor unitário decimal em centavos, como string com ponto e até 12 casas decimais. Pode ser null. Máximo 2147483647. maxLength: 10000 usage_aggregation: type: - string - "null" description: "Agregação de uso: sum (soma), last_during_period (último no período), last_ever (último conhecido) ou max (máximo). Null quando não configurada." enum: - sum - last_during_period - last_ever - max - null maxLength: 10000 FileCreate: type: object additionalProperties: false required: - filename - title properties: description: type: - string - "null" description: Descrição do item. Pode ser null; envie null para limpar. maxLength: 10000 filename: type: string maxLength: 255 description: Nome do arquivo com extensão, entre 1 e 255 caracteres. Obrigatório. metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. mime_type: type: - string - "null" description: Tipo MIME do arquivo, como application/pdf. size_bytes: type: integer minimum: 0 description: Tamanho original em bytes. Obrigatório quando a plataforma define uma cota ou limite por arquivo; reserva armazenamento e é conferido após o upload. title: type: string description: Título do item na biblioteca. Obrigatório na criação, não vazio e com até 300 caracteres no início do upload. maxLength: 300 minLength: 1 VideoCreate: type: object additionalProperties: false required: - title properties: description: type: - string - "null" description: Descrição do item. Pode ser null; envie null para limpar. maxLength: 10000 metadata: type: object additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use {} para limpar. Não aceita null. size_bytes: type: integer minimum: 0 description: Tamanho original em bytes. Obrigatório quando a plataforma define uma cota ou limite por arquivo; reserva armazenamento e é conferido após o upload. title: type: string description: Título do item na biblioteca. Obrigatório na criação, não vazio e com até 300 caracteres no início do upload. maxLength: 300 minLength: 1 PaymentLink: type: object additionalProperties: false required: - id - allow_discount_codes - amount - cancel_url - checkout_experience - created_at - currency - discount - has_surcharge - interest_payer - line_items - max_installments - metadata - object - optional_items - payment_method_collection - payment_methods - recurring - status - subscription_data - success_url - template - title - total_orders - updated_at - url properties: id: description: Identificador público estável, com prefixo chk_. É o mesmo ID do checkout no painel. Use a URL retornada; não construa o endereço a partir do ID. pattern: ^chk_[a-z0-9]{16}$ type: string allow_discount_codes: description: Permite informar códigos de desconto na página. type: boolean amount: description: Subtotal em centavos, calculado com os preços atuais dos itens. Somente leitura. minimum: 0 type: integer cancel_url: description: Destino HTTPS ao cancelar a compra. null remove. format: uri type: - string - "null" checkout_experience: additionalProperties: false description: Apresentação, banner, dados exigidos e mensagem final. Campos visuais null herdam o padrão. properties: banner: additionalProperties: false properties: ends_at: format: date-time type: - string - "null" highlight: maxLength: 120 type: - string - "null" tag: maxLength: 40 type: - string - "null" text: maxLength: 500 type: string tone: enum: - neutral - urgent - success type: string variant: enum: - strip - highlight - countdown - marquee type: string type: - object - "null" confirmation_message: maxLength: 1000 type: - string - "null" footer_expanded: type: boolean header_shows_logo: type: - boolean - "null" installment_teaser_mode: enum: - hidden - maximum_installment - lowest_installment - null type: - string - "null" order_summary_mode: enum: - expanded - collapsible - compact - hidden - null type: - string - "null" product_description_mode: enum: - hidden - summary - full - null type: - string - "null" product_image_mode: enum: - hidden - thumbnail - hero - null type: - string - "null" require_billing_address: type: - boolean - "null" require_document: type: - boolean - "null" require_phone: type: - boolean - "null" summary_style: enum: - product - subscription - null type: - string - "null" type: object created_at: description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. format: date-time type: string currency: description: Sempre BRL. enum: - BRL type: string discount: description: Desconto disponível na conta de pagamentos. null remove o desconto automático. pattern: ^disc_[A-Za-z0-9]+$ type: - string - "null" has_surcharge: description: Repassa tarifas ao comprador. Apenas compras avulsas. type: boolean interest_payer: description: "Quem absorve os juros do parcelamento: comprador ou conta." enum: - buyer - organization type: string line_items: description: Itens vendidos pelo link, na ordem de exibição. items: $ref: "#/components/schemas/PaymentLinkLineItem" maxItems: 20 minItems: 1 type: array max_installments: description: Máximo de parcelas no cartão. Assinaturas não parcelam. maximum: 12 minimum: 1 type: integer default: 12 metadata: additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. type: object object: const: payment_link type: string optional_items: description: Até três ofertas adicionais avulsas, de produtos diferentes dos itens principais. items: additionalProperties: false properties: call_to_action: maxLength: 120 type: string compare_at_amount: minimum: 1 type: - integer - "null" description: maxLength: 1000 type: - string - "null" price: pattern: ^prc_[a-z0-9]{16}$ type: string tag: enum: - recommended - special_offer - null type: - string - "null" title: maxLength: 120 type: string type: object required: - call_to_action - price - title maxItems: 3 type: array payment_method_collection: description: "Coleta do cartão nas assinaturas: sempre ou apenas quando houver pagamento imediato." enum: - always - if_required type: string payment_methods: description: Meios de pagamento. Assinaturas recorrentes usam credit_card. items: enum: - credit_card - pix - boleto type: string maxItems: 2 minItems: 1 type: array recurring: additionalProperties: false description: Período de renovação quando os itens são assinaturas; null em compras avulsas. Somente leitura. properties: interval: enum: - day - week - month - year type: string interval_count: minimum: 1 type: integer required: - interval - interval_count type: - object - "null" status: description: draft não abre compras; active está publicado; inactive foi desativado. enum: - draft - active - inactive type: string subscription_data: additionalProperties: false description: Condições da assinatura. O link aceita período grátis em dias; data final absoluta de trial pertence a sessões individuais. properties: trial_period_days: maximum: 3650 minimum: 1 type: - integer - "null" trial_settings: additionalProperties: false properties: end_behavior: additionalProperties: false properties: missing_payment_method: enum: - cancel - pause - create_invoice type: string type: object type: object type: - object - "null" success_url: description: Destino HTTPS após concluir a página; não confirma pagamento. Aceita {CHECKOUT_SESSION_ID}. type: - string - "null" template: description: Layout da página. null usa o padrão da conta. enum: - split - sidebar - stacked - null type: - string - "null" title: description: Título exibido na página. maxLength: 120 type: string total_orders: description: Compras confirmadas por este link. Somente leitura. minimum: 0 type: integer updated_at: description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. format: date-time type: string url: description: URL confirmada do checkout hospedado. Pode usar o domínio configurado. Não construa a URL a partir do ID. type: - string - "null" example: id: chk_1234567890abcdef allow_discount_codes: false amount: 4990 cancel_url: null checkout_experience: banner: null confirmation_message: Sua compra foi confirmada. Enviaremos as instruções de acesso por email. footer_expanded: false header_shows_logo: null installment_teaser_mode: null order_summary_mode: null product_description_mode: null product_image_mode: null require_billing_address: null require_document: null require_phone: null summary_style: null created_at: 2030-01-01T00:00:00.000Z currency: BRL discount: null has_surcharge: false interest_payer: buyer line_items: - adjustable_quantity: null price: prc_1234567890abcdef product: pro_1234567890abcdef quantity: 1 unit_amount: 4990 max_installments: 1 metadata: {} object: payment_link optional_items: [] payment_method_collection: always payment_methods: - credit_card - pix recurring: null status: active subscription_data: null success_url: null template: null title: Curso de exemplo total_orders: 0 updated_at: 2030-01-01T00:00:00.000Z url: https://checkout.example.com/pay/link-example PaymentLinkLineItem: type: object additionalProperties: false required: - adjustable_quantity - price - product - quantity - unit_amount properties: adjustable_quantity: additionalProperties: false description: Permite alterar quantidade; a quantidade inicial deve estar dentro dos limites. properties: enabled: type: boolean maximum: maximum: 99 minimum: 1 type: integer minimum: maximum: 99 minimum: 0 type: integer type: - object - "null" price: description: ID do preço vendido. pattern: ^prc_[a-z0-9]{16}$ type: string product: description: ID do produto do preço. Somente leitura. pattern: ^pro_[a-z0-9]{16}$ type: string quantity: description: Quantidade vendida. maximum: 99 minimum: 1 type: integer unit_amount: description: Valor unitário atual do preço, em centavos. Somente leitura. minimum: 0 type: integer PaymentLinkLineItemInput: type: object additionalProperties: false required: - price properties: adjustable_quantity: additionalProperties: false description: Permite alterar quantidade; a quantidade inicial deve estar dentro dos limites. properties: enabled: type: boolean maximum: maximum: 99 minimum: 1 type: integer minimum: maximum: 99 minimum: 0 type: integer type: - object - "null" price: description: ID de um preço ativo da conta. pattern: ^prc_[a-z0-9]{16}$ type: string quantity: default: 1 description: Quantidade vendida, de 1 a 99. maximum: 99 minimum: 1 type: integer PaymentLinkCreate: type: object additionalProperties: false required: - line_items - title properties: allow_discount_codes: description: Permite informar códigos de desconto na página. type: boolean cancel_url: description: Destino HTTPS ao cancelar a compra. null remove. format: uri type: - string - "null" checkout_experience: additionalProperties: false description: Apresentação, banner, dados exigidos e mensagem final. Campos visuais null herdam o padrão. properties: banner: additionalProperties: false properties: ends_at: format: date-time type: - string - "null" highlight: maxLength: 120 type: - string - "null" tag: maxLength: 40 type: - string - "null" text: maxLength: 500 type: string tone: enum: - neutral - urgent - success type: string variant: enum: - strip - highlight - countdown - marquee type: string type: - object - "null" confirmation_message: maxLength: 1000 type: - string - "null" footer_expanded: type: boolean header_shows_logo: type: - boolean - "null" installment_teaser_mode: enum: - hidden - maximum_installment - lowest_installment - null type: - string - "null" order_summary_mode: enum: - expanded - collapsible - compact - hidden - null type: - string - "null" product_description_mode: enum: - hidden - summary - full - null type: - string - "null" product_image_mode: enum: - hidden - thumbnail - hero - null type: - string - "null" require_billing_address: type: - boolean - "null" require_document: type: - boolean - "null" require_phone: type: - boolean - "null" summary_style: enum: - product - subscription - null type: - string - "null" type: object discount: description: Desconto disponível na conta de pagamentos. null remove o desconto automático. pattern: ^disc_[A-Za-z0-9]+$ type: - string - "null" has_surcharge: description: Repassa tarifas ao comprador. Apenas compras avulsas. type: boolean interest_payer: description: "Quem absorve os juros do parcelamento: comprador ou conta." enum: - buyer - organization type: string line_items: description: Substitui a lista inteira de itens. Cada produto aparece uma vez. items: $ref: "#/components/schemas/PaymentLinkLineItemInput" maxItems: 20 minItems: 1 type: array max_installments: description: Máximo de parcelas no cartão. maximum: 12 minimum: 1 type: integer default: 12 metadata: additionalProperties: true description: Substitui o objeto inteiro; use {} para limpar. type: object optional_items: description: Até três ofertas adicionais avulsas, de produtos diferentes dos itens principais. items: additionalProperties: false properties: call_to_action: maxLength: 120 type: string compare_at_amount: minimum: 1 type: - integer - "null" description: maxLength: 1000 type: - string - "null" price: pattern: ^prc_[a-z0-9]{16}$ type: string tag: enum: - recommended - special_offer - null type: - string - "null" title: maxLength: 120 type: string type: object required: - call_to_action - price - title maxItems: 3 type: array payment_method_collection: description: "Coleta do cartão nas assinaturas: sempre ou apenas quando houver pagamento imediato." enum: - always - if_required type: string payment_methods: description: Meios de pagamento. Assinaturas recorrentes usam credit_card. items: enum: - credit_card - pix - boleto type: string maxItems: 2 minItems: 1 type: array status: description: Publicar exige conta aprovada e itens válidos. enum: - draft - active - inactive type: string subscription_data: additionalProperties: false description: Condições da assinatura. O link aceita período grátis em dias; data final absoluta de trial pertence a sessões individuais. properties: trial_period_days: maximum: 3650 minimum: 1 type: - integer - "null" trial_settings: additionalProperties: false properties: end_behavior: additionalProperties: false properties: missing_payment_method: enum: - cancel - pause - create_invoice type: string type: object type: object type: - object - "null" success_url: description: Destino HTTPS após concluir a página; não confirma pagamento. Aceita {CHECKOUT_SESSION_ID}. type: - string - "null" template: description: Layout da página. null usa o padrão da conta. enum: - split - sidebar - stacked - null type: - string - "null" title: description: Título exibido na página. maxLength: 120 minLength: 1 type: string example: line_items: - price: prc_1234567890abcdef quantity: 1 title: Curso de exemplo PaymentLinkUpdate: type: object additionalProperties: false properties: allow_discount_codes: description: Permite informar códigos de desconto na página. type: boolean cancel_url: description: Destino HTTPS ao cancelar a compra. null remove. format: uri type: - string - "null" checkout_experience: additionalProperties: false description: Apresentação, banner, dados exigidos e mensagem final. Campos visuais null herdam o padrão. properties: banner: additionalProperties: false properties: ends_at: format: date-time type: - string - "null" highlight: maxLength: 120 type: - string - "null" tag: maxLength: 40 type: - string - "null" text: maxLength: 500 type: string tone: enum: - neutral - urgent - success type: string variant: enum: - strip - highlight - countdown - marquee type: string type: - object - "null" confirmation_message: maxLength: 1000 type: - string - "null" footer_expanded: type: boolean header_shows_logo: type: - boolean - "null" installment_teaser_mode: enum: - hidden - maximum_installment - lowest_installment - null type: - string - "null" order_summary_mode: enum: - expanded - collapsible - compact - hidden - null type: - string - "null" product_description_mode: enum: - hidden - summary - full - null type: - string - "null" product_image_mode: enum: - hidden - thumbnail - hero - null type: - string - "null" require_billing_address: type: - boolean - "null" require_document: type: - boolean - "null" require_phone: type: - boolean - "null" summary_style: enum: - product - subscription - null type: - string - "null" type: object discount: description: Desconto disponível na conta de pagamentos. null remove o desconto automático. pattern: ^disc_[A-Za-z0-9]+$ type: - string - "null" has_surcharge: description: Repassa tarifas ao comprador. Apenas compras avulsas. type: boolean interest_payer: description: "Quem absorve os juros do parcelamento: comprador ou conta." enum: - buyer - organization type: string line_items: description: Substitui a lista inteira de itens. Cada produto aparece uma vez. items: $ref: "#/components/schemas/PaymentLinkLineItemInput" maxItems: 20 minItems: 1 type: array max_installments: description: Máximo de parcelas no cartão. maximum: 12 minimum: 1 type: integer default: 12 metadata: additionalProperties: true description: Substitui o objeto inteiro; use {} para limpar. type: object optional_items: description: Até três ofertas adicionais avulsas, de produtos diferentes dos itens principais. items: additionalProperties: false properties: call_to_action: maxLength: 120 type: string compare_at_amount: minimum: 1 type: - integer - "null" description: maxLength: 1000 type: - string - "null" price: pattern: ^prc_[a-z0-9]{16}$ type: string tag: enum: - recommended - special_offer - null type: - string - "null" title: maxLength: 120 type: string type: object required: - call_to_action - price - title maxItems: 3 type: array payment_method_collection: description: "Coleta do cartão nas assinaturas: sempre ou apenas quando houver pagamento imediato." enum: - always - if_required type: string payment_methods: description: Meios de pagamento. Assinaturas recorrentes usam credit_card. items: enum: - credit_card - pix - boleto type: string maxItems: 2 minItems: 1 type: array status: description: Publicar exige conta aprovada e itens válidos. enum: - draft - active - inactive type: string subscription_data: additionalProperties: false description: Condições da assinatura. O link aceita período grátis em dias; data final absoluta de trial pertence a sessões individuais. properties: trial_period_days: maximum: 3650 minimum: 1 type: - integer - "null" trial_settings: additionalProperties: false properties: end_behavior: additionalProperties: false properties: missing_payment_method: enum: - cancel - pause - create_invoice type: string type: object type: object type: - object - "null" success_url: description: Destino HTTPS após concluir a página; não confirma pagamento. Aceita {CHECKOUT_SESSION_ID}. type: - string - "null" template: description: Layout da página. null usa o padrão da conta. enum: - split - sidebar - stacked - null type: - string - "null" title: description: Título exibido na página. maxLength: 120 minLength: 1 type: string example: status: inactive PaymentLinkDeletedEvent: type: object additionalProperties: false required: - id - allow_discount_codes - amount - cancel_url - checkout_experience - created_at - currency - deleted - discount - has_surcharge - interest_payer - line_items - max_installments - metadata - object - optional_items - payment_method_collection - payment_methods - recurring - status - subscription_data - success_url - template - title - total_orders - updated_at - url properties: id: description: Identificador público estável, com prefixo chk_. É o mesmo ID do checkout no painel. Use a URL retornada; não construa o endereço a partir do ID. pattern: ^chk_[a-z0-9]{16}$ type: string allow_discount_codes: description: Permite informar códigos de desconto na página. type: boolean amount: description: Subtotal em centavos, calculado com os preços atuais dos itens. Somente leitura. minimum: 0 type: integer cancel_url: description: Destino HTTPS ao cancelar a compra. null remove. format: uri type: - string - "null" checkout_experience: additionalProperties: false description: Apresentação, banner, dados exigidos e mensagem final. Campos visuais null herdam o padrão. properties: banner: additionalProperties: false properties: ends_at: format: date-time type: - string - "null" highlight: maxLength: 120 type: - string - "null" tag: maxLength: 40 type: - string - "null" text: maxLength: 500 type: string tone: enum: - neutral - urgent - success type: string variant: enum: - strip - highlight - countdown - marquee type: string type: - object - "null" confirmation_message: maxLength: 1000 type: - string - "null" footer_expanded: type: boolean header_shows_logo: type: - boolean - "null" installment_teaser_mode: enum: - hidden - maximum_installment - lowest_installment - null type: - string - "null" order_summary_mode: enum: - expanded - collapsible - compact - hidden - null type: - string - "null" product_description_mode: enum: - hidden - summary - full - null type: - string - "null" product_image_mode: enum: - hidden - thumbnail - hero - null type: - string - "null" require_billing_address: type: - boolean - "null" require_document: type: - boolean - "null" require_phone: type: - boolean - "null" summary_style: enum: - product - subscription - null type: - string - "null" type: object created_at: description: Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura. format: date-time type: string currency: description: Sempre BRL. enum: - BRL type: string deleted: const: true type: boolean discount: description: Desconto disponível na conta de pagamentos. null remove o desconto automático. pattern: ^disc_[A-Za-z0-9]+$ type: - string - "null" has_surcharge: description: Repassa tarifas ao comprador. Apenas compras avulsas. type: boolean interest_payer: description: "Quem absorve os juros do parcelamento: comprador ou conta." enum: - buyer - organization type: string line_items: description: Itens vendidos pelo link, na ordem de exibição. items: $ref: "#/components/schemas/PaymentLinkLineItem" maxItems: 20 minItems: 1 type: array max_installments: description: Máximo de parcelas no cartão. Assinaturas não parcelam. maximum: 12 minimum: 1 type: integer default: 12 metadata: additionalProperties: true description: Objeto JSON livre para referências da integração, limitado a 16 KB. type: object object: const: payment_link type: string optional_items: description: Até três ofertas adicionais avulsas, de produtos diferentes dos itens principais. items: additionalProperties: false properties: call_to_action: maxLength: 120 type: string compare_at_amount: minimum: 1 type: - integer - "null" description: maxLength: 1000 type: - string - "null" price: pattern: ^prc_[a-z0-9]{16}$ type: string tag: enum: - recommended - special_offer - null type: - string - "null" title: maxLength: 120 type: string type: object required: - call_to_action - price - title maxItems: 3 type: array payment_method_collection: description: "Coleta do cartão nas assinaturas: sempre ou apenas quando houver pagamento imediato." enum: - always - if_required type: string payment_methods: description: Meios de pagamento. Assinaturas recorrentes usam credit_card. items: enum: - credit_card - pix - boleto type: string maxItems: 2 minItems: 1 type: array recurring: additionalProperties: false description: Período de renovação quando os itens são assinaturas; null em compras avulsas. Somente leitura. properties: interval: enum: - day - week - month - year type: string interval_count: minimum: 1 type: integer required: - interval - interval_count type: - object - "null" status: description: draft não abre compras; active está publicado; inactive foi desativado. enum: - draft - active - inactive type: string subscription_data: additionalProperties: false description: Condições da assinatura. O link aceita período grátis em dias; data final absoluta de trial pertence a sessões individuais. properties: trial_period_days: maximum: 3650 minimum: 1 type: - integer - "null" trial_settings: additionalProperties: false properties: end_behavior: additionalProperties: false properties: missing_payment_method: enum: - cancel - pause - create_invoice type: string type: object type: object type: - object - "null" success_url: description: Destino HTTPS após concluir a página; não confirma pagamento. Aceita {CHECKOUT_SESSION_ID}. type: - string - "null" template: description: Layout da página. null usa o padrão da conta. enum: - split - sidebar - stacked - null type: - string - "null" title: description: Título exibido na página. maxLength: 120 type: string total_orders: description: Compras confirmadas por este link. Somente leitura. minimum: 0 type: integer updated_at: description: Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura. format: date-time type: string url: description: URL confirmada do checkout hospedado. Pode usar o domínio configurado. Não construa a URL a partir do ID. type: - string - "null" example: id: chk_1234567890abcdef allow_discount_codes: false amount: 4990 cancel_url: null checkout_experience: banner: null confirmation_message: Sua compra foi confirmada. Enviaremos as instruções de acesso por email. footer_expanded: false header_shows_logo: null installment_teaser_mode: null order_summary_mode: null product_description_mode: null product_image_mode: null require_billing_address: null require_document: null require_phone: null summary_style: null created_at: 2030-01-01T00:00:00.000Z currency: BRL deleted: true discount: null has_surcharge: false interest_payer: buyer line_items: - adjustable_quantity: null price: prc_1234567890abcdef product: pro_1234567890abcdef quantity: 1 unit_amount: 4990 max_installments: 1 metadata: {} object: payment_link optional_items: [] payment_method_collection: always payment_methods: - credit_card - pix recurring: null status: active subscription_data: null success_url: null template: null title: Curso de exemplo total_orders: 0 updated_at: 2030-01-01T00:00:00.000Z url: https://checkout.example.com/pay/link-example Empty: type: object additionalProperties: false properties: {} responses: ApiFailure: description: A operação não foi concluída headers: X-Request-Id: description: Identifier of this HTTP request schema: type: string content: application/json: schema: $ref: "#/components/schemas/ApiError" example: error: code: invalid_parameter doc_url: null message: The request contains invalid parameters param: null type: invalid_request_error security: - apiKeyAuth: []