NAV
shell

Introdução

API de integração para ERP's

Atualmente a API de integração disponível opera através da tecnologia REST, recebendo e enviando informações estruturadas em JSON, sendo possível ser realizada em duas partes, a carga de produtos para a Instabuy, e o registro da compra no ERP do cliente. A autenticação da API é realizada através da API key de seu e-commerce, bastando enviar a api-key no header para efetuar as requisições.

Para visualizar outros documentos click no link abaixo:

A documentação detalhada de produtos pode ser visualizada no link abaixo:

URL de integração

Todas as requisições necessárias para integrações podem ser realizadas através da url https://api.instabuy.com.br/store, esta url pode ser utilizada tanto para desenvolvimento quanto para produção conforme a API key.

Formato de requisições e resposta

O padrão de resposta é o formato JSON, Requisições que possuem dados no corpo da mensagem devem utilizar o formato JSON para definir ou atualizar atributos a serem enviados. Requisições bem sucedidas retornarão o status da requisição HTTP igual a 200 OK.

Algumas informações gerais sobre as respostas para requisições:

Formato de resposta

Todas as resposta do servidor possuem quatro campos, são eles: status, data, count, http_status.

Status

O campo status pode retornar "sucess" ou "error", Sucesso será enviado quando a operação feita pela requisição foi bem sucedida de todas as maneiras. Erro será enviado quando o resultado esperado não tiver sido alcançado durante o processo.

Data

A própria informação. Esta informação pode ser: uma mensagem de erro caso o status seja de erro, ou pode ser uma lista, um objeto, um texto, etc. caso o status seja de sucesso.

Count

O número de objetos que a consulta deve retornar se um filtro de paginação estiver aplicado.

HTTP Status

A situação da resposta do protocolo HTTP.

Errors

Ocasionalmente você pode encontrar erros enquanto estiver acessando a API REST, Abaixo estão alguns dos tipos possíveis:

Código de erro Tipo de erro
211 Unauthorized Você está tentando acessar um endpoint protegido mas não tem permissão.
212 User Blocked Você foi bloqueado pelo sistema.
213 Not Found Consulta não retornou nenhum resultado.
214 Expected Error Erro esperado, exemplo: sistema não pode salvar o item pois o slug não é único.
401 Unauthorized Você está tentando acessar um endpoint protegido mas não está logado.
404 Not Found Requisição para recursos que não existem ou estão em falta.
405 Method Not Allowed Você está tentando acessar um endpoint com um método inválido.
500 Internal Server Error Erro interno no servidor.

Tutorial de integração

Envio de carga de produtos para a Instabuy (primeira parte)

Exemplo de envio da requisição para a carga de produtos:

curl --location --request PUT 'https://api.instabuy.com.br/store/products' \
--header 'api-key: 5sLxK7hidl3LGCiDxyDNucbeY0OZEd99LKxXIT6l6zy' \
--header 'Content-Type: application/json' \
--data-raw '{
    "products": [
            {
                "internal_code": "788924-5",
                "visible": true,
                "stock": 5,
                "name": "Vinho Taparaca 750ml",
                "barcodes": ["123483209485"],
                "price": 12.90,
                "promo_price": 9.90,
                "promo_start_at": "2020-03-31T00:00:00.000000-03:00",
                "promo_end_at": "2020-03-31T23:59:59.000000-03:00"
            }
        ]
}'

A primeira parte da integração é a carga dos produtos na loja, esta carga deve ser realizada através do end-point: /products. Deve-se enviar uma lista de produtos, sendo necessário uma chave de autenticação devidamente inserida no cabeçalho da requisição através do campo api-key. Como já citado anteriormente, o conteúdo bruto deve estar no formato json.

Para cada produto, deve-se especificar:

Campo Descrição Tipo Exemplo
internal_code O Código interno do produto, deve ser um identificador único cadastrado em seu ERP Campo de texto "12345-6"
name O nome, a descrição do produto, recomenda-se enviar a gramatura do produto junto a descrição Campo de texto "Arroz TIO JORGE Integral 5KG"
unit_type Indica se é um produto de peso variável ou unitário. Para produtos de peso enviar o valor KG, para produtos unitários enviar UNI Campo de texto "UNI"
price O preço do produto, recomenda-se enviar um campo de ponto flutuante Número real 12.50
visible A visibilidade do produto na loja, deve-se enviar true ou false, a visibilidade indicará se o produto deve ou não ser visível para venda Campo boleano true
stock A quantidade em estoque do produto, pode-se enviar um campo flutuante. Nao enviar numeros negativos. Caso o estoque seja negativo em seu sistema, envie estoque igual a 0. Número real 1.5
barcodes Uma lista com os códigos de barra do produto, o código de barras será utilizado por exemplo para atualizar a imagem do produto automaticamente Lista de campos de texto, os códigos de barras devem estar em um dos formatos: EAN8, EAN12, EAN13 ["7891000023808"]
promo_price O preço promocional do produto, deve-se enviar um campo flutuante, ao enviar este campo deve-se especificar o início e fim da promoção Número real 12.50
promo_start_at A data de ínicio para validade do preço promocional, indica quando o preço promocional começa a valer Campo de texto, a data deve estar no padrão ISO 8601 "2022-01-24T17:59:14.035182"
promo_end_at A data de fim do preço promocional, a data em que o preço promocional para de valer Campo de texto, a data deve estar no padrão ISO 8601 "2022-01-24T17:59:14.035182"

Retorno da carga de produtos

Exemplo de resposta bem sucedida da requisição:

{
    "data": {
        "status": "success",
        "count": 1,
        "updated": 1,
        "registered": 1
    },
    "status": "success",
    "count": 1,
    "http_status": 200
}

O retorno é imediato, não havendo nenhuma fila para criar ou atualizar produtos, a requisição tem como resposta além dos campos já citados, as seguintes informações dentro do atributo data:

Descrição Campo Tipo
Resumo de sucesso ou erro, o resultado pode ser "sucess" ou "error" status Campo de texto
A quantidade de produtos reconhecidos count Número inteiro
A quantidade de novos produtos registrados registered Número inteiro
A quantidade de produtos atualizados, (produtos com o mesmo código e atributos diferentes) Updated Número inteiro

Atualização de produtos

A atualização dos produtos ocorre quando um produto é enviado com o mesmo código interno, a maioria dos campos com dados divergentes serão atualizados, com a exceção do campo nome, que será mantido para preservar as alterações realizadas no painel do admin.

Inativação de produtos

Caso um produto seja desativado por qualquer motivo, para inativar este produto no e-commerce deve-se enviar novamente o produto com o campo visible igual a false.

Limite de envio

A API de produtos possui um limite de 60 segundos de tempo de espera, devido a este motivo recomenda-se enviar no máximo mil produtos por requisição.

Registro da compra no ERP do cliente (segunda parte).

Exemplo de consulta de compras:

curl --location --request GET 'https://api.instabuy.com.br/store/buys?status=erp_ready' \
--header 'api-key: 5sLxK7hidl3LGCiDxyDNucbeY0OZEd99LKxXIT6l6zy' \
--header 'Content-Type: application/json'

Resposta da consulta de compras:

{
    "data": [
        {
            "id": "61ae369c9974096e205ecf33",
            "creator": "unknown",
            "created_at": "2021-12-06T16:13:16+00:00",
            "last_modified": "2021-12-06T16:13:36+00:00",
            "_subtotal": 1.45,
            "_discount": 0.0,
            "_total": 9.45,
            "buy_type": "deli",
            "comment": "",
            "status": "ib_ready",
            "status_history": [
                {
                    "message": "Alteração de status: Esperando confirmação da loja -> Produtos separados",
                    "created_at": "2021-12-06T16:13:36+00:00",
                    "author": "acesso@exemplo.com",
                    "old_status": "ib_wait_auth",
                    "new_status": "ib_ready"
                }
            ],
            "code": "XXXX-XXXX",
            "store_id": "61a667573e71ad39f31a2947",
            "delivery_info": {
                "country": "BR",
                "zipcode": "70845-530",
                "state": "DF",
                "city": "Brasília",
                "neighborhood": "Exemplo",
                "street": "Quadra X Bloco X",
                "street_number": "1",
                "complement": ""
            },
            "delivery_tax": 8.0,
            "schedule": false,
            "products": [
                {
                    "id": "61a68e2310644442811c3eac",
                    "model_internal_code": "1591",
                    "name": "Produto teste",
                    "price": 1.45,
                    "image": "b6177cdd32864caaa1d6111dca174ea5.webp",
                    "qtd": 1.0,
                    "subcategory": "Subcategoria indefinida",
                    "model_id": "1040db6eb6394fd8",
                    "model_title": "default",
                    "unit_type": "UNI",
                    "bar_codes": [
                        "7898095296018"
                    ],
                    "replace": "best_match"
                }
            ],
            "kits": [],
            "client": {
                "id": "61a77cbc1f8ee46797e4eff0",
                "created_at": "2021-12-01T13:46:35+00:00",
                "last_modified": "2021-12-06T14:36:28+00:00",
                "user_type": "PF",
                "email": "exemplo@exemplo.com",
                "phone": "(99)99999-9999",
                "addresses": [
                    {
                        "id": "d25241",
                        "label": "Brasília",
                        "country": "BR",
                        "zipcode": "00000-000",
                        "state": "DF",
                        "city": "Brasília",
                        "neighborhood": "Exemplo",
                        "street": "Quadra X Bloco X",
                        "street_number": "1",
                        "complement": ""
                    }
                ],
                "first_name": "Cliente",
                "last_name": "cliente",
                "gender": "F",
                "cpf": "000.000.000-00",
                "birthday": "1999-02-24T12:00:00+00:00"
            },
            "client_ip": "1.1.1.1",
            "seen": true,
            "platform": "ib_web",
            "device": "Unknown;Windows;Chrome",
            "payment_info": {
                "method": "cash",
                "value": "9.45"
            },
            "billet_percent_discount": 0.0,
            "online_transactions": [],
            "has_cooled_items": false,
            "erp_id": 7103147,
            "_was_paid": false,
            "is_first_buy": false,
            "buys_count": 11,
            "subtotal": 1.45,
            "discount": 0.0,
            "freight": 8.0,
            "total": 9.45
        }
    ],
    "status": "success",
    "count": 1,
    "http_status": 200,
    "delivery_tax_internal_code": null
}

A segunda parte da integração consiste em buscar os pedidos prontos para serem inseridos na pré-venda do ERP.

A busca dos pedidos prontos pode ser realizada através do end-point: /buys, onde é possível especificar a situação da compra através do campo status, para buscar as compras prontas para serem inseridas no ERP deve-se utilizar o status erp_ready.

O próximo passo é processar todas as comprar e registrar no ERP, gerando uma compra no ERP, com os valores da compra, valores do frete, registro de produtos, registro do cliente, registro do endereço de entrega, quando disponível incluir o registro da data de agendamento da entrega bem como qualquer outro campo disponível que seja necessário para o ERP, sendo esse passo da integração diretamente dependente de como os dados são estruturados no ERP do cliente.

Após processar uma compra, deve-se atualizar sua situação no e-commerce, através do método PUT no end-point: /buys, passando os campos id e status direto na URL, onde o id indica a compra processada e o status deve ser igual a ib_invoice_issued para informar ao e-commerce que a compra já foi processada pelo o ERP.

Lembrando que nossa API é aberta e em ambos os casos é necessário informar a api-key através do cabeçalho da requisição para que seja realizada a autenticação da loja.

Exemplo de alteração do status do pedido:

curl --location --request PUT 'https://api.instabuy.com.br/store/buys?id=61ae369c9974096e205ecf33&status=ib_invoice_issued' \
--header 'api-key: 5sLxK7hidl3LGCiDxyDNucbeY0OZEd99LKxXIT6l6zy' \
--header 'Content-Type: application/json'

Relação dos dados de retorno do pedido

Campo Descrição Tipo Exemplo
id Identificador da compra, este deve ser uns dos campos enviados de volta para Instabuy para que o status do pedido seja alterado. Campo de texto "61ae369c9974096e205ecf33"
erp_id Id inteiro do pedido. Número inteiro 1
code Código do pedido no e-commerce. code Campo de texto
created_at Data de criação da compra, momento em que foi realizado o checkout. Data representada em texto no padrão ISO 8601. "2021-12-06T16:13:16+00:00"
subtotal Valor total dos produtos da compra, este valor não inclui o valor de frete. Número real 1.45
discount Desconto na compra. Número real 1.00
freight Valor do frete. Número real 1.00
total Valor total do pedido, este valor é igual ao subtotal + frete - desconto. Número real 9.45
buy_type Tipo de recebimento da compra, os tipos possíveis são: deli, coll, service, pac e sedex. Campo de texto "deli"
comment Comentário enviado para o cliente ao finalizar uma compra. Campo de texto "Ótima loja."
status O status atual da compra, lista dos status possíveis: buy-status-properties Campo de Texto "ib_ready"
delivery_info Informações sobre o local de entrega address {...}
schedule Entrega agendada, informa se a entrega está ou não agendada, exemplo para entrega agendada. Campo booleano true
delivery_hour Agendamento de entrega, este campo estará disponível caso o campo schedule seja igual a true delivery_hour {...}
products Produtos do pedido, veja as propriedades dos produtos: products Array [{...}, ...]
kits Kits de produtos, em geral não é utilizado em integrações com ERPs, propriedades do kit: buy-kit-propertie Array [{...}, ...]
client Informações do cliente user {...}
client_ip Ip do cliente. Campo de texto "1.1.1.1"
platform Identificador da plataforma do cliente em que a compra foi realizada, os possíveis valores são: store_web, ib_web, store_android, store_ios, ib_android, ib_ios, unknown Campo de texto "store_android"
device Identificador do dispositivo do cliente. Campo de texto "Unknown;Windows;Chrome"
payment_info informações sobre o pagamento buy-payment-info-properties {...}
has_cooled_items Informa a existência de produtos frios na compra. Campo booleano false
is_first_buy Indica se foi a primeira compra do cliente. Campo booleano true

Código do produto da taxa de entrega (delivery_tax_internal_code)

Para solucionar o problema de alguns ERP's que nao possuem campo apropriado para a inserção da taxa de entrega no pedido, possibilitamos que a mesma seja enviada como um produto dentro da lista de produtos. Este código pode ser definido no admin da Instabuy e solicitado através do parâmetro booleano send_delivery_tax_internal_code. Sendo assim, este código representa um produto que pode ser inserido na compra para substituir o campo de taxa de entrega. Para o retorno do código o parâmetro de solicitação deve receber o valor true.

Este procedimento só deve ser realizado quando o ERP não possui o lugar correto para inserção dos valores da taxa de entrega.

Local de entrega e Agendamento de entrega

Valor do frete

O valor do frete, CEPs aceitos e possibilidade do agendamento de entrega devem ser configurados diretamente no admin da Instabuy.

Valor dos produtos

O ERP deve aceitar o preço do produto enviado pela Instabuy. Ao gerar a nota fiscal, o produto deve ter como preço o valor recebido atraves da API da Instabuy e não o valor cadastrado no ERP. Nao modifique o preço do pedido!! Caso isso não seja seguido, o lojista terá problemas de conciliação bancária e de sonegação de impostos.

Perguntas frequentes

Exemplo de tradução de método de pagamento em Python:

def translate_payment_method(payment_method: str) -> str:
    if payment_method == 'credit': return 'Crédito' 
    elif payment_method == 'debit': return 'Débito' 
    elif payment_method == 'vale': return 'Vale' 
    elif payment_method == 'check': return 'Cheque' 
    elif payment_method == 'cash': return 'Dinheiro' 
    elif payment_method == 'deposit': return 'Depósito Bancário' 
    elif ‘_billet' in payment_method: return 'Boleto Bancário' 
    elif ‘pix' in payment_method: return 'PIX' 
    elif '_credit' in payment_method: return 'Crédito Online' 
    else:raise IBException('Unknown payment_method: ' + payment_method)
shell