Conta Azul Produtos (Inventory)
API para gerenciamento de produtos
OpenAPI Specification
openapi: 3.0.1
info:
title: Produto
version: v1
description: API para gerenciamento de produtos
servers:
- url: https://api-v2.contaazul.com
description: Servidor de produção
security:
- bearerAuth: []
tags:
- name: v1
description: Operações relacionadas a produtos
paths:
/v1/produto/busca:
get:
summary: Obter produtos por filtro
operationId: getProductsByFilter
parameters:
- name: pagina
in: query
required: false
schema:
type: integer
default: 1
example: 1
- name: tamanho_pagina
in: query
required: false
schema:
type: integer
default: 10
example: 10
- name: campo_ordenacao
in: query
required: false
schema:
type: string
default: NOME
enum:
- NOME
- CODIGO
- VALOR_VENDA
- ESTOQUE
example: NOME
- name: direcao_ordenacao
in: query
required: false
description: Direção da ordenação (ASC para ascendente, DESC para descendente).
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: busca
in: query
required: false
description: Buscar produtos por nome ou código.
example: Produto
schema:
type: string
- name: status
in: query
required: false
description: Status do produto.
schema:
type: string
enum:
- ATIVO
- INATIVO
- TODOS
default: TODOS
- name: inicio
in: query
required: false
schema:
type: number
example: 10.5
- name: fim
in: query
required: false
schema:
type: number
example: 100.5
responses:
'200':
description: Resposta bem-sucedida
content:
application/json:
schema:
$ref: '#/components/schemas/ListagemDeProdutosPorFiltroResponse'
tags:
- v1
/v1/produto:
post:
summary: Criar um novo produto
operationId: createProduct
tags:
- v1
requestBody:
description: >-
Ao cadastrar um novo produto, deve-se observar o formato. Caso seja
VARIACAO, o item "variação" é obrigatório.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CriacaoProdutoRequest'
responses:
'200':
description: Produto criado com sucesso
content:
application/json:
schema:
$ref: '#/components/schemas/ProdutoResponse'
/v1/produto/{id}:
delete:
summary: Excluir um produto existente
operationId: deleteProduct
parameters:
- name: id
in: path
required: true
example: 123e4567-e89b-12d3-a456-426614174000
schema:
type: string
format: uuid
responses:
'204':
description: Produto excluído com sucesso
'404':
description: Produto não encontrado
tags:
- v1
/v1/produto/desativar:
post:
summary: Desativar produtos
description: Desativa uma lista de produtos pelo ID.
operationId: deactivateProducts
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
description: Lista de IDs dos produtos a serem desativados.
type: string
format: uuid
example:
- 123e4567-e89b-12d3-a456-426614174000
- 34471cce-67a2-48b8-a526-1120c0704ed3
responses:
'200':
description: Produtos desativados com sucesso.
content:
application/json:
schema:
$ref: '#/components/schemas/ProdutoDesativadoResponse'
'400':
description: Requisição inválida.
'500':
description: Erro interno do servidor.
tags:
- v1
components:
schemas:
ListagemDeProdutosPorFiltroResponse:
type: object
properties:
itens:
type: array
items:
$ref: '#/components/schemas/ProductListResponse'
itens_totais:
type: integer
example: 1
CriacaoProdutoRequest:
type: object
required:
- nome
- formato
- estoque
- dimensao
properties:
nome:
type: string
example: Nome do Produto
codigo_sku:
type: string
example: SKU12345
codigo_ean:
type: string
example: '1234567890123'
observacao:
type: string
example: Descrição do produto
formato:
type: string
example: VARIACAO
enum:
- SIMPLES
- VARIACAO
estoque:
$ref: '#/components/schemas/EstoqueCriacaoProduto'
dimensao:
$ref: '#/components/schemas/Dimensao'
variacao:
$ref: '#/components/schemas/VariacaoRequest'
ecommerce:
$ref: '#/components/schemas/EcommerceRequestProduto'
ProdutoResponse:
type: object
properties:
id:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
identificador_legado:
type: string
example: '123'
ativo:
type: boolean
example: true
versao:
type: integer
example: 1
nome:
type: string
example: Nome do Produto
codigo_sku:
type: string
example: PROD123
codigo_ean:
type: string
example: '1234567890123'
observacao:
type: string
example: Descrição do Produto
status:
type: string
description: Status do produto
example: ATIVO
enum:
- ATIVO
- INATIVO
formato:
type: string
example: VARIACAO
description: Formato do produto.
enum:
- SIMPLES
- VARIACAO
estoque:
$ref: '#/components/schemas/Estoque'
dimensoes:
$ref: '#/components/schemas/Dimensao'
ecommerce:
$ref: '#/components/schemas/Ecommerce'
variacao:
description: Caso o formato não seja do tipo VARIACAO, este campo será nulo.
$ref: '#/components/schemas/VariacaoResponse'
ProdutoDesativadoResponse:
type: object
properties:
todos:
type: array
example:
- 34471cce-67a2-48b8-a526-1120c0704ed3
- 123e4567-e89b-12d3-a456-426614174000
items:
type: string
format: uuid
description: Lista de todos os produtos.
produtos_desativados:
type: array
items:
type: string
format: uuid
description: Lista de produtos desativados.
example:
- 34471cce-67a2-48b8-a526-1120c0704ed3
- 123e4567-e89b-12d3-a456-426614174000
EcommerceRequestProduto:
type: object
properties:
condicao:
type: string
example: NOVO
enum:
- NOVO
- USADO
integracao_habilitada:
type: boolean
example: false
observacao_adicional:
type: string
example: Descrição adicional....
titulo_seo:
type: string
example: Produto 1.0
descricao:
type: string
example: Lorem ipsum
url_seo:
type: string
example: produto-x-1-0
Estoque:
type: object
properties:
estoque_total:
type: number
format: double
example: 100
valor_venda:
type: number
format: double
example: 99.99
custo_medio:
type: number
format: double
example: 50
estoque_disponivel:
type: number
format: double
example: 80
estoque_minimo:
type: number
format: double
example: 10
estoque_maximo:
type: number
format: double
example: 200
EstoqueCriacaoProduto:
type: object
properties:
valor_venda:
description: Valor de venda do produto.
type: number
format: double
example: 99.99
custo_medio:
description: Valor de custo médio do produto.
type: number
format: double
example: 50
estoque_disponivel:
description: Quantidade de estoque disponível do produto.
type: number
format: double
example: 50.5
estoque_minimo:
description: Quantidade mínima de estoque do produto.
type: number
format: double
example: 1
estoque_maximo:
description: Quantidade máxima de estoque do produto.
type: number
format: double
example: 100
Dimensao:
type: object
properties:
altura:
type: number
format: double
example: 10
largura:
type: number
format: double
example: 5
profundidade:
type: number
format: double
example: 2
Ecommerce:
type: object
properties:
condicao:
type: string
example: NOVO
enum:
- NOVO
- USADO
integracao_ativa:
type: boolean
example: true
descricao_adicional:
type: string
example: Descrição adicional do produto
titulo_seo:
type: string
example: Título SEO
descricao_seo:
type: string
example: Descrição SEO
url_seo:
type: string
example: url-seo
VariacaoRequest:
type: object
properties:
tipos:
description: >-
O tipo deve conter pelo menos uma opção. Que será utilizada para
criar as variações do produto.
type: array
items:
$ref: '#/components/schemas/TipoVariacaoRequest'
produtos:
type: array
description: >-
O produto deve conter pelo menos uma opção. Cada item conterá os
dados do produto e as opções de variação.
items:
$ref: '#/components/schemas/ItemVariacaoRequest'
VariacaoResponse:
type: object
properties:
tipos:
type: array
items:
$ref: '#/components/schemas/TipoVariacao'
produtos:
type: array
items:
$ref: '#/components/schemas/ItemVariacao'
TipoVariacao:
type: object
properties:
id:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
descricao:
type: string
example: Tamanho
opcoes:
type: array
items:
$ref: '#/components/schemas/ProductVariationOptionResponse'
ItemVariacao:
type: object
properties:
id:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
nome:
type: string
example: Produto Variado - Tamanho G
codigo:
type: string
example: PROD123
codigo_ean:
type: string
example: '1234567890123'
versao:
type: integer
example: 1
valor_venda:
type: number
format: double
example: 99.99
estoque:
type: number
format: double
example: 50
opcoes:
type: array
items:
$ref: '#/components/schemas/ProductVariationOptionResponse'
TipoVariacaoRequest:
type: object
required:
- descricao
- opcoes
properties:
descricao:
type: string
example: Tamanho
opcoes:
type: array
items:
$ref: '#/components/schemas/ProductVariationOptionRequest'
ItemVariacaoRequest:
type: object
required:
- nome
- codigo
- estoque
- opcoes
properties:
nome:
type: string
example: Produto Variado - Tamanho G
codigo:
type: string
example: PROD123
codigo_ean:
type: string
example: '1234567890123'
versao:
type: integer
example: 1
valor_venda:
type: number
format: double
example: 99.99
estoque:
type: number
format: double
example: 50
opcoes:
type: array
items:
$ref: '#/components/schemas/ProductVariationOptionRequest'
ProductVariationOptionResponse:
type: object
properties:
id:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
descricao:
type: string
example: G
ProductVariationOptionRequest:
type: object
required:
- id
- descricao
properties:
id:
description: >-
Identificador único da opção de variação é obrigatório. Cada opção
de variação deve ter um identificador único em cada cadastro de
produto. Ao informar a variação no produto, o mesmo identificador do
elemento tipos.opcoes deve ser informado em produtos.opcoes.
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
descricao:
description: Descrição da opção de variação é obrigatório.
type: string
example: Descrição da opção de variação
ProductListResponse:
type: object
properties:
id:
type: string
format: uuid
example: 34471cce-67a2-48b8-a526-1120c0704ed3
id_legado:
type: integer
description: ID Legado do produto.
example: 12345
nome:
type: string
description: Nome do Produto.
example: Produto Exemplo
codigo_sku:
type: string
description: Código SKU.
example: SKU123456
codigo_ean:
type: string
description: Código EAN.
example: '1234567890123'
tipo:
type: string
description: Tipo do produto.
example: VARIACAO
enum:
- PRODUTO
- VARIACAO
- KIT_PRODUTOS
status:
type: string
description: Status do produto
example: ATIVO
enum:
- ATIVO
- INATIVO
- TODOS
estoque:
type: number
format: double
description: Estoque.
example: 50
valor_venda:
type: number
format: double
description: Valor de venda.
example: 99.99
custo_medio:
type: number
format: double
description: Custo médio.
example: 50
filhos:
type: array
description: Lista de produtos filhos.
items:
$ref: '#/components/schemas/ProductListChildResponse'
example:
- id: 123e4567-e89b-12d3-a456-426614174000
id_legado: 12345
nome: Produto Filho 1
codigo_sku: SKU123456
codigo_ean: '1234567890123'
tipo: PRODUTO
status: ATIVO
estoque: 20
valor_venda: 49.99
custo_medio: 25
filhos: []
variacao: 0
nivel_estoque: MINIMO
estoque_minimo: 5
estoque_maximo: 100
movimentado: true
id_pai: 34471cce-67a2-48b8-a526-1120c0704ed3
integracao_ecommerce_ativa: true
- id: 123e4567-e89b-12d3-a456-426614174001
id_legado: 12346
nome: Produto Filho 2
codigo_sku: SKU123457
codigo_ean: '1234567890124'
tipo: VARIACAO
status: INATIVO
estoque: 10
valor_venda: 29.99
custo_medio: 15
filhos: []
variacao: 0
nivel_estoque: MAXIMO
estoque_minimo: 2
estoque_maximo: 50
movimentado: false
id_pai: 34471cce-67a2-48b8-a526-1120c0704ed3
integracao_ecommerce_ativa: false
variacao:
type: integer
description: Quantidade de filhos/variações.
example: 2
nivel_estoque:
type: string
description: Nível do estoque
example: MINIMO
enum:
- MINIMO
- MAXIMO
- PADRAO
estoque_minimo:
type: number
format: double
description: Estoque mínimo.
example: 10
estoque_maximo:
type: number
format: double
description: Estoque máximo.
example: 200
movimentado:
type: boolean
description: Indica se o produto foi movimentado
example: true
id_pai:
type: string
format: uuid
description: ID do produto pai
example: 34471cce-67a2-48b8-a526-1120c0704ed3
integracao_ecommerce_ativa:
type: boolean
description: Indica se a integração com o e-commerce está ativa.
example: true
ProductListChildResponse:
type: object
properties:
id:
type: string
format: uuid
example: 34471cce-67a2-48b8-a526-1120c0704ed3
id_legado:
type: integer
description: ID Legado do produto.
example: 12345
nome:
type: string
description: Nome do Produto.
example: Produto Exemplo
codigo_sku:
type: string
description: Código SKU.
example: SKU123456
codigo_ean:
type: string
description: Código EAN.
example: '1234567890123'
tipo:
type: string
description: Tipo do produto.
example: VARIACAO
enum:
- PRODUTO
- VARIACAO
- KIT_PRODUTOS
status:
type: string
description: Status do produto
example: ATIVO
enum:
- ATIVO
- INATIVO
- TODOS
estoque:
type: number
format: double
description: Estoque.
example: 50
valor_venda:
type: number
format: double
description: Valor de venda.
example: 99.99
custo_medio:
type: number
format: double
description: Custo médio.
example: 50
filhos:
type: array
description: Lista de produtos filhos. Neste nível retorna vazio.
items: {}
variacao:
type: integer
description: Quantidade de filhos/variações. Neste nível retorna 0.
example: 0
nivel_estoque:
type: string
description: Nível do estoque
example: MINIMO
enum:
- MINIMO
- MAXIMO
- PADRAO
estoque_minimo:
type: number
format: double
description: Estoque mínimo.
example: 10
estoque_maximo:
type: number
format: double
description: Estoque máximo.
example: 200
movimentado:
type: boolean
description: Indica se o produto foi movimentado
example: true
id_pai:
type: string
format: uuid
description: ID do produto pai
example: 34471cce-67a2-48b8-a526-1120c0704ed3
integracao_ecommerce_ativa:
type: boolean
description: Indica se a integração com o e-commerce está ativa.
example: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT