Nosso departamento de Informática está sempre disponível para qualquer dúvida:
Tel: 011 4361 3130
suporte@itlog.com.br
O objetivo desta documentação é orientar nossos parceiros sobre a integração do serviço ITLOG, descrevendo as funcionalidades e os métodos HTTP, listando informações completas do catálogo de produtos acordado comercialmente, como incluir, alterar, cancelar e realizar consultas do status do pedido.
A solução ITLOG foi desenvolvida com a tecnologia REST, que é padrão de mercado, onde todos os serviços são disponibilizados pelos WebServices e possuem disponibilidade 24/7 com retorno no formato JSON. O acesso é restrito pois as chamadas requerem chave de acesso individual fornecida a cada parceiro no início da integração.
Conhecimentos necessários: recomendamos conhecimentos intermediários em linguagem de programação para web, requisições HTTP/HTTPS e manipulação de arquivos JSON.
Estes são os nossos endpoints atuais:
Todos os serviços do tipo POST requerem o campo Parameters preenchido com o código do parceiro como no exemplo abaixo:
"parameters": {
"store": {{StoreId}}
}
Para manter a segurança, o HEADER de qualquer chamada é obrigatório e nele o parceiro deve enviar sua chave de acesso denominada AUTHORIZATION :
Authorization: mSpVsXuZx4z6B9EbGeKgNjRnTqVtYv2x5A7CaFcHeMhPkRpUrWtZw3y6B8DaGdJfMUj
Tipo de pessoa:
Gênero:
Tipo de telefone:
Código do erro:
| Tipo | Nome | Download |
|---|---|---|
| Ambiente | Integracao | ⬇️ |
| Coleção | Parceiros | ⬇️ |
O "catálogo" é a lista de produtos acordada para trabalho entre a ITLOG e o parceiro. O catálogo de cada parceiro é previamente estabelecido pelo departamento comercial e possui variações de acordo com regras disponibilidade.
Através deste serviço, o parceiro acessa todas as informações necessárias para exibição dos produtos no site de interface com o cliente final. As regras para exibição dos produtos são mantidas pelo parceiro. Por exemplo, se um produto for exibido no serviço com status 0, então a regra para suspender a venda fica no código fonte do site do parceiro.
Consulta do catálogo:
// GET
https://integracao.maisbarato.net/catalogo/[código do parceiro]
O parâmetro [código do parceiro], é o código do parceiro em nossa base de dados. Este parâmetro é disponibilizado para o parceiro no início da integração.
Schema de retorno do /catalogo :
{
"products": [
{
"product": {
"productId": 290096499,
"name": "Lápis - Elétrico - Produto para teste. (NAO COMPRE)",
"description": "Este é um produto de teste. Nada será entregue.",
"productFeatures": [
{
"productFeature": {
"name": "Peso Real",
"featureType": 5,
"value": "0"
}
},
{
"productFeature": {
"name": "Peso Volumetrico",
"featureType": 5,
"value": "0"
}
}
],
"productSkus": [
{
"productSku": {
"ean": "",
"priceFor": 4.0,
"priceFrom": 0.0,
"quantity": 90,
"productSkuId": "35746X",
"skuFeatures": [
{
"skuFeature": {
"featureType": 2,
"name": "Comprimento",
"value": "1"
}
},
{
"skuFeature": {
"featureType": 2,
"name": "Largura",
"value": "1"
}
},
{
"skuFeature": {
"featureType": 2,
"name": "Altura",
"value": "1"
}
},
{
"skuFeature": {
"featureType": 3,
"name": "Voltagem",
"value": "110V"
}
}
],
"skuImages": [
{
"skuImage": {
"largeImage": "https://maisbarato.net/image/catalog/35746X.jpg",
"mediumImage": "https://maisbarato.net/image/catalog/35746X.jpg",
"smallImage": "https://maisbarato.net/image/catalog/35746X.jpg",
"order": 1
}
}
],
"skuStatusId": 1
}
},
{
"productSku": {
"ean": "",
"priceFor": 4.0,
"priceFrom": 0.0,
"quantity": 90,
"productSkuId": "35747X",
"skuFeatures": [
{
"skuFeature": {
"featureType": 2,
"name": "Comprimento",
"value": "1"
}
},
{
"skuFeature": {
"featureType": 2,
"name": "Largura",
"value": "1"
}
},
{
"skuFeature": {
"featureType": 2,
"name": "Altura",
"value": "1"
}
},
{
"skuFeature": {
"featureType": 3,
"name": "Voltagem",
"value": "220V"
}
}
],
"skuImages": [
{
"skuImage": {
"largeImage": "https://maisbarato.net/image/catalog/35747X.jpg",
"mediumImage": "https://maisbarato.net/image/catalog/35747X.jpg",
"smallImage": "https://maisbarato.net/image/catalog/35747X.jpg",
"order": 1
}
}
],
"skuStatusId": 1
}
}
],
"sections": []
}
}
]
}
A variável "Sections" é responsável para retornar a categoria do produto. Se caso ela estiver vazia é necessário realizarmos configuração para que contemple.
Abaixo está um exemplo de como a categoria retorna após configurado. Isso vale para as chamadas /catalogo e /catalogoasync:
A variável Name sempre será fixo. Porém a Value será sempre o responsável em mostrar o nome da categoria.
"sections": [
{
"section": {
"sectionTypeId": "1",
"name": "Category",
"sectionParentId": "null",
"value": Black Friday
"sectionId": 5411
}
}
],
| Campo | Descrição |
|---|---|
| priceFrom | Preço padrão |
| priceFor | Preço promocional |
| Campo | Caminho | FeatureType | Descrição | Exemplos |
|---|---|---|---|---|
| SkuFeature | product.productSkus[].productSku.SkuFeatures[] | 2 | Características fixas para um SKU | "Altura", "Largura", "Comprimento", "Numeração" |
| SkuFeature | product.productSkus[].productSku.SkuFeatures[] | 3 | Características opcionais para um SKU | "Voltagem", "Cor", "Tamanho" |
| ProductFeature | product.productFeatures[] | 5 | Características fixas para um produto | "Peso Real", "Peso Volumétrico" |
⚠️ Importante!
Produtos com mais de uma opção terão um ProductSku pra cada variante e com o campo "featureType" com valor 3
O endpoint disponibilizado segue o modelo assíncrono, foi desenvolvido com o propósito de suportar todos tamanhos de arquivo (Catálogo de Produtos).
CallbackUrl será a URL do cliente que irá aguardar a confirmação do Catálogo, nosso Webhook irá fazer um POST nessa URL com o Retorno do Processamento e Link de Download.
Schema de chamada do /catalogoasync:
{
"callbackUrl": {{CallbackUrl}},
"parameters": {
"store": {{StoreId}}
}
}
Schema do retorno do /catalogoasync:
{
"id": "{{ProcessId}}"
}
Schema da chamada que faremos do {{CallbackUrl}}:
{
"id": "{{ProcessId}}",
"storeId": {{StoreId}},
"downloadUrl ": " https://integracao.maisbarato.net/downloadCatalogo?id={{ProcessId}}"
}
O serviço availability informa o preço e a disponibilidade de um determinado produto. Ao longo do dia, ocorrem alterações de estoque em nossa base de dados, portanto, antes do parceiro efetivar uma venda, é fundamental que consulte esse serviço.
Schema de chamada do /availability:
// POST
{
"sku": "{{SKU}}",
"parameters": {
"store": {{StoreId}}
}
}
Schema de retorno do /availability:
{
"isAvailable": true,
"costPrice": 0.01,
"defaultPrice": 0.01,
"sku": "5158X",
"errorCodes": [
{
"code": 1,
"description": "Successfully"
}
],
"quantity": 955
}
O serviço shipping informa o preço de entrega dos produtos para o CEP destino. Algumas faixas de CEP não são atendidas e os preços podem variar ao longo do dia. É importante que o parceiro utilize esse serviço durante o checkout com todos os produtos selecionados pelo cliente para que valor faturado seja correto.
Schema de chamada do /shipping:
// POST
{
"zipCode": "{{CEP}}",
"products": [
{
"sku": "{{SKU}}",
"quantity": 1,
"unitPrice": 0.01
}
],
"parameters": {
"store": {{StoreId}}
}
}
Schema de retorno do /shipping:
{
"costPrice": 21.0,
"itens": [
{
"sku": "5158X",
"scheduledDeliveryDate": "2023-12-07T10:47:04.0000000-02:00",
"qtyRequested": 1,
"qtyReleased": 955,
"qtyInStock": 955,
"costPriceUnit": 21.0
}
],
"errorCodes": [
{
"code": 1,
"description": "Successfully"
}
]
}
O serviço /order possibilita que o parceiro grave um pedido em nossa base de dados.
Schema de chamada do /order:
// POST
{
"order": {
"id": "{{OrderId}}",
"createDate": "{{CurrentDate}}",
"shipping": {
"cost": {
"costPrice": 0.05,
"deliveryForecast": "{{CurrentDate}}"
},
"receiver": {
"name": "Teste",
"cpfCnpj": "Teste",
"email": "Teste",
"birthDate": "1900-01-01T00:00:00",
"personType": 1,
"genderType": 3,
"phones": [
{
"ddd": "21",
"number": "00000000000",
"type": 0
}
]
},
"shippingAddress": {
"address": "Teste",
"number": "0",
"complement": "Teste",
"city": "Teste",
"district": "Teste",
"state": "{{UF}}",
"reference": "Teste",
"zipCode": "09950140"
}
},
"participant": {
"name": "Teste",
"cpfCnpj": "Teste",
"email": "Teste",
"login": "",
"flagTest": true,
"birthDate": "1900-01-01T00:00:00",
"inscricaoEstadual": "12345678901234",
"personType": 1,
"genderType": 3,
"phones": [
{
"ddd": "21",
"number": "00000000000",
"type": 0
}
]
},
"amount": 0.05,
"items": [
{
"sku": "5158X",
"name": "Lápis - Produto para teste. (NAO COMPRE)",
"quantity": 5,
"costPrice": 0.01
}
]
},
"parameters": {
"store": {{StoreId}}
}
}
Schema de retorno do /order :
{
"orderId": "0",
"orderVendorId": "0",
"errorCodes": [
{
"code": 1,
"description": "Successfully"
}
]
}
true
O serviço /changestatus possibilita que o parceiro mude o status de um pedido. Essa ação é necessária quando ocorre um cancelamento ou aprovação de um pedido que estava pendente. Em algumas situações, não é possível mudar o status do pedido. Por exemplo, se um pedido já foi entregue, então este não pode passar para status cancelado. A confirmação da alteração é informada no retorno da chamada.
Valores possíveis para status
Schema de chamada do /changestatus :
// POST
{
"status": "authorize",
"orderPartnerId": "{{OrderPartnerId}}",
"parameters": {
"store": {{StoreId}}
}
}
Schema de retorno do /changestatus :
{
"date": "1900-01-01T00:00:00",
"orderPartnerId": "{{orderPartnerId}}",
"done": true,
"errorCodes": [
{
"code": 1,
"description": "Successfully"
}
]
}
O serviço tracking informa o histórico de status do pedido, desde a recepção até o momento atual. Temos vários códigos e descrições de status. Os mais comuns utilizados na integração com parceiros são:
Schema de chamada do tracking:
// POST
{
"orderVendorId": "{{OrderVendorId}}",
"parameters": {
"store": {{StoreId}}
}
}
Schema de retorno do tracking:
{
"orderId": {{orderId}},
"trackingProducts": [
{
"sku": "",
"statusCode": "33",
"statusName": "Pedido cancelado",
"urlTracking": null,
"numberTracking": null,
"processDate": "10/30/2023 11:06:14 AM",
"deliveryDate": "11/8/2023 12:00:00 PM",
"estimatedDeliveryDate": "11/8/2023 12:00:00 PM",
"history": [
{
"statusCode": "33",
"statusName": "Pedido cancelado",
"processDate": "10/30/2023 11:06:14 AM",
"deliveryDate": "11/8/2023 12:00:00 PM",
"estimatedDeliveryDate": "11/8/2023 12:00:00 PM"
},
{
"statusCode": "35",
"statusName": "Processado",
"processDate": "10/30/2023 11:06:14 AM",
"deliveryDate": "11/8/2023 12:00:00 PM",
"estimatedDeliveryDate": "11/8/2023 12:00:00 PM"
},
{
"statusCode": "34",
"statusName": "Em processamento",
"processDate": "10/30/2023 11:01:59 AM",
"deliveryDate": "11/8/2023 12:00:00 PM",
"estimatedDeliveryDate": "11/8/2023 12:00:00 PM"
}
]
}
],
"errorCodes": [
{
"code": 1,
"description": "Successfully"
}
]
}