Manual API REST
Esse manual técnico tem como objetivo ajudar desenvolvedores/programadores na integração com a API Rest
ecomDC. Este manual conta também com exemplos práticos e em português para que a integração seja simples e completa.
O que é a ecomDC?
ecomDC é uma API de integração REST que realiza comunicações seguras com lojas virtuais credenciadas a esta integração através de objetos JSON
, que tenham ID e Token válidos.
A REST API pode ter seus recursos acessados e utilizados por qualquer linguagem de programação que tenha recursos Web de comunicação HTTP e manipulação de JSON.
Como posso saber se estou executando as requisições de forma correta?
A ecomDC possui um simulador de requisições, e por meio dele, pode ser feito os testes e comparações de request. Para acessar basta clicar aqui
Operações
Como posso saber se estou executando as requisições de forma correta?
A ecomDC possui um simulador de requisições, e por meio dele, pode ser feito os testes e comparações de request. Para acessar basta clicar aqui
Quais são as operações que a API ecomDC pode realizar?
Os endpoints
correspondem a cada operação permitida, abaixo a relação das operações disponíveis na API:
Tipo | Metódo | URL |
---|---|---|
Produtos | GET | https://www.meudatacenter.com/api/v1/produtos |
Produto | GET | https://www.meudatacenter.com/api/v1/produto/{COD} |
Produto | POST | https://www.meudatacenter.com/api/v1/produto |
Produto | PUT | https://www.meudatacenter.com/api/v1/produto/{COD} |
Imagem | POST | https://www.meudatacenter.com/api/v1/imagem |
Preço | GET | https://www.meudatacenter.com/api/v1/produto/{COD}/preco |
Preço | PUT | https://www.meudatacenter.com/api/v1/produto/{COD}/preco |
Preço | GET | https://www.meudatacenter.com/api/v1/item/{REFERENCIA}/precoextra |
Preço | PUT | https://www.meudatacenter.com/api/v1/item/REF/precoextra |
Estoque | GET | https://www.meudatacenter.com/api/v1/item/{REFERENCIA}/estoque |
Estoque | PUT | https://www.meudatacenter.com/api/v1/item/{REFERENCIA}/estoque |
Pedidos | GET | https://www.meudatacenter.com/api/v1/pedidos |
Pedido | GET | https://www.meudatacenter.com/api/v1/pedido/{ID} |
Pedido | PUT | https://www.meudatacenter.com/api/v1/pedido/{ID}/pago |
Pedido | PUT | https://www.meudatacenter.com/api/v1/pedido/{ID}/separacao |
Pedido | PUT | https://www.meudatacenter.com/api/v1/pedido/{ID}/entrega |
Pedido | PUT | https://www.meudatacenter.com/api/v1/pedido/{ID}/concluido |
Pedido | PUT | https://www.meudatacenter.com/api/v1/pedido/{ID}/cancelado |
Pedido | PUT | https://www.meudatacenter.com/api/v1/pedido/{ID}/nfe |
Autenticação
Somente usuários autenticados terão acesso a essa REST API. A Autenticação se dá através de um ID e Token.
Como obter meu ID e Token?
No painel de controle da loja virtual credenciada a API ecomDC, basta ativar a integração API e obter o ID
e o Token
desta integração. Com esses dados já é possível acessar os recursos desta API
Autorização
//Exemplo do GET PRODUTOS
$url = "https://www.meudatacenter.com/api/v1/produtos?page=1";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); // Código de retorno.
curl_close($curl);
$retornoJSON = json_decode($response);
var_dump($retornoJSON);
Para utilizar os recursos da API é necessário enviar em todas as requisições o ID
e Token
no cabeçalho da requisição HTTP. Os parametros a serem passados são: x-ID:Seu ID
e x-Token:Seu Token
além disso é necessário enviar o Content-Type neste formato Content-Type: application/json
A loja virtual no qual você irá utilizar, precisa está operando com o HTTPS:// (SSL instalado). Caso a loja virtual ainda não esteja com o SSL, a comunicação com a API não ocorrerá. Geralmente o SSL é instalado em uma loja virtual no período de até 24 horas.
Abaixo, veja um exemplo de uma comunicação autorizada na linguagem PHP no endpoint GET produtos
utilizando-se do Curl:
Veja o exemplo abaixo de Autorização utilizando o Postman:
GET /api/v1/produtos HTTP/1.1
Host: www.meudatacenter.com
x-ID: 9898
x-Token: 77O585194T334540R429730I71...
Content-Type: application/json
Cache-Control: no-cache
Postman-Token: 0d5cb339-7fa1-bcb8-4796-53026a8b28ed
Limites
A partir do dia 01/01/2024 a API adotará um limite de 30 requisições para todas requisições do tipo "POST" e "PUT".
E as requisições do tipo GET terão um limite de 60 requisições por minuto.
- Requisiões do tipo GET: 60/minuto
- Requisiões do tipo POST: 30/minuto
- Requisiões do tipo PUT: 30/minuto
Caso o limite seja superado, o retorno será 429 - Too Many Requests.
Nas requisições que possuem envio de URL imagens para importação, o sistema trabalhará com um timeout de 5 segundos por URL.
PRODUTOS
As operações em produtos
permitem: consultas, inserção e atualizações pontuais de preço e estoque.
A estrutura de um produto é a sequinte:
- - Produto (Código, Nome, preço, etc...)
- - - - - - - Modelos (Cor e Imagens. Exemplo: Azul, Amarelo, Vermelho...)
- - - - - - - - - - - - Opções (Referencia, Estoque, SKU. Exemplos: P, M, G, GG...)
Desta forma, observa-se que um produto pode ter vários modelos, e cada modelo pode ter vários itens. Confira abaixo alguns exemplos dos endpoints:
GET PRODUTOS
//Exemplo do GET PRODUTOS
$url = "https://www.meudatacenter.com/api/v1/produtos?page=1";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); // Código de retorno.
curl_close($curl);
$retornoJSON = json_decode($response);
var_dump($retornoJSON);
O endpoint usado na API para realizar a operação de consultar todos os produtos é a "produtos"
. Veja abaixo um exemplo do código usando o cURL PHP
Paginação do Método GET PRODUTOS
O método GET PRODUTOS possui o filtro de paginação ?page=
que deve ser passado na URL da chamada.
Caso o filtro ?page=
não seja informado, será considerada a página 1.
Observe também que no final da requisição GET PRODUTOS
é retornado pela API em "totais" o total de produtos, o total de páginas e a página atual.
Exemplo de Uso: https://www.meudatacenter.com/api/v1/produtos?page=1
Obtenção de Campanhas de Atacado Relacionadas aos Produtos
O método GET PRODUTOS possui o filtro que possibilita a exibição de campanhas de atacado relacionadas aos produtos, precos_atacado=true
que deve ser passado na URL da chamada.
Caso o filtro não seja informado, as campanhas de atacado não serão exibidas.
Exemplo de Uso:
https://www.meudatacenter.com/api/v1/produto?precos_atacado=true
Se tudo ocorreu bem, será retornado o codigo 200
no header e no body o seguinte Payload no formato json:
{
"produtos": [
{
"nome": "NOME DO PRODUTO",
"codigo": "1144AXXXXAVD4",
"descricao": "A bicicleta Caloi Andes proporciona conforto...", "departamento": "Esportes>Bicicletas",
"departamento": "Esportes>Bicicletas",
"fabricante": "Caloi",
"preco": 720.00,
"custo": 610.00,
"comprimento": 1.00,
"largura": 0.00,
"altura": 1.00,
"peso": 13.000,
"cubagem": 0.00,
"garantia": "90 dias",
"atributos_produto": "Marchas:21; Aro:22; Freios: V-BREAK",
"videos": "https://www.youtube.com/watch?v=nfv7C1Qn_So; https://www.youtube.com/watch?v=BrZBiqK0p9E",
"localizacao_estoque": "Corretor 10",
"formato_visualizacao_modelos": "1",
"modelos": [
{
"nome": "Amarela",
"crossdocking": 10,
"imagens": "https://www.exemplo.com.br/1.jpg,https://www.exemplo.com.br/2.jpg",
"imagens_retangulares": "https://www.exemplo.com.br/3.jpg,https://www.exemplo.com.br/4.jpg,https://www.exemplo.com.br/5.jpg",
"status": 0,
"formato_visualizacao_opcoes": "2",
"url_produto": "https://www.exemplo.com.br/produto/p",
"atributos_modelo": "Cor:Amarela; Entrega:Imediata",
"itens": [
{
"sku": "21891781",
"nome_opcao": "P",
"referencia": "11482378",
"estoque": 10,
"ean": "7891473021257"
},
{
"sku": "21891782",
"nome_opcao": "M",
"referencia": "11482379",
"estoque": 10,
"ean": ""
}
]
}
]
}
],
"totais": {
"totalProdutos": "1",
"totalPaginas": "1",
"paginaAtual": "1"
}
}
GET PRODUTO/CODIGO
$url = "https://www.meudatacenter.com/api/v1/produto/777";
//-OU USANDO O FILTRO REFERENCIA-
// $url = "https://www.meudatacenter.com/api/v1/produto?referencia=SKU12000";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); // Código de retorno.
curl_close($curl);
$retornoJSON = json_decode($response);
Para consultar apenas um produto com o seu código, o endpoint usado na API para realizar essa operação é a: "produto/{CODIGO}"
. Outra opção de consulta é utilizando o filtro referencia, vide abaixo.
O código do produto (CODIGO) é o mesmo que você utilizou no POST produto, caso você não tenha cadastrado o produto via POST, é possível obter os códigos dos produtos já existentes através do GET PRODUTOS.
Utilizando o filtro referencia no método GET PRODUTO
Você também poderá consultar um produto e suas variações através do filtro referencia=
que pode ser usado na URL da chamada.
Esse filtro irá buscar o produto que possui a referencia
entre suas opções.
Exemplo de Uso: https://www.meudatacenter.com/api/v1/produto?referencia=SKU12000
Essa consulta irá retornar toda a estrutura do produto que possui essa referencia
Obtenção de Campanhas de Atacado Relacionadas a um Produto
O método GET PRODUTO possui o filtro que possibilita a exibição de campanhas de atacado relacionadas a um produto, precos_atacado=true
que deve ser passado na URL da chamada.
Caso o filtro não seja informado, as campanhas de atacado não serão exibidas.
Exemplo de Uso:
https://www.meudatacenter.com/api/v1/produto/{codigo}?precos_atacado=true
Se tudo ocorreu bem, será retornado um codigo 200
no header e no body o seguinte Payload no formato json:
{
"produto": {
"nome": "Produto de Teste 777",
"codigo": "777",
"descricao": "A bicicleta Caloi Andes proporciona conforto...",
"departamento": "Esportes>Bicicletas",
"fabricante": "Caloi",
"preco": 720.00,
"custo": 610.00,
"comprimento": 1.00,
"largura": 0.00,
"altura": 1.00,
"peso": 13.000,
"cubagem": 0.00,
"garantia": 90 dias,
"atributos_produto": "Marchas:21; Aro:22; Freios: V-BREAK",
"videos": "https://www.youtube.com/watch?v=nfv7C1Qn_So; https://www.youtube.com/watch?v=BrZBiqK0p9E",
"localizacao_estoque": "Corretor 10",
"formato_visualizacao_modelos": "1",
"modelos": [
{
"nome": "Amarela",
"crossdocking": 10,
"imagens": "https://www.google.com.b/arquivos/PRODUTOS/631156285843478112/631156285843478112_G_1.jpg,https://google.com/arquivos/PRODUTOS/9521562858436591238/9521562858436591238_G_2.jpg",
"imagens_retangulares": "https://www.exemplo.com.br/3.jpg,https://www.exemplo.com.br/4.jpg,https://www.exemplo.com.br/5.jpg",
"status": 0,
"formato_visualizacao_opcoes": "2",
"url_produto": "https://www.exemplo.com.br/produto/p",
"atributos_modelo": "Cor:Amarela; Entrega:Imediata",
"itens": [
{
"sku": "21891781",
"nome_opcao": "P",
"referencia": "11482378",
"estoque": 10,
"ean": "7891473021257"
},
{
"sku": "21891782",
"nome_opcao": "M",
"referencia": "11482379",
"estoque": 10,
"ean": "891473021257"
},
]
}
]
}
}
Repare que na operação GET PRODUTOS são retornados os produtos no nó "produtos" e já na operação GET PRODUTO/CODIGO o produto é retornado no nó "produto".
Importante! Uma dúvida comum entre os programadores é a diferença que existe entre a estrutura do JSON de produtos no "GET PRODUTO" e no "PUT/POST PRODUTO". A diferença existe, principalmente na tipagem dos campos de valores, por exemplo, ao enviar deve ser em double, mas no "GET" o retorno é string. Outra diferença é no "nó" opções, no POST/PUT deve ser informado "itens" já ao receber no "GET" ele vem como "opcoes". Então é importante informa-los sobre essa diferenciação que pode ocorrer.
POST PRODUTO
Operação que permite você inserir um novo produto. O endpoint usado na API para realizar essa operação é a: "POST produto"
. Veja abaixo um exemplo do código usando o cURL PHP
$jso = array(
'nome' => 'Produto de Teste 8899',
'codigo' => '8899',
'descricao' => 'A bicicleta Caloi Andes proporciona conforto...',
'departamento' => 'Esportes>Bicicletas',
'fabricante' => 'Caloi',
'preco' => 720.00,
'custo' => 610.00,
'comprimento' => 1.62,
'largura' => 0.20,
'altura' => 1.20,
'peso' => 13.400,
'cubagem' => 0,
'garantia' => '90 dias',
"atributos_produto": "Marchas:21; Aro:22; Freios: V-BREAK",
"videos": "https://www.youtube.com/watch?v=nfv7C1Qn_So; https://www.youtube.com/watch?v=BrZBiqK0p9E",
"localizacao_estoque": "Corretor 2, Palete 10",
"formato_visualizacao_modelos": "1",
'modelos' => array(
array(
'nome' => 'Amarela',
'crossdocking' => 10,
'imagens' => 'https://www.personal.psu.edu/jul229/mini.jpg,https://www.personal.psu.edu/jul229/rv1.jpg',
'imagens_retangulares' => 'http://www.exemplo.com.br/3.jpg,http://www.exemplo.com.br/4.jpg,http://www.exemplo.com.br/5.jpg',
'status' => 1,
'formato_visualizacao_opcoes':'2',
"atributos_modelo": "Cor:Amarela; Entrega:Imediata",
'itens' =>array(
array(
'nome_opcao' => 'P',
'referencia' => "11482378",
'estoque' => 12,
'ean' => '7891473021257'
)
)
)
)
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/produto";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POST, 1); // Informando que é POST
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Envio do JSON
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); // Código de retorno header
curl_close($curl);
$retornoJSON = json_decode($response);
Caso a operação seja bem sucedida o retorno será um código 201
, repare que o retorno de sucesso para operações de consultas (GET) é o 200 e para operações de POST e PUT o retorno é o 201.
Uma dúvida comun dos usuários da API é referente ao envio em massa de produtos, sobre isso, a API não permite o envio de vários produtos. Veja que a abertura do payload do POST PRODUTO é com "{" e não com "[". Desta forma o envio em massa deverá ser tratado por loops no lado do usuário, sempre aguardando o resultado do envio anterior para enviar o próximo POST PRODUTO.
Tabela de Especificações do Produtos (POST produto)
Campo | Formato | Tamanho | Obrigatório | Exemplo |
---|---|---|---|---|
nome | string | 100 | Sim | Bicicleta Mountain Bike Caloi 21 |
codigo | string | 145 | Sim | 114 |
descricao | TEXT | 4000 | Sim | A bicicleta Caloi Andes proporciona conforto total ao pedalar seja na ciclovia, praia ou parque. Com qualidade e estilo, ela vem equipada de 21 velocidades, permitindo ao ciclista a escolha da marcha ideal de acordo com o local. |
departamento | string | 100 | Sim | Esportes>Bicicletas (Saiba mais sobre atributos do departamento aqui) |
fabricante | string | 20 | Sim | Caloi |
preco | double | 10,2 | Sim | 720.00 |
custo | double | 10,2 | Não | 610.00 |
comprimento | double | 10,2 | Não | 1.60 |
largura | double | 10,2 | Não | 0.20 |
altura | double | 10,2 | Não | 1.20 |
peso | double | 10,3 | Sim | 13.400 |
cubagem | double | 10,2 | Não | |
garantia | string | 30 | Não | 90 dias |
atributos_produto | string | 500 | Não | Marchas:21; Aro:22; Freios:V-BREAK |
videos | string | 500 | Não | https://www.youtube.com/watch?v=nfv7C1Qn_So; https://www.youtube.com/watch?v=BrZBiqK0p9E |
localizacao_estoque | string | 245 | Não | Corredor 2, Palete 10 |
formato_visualizacao_modelos | string | 1 | Não | Se não informado o padrão é o formato 1, saiba mais aqui. |
modelos | Sim | |||
nome | string | 145 | Não/Sim | Amarela (Saiba mais sobre manipulação de Cores via API). Caso o produto não possua variações de modelo, o nome do modelo não é obrigatório, mas caso possua, ele se torna obrigatório. |
crossdocking | integer | 11 | Não | 5 |
imagens | TEXT | 4000 | Não | url1, url2, url3, url4 |
imagens_retangulares | TEXT | 4000 | Não | url1, url2, url3, url4 |
status | integer | 11 | Não | 1 |
formato_visualizacao_opcoes | string | 1 | Não | Se não informado o padrão é o formato 2, saiba mais aqui. |
atributos_modelo | string | 500 | Não | Cor:Amarela; Entrega:Imediata |
itens | string | 30 | Sim | |
nome_opcao | string | 30 | Não/Sim | P Caso o produto não possua variações de opção, o nome da opção não é obrigatório, mas caso possua, ele se torna obrigatório. |
referencia | string | 145 | Não | 11482378 Geralmente esse é o código de relacionamento entre seu sistema e a Loja Virtual. A referência é o código SKU do último nível do produto, última variação, onde está o estoque. |
estoque | integer | 11 | Sim | 12 |
ean | string | 13 | Não | 7891473021257 |
Especificações dos formatos de exibição de modelos e opções:
Os campos "formato_visualizacao_modelos" e "campos formato_visualizacao_opcoes" podem ser preenchidos da seguinte maneira:
Os campos acima podem ser utilizados nos métodos POST PRODUTO e PUT PRODUTO.
PUT PRODUTO
{
"nome":"Produto de Teste 8812312399",
"descricao":"A bicicleta Caloi Andes proporciona conforto...",
"departamento":"Esportes>Bicicletas",
"fabricante":"Caloi",
"preco":720.20,
"custo":610.10,
"comprimento":1.62,
"largura":0.2,
"altura":1.2,
"peso":13.400,
"cubagem":0,
"garantia":"90 dias",
"atributos_produto": "Marchas:21; Aro:22; Freios: V-BREAK",
"videos": "https://www.youtube.com/watch?v=nfv7C1Qn_So; https://www.youtube.com/watch?v=BrZBiqK0p9E",
"localizacao_estoque": "Corretor 2, Palete 10",
"formato_visualizacao_modelos": "1",
"status":1,
"modelos":[
{
"nome":"Amarela",
"crossdocking":10,
"imagens":"https:\/\/www.personal.psu.edu\/jul229\/mini.jpg,https:\/\/www.personal.psu.edu\/jul229\/rv1.jpg",
"imagens_retangulares":"https:\/\/www.personal.psu.edu\/jul229\/mini_retangular.jpg,https:\/\/www.personal.psu.edu\/jul229\/rv1_retangular.jpg",
"status":1,
"formato_visualizacao_opcoes":"2",
"atributos_modelo": "Cor:Amarela; Entrega:Imediata",
"itens":[
{
"nome_opcao":"P",
"referencia":"11482378",
"estoque":12,
"ean":"7891473021257"
}
]
}
]
}
Operação que permite alterar um produto e nas suas variações permite alterar, incluir ou excluir. O endpoint usado na API para realizar essa operação é a: "PUT PRODUTO/{CODIGO}"
.
A estrutura do JSON do "PUT PRODUTO/{CODIGO}"
é parecida com a "POST PRODUTO" mas existem 2 diferenças importantes:
- O campo "codigo" não pode ser informado no JSON do
"PUT PRODUTO/{CODIGO}"
, ele deve ser informado em/{CODIGO}
no ENDPOINT do método para identificar o produto a ser alterado. - O campo "status" é novo na estrutura JSON do
"PUT PRODUTO/{CODIGO}"
, ele permite desativar o produto como um todo, ativar ou excluir.
Veja as regras:
As especificações dos campos do "PUT PRODUTO/{CODIGO}"
são as mesmas do "POST PRODUTO"
, com exceção das diferenças citadas acima.
- Você poderá enviar campos individualmente para atualização, e se for necessário atualizar a estrutura de modelos ou opções, devem ser informados todos campos dentro de "modelos" ou "opções".
- O identificador para atualização do "modelo" é o nome, e o identificações da "opção" (item) é a referencia. Esses campos não são alterados na atualização pois são identificadores.
- As imagens serão substituídas, se enviadas.
- O campo "url_produto" não será alterado
- Os departamentos, se diferentes serão substituídos.
- Todos os demais campos do produto e das suas variações são atualizados, com excessão dos mencionados acima.
- As variações de modelos ou opções se não localizadas para atualização serão incluídas.
Caso a operação seja bem sucedida o retorno será um código 201
Uma dúvida comun dos usuários da API é referente à atualização em massa de produtos, sobre isso, a API não permite a atualização de vários produtos na mesma requisição. A atualização em massa deverá ser tratada por loops no lado do usuário, sempre aguardando o resultado da requisição anterior para enviar a próxima.
POST imagem
{
"codigo": "12312323",
"nome_modelo": "Amarela2",
"modo": "inclusao",
"imagens":
[
"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sAB...",
"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sAB...",
"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sAB..."
]
}
Essa operação permite o envio de imagens dos modelos dos produtos por string, ao invés de enviar fornecendo a url da imagem conforme ocorre no POST PRODUTO ou PUT PRODUTO. O endpoint usado na API para realizar essa operação é a: "POST imagem"
.
Essa solução visa atender ERPs e outros sistemas locais que não utilizam de imagens em ambiente web e necessitam enviar uma imagem local para a API. Estando o produto previamente cadastrado na loja virtual, basta obter o código do mesmo, o modelo que receberá a imagem, e enviar as imagens por string, no padrão base64.
Abaixo as regras para utilização da "POST IMAGEM"
- No campo "codigo" informar o
CODIGO
do produto. - No campo "nome_modelo" informar o
"nome_modelo"
que receberá a imagem. (Lembre-se que a imagem é informada na variação do modelo, e não no produto) - Caso o produto só tenha um modelo, e este não tiver um
"nome_modelo"
deixe em branco. - O formato de envio da imagem deve ser em
base64
. Portanto, é necessário obter o fonte da imagem, aplicar umbase64_encode
para enviar como string à API. - O código base64 da imagem não podem conter pulos de linhas.
- A imagem deve ser obrigatoriamente no formato
jpg
- A resolução recomendada para imagens quadradas é
1000x1000px
- A resolução recomendada para imagens retangulares é
1200x1600px
- Podem ser enviadas várias imagens, separando as string de imagens por vírgula.
- O campo modo é destinado ao direcionamento da ação que a API POST Imagem fará, sendo eles:
- Imagens Quadradas
- inclusao: Esse modo é default do método. Se definido "inclusao", a API irá acrescenter as imagens informadas, somando com as imagens já existentes.
- substituicao: Se definido "substituicao", a API irá excluir as imagens atuais do modelo e incluir as novas imagens informadas.
- exclusao: Se definido "exclusao" o sistema irá excluir todas as imagens pertencentes ao modelo, sem incluir.
- Imagens Retangulares
- inclusao_retangular: Esse modo é default do método. Se definido "inclusao_retangular", a API irá acrescenter as imagens informadas, somando com as imagens já existentes.
- substituicao_retangular: Se definido "substituicao_retangular", a API irá excluir as imagens atuais do modelo e incluir as novas imagens informadas.
- exclusao_retangular: Se definido "exclusao_retangular" o sistema irá excluir todas as imagens pertencentes ao modelo, sem incluir.
Caso a operação seja bem sucedida o retorno será um código 201
PREÇO
As operações de Preço permitem consultar e atualizar o preço do produto. Abaixo as especificações dessas duas operações.
GET PRECO
$url = "https://www.meudatacenter.com/api/v1/produto/77/preco";
//-OU USANDO O FILTRO REFERENCIA-
// $url = "https://www.meudatacenter.com/api/v1/produto/null/preco?referencia=SKU12000";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
O endpoint usado na API para realizar a operação de consulta de preço é a: "produto/{CODIGO}/preco"
, onde CODIGO é o código do produto. Outra opção de consulta é utilizando o filtro referencia, veja abaixo.
O código do produto (CODIGO) é o mesmo que você utilizou no POST produto, caso você não tenha cadastrado o produto via POST, é possível obter os códigos dos produtos já existentes através do GET PRODUTOS.
Utilizando o filtro referencia no método GET PRECO
Você também poderá consultar o preço do produto através do filtro referencia=
que pode ser usado na URL da chamada.
Esse filtro irá buscar o preço do produto que possui a referencia
entre suas opções.
Exemplo de Uso: https://www.meudatacenter.com/api/v1/produto/null/preco?referencia=SKU12000
Essa consulta irá retornar toda a estrutura do produto que possui essa referencia
.
Caso a operação seja bem sucedida o retorno será um código 200
no header e no body você terá o retorno json do custo e do preço do produto consultado.
{
"preco": "720.00",
"custo": "610.00"
}
PUT PRECO
$jso = array(
'preco' => 1.99,
'custo' => 0.99
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/produto/99/preco";
//-OU USANDO O FILTRO REFERENCIA-
// $url = "https://www.meudatacenter.com/api/v1/produto/null/preco?referencia=SKU12000";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Definindo o PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Informando o Json
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
O endpoint usado na API para realizar a operação de atualização de preço é a: "produto/{COD}/preco"
, onde CODIGO é o código do produto. Outra opção é utilizando do filtro referencia.
Utilizando o filtro referencia no método PUT PRECO
Você também poderá processar a atualização de preço de um produto através do filtro referencia=
que pode ser usado na URL da chamada.
Esse filtro irá buscar o produto que possui a referencia
entre suas opções.
Exemplo de Uso: https://www.meudatacenter.com/api/v1/produto/null/preco?referencia=SKU12000
Se tudo ocorreu bem,será retornado um codigo 200
e o seguinte Payload:
{
"preco": "720.00",
"custo": "610.00"
}
GET PRECOEXTRA
$url = "https://www.meudatacenter.com/api/v1/item/SKU12000/precoextra";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
O endpoint usado na API para realizar a operação de consulta de preço de "Valores Extra" é o: "item/REF/precoextra"
, devendo passar o parâmetro no REF a referencia da opção a ter o preço extra alterado.
Requisitos para utilização o método GET PRECOEXTRA:
- A opção (REF) indicada para consulta já precisa está com "Valores Extras" configurados dentro da plataforma.
- Caso a opção (REF) indicada para consulta não tiver com "Valores Extras" configurados previamente a operação não irá retornar o valor.
- Se a opção (REF) indicada tiver duplicação de referencia dentro da plataforma, a operação não irá retornvar valores.
Exemplo de Uso: https://www.meudatacenter.com/api/v1/item/SKU12000/precoextra
Caso a operação seja bem sucedida o retorno será um código 200
no header e no body você terá o retorno json do preço da opção (REF)
{
"preco": "720.00"
}
PUT PRECOEXTRA
$jso = array(
'preco' => 29.99
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/item/SKU12000/precoextra";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Definindo o PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Informando o Json
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
O endpoint usado na API para realizar a operação de atualização de preço extra é o: "item/REF/precoextra"
, devendo passar o parâmetro de referencia REF da opção a ter o preço extra alterado.
Requisitos para utilização o método PUT PRECOEXTRA:
- A opção (REF) indicada para atualização já precisa está com "Valores Extras" configurados dentro da plataforma.
- Caso a opção (REF) indicada para atualização não tiver com "Valores Extras" configurados previamente a operação não será executada.
- Se a opção (REF) indicada tiver duplicação de referencia dentro da plataforma, a operação não será executada.
- É necessário informar no campo "preco" o valor final da opção (REF) e não a fatia de preço a ser acrescentada.
- O preço informado não pode ser menor que o preço do produto principal.
Exemplo de Uso: https://www.meudatacenter.com/api/v1/item/SKU12000/precoextra
Se tudo ocorreu bem,será retornado um codigo 201
e o seguinte Payload:
{
"preco": "29.99"
}
ESTOQUE
As operações de Estoque permitem consultar e atualizar o estoque da última variação do produto, chamada de opção do produto ou item do produto. Abaixo as especificações dessas duas operações.
GET ESTOQUE
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/item/2348923/estoque";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
O endpoint usado na API para realizar a operação de consulta de estoque é a: "item/{REFERENCIA}/estoque"
, onde REFERENCIA é o código utilizado no último nível do produto, em opções, onde fica o estoque da última variação. Para obter a referencia do item, você poderá realizar consultas através dos métodos de consulta de PRODUTOS
ou consultar diretamente na loja virtual.
Se tudo ocorreu bem,será retornado um codigo 200
e o seguinte Payload:
{
"estoque": 22
}
PUT ESTOQUE
$jso = array(
'estoque' => 115
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/item/129312/estoque";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Tipo PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Envio json
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
O endpoint usado na API para realizar a operação de atualização de estoque é a: "item/{REFERENCIA}/estoque"
, onde REFERENCIA é o código utilizado no último nível do produto, em opções, onde fica o estoque da última variação. Para obter a referencia do item, você poderá realizar consultas através dos métodos de consulta de PRODUTOS
ou consultar diretamente na loja virtual.
PEDIDOS
Abaixo poderá ser visto todas as solicitações relacionadas a pedidos, você poderá realizar consulta a todos pedidos, pedidos especificos e realizar mudanças de fase dos pedidos enviando informações relacionadas a cada fase.
Importante!
Nas operações de mudanças de fase de pedidos, é importante observar a fase atual do pedido a ser alterado, pois só é permitido alterar as fases de forma sequencial.
Sequencia de Fases: Novo > Pago > Separação > Entrega > Concluído (Cancelamento poderá ocorrer em qualquer fase)
GET PEDIDOS
$url = "https://www.meudatacenter.com/api/v1/pedidos?dataInicial=2019-10-01&dataFinal=2019-10-07";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
O sequinte retorno JSON será emitido:
{
"pedidos": [
{
"id": 201,
"codigo": "PA091233",
"numero_controle": "22454556764",
"origem": "PLAT",
"loja": "PLAT",
"fase_marketplace": "",
"fase_atual": "novo",
"data_pedido": "2019-10-04 11:15:41",
"data_pagamento": "0000-00-00 00:00:00",
"data_separacao": "0000-00-00 00:00:00",
"data_enviado": "0000-00-00 00:00:00",
"data_concluido": "0000-00-00 00:00:00",
"data_cancelado": "0000-00-00 00:00:00",
"frete_tipo": "PAC",
"frete_valor": 20.00,
"frete_rastreio": "BR1235467643",
"frete_prazo": 6,
"forma_pagamento": "CARTAO",
"parcelas": 3,
"parcelas_valor": 40.00,
"bandeira_cartao": "VISA",
"valor_desconto": 0.00,
"valor_desconto_cupom": 0.00,
"juros": 0.00,
"valor_total": 140.00,
"valor_total_credito": 140.00,
"observacao_cliente": "",
"nf": 44444444444444444444444444444444444444444444,
"nf_emissao": "20/10/2019",
"cliente": {
"nome": "JOÃO VITOR DA SILVA",
"tipo_conta": "CPF",
"doc": "07162277812",
"ie": "",
"email": "JOAOVITOR@DKK.COM",
"celular": "(32) 99118-2992",
"telefone": "(32) 3232-3333",
"data_nascimento": "29/08/1985",
"cep": 36015001,
"codigo_ibge": "3543402",
"endereco": "RUA SANTO ANTONIO",
"numero": 22640,
"complemento": 22208,
"bairro": "CENTRO",
"cidade": "JUIZ DE FORA",
"estado": "MG",
"pais": "BR",
"referencia": "ESQUINA",
"tipo": "recebedor",
"recebedor": "PEDRO EMANUEL SILVA"
},
"itens": [
{
"produto": "Produto de Teste",
"quantidade": "1",
"modelo": "",
"nome_opcao": "",
"sku": "1212333",
"referencia": "",
"variavel": "",
"valor": "120.00",
"valor_final": "120.00",
"desconto": "0.00",
"estoque_atual": "9",
"ean": ""
}
]
}
]
}
Operação que retorna todos os pedidos na loja virtual em ordem do mais recente para o mais antigo, independente da fase. O endpoint usado na API para realizar essa operação é a: "pedidos"
. Se sua solicitação ocorrer como o previsto o retorno será um 200 code
no header o no body o resultado da consulta em json.
Filtro de data do Método GET PEDIDOS
O método GET PEDIDOS possui filtros de data de realização do pedido dataInicial=
e dataFinal=
que deve ser passado na URL da chamada.
Caso o range de datas não seja informado, será retornado pela API os últimos 100 pedidos mais recentes.
O padrão de datas a ser utilizado nos filtros é o YYYY-MM-DD
Exemplo de Uso: https://www.meudatacenter.com/api/v1/pedidos?dataInicial=2019-10-01&dataFinal=2019-10-07
Filtro da data da última alteração no Pedido - Método GET PEDIDOS
O método GET PEDIDOS possui o filtro "data da última alteração" no Pedido dataAlteracao=
que deve ser passado na URL da chamada.
Esse filtro irá obter todos os pedidos que tiveram a sua última movimentação/atualização na data indicada.
O padrão de datas a ser utilizado nos filtros é o YYYY-MM-DD
Exemplo de Uso: https://www.meudatacenter.com/api/v1/pedidos?dataAlteracao=2020-06-23
Essa consulta irá retornar todos os pedidos que tiveram a sua última movimentação no dia 23/06/2020.
Filtro de STATUS do Método GET PEDIDOS
O método GET PEDIDOS possui também o filtro de STATUS pedido status=
que deve ser passado na URL da chamada.
Os valores aceitos para esse filtro são: novo, pago, separacao, entrega, concluido OU cancelado
Exemplo de Uso: https://www.meudatacenter.com/api/v1/pedidos?status=pago
Serão retornados desta forma somente pedidos com o status "pago".
Filtro de carrinhoAbandonado do Método GET PEDIDOS
O método GET PEDIDOS possui também o filtro de carrinhoAbandonado carrinhoAbandonado=
que deve ser passado na URL da chamada.
Os valores aceitos para esse filtro são: T
para trazer carrinhos abandonados junto com os pedidos normais.
ou L
que irá retornar somente pedidos de carrinho abandonado.
Exemplo de Uso: https://www.meudatacenter.com/api/v1/pedidos?carrinhoAbandonado=L
Serão retornados desta forma somente pedidos de carrinho abandonado.
Filtro de codigoPedido do Método GET PEDIDOS
O método GET PEDIDOS possui também o filtro de codigoPedido codigoPedido=
que deve ser passado na URL da chamada.
O filtro codigoPedido visa atender a quem não deseja buscar pelo código interno do pedido, mas pelo o "código externo" que o cliente ver ou pode buscar pelo "numero_controle".
Exemplo de Uso: https://www.meudatacenter.com/api/v1/pedidos?codigoPedido=UM878212
Exemplo de Uso: https://www.meudatacenter.com/api/v1/pedidos?codigoPedido=614492212224708
GET PEDIDO
$url = "https://www.meudatacenter.com/api/v1/pedido/30";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
Operação que retorna um pedido especifico da loja virtual. O endpoint usado na API para realizar essa operação é a: "pedido/{ID}"
, onde ID é o identificar do pedido na plataforma. Para obter os ID realize a consulta GET PEDIDOS
que irá retornar os pedidos da loja virtual dos mais recentes para os mais antigos.
Se tudo ocorreu bem, será retornado um codigo 200
no header, e no body o seguinte Payload em Json:
{
"pedido": {
"id": "1",
"codigo": "II115715",
"numero_controle": "22454556764",
"origem": "PLAT",
"loja": "PLAT",
"fase_marketplace": "",
"fase_atual": "novo",
"data_pedido": "2019-10-04 11:15:41",
"data_pagamento": "0000-00-00 00:00:00",
"data_separacao": "0000-00-00 00:00:00",
"data_enviado": "0000-00-00 00:00:00",
"data_concluido": "0000-00-00 00:00:00",
"data_cancelado": "0000-00-00 00:00:00",
"frete_tipo": "PAC",
"frete_valor": "51.60",
"frete_rastreio": "ggggggggggggggg",
"frete_prazo": "15",
"forma_pagamento": "Depósito ou Transferência",
"parcelas": "0",
"parcelas_valor": "",
"bandeira_cartao": "",
"valor_desconto": "0.00",
"valor_desconto_cupom": "0.00",
"juros": "0.00",
"valor_total": "771.60",
"valor_total_credito": "771.60",
"observacao_cliente": "",
"nf": "",
"nf_emissao": "0000-00-00",
"cliente": {
"nome": "PEDRO EMANUEL SILVA",
"tipo_conta": "pf",
"doc": "071.999.186-18",
"ie": "",
"email": "BH83@gmail.com",
"celular": "(32) 99118-2222",
"telefone": "(32) 3232-222",
"data_nascimento": "1983-08-23",
"cep": "36015-001",
"codigo_ibge": "3543402",
"endereco": "Rua Santo Antônio",
"numero": "640",
"complemento": "203",
"bairro": "Centro",
"cidade": "Juiz de Fora",
"estado": "MG",
"pais": "BR",
"referencia": "ESQUINA",
"tipo": "",
"recebedor": "PEDRO EMANUEL SILVA"
},
"itens": [
{
"produto": "joao teste zzzz xxxx",
"quantidade": "1",
"modelo": "Amarela",
"nome_opcao": "m",
"sku": "21891782",
"referencia": "11482378",
"variavel": "",
"valor": "720.00",
"valor_final": "720.00",
"desconto": "0.00",
"estoque_atual": "11",
"ean": "7891473021257"
}
]
}
}
Filtro de codigoPedido do Método GET PEDIDO
O método GET PEDIDO possui também o filtro de codigoPedido codigoPedido=
que deve ser passado na URL da chamada.
O filtro codigoPedido visa atender a quem não deseja buscar pelo código interno do pedido, mas pelo o "código externo" que o cliente ver ou pode buscar pelo "numero_controle".
Exemplo de Uso: https://www.meudatacenter.com/api/v1/pedido/codigoPedido=UM878212
Exemplo de Uso: https://www.meudatacenter.com/api/v1/pedidos/codigoPedido=614492212224708
Repare que na operação GET PEDIDOS são retornados os pedidos no nó "pedidos" e já na operação GET PEDIDO/ID o pedido é retornado no nó "pedido".
PUT PAGO
$jso = array(
'conferencia' => 14577,
'codigo_pagamento' => 154377,
'obs' => 15777,
'xml' => ''
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/pedido/33/pago";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Definindo PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Envio JSON
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
Operação responsável em passar um pedido na fase "Novo" para "Pago". O endpoint usado na API para realizar a operação é: "pedido/{ID}/pago"
. Nesta operação também é possível fornecer o xml da nota fiscal do pedido.
Formato do XML
O XML enviado para a API deve está em texto puro. Abaixo os problemas mais comuns que devem ser tratados:
- Deve realizar a remoção dos \r\n (breaklines)
- Deve substituir na string os \/ por / (strip por barra direita)
- O XML não pode conter aspas duplas, as aspas duplas " devem ser substituídas por aspas simples '
PUT SEPARACAO
$jso = array(
"nf_chave" => "444444444444444",
"nf_numero" => "1453277",
"nf_emissao" => "2019-07-03",
"xml" => ""
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/pedido/33/separacao";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Definindo PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Envio JSON
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
Operação responsável em passar um pedido na fase "Pago" para "Separação". O endpoint usado na API para realizar a operação é: "pedido/{ID}/separacao"
. Nesta operação você informa os dados de Nota Fiscal.
PUT ENTREGA
$jso = array(
"codigo_rastreamento" => "OA895469969BR"
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/pedido/33/entrega";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Definindo PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Envio JSON
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
O endpoint usado na api para realizar a operação é: "pedido/{ID}/entrega"
Se sua solicitação ocorreu como o previsto o retorno será um 201 code
Veja abaixo um exemplo do código usando o cURL PHP
PUT CONCLUIDO
$jso = array(
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/pedido/33/concluido";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Definindo PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Envio JSON
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
Operação responsável em passar um pedido na fase "Entrega" para "Concluído". O endpoint usado na API para realizar a operação é: "pedido/{ID}/concluido"
.
PUT CANCELADO
$jso = array(
"motivo" => "Sem estoque disponivel para suprir demanda"
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/pedido/33/cancelado";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Definindo PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Envio JSON
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
Operação responsável em passar um pedido para "Cancelado", pode ser acionada em qualquer fase de pedido. O endpoint usado na API para realizar a operação é: "pedido/{ID}/cancelado"
, é possível informar o motivo do cancelamento para a loja virtual.
PUT NFe
$jso = array(
"nf_chave" => "55555555555555555555555555555555555555555555",
"nf_numero" => "332232",
"nf_emissao" => "2020-07-14",
"xml" => "........."
);
$jso = json_encode($jso);
$url = "https://www.meudatacenter.com/api/v1/pedido/34422/nfe";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
$headers = array();
$headers[] = "x-ID:3566"; // Coloque seu ID aqui
$headers[] = "x-Token:3481260001..."; // Coloque aqui seu Token
$headers[] = "Content-Type: application/json";
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PUT'); // Definindo PUT
curl_setopt($curl, CURLOPT_POSTFIELDS, $jso); // Envio JSON
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$retornoJSON = json_decode($response);
Operação responsável por informar a qualquer momento os dados de Nota Fiscal à plataforma, independente da fase do pedido: "pedido/{ID}/nfe"
. Além do {ID} no end-point, essa função aceita também o código de controle do pedido. Se for um pedido de origem "ML" (Mercado Livre) a plataforma tentará enviar o xml informado ao Mercado Livre.
Formato do XML
O XML enviado para a API deve está em texto puro. Abaixo os problemas mais comuns que devem ser tratados:
- Deve realizar a remoção dos \r\n (breaklines)
- Deve substituir na string os \/ por / (strip por barra direita)
- O XML não pode conter aspas duplas, as aspas duplas " devem ser substituídas por aspas simples '
Callbacks (Retorno automático)
CallBack de Estoque
Modelo de JSON enviado no callback de Estoque
{
"evento":"estoque",
"ID_ACESSO":"0000",
"data":"2021-09-14 09:47:43",
"url_loja":"https://www.apiplusplus.com.br/",
"movimento":"ADD",
"tipo":"Produto",
"origem":"Cadastro Rápido",
"ean":"5010993628124",
"id_estoque":"132",
"referencia_sku":"PL_890M",
"estoque":"21"
}
O CallBack de Estoque será disparado havendo qualquer alteração no estoque do item, o sistema emitirá um POST de JSON para a URL configurada na administração da loja virtual, na aba "Callbacks". A URL informada para callback deverá está preparada para receber o callback.
O sistema poderá interromper o envio de callback caso seja observado algum erro de recepção na URL informada, por exemplo, uma URL inválida ou com erro.
Modelo do arquivo para receber POST enviado pelo CALLBACK em PHP
$data = json_decode(file_get_contents('php://input'), true); // Pegando o POST enviado pelo Callback.
//Obtenção das informações do JSON
$evento = $data['evento']; // Evento disparado
$ID_ACESSO = $data['ID_ACESSO']; // ID da loja
$referencia_sku = $data['referencia_sku']; // SKU do item - referencia.
$estoque = $data['estoque']; // Novo estoque
...
CallBack de Pedido
Modelo de JSON enviado no callback de Pedido
{
"evento":"pedido",
"ID_ACESSO":"0000",
"data":"2021-09-14 10:11:32",
"url_loja":"https://www.apiplusplus.com.br/",
"pedido":{
"id":"1",
"codigo":"IA783614",
"numero_controle":"166843517982325",
"origem":"PLAT",
"loja":"PLAT",
"fase_marketplace":"",
"fase_atual":"novo"
....
O CallBack de Pedido será disparado havendo qualquer alteração no pedido, o sistema emitirá um POST de JSON com todas informações do pedido para a URL configurada na administração da loja virtual, na aba "Callbacks". A URL informada para callback deverá está preparada para receber o callback.
O sistema poderá interromper o envio de callback caso seja observado algum erro de recepção na URL informada, por exemplo, uma URL inválida ou com erro.
Observe no JSON acima que o conteúdo do nó "pedido" é o mesmo retornado pelos métodos GET PEDIDO ou GET PEDIDOS. A composição completa dos campos do pedido poderá ser consultada nesses métodos.
Modelo do arquivo para receber POST enviado pelo CALLBACK em PHP
$data = json_decode(file_get_contents('php://input'), true); // Pegando o POST enviado pelo Callback.
//Obtenção das informações do JSON
$evento = $data['evento']; // Evento disparado
$ID_ACESSO = $data['ID_ACESSO']; // ID da loja
$codigo = $data['pedido']['codigo']; // Código do Pedido
$fase_atual = $data['pedido']['fase_atual']; // Fase atual.
...
Observe que no callback é enviado o campo "evento", esse campo diferenciará o que é evento de "estoque" e o que é evento de "pedido", já que a URL de envio é a mesma para ambos os callbacks.
Exemplo
...
if($evento=='estoque')
{
//tratamento de estoque
}
else if($evento=='pedido')
{
//tratamento de pedido
}
...
Códigos de retorno da API
Codigo | Descrição |
---|---|
200 | A requisição foi bem sucedida |
201 | Recurso criado ou alterado com sucesso |
400 | Alguma informação enviada está incorreta. {Descrição do erro} |
401 | Problemas na autenticação. Verifique sua api key |
403 | Acesso a um recurso não permitido |
404 | Método não existe ou tipo de chamada não aceita neste método |
406 | Token não existe, desativado ou alterado na loja virtual. |
407 | A origem do acesso não é API. Não autorizado. |
409 | Erro de conflito: código, SKU ou ID já existe. |
412 | Erro de tipagem. Ex: Envio deve ser float e foi enviado string. Retorno exclusivo do PUT PRODUTO. |
495 | Requisição não segura - SSL Certificate Error |
500 | Erro interno do sistema. Comunique nossa equipe técnica pois este erro não deve acontecer |
501 | A operação não foi concluída. Erro interno, comunique nossa equipe técnica. |
429 | Too Many Requests. Clique aqui para verificar os limites da API |
Atualizações
Data | Atualização |
---|---|
10/02/2025 |
Mudança do campo "peso" para aceitar 3 casas decimais Os métodos POST PRODUTO e PUT PRODUTO poderão receber agora 3 casas decimais no campo peso A API irá continua aceitando os envios com 2 casas decimais. |
24/09/2024 |
Departamentos com várias árvores (Ramificações) Essa atualização permite enviar várias ramificações de departamentos nos métodos POST produto, PUT produto. Para utilizar mais de uma ramificação, basta separar por ponto e vírgula ";" e iniciar a próxima ramificação. Exemplo: Esportes>Bicicletas;Caloi>Cross Teremos então uma ramificação Esportes > Bicicletas, e outra Caloi > Cross Os métodos "GET PRODUTO e PRODUTOS" retornarão os departamentos neste mesmo padrão, separando com ";" caso tenha mais de uma ramificação. |
19/08/2024 |
Manipulação de Cores dos Modelos As cores dos modelos de um produtos poderão ser manipulados através dos métodos GET getCoresModelos e PUT putCoresModelos. Para incluir uma nova cor, basta não informar o campo "cod_cor", para atualizar deve-se informar o "cod_cor" obtive no GET getCoresModelos Consulte o simulador para exemplo dos métodos. |
19/08/2024 |
Manipulação de atributos em departamentos Os atributos do departamento poderão ser manipulados através dos métodos POST atributosDepartamentos, PUT atributosDepartamentos e GET atributosDepartamentos Consulte o simulador para exemplo dos métodos. |
07/05/2024 |
Busca de pedidos pelo código externo ou número de controle Os métodos GET PEDIDO e GET PEDIDOS receberam o novo filtro codigoPedido Através desse filtro não é mais necessário buscar o pedido pelo código interno, você poderá consultar pelo código externo da plataforma, Mercado Livre ou outras integrações. Consulte mais informações desse filtro aqui. |
07/05/2024 |
Campo Localização e Formato de Visualização Os métodos POST produto, PUT produto, GET produto, GET produtos receberam duas atualizações: 1) A configuração Localização no Estoque que antes era acessível somente via administração da loja virtual agora está disponível na API. Consulte aqui. 2) As configurações Formato de Visualização dos Modelos e Formato de Visualização das Opções que antes eram acessíveis somente via administração da loja virtual agora está disponível na API. Consulte aqui e saiba mais. |
03/05/2024 |
Delay para consultar pedidos Mercado Livre na API Essa atualização é um informativo: Pedidos Mercado Livre após entrarem na sua loja virtual, só estarão disponíveis após 10 minutos na API. Esse delay foi adicionado devido aos problemas relacionados à pedidos de "carrinho" do Mercado Livre que não chegam com as informações completas de imediato. |
30/04/2024 |
Seleção automática na palette da Cor do Modelo Os métodos POST produto e PUT produto receberam uma atualização. Caso o campo "nome" do modelo seja o mesmo nome de uma cor cadastrada na loja virtual, o sistema irá marcar automaticamente a cor na palette. Isso ajudará nos filtros de pesquisa da loja virtual. Caso utilize na API uma cor não cadastrada, você pode realizar o cadastro via administração da loja virtual. Para duas cores em um modelo separe as cores com /, exemplo: Azul/Amarela - ATENÇÃO: Para cadastrar uma nova cor via API , utiliza os métodos descritos aqui. ![]() |
08/01/2024 |
Filtro carrinhoAbandonado na GET PEDIDOS Possibilidade de consultar pedidos de Carrinho Abandonado na API. |
11/12/2023 |
Limites da API A partir de 01/01/2024 a API irá utilizar limites de requisições. Clique aqui e saiba mais |
14/11/2023 |
GET PEDIDOS, GET PEDIDO - Inclusão de informação para pedidos Mercado Livre Foram incluídas novas informações de retorno nos métodos de pedidos do Mercado Livre para informar se o pedido é fulfillment e também dados de fiscais para emissão de nota. O campo frete_tipo se tiver o valor fulfillment é porque o pedido do Mercado Livre é do tipo FULL. O campo buyer_fiscal irá conter um JSON com os dados fiscais para quem deve ser realizada a emissão da nota fiscal. |
23/03/2023 |
GET PRECOEXTRA, PUT PRECOEXTRA - Inclusão de Funcionalidade A API permite agora consultar e alterar o preço das opções de produtos com "Valores Extras" ativadas na plataforma. |
07/03/2023 |
GET PRODUTOS, GET PRODUTO, POST PRODUTO, PUT PRODUTO - Inclusão de Atributos Os métodos que envolvem produtos receberam os campos "atributos_produto" para atributos do produto e "atributos_modelo" para atributos do modelo. Os atributos devem ser informados separando-os com ponto e virgula conforme exemplo: "Marchas:21; Aro:22; Freios: V-BREAK" |
07/03/2023 |
GET PRODUTOS, GET PRODUTO, POST PRODUTO, PUT PRODUTO - Inclusão de Vídeos Os métodos que envolvem produtos receberam o campo "video" para informar o vídeo do produto. Usar sempre um link do Youtube separando-os por ponto e virgula, limitando a 2 vídeos. |
20/10/2022 |
GET PRODUTOS - Inclusão de Imagens Retangulares Adição de um campo para obtenção dos links de imagens retangulares inseridas do modelo do produto. |
19/10/2022 |
GET PRODUTO - Inclusão de Imagens Retangulares Adição de um campo para obtenção dos links de imagens retangulares inseridas do modelo do produto. |
18/10/2022 |
POST PRODUTO - Inclusão de Imagens Retangulares Adição de um campo para inclusão de links de imagens retangulares no modelo do produto. |
17/10/2022 |
PUT PRODUTO - Inclusão de Imagens Retangulares Adição de um campo para inclusão e/ou alteração de links de imagens retangulares do modelo do produto. |
14/10/2022 |
POST IMAGEM - Inclusão de Imagens Retangulares Adição de um campo para inclusão de imagens retangulares no modelo do produto. |
31/08/2022 |
GET PRODUTOS - Filtro de Campanhas de Atacado Adição de filtro de busca de campanhas de atacado atreladas aos produtos existentes na loja. |
31/08/2022 |
GET PRODUTO - Filtro de Campanhas de Atacado Adição de filtro de busca de campanhas de atacado atreladas a um produto existente na loja. |
20/12/2021 |
POST IMAGEM - Inclusão de "modo" Adicionado neste método o campo "modo" onde é possível configurar ações de "inclusao", "substituicao" e "exclusao". |
01/11/2021 |
GET PRODUTO - Filtro de referencia. Agora é possível consultar um produto através da referencia, ao informar o filtro referencia= a API irá localizar o produto que possui essa referencia entre suas opções. Antes só era possível através do {CODIGO} do produto. |
01/11/2021 |
GET PRECO - Filtro de referencia Agora é possível consultar o preço de um produto através da referencia, ao informar o filtro referencia= a API irá localizar o produto que possui essa referencia entre suas opções. Antes só era possível através do {CODIGO} do produto. |
01/11/2021 |
PUT PRECO - Filtro de referencia Agora é possível referenciar o produto a ter o preço atualizado pela referencia, ao informar o filtro referencia= a API irá localizar o produto que possui essa referencia entre suas opções. Antes só era possível através do {CODIGO} do produto. |
15/09/2021 |
GET PRODUTO e GET PRODUTOS - campo "url_produto" A API, nos métodos GET PRODUTO e GET PRODUTOS irá retornar a partir desta atualização o campo "url_produto" dentro do nó de "modelos" que corresponde ao link do produto. |
14/09/2021 |
CALLBACKS Implementação e disponibilização dos Callbacks (Retorno Automático) de Estoque e Pedidos. Havendo qualquer alteração em estoque ou pedido o sistema emitirá uma comunicação com o conteúdo do item alterado para a URL configurada na administração da loja virtual. |
09/08/2021 |
POST IMAGEM Para atender demandas de ERPS e sistemas que não utilizam de imagens em ambiente web, foi criado o método POST IMAGEM que envia para a loja virtual imagens em formato string em base64. |
02/08/2021 |
GET PEDIDO e GET PEDIDOS - campo "ie" (Inscrição Estadual) A API, nos métodos GET PEDIDO e GET PEDIDOS irá retornar a partir desta atualização o campo "ie" (Inscrição Estadual) dentro do nó cliente. |
27/07/2021 |
PUT PRODUTO Foi disponilizado o endpoint de atualização de produto e suas variações. A documentação pode ser acessada e aqui. e o método pode ser testado na API Explorer. |
02/06/2021 |
GET PEDIDOS e GET PEDIDO campo "codigo_ibge" Quando não for localizado o código do IBGE de acordo com o CEP do pedido, a API retornará no campo "codigo_ibge" o valor "N/I" devendo o empenho da exatidão do código do IBGE ser realizado pela integradora. |
05/08/2020 |
END-POINT: PUT NFe - O recurso PUT NFe foi criado na API visando automatizar processos de envios de Nf2 (XML) para a plataforma. - Essa função possui uma exclusividade pois também envia o XML diretamente para os pedidos oriundos do Mercado Livre. |
25/07/2020 |
END-POINT: POST PRODUTO - o POST PRODUTO recebeu uma alteração no campo "referencia", é necessário enviar em string agora, antes era integer. - A alteração foi realizada pois a referencia com letras não estava funcionando, aceitava somente números. |
23/06/2020 |
END-POINT: GET PEDIDOS - O recurso GET PEDIDOS recebeu um novo filtro de dataAlteracao, podendo filtrar desta forma todos os pedidos que tiveram sua última alteração/atualização na data indicada. Padrão YYYY-MM-DD |
21/05/2020 |
END-POINT: GET PEDIDOS e GET PEDIDO 1 - GET PEDIDOS e GET PEDIDO - Os campos "valor", "valor_final" e "desconto" dentro do nó "itens", que se refere aos valores dos produtos do pedido, recebem agora valores reais da compra ao invés de apenas o preço base do produto. Essa normalização exibirá os mesmos valores que são exibidos no painel de pedidos da plataforma. Dos campos acima, o campo "valor_final" é uma novidade no recurso GET PEDIDO e GET PEDIDOS a partir desta atualização. |
04/05/2020 |
END-POINT: GET PEDIDOS e GET PEDIDO 1 - GET PEDIDOS - O recurso GET PEDIDOS recebeu um novo filtro de status, podendo filtrar pela função status os valores: novo, pago, separacao, entrega, concluido ou cancelado 2 - GET PEDIDOS e GET PEDIDO Os recursos get PEDIDO e get PEDIDOS receberam o campo codigo_ibge em seu retorno. O código IBGE se refere no caso à cidade do cliente que solicitou o pedido. |
23/10/2019 |
END-POINT: GET PRODUTOS E GET PEDIDOS Os recursos GET PRODUTOS e GET PEDIDOS receberam filtros de consulta. 1 - GET PRODUTOS - Recebeu o filtro page, cada página retornará 100 resultados. Se não informado, o sistema considera como ?page=1, o filtro deve ser informado na URL da requisição. Agora, ao final do retorno JSON da requisição, será informado os totais de produtos, total de páginas e página atual. 2 - GET PEDIDOS - Recebeu os filtros DataInicial e DataFinal, caso não informado retornará os 100 últimos pedidos mais recentes. O padrão de datas destes filtros é YYYY-MM-DD. Exemplo: ?dataInicial=2019-10-01&dataFinal=2019-10-07 |
08/10/2019 |
END-POINT: GET PEDIDO E GET PEDIDOS Recurso retornará agora novos campos, são eles - campo "quantidade" dentro de pedido->itens - campo "origem" dentro de pedido - campo "loja" dentro de pedido - campo "fase_marketplace" dentro de pedido - campo "data_pedido" dentro de pedido - campo "data_pagamento" dentro de pedido - campo "data_separacao" dentro de pedido - campo "data_enviado" dentro de pedido - campo "data_concluido" dentro de pedido - campo "data_cancelado" dentro de pedido |