Especificação 

 
Interfaces de 
Integração 
SUMÁRIO

Introdução 2

Interfaces de Integração 2

Credenciais de acesso (Segurança) 3

Ambiente Admin da VTEX (Produção) 3

Integração de Catálogo 4

Integração de Estoque 9

Integração de Preço 10

Integração de Pedido (OMS) 11

Chamadas de API 16
Chamadas de API 18
Chamada de API 20
Introdução

Este documento tem como objetivo mapear as interfaces necessárias para integração entre os
sistemas VTEX e pegada.

O sistema VTEX utiliza interfaces que se conectam através de REST APIs, exceto para a
integração de Catálogo (produtos, SKUs, categorias, marca, etc) que utiliza Web Service SOAP.

Para se comunicar com a VTEX será necessário criar um programa para acessar as APIs e
atualizar/consumir os dados da loja, através de uma comunicação REST.
Sendo assim não é necessário fechar uma VPN ou criar um range de IPs para troca de
informações entre os sistemas.

Interfaces de Integração

Alguns programas nos ajudam a lidar com APIs e construir requests rapidamente. Um dos mais
utilizados é o Postman, que usamos aqui como referência. E para Web Service sugerimos que
utilize soapUI.

Guia de informações sobre interface API da VTEX

http://help.vtex.com/pt/developer-docs
http://help.vtex.com/pt/tutorial/introducao-as-apis-vtex

Guia de informações sobre Web Service da VTEX (para catálogo apenas)

https://help.vtex.com/pt/tutorial/manual-das-classes-e-metodos-usados-no-webservice/
https://help.vtex.com/pt/tutorial/testando-webservice-com-soapui

URL para Web Service:

A sua URL em produção para interface Web Service:

https://webservice-pegada.vtexcommerce.com.br/service.svc?wsdl
Credenciais de acesso (Segurança)

Toda chamada feita ao Web Service deve ser em “https” e um usuário e senha são exigidos para
iniciar a conexão. As chamadas para as APIs REST também devem ser feitas em “https” e
devem conter em seu header as chaves de autenticação.
Para fins de rastreabilidade, cada integração (diferentes sistemas ou ERP) deve possuir seu
usuário exclusivo.

O seu “Account Name” na VTEX é “pegada”.

Portanto, substitua o “accountname” ou “environment” nos links de acesso às interfaces para o

seu Account Name.

Nos artigos abaixo você encontrará informações sobre a autenticação de segurança com
interfaces REST na VTEX:
http://help.vtex.com/pt/tutorial/criar-appkey-e-apptoken-para-autenticar-integracoes
http://help.vtex.com/pt/tutorial/autenticando-com-usuario-e-senha-na-interface-rest-2

No artigo abaixo você encontra informações sobre credenciais SOAP:

http://help.vtex.com/pt/faq/como-criar-usuario-webservice

Acesso ao Ambiente Admin da VTEX (Produção)

URL para acesso ao Admin da loja em produção:

http://pegada.vtexcommercestable.com.br/admin

É importante ter a definição clara de acessos e permissões dentro do Admin da loja. Abaixo você
pode consultar mais informações sobre perfis de acesso:
http://help.vtex.com/pt/tutorial/como-criar-perfil-de-acesso
http://help.vtex.com/pt/tutorial/visao-geral-do-modulo-license-manager
Integração de Catálogo

Na arquitetura de catálogo, geralmente os produtos são organizados dentro da loja em

estruturas mercadológicas formadas por: Departamento, Categoria e SubCategoria.
● Departamento - categoria cujo ID de categoria pai é nulo
● Categoria - categoria cujo ID de categoria pai é um departamento
● Subcategoria - categoria cujo ID de categoria pai é uma categoria
Exemplo: Departamento/Categoria/Subcategoria/Produto
O cadastro da estrutura mercadológica deve ser feito diretamente no admin da própria loja, e
para atender a integração vinda do ERP, é criado um departamento padrão para produtos que
vem do ERP, ou seja, todos os produtos caem no admin da loja nesse departamento padrão, e
depois no momento do enriquecimento é colocado na categoria desejada

Nesse cenário de fluxo completo (imagem abaixo), a maioria dos dados de produtos e SKUs são
manipulados pelo ERP. A manipulação de campos de especificação nesse modelo é possível
ser feita por API REST, ​mas a melhor prática seria pelo admin da VTEX.

Nesse tipo de integração a administração da loja está no admin da VTEX, sendo o ERP apenas
uma fonte de onde nascem os produtos e SKUs.
Nesse cenário de fluxo básico, apenas os dados básicos de produtos e SKUs são manipulados
pelo ERP, e todo o enriquecimento (marca, fornecedor, imagens, categoria, ativação, etc.) será
feito pelo admin da loja na plataforma VTEX.
http://help.vtex.com/pt/tutorial/guia-de-integracao-de-erps-catalogo-expresso
http://help.vtex.com/pt/tutorial/manual-das-classes-e-metodos-usados-no-webservice/

Produto

Abaixo exemplo de chamada de uma inserção de produto usando o método

“ProductInsertUpdate”:

Métodos: “ProductInsertUpdate”

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/"
xmlns:vtex="http://schemas.datacontract.org/2004/07/Vtex.Commerce.WebApps.AdminWcfServi
ce.Contracts" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<soapenv:Header/>
<soapenv:Body>
<tem:ProductInsertUpdate>
<tem:productVO>
<!--int, identificdor da marca-->
<vtex:BrandId>2000011</vtex:BrandId>
<!--int, identificdor da categoria-->
<vtex:CategoryId>1000020</vtex:CategoryId>
<!--int, identificdor do departamento-->
<vtex:DepartmentId>1000018</vtex:DepartmentId>
<!--string, descrição completa do produto-->
<vtex:Description>Vaso de barro vermelho, feito a mão com barro do mar
vermelho</vtex:Description>
 <!--string, descrição curta do produto-->
<vtex:DescriptionShort>Vaso de barro vermelho artesanal</vtex:DescriptionShort>
<!--int, opcional, identificador no ERP caso int-->
<vtex:Id>1234567</vtex:Id>
<!--bool, se não atender requisitos de ativação(ter SKUs ativas), não será ativado-->
<vtex:IsActive>true</vtex:IsActive>
<!--bool, vai ser visível no site-->
<vtex:IsVisible>true</vtex:IsVisible>
<!--string, palavras chaves relevantes para a busca-->
<vtex:KeyWords> Barro, vaso, vermelho</vtex:KeyWords>
<!--lista de inteiros, pra qual canal de vendas = loja principal = 1-->
<vtex:ListStoreId>
<arr:int>1</arr:int>
<arr:int>2</arr:int>
</vtex:ListStoreId>
<!--meta tag de description (SEO)-->
<vtex:MetaTagDescription>feito a mão com barro do mar
vermelho</vtex:MetaTagDescription>
<!--string, nome do produto-->
<vtex:Name>Vaso Artesanal de Barro Vermelho</vtex:Name>
<!--string, identificador do produto no ERP-->
<vtex:RefId>1234567890</vtex:RefId>
<!--string, titulo do produto-->
<vtex:Title>Vaso Artesanal de Barro Vermelho</vtex:Title>
</tem:productVO>
</tem:ProductInsertUpdate>
</soapenv:Body>
</soapenv:Envelope>
SKU

Uma vez inseridos todos os produtos, que teoricamente são os pais das SKUs, chegou o
momento de enviar os SKUs filhos dos produtos. Abaixo exemplo de chamada de uma inserção
de SKU usando o metodo “StockKeepingUnitInsertUpdate”:

Métodos: “StockKeepingUnitInsertUpdate”

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/"
xmlns:vtex="http://schemas.datacontract.org/2004/07/Vtex.Commerce.WebApps.AdminWcfServi
ce.Contracts">
<soapenv:Header/>
<soapenv:Body>
<tem:StockKeepingUnitInsertUpdate>
<tem:stockKeepingUnitVO>
<!--decimal, cubagem = peso cubico -->
<vtex:CubicWeight>100</vtex:CubicWeight>
<!--decimal, altura com embalagem e metros-->
<vtex:Height>1.800</vtex:Height>
<!--int, opcional, identificador da sku no ERP caso int-->
<vtex:Id>00123456</vtex:Id>
<!--bool, se não atender requisitos de ativação(imagem, preço, estoque, espec., outros
reqs obrig.), não será ativado-->
<vtex:IsActive>true</vtex:IsActive>
<!--bool, disponibilidade -->
<vtex:IsAvaiable>true</vtex:IsAvaiable>
<!--bool, é um KIT? -->
<vtex:IsKit>false</vtex:IsKit>
<!--decimal, comprimento com embalagem em metros -->
<vtex:Length>1.52</vtex:Length>
<!--decimal, ** ler obs -->
<vtex:ListPrice>150.0</vtex:ListPrice>
<!--number, prefixo do estoque (id estoque = 1_1, mandar 1) -->
<vtex:ModalId>1</vtex:ModalId>
<!--string, opicional, tipo de carga, necessita configuração de transportadora especial
quando preenchido -->
<vtex:ModalType>Vidro</vtex:ModalType>
<!--string, nome da SKU -->
<vtex:Name>Vaso Artesanal de Barro Vermelho Escuro </vtex:Name>
<!--decimal, preço, "POR", opcional **ler obs-->
<vtex:Price>110.0</vtex:Price>
<!--int, identificador do produto pai da SKU -->
<vtex:ProductId>31018369</vtex:ProductId>
<!--decimal, peso real em kilos -->
<vtex:RealHeight>1.740</vtex:RealHeight>
 <!--decimal, altural real em metros -->
<vtex:RealLength>1.60</vtex:RealLength>
<!--decimal, peso real em kilos -->
<vtex:RealWeightKg>2.750</vtex:RealWeightKg>
<!--decimal, comprimento real em metros -->
<vtex:RealWidth>1.7</vtex:RealWidth>
<!--string, identificador da SKU no ERP -->
<vtex:RefId>00123456</vtex:RefId>
<!--number, opcional, numero de pontos dessa SKU -->
<vtex:RewardValue>0</vtex:RewardValue>
<!--lista de string, EANs do produto -->
<vtex:StockKeepingUnitEans>
<vtex:StockKeepingUnitEanDTO>
<vtex:Ean>0123456789123</vtex:Ean>
</vtex:StockKeepingUnitEanDTO>
</vtex:StockKeepingUnitEans>
<!--int, unidade de multipliçao para venda -->
<vtex:UnitMultiplier>1</vtex:UnitMultiplier>
<!--decimal, peso em kilos-->
<vtex:WeightKg>1.5</vtex:WeightKg>
<!--decimal, largura com embalagem em metros -->
<vtex:Width>2.780</vtex:Width>
</tem:stockKeepingUnitVO>
</tem:StockKeepingUnitInsertUpdate>
</soapenv:Body>
</soapenv:Envelope>

Atenção:​ o ERP não deve inferir um ID no cadastro de um novo SKU, deixando o campo vazio
(null), fazendo com que a VTEX gerencie a criação de IDs. O ID que for gerado pode ser
recuperado pelo response do request e deve ser armazenado no sistema para futuras
atualizações deste produto/SKU
O código do SKU nativo do ERP deve ficar no campo RefID na VTEX.
Integração de Estoque

Antes de iniciar a carga de estoque dos SKUs é necessário ir no Admin da VTEX e Cadastrar
Estoque. Veja mais em ​http://help.vtex.com/pt/tutorial/gerenciar-estoque​. A plataforma VTEX
permite que você tenha mais de 1 estoque (warehouse), e a integração indicará para qual
estoque (warehouse) o saldo será impactado.

A integração é feita por REST API e você pode encontrar mais detalhes em
https://documenter.getpostman.com/view/3848/logistics/Hs42#2e41254e-0d48-fcb0-c849-4a76c6
ebf390

Note que a URL da REST API é montada utilizando:

- {{environmen}}t = pegada
- {{skuId}} = Código do SKU
- {{warehouseId}} = ID do estoque criado no Admin VTEX

Método: Update Inventory By Sku and Warehouse

http://logistics.{{environment}}.com.br/api/logistics/pvt/inventory/skus/{{skuI
d}}/warehouses/{{warehouseId}}?an={{accountName​}}

Sample Request:

curl --request PUT \

--url
'http://logistics.{{environment}}.com.br/api/logistics/pvt/inventory/skus/{{skuId}}/warehouses/{{war
ehouseId}}?an={{accountName}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--data '{
"unlimitedQuantity": false,
"dateUtcOnBalanceSystem": null,
"quantity": 101
}'

Integração de Preço

Este método irá criar ou atualizar o preço de um SKU.

Mais detalhes em:
https://documenter.getpostman.com/view/101975/pricing-vault/6YsWxKT#45e96a27-2f96-f2d3-7
4b2-9d7b0be0c53a

ATENÇÃO: no body da request PUT é necessário informar o número da Política Comercial para
qual o item será vendido, caso ele esteja disponível em mais de uma Política.

Método(s): Create / Edit Price

https://api.vtex.com/{{account}}/pricing/prices/{{itemId​}}
Sample Request

curl --request PUT \

--url 'https://api.vtex.com/{{account}}/pricing/prices/{{itemId}}' \
--header 'Accept: application/vnd.vtex.pricing.v3+json' \
--header 'Content-Type: application/json' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--data '{
"listPrice": 300,
"costPrice": 100,
"markup": 50,
"fixedPrices": [
{
"tradePolicyId": "9",
"value": 300,
"listPrice": null,
"minQuantity": 1
},
{
"tradePolicyId": "9",
"value": 280.00,
"listPrice": null,
"minQuantity": 1,
"dateRange": {
"from": "2017-12-07T14:30:00Z",
"to": "2017-12-30T14:30:00Z"
}
}
]
}'

Integração de Pedido (OMS)

A integração de Pedidos acontece por etapas, e é necessário utilizar um método de REST
específico para cada etapa do processo de pedido.

Vamos olhar com mais detalhes cada um dos passos da integração de pedido.

Download de pedido

A primeira coisa que você precisa para o download de um pedido é saber o momento certo de
fazer isso. Para ajudá-lo nessa tarefa, a VTEX oferece o Feed de pedidos. Esse serviço informa
mudanças importantes no workflow do pedido, especialmente mudanças no status dos pedidos.

Após decidir que é hora de levar um pedido para sua plataforma de fulfillment, você precisa
apenas fazer o download dos detalhes desse pedido e dizer ao feed que ele não precisa lhe
enviar aquele evento novamente, uma vez que seu interesse nele terminou.

No fim, para os pedidos processados, você envia ao OMS uma mensagem de “Start Handling”.

Veja mais em:

http://help.vtex.com/pt/tutorial/guia-de-integracao-de-erps-pedidos
https://documenter.getpostman.com/view/487146/oms/6tjSKqi
Chamadas de API

1. Take feed event:

https://documenter.getpostman.com/view/487146/oms/6tjSKqi#49ba56c0-0358-4579-b99e-ad33
0bfc37d0
curl --request GET \
--url
'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/feed/orders/status?maxLot={{ma
xLot}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}’
 
2. Get order detail:
https://documenter.getpostman.com/view/487146/oms/6tjSKqi#43524211-bbed-4f80-9a9b-d96b3
2347f0a
curl --request GET \
--url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}'
 
3. Status change: start handling:
https://documenter.getpostman.com/view/487146/oms/6tjSKqi#d1f4d8fb-1173-4a1e-8a55-38ed5
521704e
Você também verá essa chamada em outros passos do processo de integração, com a mudança
apenas do evento-alvo.
É muito importante chamar a transição “start handling”, já que essa é a operação que liga o
pedido e a contagem de estoque com a reserva de estoque no módulo de logística da VTEX.
curl --request POST \
--url
'http://{{accountname}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/changestate/st
arthandling' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}'
 
4. Ack feed:
https://documenter.getpostman.com/view/487146/oms/6tjSKqi#1befe019-2219-40ad-b693-ff16aa
f51d84
curl --request POST \
--url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/feed/orders/status/confirm'
\
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
--data '[
{
"commitToken":
"Marketplace##{\"Receipt\":\"+eXJYhj5rDqHa28+XUcfebDO4pve3TvMpPlW0ivc5STyE/
40J6wxooXgBF8LZ9CdhZkFJnMYBVDwPwQtNEoZQrVtErDB2Yq2zs16QqsJuYxSrQtBfl9rMfmk
O5orB9oDHSpvwL6DjDzcuJeQBBNxono/
m4F6BloJEsk9BmuTmPaRI+7xsrN5Oeg8NPUoNSnsT983JPr1B+Y+TbbFjC1R8ZkvFHGVfti1Qb
hOwmYWTHPG08YMqla+Qwh7kUONLBXPqpo
rF/CcqJo5YVTSu2uBcCuXkUo+OH9uUTn6hHkUROo=\",\"PublisheId\":\"C0111A50CEB244E59
C95422870127A4F\",
\"PublisheId_Item\":\"C0111A50CEB244E59C95422870127A4F\",\"EventId\":\"0dc05b6b-48a5-4f
03-975aa69fb6550aaa\",\"
LastSendOverwrite\":null}"
}
]'

Fatura

Agora o pedido está sendo processado por sua plataforma de fulfillment. Durante esse processo,
você pode precisar fazer mudanças no pedido original, seja por conta de ruptura de estoque,
seja por outra razão qualquer. Você pode desejar remover, adicionar ou alterar ítens, causando
ou não mudanças no valor do pedido.
Quando você estiver pronto para a entrega do pedido, é hora de informar isso à VTEX. Assim, a
autorização de pagamento poderá ser capturada e o consumidor será notificado sobre o
progresso.
 
  
   
Chamadas de API

1. Enviar mudanças para a loja:

A variável {{status}} deverá seguir ​esta tabela​, de acordo com os status da coluna API REST.
https://documenter.getpostman.com/view/487146/oms/6tjSKqi#4701480a-d95f-4279-9e9d-da256
ee8ea5c
curl --request POST \
--url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/changes'
\
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
--data '{
"reason": “Promotion by phone.”,
"discountValue": 1000,
"incrementValue": 0,
"itemsRemoved": [
{
"id": "234794",
"price": 600,
"quantity": 2
}
],
"itemsAdded": [
{
"id": "234788",
"price": 200,
"quantity": 1
}
]
}’
2. Enviar fatura para a loja:
https://documenter.getpostman.com/view/487146/oms/6tjSKqi#102391a1-346d-4fa8-91fe-b1170
6922a77
curl --request POST \
--url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/invoice'
\
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
--data '{
"type":"Output",
 "issuanceDate":"2010-01-31",
"invoiceNumber":"9999",
"invoiceValue":"10000",
"invoiceKey": null,
"invoiceUrl": null,
"courier": null,
"trackingNumber": null,
"trackingUrl": null,
"items": [
{
"id": "1234",
"price": 10000,
"quantity": 1
}
]
}’

Rastreamento de pedido

A última etapa do seu gerenciamento de pedido é enviar informações de rastreamento do pedido

à VTEX.

Embora não seja um passo necessário para que o pedido chegue ao consumidor, esta é uma
das funcionalidades mais importantes para uma boa experiência do usuário. Não há nada como
saber com precisão a localização do produto comprado.

Não há limite para o número de mensagens de rastreamento que podem ser adicionadas a uma
fatura. Normalmente, é adicionada uma mensagem para cada evento de rastreamento até que
os itens sejam entregues ao comprador. No caso de produtos digitais, este último evento seria a
URL para download.

É importante ressaltar que essa informação é, na verdade, um conjunto de atributos de uma

fatura. Portanto, pode ser enviada junto à fatura, no momento de envio à loja, caso você tenha
essa informação nessa etapa.
Chamadas de API

1. Enviar informação de entrega à loja:

https://documenter.getpostman.com/view/487146/oms/6tjSKqi#2bc08480-cc43-4126-8368-6508a
4358d28
curl --request PATCH \
--url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/invoice/
{{invoiceNumber}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
--data '{
"trackingNumber": "87658",
"trackingUrl": "https://my.tracking.url/package",
"courier": "WorldEx"
}’
2. Enviar mensagens de rastreamento à loja:
https://documenter.getpostman.com/view/487146/oms/6tjSKqi#97ec170c-076e-4347-870b-14370
4124e17
curl --request PUT \
--url http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/invoice/
{{invoiceNumber}}/tracking \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
--data '{
"isDelivered": true,
"events": [
{
"city": "Rio de Janeiro",
"state": "RJ",
"description": “Left the distribution center.”,
"date": "2015-06-23"
},
{
"city": "Sao Paulo",
"state": "SP",
"description": “On its way to Curitiba.”,
"date": "2015-06-24"
}
]
}’

Passo extra: Cancelamento de pedido

Quando, por algum motivo operacional, você precisar cancelar o pedido sendo processado, você
pode enviar uma mensagem de cancelamento ao workflow do OMS. Se o pedido estiver em um
status que não permite cancelamento, aparecerá um erro.
Atenção: pedidos com fatura não podem ser cancelados.
Chamada de API

https://documenter.getpostman.com/view/487146/oms/6tjSKqi#8e74afca-431d-413e-92ad-01710
2abdbe2
curl --request POST \
--url 'http://{{accountName}}.{{environment}}.com.br/api/oms/pvt/orders/{{orderId}}/cancel' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
--header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}'