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 |
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 utilizadefault. - A notificação aos administradores é sempre procurada para o idioma
defaulte é 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.
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 aoshop_idda lista de lojas, se não o enviar,language_iso— o valor do parâmetrolanguage.
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.
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:
Em caso de erro:
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. |
Obrigado pelo seu feedback.