Documento de Integração

ACESSO RÁPIDO

 

 

INBOUND

1. Enviar produtos com preço único. 1

2. Enviar produtos com múltiplos preços. 1

3. Atualizar status de pedido. 1

4. Atualizar produtos de pedido. 1

5. Enviar novos clientes. 1

6. Atualizar status de clientes. 1

 

 

OUTBOUND

1. Recuperar lista de pedidos. 1

2. Recuperar dados de pedido

 

DOCUMENTO DE INTEGRAÇÃO

v1.7.0

 

 

A API de Integração do Fornecedor permite sincronizar produtos e pedidos do ERP do Fornecedor com a plataforma de comércio eletrônico do VENDDOR.

 

Considerando a possibilidade de eventos bidirecionais, a plataforma de integração do VENDDOR disponibiliza duas API’s, a API Inbound e a API Outbound, que são responsáveis pelos eventos de negócio.

 

 

Inbound:v1.7.0

 

A API Inbound utiliza o protocolo HTTPS como transporte disponibilizando 05 (cinco) recursos RESTFul.

 

Os recursos inbound (entrada) são responsáveis por sincronizar eventos de negócio que precisam ser criados ou atualizados na plataforma VENDDOR.

 

A media padrão é application/json.

 

 

Outbound:v1.7.0

 

A API Outbound utiliza o protocolo HTTPS como transporte disponibilizando 02 (dois) recursos RESTFul.

 

Os recursos outbound (saída) são responsáveis por recuperar informações de pedidos da plataforma VENDDOR.

 

A media padrão é application/json.

 

 

Ambientes

 

URL de Desenvolvimento: https://integracao-dev.venddor.com.br/

 

URL de Produção: https://integracao.venddor.com.br/

 

 

Credenciais de acesso

 

O usuário e a senha devem ser solicitados diretamente pelo Fornecedor ao analista comercial responsável pelo seu onboarding na plataforma.

 

 

 

INBOUND

v1.7.0


 

1. Enviar produtos com preço único

 

Caso

Path

Verb

Objetivo

1

/catalog

POST

Enviar os produtos com preço único que serão armazenados e sincronizados na plataforma VENDDOR

  

EXEMPLO:

 

REQUEST

 

curl --location --request POST 'https://49.12.98.124:8243/inbound/catalog' \

--header 'Authorization: Basic base64(usuario:senha)' \

--header 'Content-Type: application/json' \

--data-raw '{

    "products" :[

        {

            "ean" : "7891000071014",

            "ncm" : "18069000",

            "name" : "Nestlé Sensação",

            "brand" : "NESTLE",

            "weight" : "4500",

            "price" : "17.23",

            "amount" : "23",

            "qty_step" : "1",

            "status" : "1",

            "number" : "1",

            "last" : false

        }

    ]

}'

 

 

RESPONSE - SUCESSO

 

{

    "Response": "1.0" // Representa a quantidade de produtos em fila de sincronismo

}

 

 

RESPONSE - FALHA

 

{

    "Response": "object has missing required properties ([\"amount\"])"

}

 

  

REGRAS:

 

·      O cabeçalho  ‘Authorization’ deve ser do tipo Basic e o conteúdo deve ser

usuario + : + senha no formato base64.

 

·      Devem ser enviados no máximo 60 produtos por requisição. Ex: Caso seja necessário atualizar 240 produtos, deve efetuar 4 requisições com 60 produtos cada.

 

·      Informações obrigatórias:

o   Ean (código universal do produto)

o   amount (quantidade que deve ficar disponível na plataforma)

o   status (informa se a plataforma deve adicionar/atualizar o produto ou remover )

o   name (nome do produto)

o   price (valor unitário do produto)

 

·      Informações desejáveis:

o   internal_product_code (número interno do produto no sistema de gestão do fornecedor).

o   quantity_per_package  (quantidade de unidades por embalagem/fardo. Se maior do que um, o cliente também terá a opção de comprar a embalagem fechada além de comprar por unidade)

o   qty_step (múltiplo de unidades do produto que o cliente pode adquirir).

o   last (Informa ao processador que não serão mais enviados produtos).

o   number  (pode ser um número de controle sequencial e único ou o ID interno do produto do fornecedor)

 

 

 

 

2. Enviar produtos com múltiplos preços

 

Caso

Path

Verb

Objetivo

2

/catalog

POST

Enviar os produtos com que serão armazenados e sincronizados na plataforma VENDDOR, quando o fornecedor possui mais de uma tabela de preços (perfis de clientes) e/ou oferece descontos em quantidade

  

EXEMPLO:

 

REQUEST

 

curl --location --request POST 'https://49.12.98.124:8243/inbound/catalog' \

--header 'Authorization: Basic base64(usuario:senha)' \

--header 'Content-Type: application/json' \

--data-raw '{

    "products" :[

        {

            "ean" : "7891000071014",

            "ncm" : "18069000",

            "name" : "Nestlé Sensação",

            "brand" : "NESTLE",

            "weight" : "4500",

            "price" : "17.23",

            "amount" : "23",

            "status" : "1",

            "last" : false,

            "prices" : [

                {

                    "lower_limit" : "1",

                    "usergroup_id" : "109",

                    "price" : "26.85",

                },

                {

                    "lower_limit" : "50",

                    "usergroup_id" : "110",

                    "price" : "26.80"

                }

            ],

            "internal_product_code" : "567",

            "quantity_per_package" : "30",

            "last" : false,

            "number" : "1"

        }

    ]

}'

 

 

RESPONSE - SUCESSO

 

{

    "Response": "1.0" // Representa a quantidade de produtos em fila de sincronismo

}

 

 

RESPONSE - FALHA

 

{

    "Response": "object has missing required properties ([\"amount\"])"

}

 

  

REGRAS:

 

·      O cabeçalho  ‘Authorization’ deve ser do tipo Basic e o conteúdo deve ser

usuario + : + senha no formato base64.

 

·      Devem ser enviados no máximo 60 produtos por requisição. Ex: Caso seja necessário atualizar 240 produtos, deve efetuar 4 requisições com 60 produtos cada.

 

·      Informações obrigatórias:

o   Ean (código universal do produto)

o   amount (quantidade que deve ficar disponível na plataforma)

o   status (informa se a plataforma deve adicionar/atualizar o produto ou remover )

o   name (nome do produto)

o   price (valor padrão unitário do produto que será exibido para os lojistas que não pertençam a nenhuma tabela de preço, ou caso não seja preenchida a condicionante de quantidade mínima estabelecida no array prices)

 

·      Informações obrigatórias no array prices:

o   lower_limit (quantidade mínima que deve ser adquirida do produto para o preço ser exibido. Se o fornecedor não deseja oferecer preços diferenciados por quantidade, deve ser enviado "lower_limit": "1" obrigatoriamente)

o   usergroup_id (identificador do perfil do lojista, informado pelo Venddor, ao qual o preço do produto no array ficará condicionado. Se o fornecedor não deseja oferecer preços diferenciados por perfil de cliente, deve ser enviado "usergroup_id":"0" obrigatoriamente)

o   price (preço unitário do produto que será exibido para o lojista que fizer parte do perfil indicado no usergroup_id desde que respeitada a quantidade mínima para compra, indicada no lower_limit)

 

·      Informações desejáveis:

o   internal_product_code (número interno do produto no sistema de gestão do fornecedor).

o   quantity_per_package  (quantidade de unidades por embalagem/fardo. Se maior do que um, o cliente também terá a opção de comprar a embalagem fechada além de comprar por unidade)

o   last (informa ao processador que não serão mais enviados produtos).

o   number (pode ser um número de controle sequencial e único ou o ID interno do produto do fornecedor)

 

 

 


3. Atualizar status de pedido


 

Caso

Path

Verb

Objetivo

3

order/{orderId}

PUT

Atualizar status de um determinado pedido no VENDDOR (orderId).

 

EXEMPLO:

 

REQUEST

 

curl --location --request PUT 'https://49.12.98.124:8243/inbound/order/130023' \

--header 'Authorization: Basic base64(usuario:senha)' \

--header 'Content-Type: application/json' \

--data-raw '{

    "order" :

        {

            "status" : "O"

        }

}'

 

 

RESPONSE - SUCESSO

 

{

    "Response": "1.0" // Representa a quantidade de  pedidos na fila de atualização

}

 

 

RESPONSE - FALHA

 

{

    "Response": "object has missing required properties ([\"status\"])"

}

 

 

  

REGRAS:

 

·      O cabeçalho  ‘Authorization’ deve ser do tipo Basic e o conteúdo deve ser

usuario + : + senha no formato base64.

 

·      Informações obrigatórias:

o   status (novo status para o pedido)

 

·      Valores possíveis:

 

P

Em preparação

H

Despachado

G

Solicitado cancelamento

E

Enviado ao fornecedor

A

Pendente aceite do cliente

Y

Pagamento em atraso

I

Cancelado

B

Aguardando estoque

D

Pagamento negado

F

Erro

O

Em aberto

C

Finalizado

J

Cancelamento negado

 

 



4. Atualizar produtos de pedido



Caso

Path

Verb

Objetivo

4

order/{orderId}

PUT

Atualizar os produtos de um determinado pedido no VENDDOR (orderId).

 

EXEMPLO:

 

REQUEST

 

curl --location --request PUT 'https://49.12.98.124:8243/inbound/order/3986' \

--header 'Authorization: Basic base64(usuario:senha)' \

--header 'Content-Type: application/json' \

--data-raw '{

    "products" :  {

                      "7891522020026" : {

                                "amount" : "6"

                            },

                      "3228020191349" : {

                                "amount" : "7"

                            }

                  }

            }'

 

 

RESPONSE - SUCESSO

 

{

    “order_id”: “3986”

}

 

 

RESPONSE - FALHA

 

{

    "Response": "object has missing required properties ([\"amount\"])"

}

 

 

REGRAS:

 

·      O cabeçalho  ‘Authorization’ deve ser do tipo Basic e o conteúdo deve ser

usuario + : + senha no formato base64.

 

·      Informações obrigatórias:

o   product_code (enviado como chave dentro de “products”)

o   amount (nova quantidade do produto no pedido)

 

·       ATENÇÃO: Se um pedido tiver vários produtos, certifique-se de especificar todos eles ao atualizar o pedido com a solicitação PUT. Os produtos não especificados na solititação PUT serão removidos do pedido.


 



5. Enviar novos clientes



Caso

Path

Verb

Objetivo

5

/customer

POST

Criar a lista de clientes do fornecedor na plataforma VENDDOR

 

EXEMPLO:

 

REQUEST

 

curl --location --request PUT 'https://49.12.98.124:8243/inbound/customer' \

--header 'Authorization: Basic base64(usuario:senha)' \

--header 'Content-Type: application/json' \

--data-raw '{

  "email": "[email protected]", 

  "CNPJ": "27876999000144",

  "trade_name": "Nome Fantasia",

  "company": "Razão Social",

  "segmento": 12,

  "phone": "(11)99421-4743",

  "cnae_principal": "123456",

  "inscricaoestadual": "12345678",

  "indicador_inscricao_estadual_des": 3,

  "responsavel": "Nome da pessoa responsável",

  "s_address": "Nome da Rua, 333",

  "s_state": "Sergipe",

  "s_city": "Aracaju",

  "s_district": "Bairro",

  "s_zipcode": "59008-350",

  "s_phone": "(79)3222-8899"

}'

 

 

RESPONSE - SUCESSO

 

{

    "status": "true",

    "user_id": "3753"

}

 

 

RESPONSE - FALHA

 

{

   "status": "false"

   "message": "Bad request: O usuário ou e-mail que você escolheu já existe. Tente outros dados."

}

 

 

REGRAS:

 

·      O cabeçalho  ‘Authorization’ deve ser do tipo Basic e o conteúdo deve ser usuario + : + senha no formato base64.

 

·      Informações obrigatórias:

o   email (endereço de e-mail do lojista)

o   CNPJ (número do CNPJ do lojista - apenas números)

o   trade_name (nome fantasia do lojista)

o   company (razão social do lojista)

o   segmento (segmento de atuação do lojista)

o   phone (telefone do lojista - preferencialmente celular)

o   cnae_principal (número do CNAE principal do lojista - apenas números)

o   inscricaoestadual (número da inscrição estadual do lojista - apenas números)

o   indicador_inscricao_estadual_des (informa se o lojista é ou não contribuinte de ICMS)

o   responsavel (nome da pessoa responsável pelo contato no lojista)

o   s_address (nome da rua e número do endereço de entrega do lojista)

o   s_state (estado do endereço de entrega do lojista)

o   s_city (cidade do endereço de entrega do lojista)

o   s_district (bairro do endereço de entrega do lojista)

o   s_zipcode (número do CEP do lojista no formato 55555-555)

 

·      O campo segmento deve ser enviado com um dos seguintes valores numéricos:

 

4

Bancas, Gráficas e Papelarias

5

Bares, Restaurantes, Lanchonetes e Padarias

6

Casa e Construções

7

Farmácias, Clínicas Médicas e Perfumarias

8

Informática, Games e Eletrônicos

9

Mercados e Empórios

10

Oficinas Mecânicas e Assistências

11

Prestadores de Serviço

12

Roupas, Calçados e Acessórios

13

Salões de Beleza, Clínicas Estéticas e Spa

14

Veterinárias e Petshops

15

-

 

·      O campo indicador_inscricao_estadual_des deve ser enviado com um dos seguintes valores numéricos:

 

1

Contribuinte de ICMS

2

Não-Contribuinte de ICMS

3

Isento de Inscrição

 

·      Informações adicionais:

o   Somente é possível o envio de 01 (um) lojista novo por request

o   Caso o lojista já esteja cadastrado na plataforma Venddor, não será criado um novo cadastro para fins de evitar duplicidade. Todavia, o cadastro já existente do lojista será vinculado à cartela de clientes do fornecedor.


 



6. Atualizar status de clientes



Caso

Path

Verb

Objetivo

6

/customer

PUT

Atualizar os dados de clientes do fornecedor na plataforma VENDDOR

 

EXEMPLO:

 

REQUEST

 

curl --location --request PUT 'https://49.12.98.124:8243/inbound/customer' \

--header 'Authorization: Basic base64(usuario:senha)' \

--header 'Content-Type: application/json' \

--data-raw '{

   "customer": [

      {

         "33333333333":false,

         "limit":"47894.01"

         "payments": [

            {

               "code":"CARX",

               "status":0

            },

            {

               "code":"DINH",

               "status":"1

            }

         ],

         "usergroups": [

            {

                "code":"51"

                "status":"1"

            }

         ]

      },

      {

         "08303882000181":true,

         "limit":"87598.35"

      }

   ]

}'

 

 

RESPONSE - SUCESSO

 

{

    {"result": "true"}

}

 

 

RESPONSE - FALHA

 

{

   {"result": "false"}

}

 

 

REGRAS:

 

·      O cabeçalho  ‘Authorization’ deve ser do tipo Basic e o conteúdo deve ser usuario + : + senha no formato base64.

 

·      Informações obrigatórias:

o   status de bloqueio - lista dos CNPJ’s e boolean com o respectivo status de bloqueio

 

·      Informações complementares:

o   limit - valor máximo que o cliente pode ter em aberto junto ao fornecedor (referentes às compras ainda não finalizadas) para que possa efetuar um novo pedido. O número deve ser passado utilizando ponto (e não vírgula) como separador das casas decimais. No valor do limite enviado, já devem ser subtraídos os montantes referentes aos pedidos em aberto. Caso nenhum valor seja enviado, será atribuído ao lojista o valor padrão de R$ 99.999.999,00.

 

·      Valores possíveis para os status de bloqueio:

o   true – Indica que o cliente está bloqueado

o   false – Indica que o cliente não está bloqueado (portanto, está apto para compra, caso tenha limite disponível)

 

·      Informações adicionais

o   Recomendamos o envio de no máximo 50 CNPJ por request




OUTBOUND

v1.7.0


 

1. Recuperar lista de pedidos

 

 

Caso

Path

Verb

Objetivo

1

/orders?status={statusId}

&page={pageNumber}

GET

Recuperar pedidos da plataforma VENDDOR de forma paginada com base no status

 

EXEMPLO:

 

REQUEST

 

curl --location --request GET 'https://49.12.98.124:8243/outbound/orders?status=C' \

--header 'Authorization: Basic base64(usuario:senha)' \

--header 'Accept: application/json'

 

 

RESPONSE - SUCESSO

 

{

    "orders": [

        {

            "order_id": "3974",

            "timestamp": "1614132087",

            "firstname": "João da Silva",

            "lastname": "Bezerra",

            "email": "[email protected]",

            "phone": "(11)98800-0000",

            "status": "C",

            "total": "56.85"

        },

        {

            "order_id": "3973",

            "timestamp": "1614132078",

            "firstname": "Maria da Silva",

            "lastname": "Xavier",

            "email": "[email protected]",

            "phone": "(12)93456-7890",

            "status": "C",

            "total": "61.98"

        }

    ],

    "params": {

        "page": 1,

        "items_per_page": 20,

        "total_items": "2"

    }

}

 

 

RESPONSE - FALHA

 

{

    "Response": "object has missing required properties ([\"status\"])"

}

 


REGRAS:

 

·      O cabeçalho  ‘Authorization’ deve ser do tipo Basic e o conteúdo deve ser

usuario + : + senha no formato base64.

 

·      São limitados 20 registros por solicitação.

 

·      Informações obrigatórias:

o   status (novo status para o pedido)

o   page (página com o limite de 20 registros)

 

·      Valores possíveis do status:

 

P

Em preparação

H

Despachado

G

Solicitado cancelamento

E

Enviado ao fornecedor

A

Pendente aceite do cliente

Y

Pagamento em atraso

I

Cancelado

B

Aguardando estoque

D

Pagamento negado

F

Erro

O

Em aberto

C

Finalizado

J

Cancelamento negado

 

 

 

 

2. Recuperar dados de pedido



Caso

Path

Verb

Objetivo

2

/orders/{orderId}

GET

Recuperar dados de um determinado pedido na plataforma VENDDOR

 

EXEMPLO:

 

REQUEST

 

curl --location --request GET 'https://49.12.98.124:8243/outbound/orders/3974' \

--header 'Authorization: Basic base64(usuario:senha)' \

--header 'Accept: application/json'

 

 

RESPONSE - SUCESSO

 

{

    "order_id": "3974",

    "total": "56.85",

    "subtotal": 46.85,

    "discount": 0,

    "subtotal_discount": 0,

    "shipping_ids": "",

    "shipping_cost": "0.00",

    "timestamp": "1614132087",

    "status": "C",

    "notes": "",

    "details": null,

    "firstname": "João da Silva",

    "lastname": "Bezerra",

    "b_firstname": "João da Silva",

    "b_lastname": "Bezerra",

    "b_address": "Rua Quinze de Novembro, 2000",

    "b_address_2": "",

    "b_city": "Natal",

    "b_county": "",

    "b_state": "RN",

    "b_country": "BR",

    "b_zipcode": "",

    "b_phone": "(11)99090-9999",

    "s_firstname": "",

    "s_lastname": "",

    "s_address": "Rua Quinze de Novembro, 2000",

    "s_address_2": "",

    "s_city": "São Paulo",

    "s_county": "Bairro Vila Velha",

    "s_state": "SP",

    "s_country": "BR",

    "s_zipcode": "",

    "s_phone": "",

    "s_address_type": "",

    "phone": "(12)98484-1234",

    "fax": "",

    "url": "",

    "email": "[email protected]",

    "payment_id": "0",

    "tax_exempt": "N",

    "fields": {

        "56": "23.423.423/0001-33",

        "67": "testando"

    },

    "products": {

        "515131976": {

            "item_id": "515131976",

            "product_code": "7891000140307",

            "price": "12.81",

            "amount": "1",

            "product": "Leite Em Pó Integral Ninho 400g",

            "product_status": "A",

            "discount": 0,

            "base_price": 12.81,

            "original_price": 12.81,

            "tax_value": 0,

            "subtotal": 12.81,

            "shipped_amount": 0,

            "shipment_amount": "1"

        },

        "1773370078": {

            "item_id": "1773370078",

            "product_code": "7891000244265",

            "price": "2.79",

            "amount": "1",

            "product": "Iogurte Parcialmente Desnatado Morango Nestlé Frasco 170g",

            "product_status": "A",

            "discount": 0,

            "base_price": 2.79,

            "original_price": 2.79,

            "tax_value": 0,

            "subtotal": 2.79,

            "shipped_amount": 0,

            "shipment_amount": "1"

        }

    },

    "taxes": [],

    "tax_subtotal": 0,

    "b_country_descr": "Brasil",

    "s_country_descr": "Brasil",

    "b_state_descr": "Rio Grande do Norte",

    "s_state_descr": "Rio Grande do Norte"

}

 


RESPONSE - FALHA

 

{

    "Response": "object has missing required properties ([\"orderId\"])"

}

 

 

REGRAS:

 

·      O cabeçalho  ‘Authorization’ deve ser do tipo Basic e o conteúdo deve ser

usuario + : + senha no formato base64.

 

·      Informações obrigatórias:

            orderId ( identificador do pedido )

 

·      Valores possíveis do status:

 

P

Em preparação

H

Despachado

G

Solicitado cancelamento

E

Enviado ao fornecedor

A

Pendente aceite do cliente

Y

Pagamento em atraso

I

Cancelado

B

Aguardando estoque

D

Pagamento negado

F

Erro

O

Em aberto

C

Finalizado

J

Cancelamento negado

 

 

 

Adicionar itens selecionados ao carrinho