A API V3 JÁ ESTÁ DISPONÍVEL
As integrações API v2 que já estão configuradas, seguirão funcionando temporariamente. |
Insere um pedido
Insere um pedido no sistema.
curl |
curl -X POST "https://bling.com.br/Api/v2/pedido/json/" |
PHP |
$url = 'https://bling.com.br/Api/v2/pedido/json/'; $xml = '...'; $posts = array ( "apikey" => "{apikey}", "xml" => rawurlencode($xml) ); $retorno = executeSendOrder($url, $posts); echo $retorno; function executeSendOrder($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 ExecuteSendOrder() { HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://bling.com.br/Api/v2/pedido/"); ASCIIEncoding encoding = new ASCIIEncoding(); string postData = "apikey={apiKey}&xml={xml_do_pedido}"; 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); } |
Parâmetro | Descrição | Tipo |
apikey |
apikey gerada no sistema | string |
xml |
xml contendo o pedido | string |
gerarnfe |
parâmetro opcional para gerar NFe a partir do pedido | string (true/false) |
Caso não queira gerar NFe a partir do pedido, o parâmetro gerarnfe
não precisa ser inserido.
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 | pedido | Obrigatório | ||||
pedido | data | Data do pedido | DATE | 99/99/9999 | Opcional | 1 |
pedido | data_saida | Data de saída do pedido | DATETIME | 99/99/9999 | Opcional | |
pedido | data_prevista | Data prevista do pedido | DATE | 99/99/9999 | Opcional | |
pedido | numero | Número do pedido | STRING(10) | 9 | Opcional | |
pedido | numero_loja | Número do pedido na loja virtual | STRING(50) | 9 | Opcional | |
pedido | loja | Número identificador da loja. | INTEGER(10) | 9 | Opcional | 4 |
pedido | nat_operacao | Nome da natureza de operação cadastrada | STRING(60) | Venda de mercadorias | Opcional | |
pedido | vendedor | Nome o vendedor cadastrado no Bling | STRING | Opcional | ||
pedido | cliente | Obrigatório | ||||
cliente | id | Id do contato | INTEGER(20) | Opcional | ||
cliente | nome | Nome do Consumidor | STRING(80) | Obrigatório | ||
cliente | tipoPessoa | Pessoa Física/Jurídica (Jurídica ) | STRING(1) | J ou F | Opcional | |
cliente | cpf_cnpj | CNPJ do Consumidor | STRING(18) | 99999999999999 | Opcional | |
cliente | ie | Inscrição Estadual do Consumidor | STRING(18) | 9999999999 | Opcional | 2 |
cliente | rg | RG do Consumidor | STRING(18) | 9999999999 | Opcional | 2 |
cliente | contribuinte | 1 - Contribuinte do ICMS, 2 - Contribuinte isento do ICMS ou 9 - Não contribuinte | STRING(1) | 9 | Opcional | |
cliente | endereco | Endereço do Consumidor | STRING(50) | Opcional | ||
cliente | numero | Número da casa do Consumidor | STRING(10) | Opcional | ||
cliente | complemento | Complemento do endereço do Consumidor | STRING(100) | Opcional | ||
cliente | bairro | Bairro do Consumidor | STRING(40) | Opcional | ||
cliente | cep | CEP do Consumidor | STRING(10) | 99.999-999 | Opcional | |
cliente | cidade | Cidade do Consumidor | STRING(30) | Opcional | ||
cliente | uf | Sigla do estado do Consumidor | STRING(2) | Opcional | ||
cliente | fone | Telefone do Consumidor | STRING(40) | Opcional | ||
cliente | celular | Celular do Consumidor | STRING(40) | Opcional | ||
cliente | E-mail do Consumidor | STRING(60) | Opcional | |||
pedido | transporte | Opcional | ||||
transporte | transportadora | Nome da transportadora | STRING(100) | Opcional | ||
transporte | tipo_frete | Frete por conta do Destinatário/Remetente | STRING(1) | Opcional | 10 | |
transporte | servico_correios | Nome do Serviço dos correios utilizado | STRING(150) | Opcional | 6 | |
transporte | codigo_cotacao | Código da cotação obtida na loja virtual | STRING(20) | Opcional | ||
transporte | peso_bruto | Peso bruto do volume | DECIMAL(11,3) | Opcional | ||
transporte | qtde_volumes | Quantidade de Volumes do pedido | INTEGER(10) | Opcional | ||
transporte | dados_etiqueta | Grupo com endereço alternativo para a etiqueta de envio | Opcional |
|
||
dados_etiqueta | nome | Nome do destinatário | STRING(120) | Opcional | ||
dados_etiqueta | endereco | Endereço do destinatário | STRING(50) | Opcional | ||
dados_etiqueta | numero | Número do destinatário | STRING(10) | Opcional | ||
dados_etiqueta | complemento | Complemento do destinatário | STRING(100) | Opcional | ||
dados_etiqueta | municipio | Nome do município do destinatário | STRING(30) | Opcional | ||
dados_etiqueta | uf | Sigla da UF do destinatário | STRING(2) | Opcional | ||
dados_etiqueta | cep | CEP do destinatário | STRING(8) | 99.999-999 | Opcional | |
dados_etiqueta | bairro | Bairro do destinatário | STRING(30) | Opcional | ||
transporte | volumes | Grupo de volumes vinculado ao pedido | Opcional | |||
volumes | volume | Volume vinculado ao pedido | Opcional | |||
volume | servico | Alías do serviço de entrega vinculado ao volume | STRING(150) | Obrigatório | ||
volume | codigoRastreamento | Código de rastreamento vinculado ao volume | STRING(30) | Opcional | ||
pedido | itens | Opcional | ||||
itens | item | Opcional | ||||
item | codigo | Código do Item | STRING(60) | Opcional | 5 | |
item | descricao | Nome do item | STRING(120) | Obrigatório | ||
item | un | Tipo de unidade do item | STRING(6) | pc, un, cx | Opcional | |
item | qtde | Quantidade do item no pedido | DECIMAL(11,4) | Obrigatório | ||
item | vlr_unit | Valor unitário do item | DECIMAL(17,10) | Obrigatório |
|
|
item | vlr_desconto | Percentual de desconto do item | DECIMAL(11,2) | Opcional |
|
|
pedido | idFormaPagamento | Id da forma de pagamento cadastrada no sistema | INTEGER(10) | Opcional | 9 | |
pedido | parcelas | Opcional | ||||
parcelas | parcela | Opcional | ||||
parcela | dias | Dias de prazo de pagamento da parcela | INTEGER(10) | Opcional | 3 | |
parcela | data | Data do vencimento da parcela | DATETIME | 99/99/9999 | Opcional | 3 |
parcela | vlr | Valor da parcela | DECIMAL(11,2) | Obrigatório | ||
parcela | obs | Observação da parcela | STRING(150) | Opcional | ||
parcela | forma_pagamento | Opcional | 7 | |||
forma_pagamento | id | Id da forma de pagamento da parcela | INTEGER(10) | Opcional | 7 | |
pedido | vlr_frete | Valor do Frete | DECIMAL(11,2) | Opcional | ||
pedido | vlr_desconto | Valor do Desconto no pedido | STRING(20) | Opcional | ||
pedido | obs | Observações do Pedido | STRING | Opcional | ||
pedido | obs_internas | Observações internas do Pedido | STRING | Opcional | ||
pedido | numeroOrdemCompra | Numero da Ordem de Compra | STRING(30) | Opcional | ||
pedido |
outrasDespesas | Outras despesas da venda | DECIMAL(11,2) | Opcional | ||
pedido |
intermediador | Opcional | ||||
intermediador |
cnpj | CNPJ do intermediador | STRING(14) | Opcional | ||
intermediador |
nomeUsuario | Nome usuário ou identificação do perfil do vendedor no site do intermediador | STRING(60) | Opcional | ||
intermediador |
cnpjInstituicaoPagamento | CNPJ da instituição de pagamento | STRING(14) | Opcional |
Se for realizado o POST do pedido sem gerar a NFe, caso ela seja gerada de forma manual, o sistema irá gerar a nota baseado nos padrões do sistema. Para que a tag nat_operacao
funcione, é necessário dar o comando de geração de NFe como true.
Notas:
- O campo data é opcional, caso não seja preenchido a data da inclusão será informada. Este campo é utilizado como base para cálculo do vencimento quando na parcela é informado o número de dias.
- Caso seja pessoa jurídica é obrigatório informar a Inscrição Estadual.
- Na parcela deve ser informada somente a data de vencimento ou somente o número de dias.
- Caso deseje vincular os pedidos a uma integração multiloja, deve-se informar o identificador da loja.
- O campo código é opcional somente quando a opção de vínculo seja pelo campo descrição.
- O campo está depreciado e será removido em atualizações futuras. Para substituí-lo, deve-se utilizar a estrutura de múltiplos volumes (campo
volumes
na seçãotransporte
). - Não informando a forma de pagamento, será utilizada a forma padrão.
- Caso não informado o vínculo será realizado pelo campo
cpf_cnpj
. - IdFormaPagamento, se informado vai gerar as parcelas automaticamente respeitando as condições cadastradas na forma de pagamento, EX "5x ou 30,60,90". Para lançar as parcelas manualmente este campo não tem que estar preenchido, pois ignorará as parcelas inseridas.
-
No campo Tipo Frete, podemos salvar com os seguintes valores com letra maiúscula para os caracteres.
Valor Descrição R 0 - Contratação do Frete por conta do Remetente (CIF) D 1 - Contratação do Frete por conta do Destinatário (FOB) T 2 - Contratação do Frete por conta de Terceiros 3 3 - Transporte Próprio por conta do Remetente 4 4 - Transporte Próprio por conta do Destinatário S 9 - Sem Ocorrência de Transporte
Vínculo do produto com o cadastro do sistema
O produto será vinculado com um produto previamente cadastrado no sistema caso o campo descricao ou codigo sejam idênticos ao do cadastro.
A escolha de qual campo será utilizado para realizar a comparação é definida acessando Preferências > Parâmetros da empresa > Configurações de Lojas Virtuais e alterando a opção Na importação através da API, buscar produtos por código ou descrição.
Mensagens de erros específicos
Código | Mensagem |
---|---|
29 | Produto de codigo ([codigo_do_produto]) possui o formato com variacoes |
30 | Pedido ja cadastrado no sistema - Um pedido com o mesmo hash ja encontra-se cadastrado |
31 | Nao ha itens informados no pedido |
32 | Informe a data ou o vencimento da parcela |
33 | Pedido invalido |
34 | Codigo do produto [descricao_do_produto] deve ser informado |
35 | Forma de pagamento da parcela numero [numero_parcela] nao foi encontrada |
36 | Situacao invalida. |
37 | Estoque insuficiente para gerar nfe |
38 | Loja invalida |
39 | Número do pedido na loja já existente (nº do pedido) |
Exemplo de XML
<?xml version="1.0" encoding="UTF-8"?>
<pedido>
<cliente>
<nome>Organisys Software</nome>
<tipoPessoa>J</tipoPessoa>
<endereco>Rua Visconde de São Gabriel</endereco>
<cpf_cnpj>00000000000000</cpf_cnpj>
<ie>3067663000</ie>
<numero>392</numero>
<complemento>Sala 54</complemento>
<bairro>Cidade Alta</bairro>
<cep>95.700-000</cep>
<cidade>Bento Gonçalves</cidade>
<uf>RS</uf>
<fone>5481153376</fone>
<email>teste@teste.com.br</email>
</cliente>
<transporte>
<transportadora>Transportadora XYZ</transportadora>
<tipo_frete>R</tipo_frete>
<servico_correios>SEDEX - CONTRATO</servico_correios>
<dados_etiqueta>
<nome>Endereço de entrega</nome>
<endereco>Rua Visconde de São Gabriel</endereco>
<numero>392</numero>
<complemento>Sala 59</complemento>
<municipio>Bento Gonçalves</municipio>
<uf>RS</uf>
<cep>95.700-000</cep>
<bairro>Cidade Alta</bairro>
</dados_etiqueta>
<volumes>
<volume>
<servico>SEDEX - CONTRATO</servico>
<codigoRastreamento></codigoRastreamento>
</volume>
<volume>
<servico>PAC - CONTRATO</servico>
<codigoRastreamento></codigoRastreamento>
</volume>
</volumes>
</transporte>
<itens>
<item>
<codigo>001</codigo>
<descricao>Caneta 001</descricao>
<un>Pç</un>
<qtde>10</qtde>
<vlr_unit>1.68</vlr_unit>
</item>
<item>
<codigo>002</codigo>
<descricao>Caderno 002</descricao>
<un>Un</un>
<qtde>3</qtde>
<vlr_unit>3.75</vlr_unit>
</item>
<item>
<codigo>003</codigo>
<descricao>Teclado 003</descricao>
<un>Cx</un>
<qtde>7</qtde>
<vlr_unit>18.65</vlr_unit>
</item>
</itens>
<parcelas>
<parcela>
<data>01/09/2009</data>
<vlr>100</vlr>
<obs>Teste obs 1</obs>
</parcela>
<parcela>
<data>06/09/2009</data>
<vlr>50</vlr>
<obs></obs>
</parcela>
<parcela>
<data>11/09/2009</data>
<vlr>50</vlr>
<obs>Teste obs 3</obs>
</parcela>
</parcelas>
<vlr_frete>15</vlr_frete>
<vlr_desconto>10</vlr_desconto>
<obs>Testando o campo observações do pedido</obs>
<obs_internas>Testando o campo observações internas do pedido</obs_internas>
</pedido>
Exemplo de retorno
{ "retorno": { "pedidos": [ { "pedido": { "numero": "82", "idPedido": 52389274, "codigos_rastreamento": { "codigo_rastreamento": "SX052413665BR" }, "volumes": [ { "volume": { "servico": "SEDEX - CONTRATO", "codigoRastreamento": "SG016634880BR" } }, { "volume": { "servico": "PAC CONTRATO AGENCIA", "codigoRastreamento": "EC314697823BR" } } ] } } ] } }
Retorno utilizando parâmetro "gerarnfe"
Ao utilizar o parâmetro opcional para gerar NFe, o retorno será:
Exemplo de retorno com sucesso ao gerar NFe
{ "retorno": { "pedidos": [ { "pedido": { "numero": "82", "idPedido": 52389274, "codigos_rastreamento": { "codigo_rastreamento": SX052413665BR }, "volumes": [ { "volume": { "servico": "SEDEX - CONTRATO", "codigoRastreamento": "SG016634880BR" } }, { "volume": { "servico": "PAC CONTRATO AGENCIA", "codigoRastreamento": "EC314697823BR" } } ] }, "notaFiscal": { "numero": "000001", "serie": "1", "idNotaFiscal": 2077102 } } ] } }
Também é possível que ocorra erro ao tentar gerar a NFe, pois o saldo de algum item pode ser insuficiente, conforme parâmetro do sistema "Permite geração de NF a partir da venda e ordem de serviço com estoque negativo".
Exemplo de retorno com error ao gerar NFe
{ "retorno": { "pedidos": [ { "pedido": { "numero": "82", "idPedido": 52389274, "codigos_rastreamento": { "codigo_rastreamento": SX052413665BR }, "volumes": [ { "volume": { "servico": "SEDEX - CONTRATO", "codigoRastreamento": "SG016634880BR" } }, { "volume": { "servico": "PAC CONTRATO AGENCIA", "codigoRastreamento": "EC314697823BR" } } ] }, "notaFiscal": { "erro": "Estoque insuficiente para gerar nfe" } } ] } }