A API V3 JÁ ESTÁ DISPONÍVEL
As integrações API v2 que já estão configuradas, seguirão funcionando temporariamente. |
Insere um produto
Insere um produto simples no sistema.
Padrões
Para incluir um produto com variação, deve-se seguir um padrão, o qual é aplicado para os produtos cadastrados manualmente no sistema. Para maiores informações acesse o manual Variação de Produto
Dois Pontos ( : ) - Serve para separar atributo de valor
Ponto e Vírgula ( ; ) - Serva para separar variações
Produto Simples
Não deve ser informado no XML enviado as tags referente as variações, dessa forma o sistema irá entender que se trata de um produto simples.
Variação Simples
Deve-se informar o nome do atributo e o seu respectivo valor separados por ":" sem espaço ( atributo:valor ).
Consideramos que o produto Camisa Preta, seu atributo é "Cor" e o seu valor é "Preta", dessa forma deve ser informado como nome "Cor:Preta".
curl |
curl -X POST "https://bling.com.br/Api/v2/produto/json/" |
PHP |
$url = 'https://bling.com.br/Api/v2/produto/json/'; $xml = '...'; $posts = array ( "apikey" => "{apikey}", "xml" => rawurlencode($xml) ); $retorno = executeInsertProduct($url, $posts); echo $retorno; function executeInsertProduct($url, $data){ $curl_handle = curl_init(); curl_setopt($curl_handle, CURLOPT_URL, $url); curl_setopt($curl_handle, CURLOPT_POST, count($data)); curl_setopt($curl_handle, CURLOPT_POSTFIELDS, $data); curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, TRUE); $response = curl_exec($curl_handle); curl_close($curl_handle); return $response; } |
C# |
public static void ExecuteInsertProduct() { HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://bling.com.br/Api/v2/produto/json/"); ASCIIEncoding encoding = new ASCIIEncoding(); string postData = "apikey={apiKey}&xml={xml_do_produto}"; byte[] data = encoding.GetBytes(postData); request.Method = "POST"; request.ContentType = "application/x-www-form-urlencoded"; request.ContentLength = data.Length; using (Stream stream = request.GetRequestStream()) stream.Write(data,0,data.Length); HttpWebResponse response = (HttpWebResponse)request.GetResponse(); string responseString = new StreamReader(response.GetResponseStream()).ReadToEnd(); Console.Out.WriteLine("Response Body: \r\n {0}", responseString); } |
Variação Dupla
Deve-se utilizar o mesmo método citado acima, apenas adicionando o segundo atributo além do separador ";" entre eles ( atributo1:valor1;atributo2:valor2 ).
Consideramos que o produto Camisa Preta G, seus atributos são "Cor" e "Tamanho", já seus valores são "Preta" e "G" respectivamente, dessa forma deve ser informado como nome "Cor:Preta;Tamanho:G"
Parâmetro | Descrição | Tipo |
apikey |
apikey gerada no sistema | string |
xml |
xml contendo o produto | string |
Para o parâmetro xml
, é necessário seguir um padrão.
Tabela de campos do XML
Grupo | Campo | Informação | Tipo | Padrão | Opcional | Nota |
---|---|---|---|---|---|---|
raiz | produto | Obrigatório | ||||
produto | codigo | Código do produto | STRING(60) | Opcional | ||
produto | codigoItem | Código de item de serviço (06, 21 e 22) | INTEGER(4) | Opcional | ||
produto | descricao | Descrição do produto | STRING(120) | Obrigatório | ||
produto | tipo | Tipo ('S' para serviço, 'P' para produto e 'N' para serviço de nota 06, 21 e 22) | STRING(1) | P | Opcional | |
produto | situacao | Situação do produto (Ativo ou Inativo) | STRING | Ativo | Opcional | |
produto | descricaoCurta | Descrição curta do produto | STRING | Opcional | ||
produto | descricaoComplementar | Descrição complementar do produto | STRING | Opcional |
|
|
produto | un | Tipo de unidade do produto | STRING(6) | pc, un, cx | Opcional | |
produto | vlr_unit | Valor unitário do produto | DECIMAL(17,10) | Opcional | ||
produto | preco_custo | Preço de custo do produto | DECIMAL(17,10) | Opcional | ||
produto | peso_bruto | Peso bruto do produto | DECIMAL(11,3) | Opcional | 1 | |
produto | peso_liq | Peso líquido do produto | DECIMAL(11,3) | Opcional | 1 | |
produto | class_fiscal | NCM do produto | STRING(10) | 9999.99.99 | Opcional | |
produto | marca | Marca do produto | STRING(40) | Opcional | ||
produto | cest | CEST do produto | STRING(7) | 99.999.99 | Opcional | |
produto | origem | Origem do produto | STRING(1) | 9 | Opcional | |
produto | idGrupoProduto | Identificador do grupo do produto | DECIMAL(11) | 0 | Opcional | 2 |
produto | condicao | Condição do produto (Não especificado, Novo, Recondicionado ou Usado) | STRING | Não especificado | Opcional | 1 |
produto | freteGratis | Frete grátis (S para Sim ou N para Não) | STRING(1) | N | Opcional | 1 |
produto | linkExterno | Link do produto na loja virtual, marketplace, catálago etc. | STRING(100) | Opcional | ||
produto | observacoes | Observações do produto | STRING | Opcional | ||
produto | producao | Tipo de produção do produto (T para Terceiros ou P para Própria) | STRING(1) | P | Opcional | 1 |
produto | unidadeMedida | Unidade de medida do produto (Metros, Centímetros ou Milímetro) | STRING | Centímetros | Opcional | 1 |
produto | dataValidade | Data de validade do produto | DATE | dd/mm/YYYY | Opcional | 1 |
produto | descricaoFornecedor | Descrição do fornecedor | STRING | Opcional | ||
produto | idFabricante | Id do fornecedor (pode ser obtido no GET de contatos) | DECIMAL(11) | Opcional | ||
produto | codigoFabricante | Código do produto no fornecedor | STRING | Opcional | ||
produto | deposito | Depósito ao qual será lançado estoque | Opcional | 1 | ||
deposito | id | Código identificador do depósito | DECIMAL(11) | Opcional | 1 | |
deposito | estoque | Estoque atual do produto no depósito | DECIMAL(11,4) | Opcional | 1 | |
produto | gtin | GTIN / EAN do produto | STRING(14) | Opcional | 1 | |
produto | gtinEmbalagem | GTIN / EAN tributário da menor unidade comercializada | STRING(14) | Opcional | 1 | |
produto | largura | Largura do produto com embalagem | STRING(15) | Opcional | 1 | |
produto | altura | Altura do produto com embalagem | STRING(15) | Opcional | 1 | |
produto | profundidade | Profundidade do produto com embalagem | STRING(15) | Opcional | 1 | |
produto | estoqueMinimo | Estoque mínimo do produto | DECIMAL(11,2) | 99999999999.99 | Opcional | 1 |
produto | estoqueMaximo | Estoque máximo do produto | DECIMAL(11,2) | 99999999999.99 | Opcional | 1 |
produto | itensPorCaixa | Quantidade de itens por caixa | DECIMAL(11,2) | Opcional | 1 | |
produto | volumes | Quantidade de volumes do produto | DECIMAL(2) | 0 | Opcional | 1 |
produto | urlVideo | Url do vídeo do produto, utilizado na exportação do produto para lojas virtuais | STRING(100) | Opcional | ||
produto | localizacao | Localização do produto | STRING(50) | Opcional | 1 | |
produto | crossdocking | Quantidade de dias para o processo de distribuição em que a mercadoria recebida é redirecionada ao consumidor final sem uma armazenagem prévia. | DECIMAL(4) | Opcional | 1 | |
produto | garantia | Garantia do produto, deve ser informada em meses. | INTEGER(3) | Opcional | 1 | |
produto | spedTipoItem |
Código do tipo do item no SPED
|
INTEGER(2) | Opcional |
5 |
|
produto | variacoes | Grupo de variações | Opcional | |||
variacoes | variacao | Grupo de variação | Obrigatório | |||
variacao | nome | nome da variação | STRING(120) | Obrigatório | ||
variacao | codigo | código da variação | STRING(60) | Opcional | 6 | |
variacao | vlr_unit | valor unitário da variação | DECIMAL(17,10) | Opcional | 6 | |
variacao | clonarDadosPai | Utilizar informações do produto pai (S para Sim ou N para Não) | STRING(1) | N | Opcional | |
variacao | estoque | estoque da variação | DECIMAL(11,4) | Opcional | 1, 6 | |
variacao | deposito | Depósito ao qual será lançado estoque da variação | Opcional | 1, 6 | ||
variacao | un | Unidade da Variação (somente se o campo clonarDadosPai for N) | Opcional | 1, 6 | ||
deposito | id | Código identificador do depósito | DECIMAL(11) | Opcional | 1 | |
deposito | estoque | Estoque atual da variação no depósito | DECIMAL(11,4) | Opcional | 1 | |
produto | imagens | Lista de imagens do produto | Opcional | 1 | ||
imagens | url | URL da imagem | STRING | Opcional | 1 | |
camposCustomizados |
alias | Alias do campo customizado | STRING | Opcional | 1, 3 | |
produto |
idCategoria | ID da categoria do produto | DECIMAL(11) | Opcional | 1, 4 | |
produto |
estrutura | Composição do produto | Opcional | |||
estrutura |
tipoEstoque | Tipo do estoque | STRING(1) | F - Físico V - Virtual |
Opcional | |
estrutura |
lancarEstoque | Lançar estoque em | STRING(1) | P - Produto C - Componente PC - Produto e Componente |
Opcional | |
estrutura |
componente | Componente da composição | Obrigatório | |||
componente |
nome | Nome do produto | STRING(120) | N | Obrigatório | |
componente |
codigo | Código do produto | STRING(60) | Obrigatório | ||
componente |
quantidade | Quantidade do produto na composição | DECIMAL(11,4) | Obrigatório |
Notas:
- Campos exclusivos do produto, para realizar cadastro de serviços estes campos devem ser omitidos do xml.
- Para inserir multiplas imagens, insira mais de uma tag <url> dentro da tag <imagens>
- Se o grupo de produtos não for encontrado, a inclusão/alteração do produto ocorre normalmente. Porém o produto ficará sem grupo e será retornando "idGrupoProduto":"0" na resposta da API.
- Estrutura com o alias do campo customizado e valor. Utilize o manual da API de campos customizados para consultar o alias específico de cada campo. Obs.: os campos customizados não são enviados em produto variação.
- Para obter o idCategoria é possível acessar a API de categoria, utilizando o manual da API de categorias
- Código do tipo do item no SPED:
Código |
Descrição |
00 |
Mercadoria para Revenda |
01 |
Matéria-Prima |
02 |
Embalagem |
03 |
Produto em Processo |
04 |
Produto Acabado |
05 |
Subproduto |
06 |
Produto Intermediário |
07 |
Material de Uso e Consumo |
08 |
Ativo Imobilizado |
09 |
Serviços |
10 |
Outros insumos |
99 |
Outras |
6. Para atualizar os demais campos de uma variação, por exemplo o campo "crossdocking", utilize a API de produtos pelo código (SKU) do produto passando diretamente a variação e os campos necessários.
Mensagens de erros específicos
Código | Mensagem |
---|---|
40 | Nao foi possivel salvar as informacoes do produto |
41 | O produto nao pode ser cadastrado sem descricao |
42 | Nao foi possivel atualizar o produto - Produto nao encontrado no sistema |
43 | O produto nao foi encontrado |
44 | O produto ja foi excluido anteriormente |
45 | Falha no schema |
46 | Um ou mais depositos nao foram encontrados |
47 | Tipo invalido. Os valores aceitos sao P (produto) e S (servico) |
48 | Situação invalida. Os valores aceitos sao Ativo e Inativo |
49 | Fornecedor invalido |
50 | Nao e possivel inserir variacoes em uma variacao |
51 | Codigo do produto ja esta em uso e nao pode ser utilizado |
54 | Campo idCategoria nao corresponde a nenhuma categoria cadastrada |
Exemplo de XML - Produtos Simples
<?xml version="1.0" encoding="UTF-8"?>
<produto>
<codigo>223435780</codigo>
<descricao>Caneta 001</descricao>
<situacao>Ativo</situacao>
<descricaoCurta>Descrição curta da caneta</descricaoCurta>
<descricaoComplementar>Descrição complementar da caneta</descricaoComplementar>
<un>Pc</un>
<vlr_unit>1.68</vlr_unit>
<preco_custo>1.23</preco_custo>
<peso_bruto>0.2</peso_bruto>
<peso_liq>0.18</peso_liq>
<class_fiscal>1000.01.01</class_fiscal>
<marca>Marca da Caneta</marca>
<origem>0</origem>
<estoque>10</estoque>
<deposito>
<id>123456</id>
<estoque>200</estoque>
</deposito>
<gtin>223435780</gtin>
<gtinEmbalagem>54546</gtinEmbalagem>
<largura>11</largura>
<altura>21</altura>
<profundidade>31</profundidade>
<estoqueMinimo>1.00</estoqueMinimo>
<estoqueMaximo>100.00</estoqueMaximo>
<cest>28.040.00</cest>
<idGrupoProduto>12345</idGrupoProduto>
<condicao>Novo</condicao>
<freteGratis>N</freteGratis>
<linkExterno>https://minhaloja.com.br/meu-produto</linkExterno>
<observacoes>Observações do meu produtos</observacoes>
<producao>P</producao>
<dataValidade>20/11/2019</dataValidade>
<descricaoFornecedor>Descrição do fornecedor</descricaoFornecedor>
<idFabricante>0</idFabricante>
<codigoFabricante>123</codigoFabricante>
<unidadeMedida>Centímetros</unidadeMedida>
<garantia>4</garantia>
<itensPorCaixa>2</itensPorCaixa>
<volumes>2</volumes>
<urlVideo>https://www.youtube.com/watch?v=zKKL-SgC5lY</urlVideo>
<imagens>
<url>https://bling.com.br/bling.jpg</url>
<url>https://bling.com.br/bling2.jpg</url>
</imagens>
<camposCustomizados>
<memoriaRam>16</memoriaRam>
<eDualSim>false</eDualSim>
</camposCustomizados>
<idCategoria>1234</idCategoria>
</produto>
Exemplo de XML - Produtos com variação
<?xml version="1.0" encoding="UTF-8"?>
<produto>
<codigo>223435780</codigo>
<descricao>Caneta 001</descricao>
<descricaoCurta>Descrição curta da caneta</descricaoCurta>
<descricaoComplementar>Descrição complementar da caneta</descricaoComplementar>
<un>Pc</un>
<vlr_unit>1.68</vlr_unit>
<preco_custo>1.23</preco_custo>
<peso_bruto>0.2</peso_bruto>
<peso_liq>0.18</peso_liq>
<class_fiscal>1000.01.01</class_fiscal>
<marca>Marca da Caneta</marca>
<origem>0</origem>
<gtin>223435780</gtin>
<gtinEmbalagem>54546</gtinEmbalagem>
<largura>11</largura>
<altura>21</altura>
<profundidade>31</profundidade>
<estoqueMinimo>1.00</estoqueMinimo>
<estoqueMaximo>100.00</estoqueMaximo>
<class_fiscal>1111.11.11</class_fiscal>
<cest>28.040.00</cest>
<idGrupoProduto>12345</idGrupoProduto>
<condicao>Usado</condicao>
<freteGratis>S</freteGratis>
<linkExterno>https://minhaloja.com.br/meu-produto</linkExterno>
<observacoes>Observações do meu produto</observacoes>
<producao>P</producao>
<dataValidade>20/11/2019</dataValidade>
<descricaoFornecedor>Descrição do fornecedor</descricaoFornecedor>
<idFabricante>0</idFabricante>
<codigoFabricante>123</codigoFabricante>
<unidadeMedida>Centímetros</unidadeMedida>
<crossdocking>2</crossdocking>
<garantia>4</garantia>
<itensPorCaixa>2</itensPorCaixa>
<volumes>2</volumes>
<urlVideo>https://www.youtube.com/watch?v=zKKL-SgC5lY</urlVideo>
<idCategoria>1234</idCategoria>
<variacoes>
<variacao>
<nome>Cor:Preto</nome>
<codigo>223435780-Preto</codigo>
<clonarDadosPai>S</clonarDadosPai>
<deposito>
<id>123456</id>
<estoque>200</estoque>
</deposito>
</variacao>
<variacao>
<nome>Cor:Branco</nome>
<codigo>223435780-Branco</codigo>
<vlr_unit>1.50</vlr_unit>
<deposito>
<id>654321</id>
<estoque>120</estoque>
</deposito>
</variacao>
</variacoes>
<imagens>
<url>https://www.bling.com.br/bling.jpg</url>
<url>https://bling.com.br/bling2.jpg</url>
</imagens>
</produto>
DICASe deseja informar imagens diferentes para cada variação, insira a tag <imagens>/imagens> dentro da tag da variação, ou seja, dentro de <variacao></variacao> |
Exemplo de XML - Produtos com composição
<?xml version="1.0" encoding="UTF-8"?>
<produto>
<codigo>456489798</codigo>
<descricao>Kit 001</descricao>
<descricaoCurta>Kit caneca e copo</descricaoCurta>
<descricaoComplementar>Descrição complementar</descricaoComplementar>
<un>Pc</un>
<vlr_unit>1.68</vlr_unit>
<preco_custo>1.23</preco_custo>
<peso_bruto>0.2</peso_bruto>
<peso_liq>0.18</peso_liq>
<class_fiscal>1000.01.01</class_fiscal>
<marca>Marca da Caneta</marca>
<origem>0</origem>
<gtin>223435780</gtin>
<gtinEmbalagem>54546</gtinEmbalagem>
<largura>11</largura>
<altura>21</altura>
<profundidade>31</profundidade>
<estoqueMinimo>1.00</estoqueMinimo>
<estoqueMaximo>100.00</estoqueMaximo>
<class_fiscal>1111.11.11</class_fiscal>
<cest>28.040.00</cest>
<idGrupoProduto>12345</idGrupoProduto>
<condicao>Usado</condicao>
<freteGratis>S</freteGratis>
<linkExterno>https://minhaloja.com.br/meu-produto</linkExterno>
<observacoes>Observações do meu produto</observacoes>
<producao>P</producao>
<dataValidade>20/11/2019</dataValidade>
<descricaoFornecedor>Descrição do fornecedor</descricaoFornecedor>
<idFabricante>0</idFabricante>
<codigoFabricante>123</codigoFabricante>
<unidadeMedida>Centímetros</unidadeMedida>
<crossdocking>2</crossdocking>
<garantia>4</garantia>
<itensPorCaixa>2</itensPorCaixa>
<volumes>2</volumes>
<urlVideo>https://www.youtube.com/watch?v=zKKL-SgC5lY</urlVideo>
<idCategoria>1234</idCategoria>
<imagens>
<url>https://www.bling.com.br/bling.jpg</url>
</imagens>
<estrutura>
<tipoEstoque>F</tipoEstoque>
<lancarEstoque>P</lancarEstoque>
<componente>
<nome>Caneca Vermelha</nome>
<codigo>caneca123</codigo>
<quantidade>2</quantidade>
</componente>
<componente>
<nome>Copo 300 ml</nome>
<codigo>copo123</codigo>
<quantidade>2</quantidade>
</componente>
</estrutura>
</produto>
Exemplo de XML - Serviço
<?xml version="1.0" encoding="UTF-8"?>
<produto>
<codigo>123456</codigo>
<tipo>S</tipo>
<situacao>Ativo</situacao>
<descricao>Formatação PC</descricao>
<descricaoCurta>Descrição curta do serviço</descricaoCurta>
<descricaoComplementar>Descrição complementar do serviço</descricaoComplementar>
<un>UN</un>
<idGrupoProduto>1675</idGrupoProduto>
<linkExterno>https://site.com.br/servico</linkExterno>
<observacoes>Observações do serviço</observacoes>
<vlr_unit>85.00</vlr_unit>
<preco_custo>50.00</preco_custo>
<urlVideo>https://www.youtube.com/watch?v=zKKL-SgC5lY</urlVideo>
</produto>
Retorno
Em caso de sucesso, retornará o produto inserido, no mesmo modelo do exemplo a seguir. Caso contrário, retornará um erro.
A resposta será no formato especificado na URL (XML ou JSON).
Exemplo de retorno
{ "retorno": { "produtos": [ { "produto": { "codigo": "CAD00011", "tipo": "P", "situacao": "Ativo", "descricao": "CADEIRA XYZ F5", "unidade": "", "preco": "100.0000000000", "precoCusto": "85.0000000000", "pesoLiq": "1.000", "pesoBruto": "1.000", "gtin": "", "gtinEmbalagem": "", "descricaoComplementar": "CADEIRA", "larguraProduto": "10", "alturaProduto": "89", "profundidadeProduto": "67", "estoqueMinimo": "1", "estoqueMaximo": "100", "class_fiscal": "1111.11.11", "cest": "28.040.00", "idGrupoProduto":"12345", "condicao":"Não Especificado", "freteGratis":"N", "linkExterno":"https://minhaloja.com.br/cadeira-xyz-f5", "observacoes":"Observações da CADEIRA XYZ F5", "producao":"P", "unidadeMedida":"Centímetros", "itensPorCaixa": 2, "volumes": 2, "urlVideo": "https://www.youtube.com/watch?v=zKKL-SgC5lY", "localizacao":"Prateleira B", "crossdocking": 2, "marca": "Marca da Caneta", "garantia": 4, "condicao": "Novo", "freteGratis": "S", "producao": "P", "dataValidade": "20-11-2019", "spedTipoItem": "00", "descricaoFornecedor": "Descrição do fornecedor", "codigoFabricante": "123", "idCategoria": "1234" } } ] } }