Produtos (v1)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

A API de Produtos (Inventário) da Conta Azul tem como objetivo permitir que sistemas externos gerenciem o catálogo de produtos de forma automatizada, desde a criação ou alteração dos itens, até sua listagem, detalhamento e desativação. Isso facilita a integração com e-commerce, ERPs, marketplaces e outros sistemas de vendas.

Se desejar aprofundar o entendimento das regras de negócio aplicadas pelo ERP, recomendamos, de forma opcional a consulta à nossa Central de Ajuda:

Produtos: https://ajuda.contaazul.com/hc/pt-br/sections/19716513113997-Cadastro-de-produtos

Download OpenAPI description

open-api-inventory.json

open-api-inventory.yaml

Overview

Servers

https://api-v2.contaazul.com

Mock server

https://developers.contaazul.com/_mock/open-api-docs/open-api-inventory

v1

Operações relacionadas a produtos

Operations

Retornar os produtos por filtro

Request

Permite listar os produtos cadastrados, com suporte a filtros como página, tamanho, busca por nome, sku ou ean, status ("ativo", "inativo") e ordenação.

Security

BearerAuth

Query

paginainteger

Página

Default 1

tamanho_paginainteger

Tamanho da página

Default 10

Enum1020501002005001000

campo_ordenacaostring

Campos de ordenação

Default "NOME"

Enum"NOME""CODIGO""VALOR_VENDA"

direcao_ordenacaostring

Direção de ordenação

Default "ASC"

Enum"ASC""DESC"

buscastring

Busca textual pelo nome, ean ou sku do produto

statusstring

Status do produto

Default "ATIVO"

Enum"ATIVO""INATIVO"

integracao_ecommerce_ativoboolean

Produtos com integração ativa

Default false

produtos_kit_ativoboolean

Filtrar com kits de produto

Default false

valor_venda_inicialnumber(float64)

Intervalo inicial do valor de venda

valor_venda_finalnumber(float64)

Intervalo final do valor de venda

skustring

SKU do produto para filtro exato

data_alteracao_destring

Data de alteração de (ISO 8601, São Paulo/GMT-3)

data_alteracao_atestring

Data de alteração até (ISO 8601, São Paulo/GMT-3)

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/produtos?pagina=1&tamanho_pagina=10&campo_ordenacao=NOME&direcao_ordenacao=ASC&busca=string&status=ATIVO&integracao_ecommerce_ativo=false&produtos_kit_ativo=false&valor_venda_inicial=0&valor_venda_final=0&sku=string&data_alteracao_de=string&data_alteracao_ate=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

itemsArray of objects(ItemResumoDeProdutos)

Lista de itens do resumo de produtos

totalItemsinteger

Total de itens encontrados

Example: 10

Response

application/json

{
  "items": [
    { … }
  ],
  "totalItems": 10
}

Criar um novo produto

Request

Permite criar um novo produto, informando dados como nome, código interno, unidade de medida, categoria, preço, estoque inicial, entre outros parâmetros. Ideal para automatizar o cadastro de itens novos no sistema.

Security

BearerAuth

Bodyapplication/jsonrequired

Dados do produto a ser criado

ativoboolean

Indica se o produto está ativo

Example: true

categoriaobject

Grupo ou categoria do produto

codigo_eanstring

Código EAN do produto

Example: "EAN123"

codigo_skustring<= 20 characters

Código SKU do produto

Example: "SKU123"

conversoes_unidade_medidaArray of objects(CriacaoConversaoUnidadeMedidaProduto)

Conversões de unidade de medida do produto, depende da unidade de medida das informações fiscais

descricaostring

Descrição do produto

Example: "Descrição do produto"

detalhe_kitobject

Detalhes do kit de produto

ecommerceobject

Informações de e-commerce do produto

estoqueobject

Informações de estoque do produto

fiscalobject

Informações fiscais do produto

formatostring

Formato do produto (SIMPLES ou VARIACAO)

Enum"SIMPLES""VARIACAO"

id_centro_custostring

ID do centro de custo associado ao produto

Example: "9aa9af47-a539-40fc-9005-85c70e757fcf"

nomestringrequired

Nome do produto

Example: "nome do produto"

pesos_dimensoesobject

Dimensões e pesos do produto

statusstring

Status do produto (ATIVO ou INATIVO)

Enum"ATIVO""INATIVO"

unidade_medidaobject

Unidade de medida fiscal do kit de produto

variacaoobject

Informações de variação do produto

curl -i -X POST \
  https://api-v2.contaazul.com/v1/produtos \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "ativo": true,
    "categoria": {
      "id": 1
    },
    "codigo_ean": "EAN123",
    "codigo_sku": "SKU123",
    "conversoes_unidade_medida": [
      {
        "fator": 1000,
        "id_fornecedor": [
          "string"
        ],
        "unidade_medida": {
          "id": 1
        }
      }
    ],
    "descricao": "Descrição do produto",
    "detalhe_kit": {
      "itens": [
        {
          "id_produto": "0e9b442a-3af0-45f1-9c5c-415473084092",
          "quantidade": 1,
          "valor_total": 100,
          "valor_unitario": 100
        }
      ],
      "valor_venda": 100
    },
    "ecommerce": {
      "categoria_ecommerce": {
        "id": "0e9b442a-3af0-45f1-9c5c-415473084092"
      },
      "condicao": "NOVO",
      "descricao_adicional": "Descrição adicional do produto",
      "descricao_seo": "Descrição SEO do produto",
      "integracao_ativa": true,
      "marca": {
        "id": "0e9b442a-3af0-45f1-9c5c-415473084092"
      },
      "titulo_seo": "Título SEO do produto",
      "url_seo": "https://www.exemplo.com/produto"
    },
    "estoque": {
      "custo_medio": 80,
      "estoque_disponivel": 50,
      "estoque_maximo": 100,
      "estoque_minimo": 10,
      "valor_venda": 100
    },
    "fiscal": {
      "cest": {
        "id": 1
      },
      "ncm": {
        "id": 1
      },
      "origem": "NACIONAL",
      "tipo_produto": "MERCADORIA_PARA_REVENDA",
      "unidade_medida": {
        "id": 1
      }
    },
    "formato": "SIMPLES",
    "id_centro_custo": "9aa9af47-a539-40fc-9005-85c70e757fcf",
    "nome": "nome do produto",
    "pesos_dimensoes": {
      "altura": 10,
      "largura": 10,
      "peso_bruto": 10,
      "peso_liquido": 10,
      "profundidade": 10,
      "volumes": 10
    },
    "status": "ATIVO",
    "unidade_medida": {
      "id": 1
    },
    "variacao": {
      "produtos": [
        {
          "codigo_ean": "EAN123",
          "codigo_sku": "SKU123",
          "nome": "pacote 5kg",
          "opcoes": [
            {
              "id": "0e9b442a-3af0-45f1-9c5c-415473084092"
            }
          ],
          "saldo": 10,
          "valor_venda": 99.99
        }
      ],
      "tipos": [
        {
          "descricao": "pacote 5kg",
          "opcoes": [
            {
              "descricao": "5kg",
              "id": "0e9b442a-3af0-45f1-9c5c-415473084092"
            }
          ]
        }
      ]
    }
  }'

Responses

Created

Bodyapplication/json

ativoboolean

Indica se o produto está ativo

Example: true

categoriaobject

Grupo ou categoria do produto

codigo_eanstring

Código de barras do produto

Example: "EAN123"

codigo_skustring

Código interno do produto

Example: "SKU123"

conversao_unidade_medidaArray of objects(ConversaoDeUnidadeDeMedidaDoProduto)

Conversões de unidade de medida do produto

descricaostring

Descrição detalhada do produto

Example: "Descrição do produto"

detalhe_kitobject

Detalhes do kit de produtos

ecommerceobject

Informações de e-commerce do produto

estoqueobject

Informações de estoque do produto

fiscalobject

Informações fiscais do produto

formatostring

Formato do produto

Enum"SIMPLES""VARIACAO"

Example: "SIMPLES"

idstring

ID do produto no sistema legado

Example: "9aa9af47-a539-40fc-9005-85c70e757fcf"

id_centro_custostring

ID do centro de custo associado ao produto

Example: "9aa9af47-a539-40fc-9005-85c70e757fcf"

id_legadointeger

ID do produto no sistema legado

Example: 78305

imagensArray of objects(ImagemDoProduto)

Lista de imagens do produto

nomestring

Nome do produto

Example: "nome do produto"

pesos_dimensoesobject

Dimensões e pesos do produto

statusstring

Status atual do produto

Enum"ATIVO""INATIVO"

Example: "ATIVO"

ultima_atualizacaostring

Data da última atualização do produto

Example: "2025-07-22T17:47:35.825004839Z"

unidade_medidaobject

Unidade de medida fiscal do produto

variacaoobject

Informações de variação do produto

versaointeger

Versão do produto

Example: 1

Response

application/json

{
  "ativo": true,
  "categoria": {
    "descricao": "Categoria do produto",
    "id": 1,
    "uuid": "9aa9af47-a539-40fc-9005-85c70e757fcf"
  },
  "codigo_ean": "EAN123",
  "codigo_sku": "SKU123",
  "conversao_unidade_medida": [
    { … }
  ],
  "descricao": "Descrição do produto",
  "detalhe_kit": {
    "items": [ … ],
    "valor_venda_kit": 40
  },
  "ecommerce": {
    "categoria_ecommerce": { … },
    "condicao": "NOVO",
    "descricao_adicional": "Descrição adicional do produto",
    "descricao_seo": "Descrição SEO do produto",
    "integracao_ativa": true,
    "marca": { … },
    "titulo_seo": "Título SEO do produto",
    "url_seo": "https://www.exemplo.com/produto"
  },
  "estoque": {
    "custo_medio": 10,
    "maximumStock": 10,
    "minimumStock": 10,
    "quantidade_disponivel": 10,
    "quantidade_reservada": 10,
    "quantidade_total": 10,
    "valor_venda": 10
  },
  "fiscal": {
    "cest": { … },
    "ncm": { … },
    "origem": "NACIONAL",
    "tipo_produto": "EMBALAGEM",
    "unidade_medida": { … }
  },
  "formato": "SIMPLES",
  "id": "9aa9af47-a539-40fc-9005-85c70e757fcf",
  "id_centro_custo": "9aa9af47-a539-40fc-9005-85c70e757fcf",
  "id_legado": 78305,
  "imagens": [
    { … }
  ],
  "nome": "nome do produto",
  "pesos_dimensoes": {
    "altura": 10,
    "largura": 15,
    "peso_bruto": 1.5,
    "peso_liquido": 1,
    "profundidade": 5,
    "volumes": 10
  },
  "status": "ATIVO",
  "ultima_atualizacao": "2025-07-22T17:47:35.825004839Z",
  "unidade_medida": {
    "descricao": "Descrição da unidade de medida fiscal",
    "id": 1
  },
  "variacao": {
    "produtos": [ … ],
    "tipos": [ … ]
  },
  "versao": 1
}

Retornar as categorias por filtro

Request

Permite listar categorias de produtos cadastradas na Conta Azul, com paginação e filtro por texto. Útil para validar categoria na criação de produtos.

Security

BearerAuth

Query

paginainteger

Página

Default 1

tamanho_paginainteger

Tamanho da página

Default 10

Enum1020501002005001000

busca_textualstring

Busca textual pela descrição da categoria

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/produtos/categorias?pagina=1&tamanho_pagina=10&busca_textual=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

itemsArray of objects(CategoriaDeProduto)

lista de categorias de produtos

total_itemsinteger

total de itens

Example: 10

Response

application/json

{
  "items": [
    { … }
  ],
  "total_items": 10
}

Retornar os cests por filtro

Request

Retorna códigos CEST (Código Especificador da Substituição Tributária) usados para questões fiscais, com filtro por texto e paginação. Importante para definir a tributação correta de produtos no ERP.

Security

BearerAuth

Query

paginainteger

Página

Default 1

tamanho_paginainteger

Tamanho da página

Default 10

Enum1020501002005001000

busca_textualstring

Busca textual pela descrição ou código do CEST

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/produtos/cest?pagina=1&tamanho_pagina=10&busca_textual=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

itemsArray of objects(CEST)

lista de CEST

total_itemsinteger

total de itens

Example: 10

Response

application/json

{
  "items": [
    { … }
  ],
  "total_items": 10
}

Retornar as categorias de e-commerce por filtro

Request

Retorna categorias específicas para e-commerce (não necessariamente as mesmas categorias internas), permite filtro por descrição. Útil para integrar categorização de produtos entre seu sistema e Conta Azul.

Security

BearerAuth

Query

busca_textualstring

Busca textual pela descrição da categoria

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/produtos/ecommerce-categorias?busca_textual=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

idstring

Example: "b9ec512f-98a5-44b2-b65f-b378a1db3ce5"

itemsArray of objects(ProdutoEcommerceCategoriaItem)

versaointeger

Example: 1

Response

application/json

{
  "id": "b9ec512f-98a5-44b2-b65f-b378a1db3ce5",
  "items": [
    { … }
  ],
  "versao": 1
}

Retornar as marcas de ecommerce por filtro

Request

Busca marcas usadas no contexto de e-commerce, com paginação, ordenação e filtro por nome. Permite sincronizar marcas entre sistema de vendas online e Conta Azul.

Security

BearerAuth

Query

paginainteger

Página

Default 1

tamanho_paginainteger

Tamanho da página

Default 10

Enum1020501002005001000

direcaostring

Direção de ordenação

Default "ASC"

Enum"ASC""DESC"

busca_textualstring

Busca textual pelo nome da marca

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/produtos/ecommerce-marcas?pagina=1&tamanho_pagina=10&direcao=ASC&busca_textual=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

itemsArray of objects(MarcaDeEcommerceItem)

lista de marcas de ecommerce

total_itemsinteger

total de itens

Example: 10

Response

application/json

{
  "items": [
    { … }
  ],
  "total_items": 10
}

Retornar os ncms por filtro

Request

Retorna códigos NCM (Nomenclatura Comum do Mercosul), com filtro por texto e paginação. Necessário para classificação fiscal de produtos.

Security

BearerAuth

Query

paginainteger

Página

Default 1

tamanho_paginainteger

Tamanho da página

Default 10

Enum1020501002005001000

busca_textualstring

Busca textual pela descrição ou código do NCM

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/produtos/ncm?pagina=1&tamanho_pagina=10&busca_textual=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

itemsArray of objects(Ncm)

lista de NCM

total_itemsinteger

total de itens

Example: 10

Response

application/json

{
  "items": [
    { … }
  ],
  "total_items": 10
}

Retornar as unidades de medida por filtro

Request

Retorna as unidades de medida possíveis para produtos, com paginação e busca por descrição. Essencial para definir medidas fiscais (peso, volume, etc.) ou unidades de estoque.

Security

BearerAuth

Query

paginainteger

Página

Default 1

tamanho_paginainteger

Tamanho da página

Default 10

Enum1020501002005001000

busca_textualstring

Busca textual pela descrição da unidade de medida

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/produtos/unidades-medida?pagina=1&tamanho_pagina=10&busca_textual=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

itemsArray of objects(UnidadeDeMedidaDeProduto)

lista de unidades de medida de produto

total_itemsinteger

total de itens

Example: 10

Response

application/json

{
  "items": [
    { … }
  ],
  "total_items": 10
}

Retornar o produto por id

Request

Traz todos os detalhes de um produto específico (estoque, fiscal, e-commerce, variações, pesos, unidades, etc.). Ideal para consultar dados completos antes de exibir para usuário ou para sincronização.

Security

BearerAuth

Path

idstringrequired

id do produto

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/produtos/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

ativoboolean

Indica se o produto está ativo

Example: true

categoriaobject

Grupo ou categoria do produto

codigo_eanstring

Código de barras do produto

Example: "EAN123"

codigo_skustring

Código interno do produto

Example: "SKU123"

conversao_unidade_medidaArray of objects(ConversaoDeUnidadeDeMedidaDoProduto)

Conversões de unidade de medida do produto

descricaostring

Descrição detalhada do produto

Example: "Descrição do produto"

detalhe_kitobject

Detalhes do kit de produtos

ecommerceobject

Informações de e-commerce do produto

estoqueobject

Informações de estoque do produto

fiscalobject

Informações fiscais do produto

formatostring

Formato do produto

Enum"SIMPLES""VARIACAO"

Example: "SIMPLES"

idstring

ID do produto no sistema legado

Example: "9aa9af47-a539-40fc-9005-85c70e757fcf"

id_centro_custostring

ID do centro de custo associado ao produto

Example: "9aa9af47-a539-40fc-9005-85c70e757fcf"

id_legadointeger

ID do produto no sistema legado

Example: 78305

imagensArray of objects(ImagemDoProduto)

Lista de imagens do produto

nomestring

Nome do produto

Example: "nome do produto"

pesos_dimensoesobject

Dimensões e pesos do produto

statusstring

Status atual do produto

Enum"ATIVO""INATIVO"

Example: "ATIVO"

ultima_atualizacaostring

Data da última atualização do produto

Example: "2025-07-22T17:47:35.825004839Z"

unidade_medidaobject

Unidade de medida fiscal do produto

variacaoobject

Informações de variação do produto

versaointeger

Versão do produto

Example: 1

Response

application/json

{
  "ativo": true,
  "categoria": {
    "descricao": "Categoria do produto",
    "id": 1,
    "uuid": "9aa9af47-a539-40fc-9005-85c70e757fcf"
  },
  "codigo_ean": "EAN123",
  "codigo_sku": "SKU123",
  "conversao_unidade_medida": [
    { … }
  ],
  "descricao": "Descrição do produto",
  "detalhe_kit": {
    "items": [ … ],
    "valor_venda_kit": 40
  },
  "ecommerce": {
    "categoria_ecommerce": { … },
    "condicao": "NOVO",
    "descricao_adicional": "Descrição adicional do produto",
    "descricao_seo": "Descrição SEO do produto",
    "integracao_ativa": true,
    "marca": { … },
    "titulo_seo": "Título SEO do produto",
    "url_seo": "https://www.exemplo.com/produto"
  },
  "estoque": {
    "custo_medio": 10,
    "maximumStock": 10,
    "minimumStock": 10,
    "quantidade_disponivel": 10,
    "quantidade_reservada": 10,
    "quantidade_total": 10,
    "valor_venda": 10
  },
  "fiscal": {
    "cest": { … },
    "ncm": { … },
    "origem": "NACIONAL",
    "tipo_produto": "EMBALAGEM",
    "unidade_medida": { … }
  },
  "formato": "SIMPLES",
  "id": "9aa9af47-a539-40fc-9005-85c70e757fcf",
  "id_centro_custo": "9aa9af47-a539-40fc-9005-85c70e757fcf",
  "id_legado": 78305,
  "imagens": [
    { … }
  ],
  "nome": "nome do produto",
  "pesos_dimensoes": {
    "altura": 10,
    "largura": 15,
    "peso_bruto": 1.5,
    "peso_liquido": 1,
    "profundidade": 5,
    "volumes": 10
  },
  "status": "ATIVO",
  "ultima_atualizacao": "2025-07-22T17:47:35.825004839Z",
  "unidade_medida": {
    "descricao": "Descrição da unidade de medida fiscal",
    "id": 1
  },
  "variacao": {
    "produtos": [ … ],
    "tipos": [ … ]
  },
  "versao": 1
}

Deletar produto por id

Request

Remove o produto correspondente ao Id. Use para excluir produtos que não são mais necessários ou foram removidos do catálogo.

Security

BearerAuth

Path

idstringrequired

id do produto

curl -i -X DELETE \
  'https://api-v2.contaazul.com/v1/produtos/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

No Content

Response

No content

Atualizar parcialmente um produto por id

Request

Permite atualizar apenas alguns campos de um produto (nome, EAN, SKU, NCM, peso, valor de venda, unidade de medida, etc.). É útil para ajustes pontuais sem precisar reenviar o objeto completo do produto.

Security

BearerAuth

Path

idstringrequired

ID do produto a ser atualizado

Bodyapplication/jsonrequired

Dados do produto a ser atualizado

cestinteger

ID do Código CEST do produto

Example: 1

codigo_eanstring

Código EAN do produto

Example: "EAN123"

codigo_skustring

Código do produto

Example: "codigo do produto"

ncminteger

ID do Código NCM do produto

Example: 1

nomestring

Nome do produto

Example: "nome do produto"

peso_brutonumber

Peso bruto do produto

Example: 10

peso_liquidonumber>= 0

Peso líquido do produto

Example: 10

unidade_medidainteger

ID da unidade de medida do produto

Example: 1

valor_vendanumber>= 0

Valor de venda do produto

Example: 99.9

curl -i -X PATCH \
  'https://api-v2.contaazul.com/v1/produtos/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "cest": 1,
    "codigo_ean": "EAN123",
    "codigo_sku": "codigo do produto",
    "ncm": 1,
    "nome": "nome do produto",
    "peso_bruto": 10,
    "peso_liquido": 10,
    "unidade_medida": 1,
    "valor_venda": 99.9
  }'

Responses

No Content

Response

No content

Produtos (v1)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

v1

Retornar os produtos por filtro

Request

Responses

Was this helpful?

Criar um novo produto

RequestExpand all

Responses

Was this helpful?

Retornar as categorias por filtro

Request

Responses

Was this helpful?

Retornar os cests por filtro

Request

Responses

Was this helpful?

Retornar as categorias de e-commerce por filtro

Request

Responses

Was this helpful?

Retornar as marcas de ecommerce por filtro

Request

Responses

Was this helpful?

Retornar os ncms por filtro

Request

Responses

Was this helpful?

Retornar as unidades de medida por filtro

Request

Responses

Was this helpful?

Retornar o produto por id

Request

Responses

Was this helpful?

Deletar produto por id

Request

Responses

Was this helpful?

Atualizar parcialmente um produto por id

Request

Responses

Was this helpful?

Produtos (v1)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Request