Nada encontrado

E-shop API – visão geral

A E-shop API liga qualquer loja online à BulkGate. Através dela, a sua loja online comunica à BulkGate os eventos da loja: uma nova encomenda, uma alteração de estado, um pagamento, um novo cliente e outros. Para cada evento, o portal encontra a notificação configurada para a aplicação em causa, preenche no modelo as variáveis do pedido e envia a mensagem ao cliente, aos administradores da loja ou a ambos.

A própria API não define o texto da mensagem. Se não houver nenhuma notificação configurada para o evento, o pedido é aceite e nada é enviado.

Endpoints

Todos os endpoints aceitam POST no endereço https://portal.bulkgate.com/api/1.0/eshop/<área>/<ação>.

ENDPOINT EVENTO PÁGINA
eshop/order/new Nova encomenda Encomendas
eshop/order/change-status Alteração do estado da encomenda Encomendas
eshop/order/payment Pagamento da encomenda Encomendas
eshop/order/tracking-number Atribuição do número de seguimento Encomendas
eshop/order/product-cancel Cancelamento de um produto da encomenda Encomendas
eshop/order/slip-add Emissão de nota de crédito da encomenda Encomendas
eshop/customer/new Novo cliente Clientes
eshop/product/out-of-stock Produto esgotado Produtos
eshop/product/on-back-order Produto por encomenda Produtos
eshop/product/update-quantity Alteração da quantidade em stock Produtos
eshop/product/delete Eliminação do produto Produtos
eshop/return/new Nova devolução Devoluções
eshop/return/change-status Alteração do estado da devolução Devoluções
eshop/contact/form Envio do formulário de contacto Formulário de contacto
eshop/setup Configuração de idiomas, lojas e estados Configuração
Nota

Se o pedido não chegar ao destino, repita-o no servidor de reserva backup1.bulkgate.com.

Parâmetros do pedido

Os endpoints de eventos (todos exceto eshop/setup) aceitam os mesmos parâmetros. Um parâmetro desconhecido no nível superior faz com que o pedido seja rejeitado com o erro invalid_input_parameters; por isso, os dados do evento pertencem ao objeto variables.

NOME DO PARÂMETRO VALOR OBRIGATÓRIO VALOR PREDEFINIDO
application_id ID da aplicação Sim -
application_token Token de autenticação da aplicação Sim -
language Idioma da notificação ao cliente, por exemplo pt Não default
shop_id Identificador da loja, se tiver várias Não 0
variables Dados do evento — objeto nome: valor, com valores escalares Não {}

Envie o pedido como application/json.

Como o portal escolhe a notificação

As notificações configuram-se no portal para cada aplicação em separado, nas secções SMS do cliente e SMS Admin. Cada uma está associada a um evento e a uma loja (shop_id) e, no caso das notificações ao cliente, também a um idioma. A lista de idiomas, lojas e estados de encomendas e devoluções para os quais o portal disponibiliza notificações é carregada pela sua loja online através da configuração.

  • A notificação ao cliente é procurada para o idioma indicado no parâmetro language. Se a aplicação não tiver as versões linguísticas ativadas, o portal ignora o idioma e utiliza default.
  • A notificação aos administradores é sempre procurada para o idioma default e é enviada para os números dos administradores atribuídos a essa notificação.
  • As notificações ao cliente e aos administradores são avaliadas de forma independente — um evento pode enviar uma, ambas ou nenhuma.
Importante

O portal não envia o mesmo texto para o mesmo número duas vezes no espaço de 24 horas. Assim, uma nova chamada do mesmo evento não envia ao cliente uma mensagem duplicada.

Número de telefone do cliente

O portal procura o número do cliente em variables. A ordem é definida pela variável contact_address_preference:

contact_address_preference ORDEM DAS VARIÁVEIS COM O NÚMERO ORDEM DAS VARIÁVEIS COM O PAÍS
delivery (predefinido) customer_mobile, customer_phone, customer_invoice_mobile, customer_invoice_phone, phone_mobile, phone, phone_number customer_country_id, customer_invoice_country_id, customer_country, customer_invoice_country, iso, country_iso
invoice customer_invoice_mobile, customer_invoice_phone, customer_mobile, customer_phone, phone_mobile, phone, phone_number customer_invoice_country_id, customer_country_id, customer_invoice_country, customer_country, iso, country_iso

É utilizada a primeira variável a partir da qual seja possível compor um número válido. O portal lê o país como código ISO de duas letras (cz, sk, …) e, com base nele, acrescenta o indicativo aos números introduzidos sem ele. Se não encontrar nenhum número válido, a notificação ao cliente não é enviada.

Variáveis nos modelos

O modelo da notificação utiliza as variáveis de variables na forma <nome>, por exemplo <order_id>. Um valor predefinido pode ser escrito diretamente no modelo como <nome:valor>. O portal preenche ainda:

  • shop_name — o nome da loja correspondente ao shop_id da lista de lojas, se não o enviar,
  • language_iso — o valor do parâmetro language.

As variáveis que não enviar são substituídas no texto pelo valor predefinido — na maioria dos casos, uma cadeia vazia; em order_id, long_order_id e order_ref, um hífen. Têm valor predefinido as seguintes variáveis:

GRUPO VARIÁVEIS
Loja shop_id, shop_email, shop_name, shop_domain, shop_currency, shop_phone, store_id, lang_id, language_iso
Cliente customer_id, customer_company, customer_firstname, customer_lastname, customer_name, customer_address, customer_postcode, customer_city, customer_state, customer_country, customer_country_id, customer_phone, customer_mobile, customer_email, customer_vat_number, customer_fax, customer_message, customer_firstname_vokativ, customer_lastname_vokativ
Faturação customer_invoice_company, customer_invoice_firstname, customer_invoice_lastname, customer_invoice_address, customer_invoice_postcode, customer_invoice_city, customer_invoice_state, customer_invoice_country, customer_invoice_country_id, customer_invoice_phone, customer_invoice_mobile, customer_invoice_vat_number, customer_invoice_firstname_vokativ, customer_invoice_lastname_vokativ
Encomenda order_id, long_order_id, order_ref, order_reference, order_status, order_status_id, order_status_message, order_message, order_currency, order_payment, order_total_paid, order_total_locale, order_date, order_datetime, order_time, order_date1–order_date7, order_time1, order_products1–order_products8, order_smsprinter1–order_smsprinter4, cart_id, id_address_delivery, id_address_invoice
Envio carrier_id, order_carrier_name, order_carrier_code, order_carrier_url, order_carrier_delay, order_carrier_tracking_number, order_carrier_tracking_date, order_carrier_price, order_carrier_price_locale, order_carrier_weight, order_tracking
Produto product_id, product_name, product_quantity, product_minimal_quantity, product_model, product_ref, product_description, product_manufacturer, product_supplier, product_supplier_id, product_supplier_ref, product_price, product_price_locale, product_ean, product_ean13, product_upc, product_isbn, product_jan, product_mpn, product_sku
Devolução return_id, return_status, return_status_id, return_action, return_action_id, return_reason, return_reason_id, return_date, return_customer_message, return_question, return_products1–return_products8
Funcionário employee_id, employee_email, employee_firstname, employee_lastname

Também pode enviar variáveis próprias — o modelo utiliza-as da mesma forma.

Resposta

Em caso de sucesso, devolve um objeto data com o resultado de cada mensagem enviada, separadamente para o cliente (customer) e para os administradores (admin). A chave não aparece quando a respetiva notificação não está configurada para o evento. Uma notificação ao cliente configurada, mas desativada, devolve um array vazio.

{ "data": { "customer": [ { "status": "accepted", "message_id": "tmpde1bcd4b1d1", "part_id": ["tmpde1bcd4b1d1"], "number": "420777777777", "channel": "sms" } ] } }

Se não houver nenhuma notificação configurada para o evento, a resposta é {"data": []}.

Se não for possível enviar a notificação (remetente inválido, número na blacklist, mensagem duplicada…), o pedido termina mesmo assim com sucesso e, em vez do resultado da mensagem, contém o código do erro:

{ "data": { "customer": [ ["duplicity_message"] ] } }

Em caso de erro:

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

Em que:

  • type e error (descrição do erro) encontram-se na tabela de tipos de erros
  • code representa o código de erro HTTP
  • detail contém informações adicionais sobre o erro

Tipos de erros da E-shop API

TIPO QUANDO OCORRE
unknown_identity Falta application_id ou application_token, ou não são válidos.
invalid_input_parameters O pedido contém um parâmetro desconhecido ou um parâmetro com o tipo errado.
unknown_action A ação no endereço não existe, por exemplo eshop/order/cancel.
Esta página foi útil?