Conectar o Brightpearl: receber pedidos, consultar estoque

Primeiro obtenha app_ref e dev_ref do seu app no portal de desenvolvedores do Brightpearl, depois execute a autorização OAuth da sua conta para obter o access token e o api_domain para datacenter, preencha os cinco campos no Integration, teste, mapeie e ative: entram pedidos de venda e o estoque pode ser consultado.

O conector do Brightpearl traz pedidos de venda do Brightpearl para este sistema e pode consultar a disponibilidade de estoque de produtos mantida no Brightpearl. Ele lê dados do Brightpearl: não traz clientes do Brightpearl e não devolve estoque nem nenhuma outra alteração ao Brightpearl. Aqui a ordem importa: o valor de datacenter não é escolhido de uma lista, ele é retornado como api_domain na resposta do token OAuth, então você conclui a autorização primeiro e preenche a conexão depois.

Pré-requisitos#

• Uma conta do Brightpearl e seu código de conta: a parte do subdomínio do seu endereço do Brightpearl. Por exemplo, em acme.brightpearl.com o código de conta é acme.
• Acesso ao portal de desenvolvedores do Brightpearl em developer.brightpearl.com, e um app lá para esta integração: você precisa da referência do aplicativo e da sua referência de desenvolvedor.
• Você consegue concluir o fluxo OAuth2 Authorization Code para essa conta do Brightpearl, a partir do endereço de autorização indicado na etapa de credenciais.
• Você entende a ordem invertida de datacenter: ele vem da resposta do token, como api_domain, depois da autorização. Não adivinhe e não preencha ali o subdomínio da conta.

Obter credenciais#

1. Anote primeiro seu código de conta: a parte do subdomínio do seu endereço do Brightpearl, por exemplo acme de acme.brightpearl.com.
2. Abra o portal de desenvolvedores do Brightpearl em developer.brightpearl.com, abra seu app e anote sua referência de aplicativo. Esse é o valor de app_ref, e essa mesma referência de aplicativo também é usada como client_id no fluxo OAuth.
3. Anote ao mesmo tempo sua referência de desenvolvedor. Esse é o valor de dev_ref: ele é enviado com cada solicitação como cabeçalho brightpearl-dev-ref, assim como app_ref é enviado como brightpearl-app-ref.
4. Inicie a autorização OAuth da sua conta a partir de https://oauth.brightpearl.com/authorize/{account}, com seu próprio código de conta no lugar de {account}, e conclua o fluxo Authorization Code Grant para obter o access token.
5. Dessa mesma resposta do token, anote dois valores: o próprio access_token e o valor api_domain. O api_domain, por exemplo use1.brightpearlconnect.com, é exatamente o que vai no campo datacenter: copie da resposta, não monte você mesmo.

Preencher no Integration#

1. Abra Integration → Marketplace → Brightpearl → Nova conexão. Os cinco campos abaixo são todos obrigatórios.
2. account, obrigatório, código de conta do Brightpearl: a parte do subdomínio do seu endereço do Brightpearl, por exemplo acme.
3. datacenter, obrigatório, domínio do datacenter da API: preencha o api_domain retornado na resposta do token OAuth, por exemplo use1.brightpearlconnect.com. Não preencha aqui o subdomínio da conta.
4. app_ref, obrigatório, referência do aplicativo: a referência do seu app no portal de desenvolvedores do Brightpearl, em developer.brightpearl.com.
5. dev_ref, obrigatório, referência de desenvolvedor: sua referência de desenvolvedor do Brightpearl. Ela é enviada como cabeçalho brightpearl-dev-ref em cada solicitação.
6. access_token, obrigatório, token de acesso OAuth2: cole o access token obtido do fluxo Authorization Code Grant. É um campo do tipo senha e é guardado como segredo.

Testar a conexão#

Clique em Testar a conexão. O teste primeiro verifica os cinco campos (account, datacenter, app_ref, dev_ref e access_token) e, se algum estiver ausente, para e informa o campo ausente antes de enviar qualquer solicitação. Caso contrário, envia uma solicitação com três cabeçalhos, Authorization: Bearer com seu token, brightpearl-dev-ref e brightpearl-app-ref, para ler os dados de referência de status de pedidos: GET https://{datacenter}/public-api/{account}/order-service/order-status, com seus próprios valores de datacenter e account no endereço. É a verificação somente leitura mais leve do Brightpearl. Uma resposta 200 significa que a conexão funciona. Uma resposta 401 aponta para o token. Uma resposta 403 aponta para a permissão. O teste expira após 12 segundos.

Mapping / escolher modelo#

Escolha o mapping padrão do Brightpearl. Os pedidos de venda são encontrados pela busca do serviço de pedidos do Brightpearl e depois lidos por completo, e as consultas de estoque leem a disponibilidade de produtos do serviço de armazém. Depois que o teste aprovar, execute uma extração e confira um pedido real lado a lado (número do pedido, nome do cliente exibido no pedido, linhas e quantidades) e compare a disponibilidade de um produto com o que o Brightpearl mostra, antes de ativar. Se um campo dos seus pedidos diferir, ajuste esse campo no mapping em vez de mudar registros no Brightpearl.

Ativar#

Após ativar, a conexão traz pedidos de venda do Brightpearl para este sistema na frequência definida, e as consultas de estoque leem a disponibilidade atual de produtos do Brightpearl. Acompanhe as primeiras extrações em Runs / Logs e compare com o Brightpearl antes de deixar a conexão sem supervisão. Quando o access token parar de funcionar, execute a autorização OAuth novamente para a mesma conta e depois atualize access_token e datacenter juntos a partir da nova resposta do token.

O que esta conexão não faz: não traz clientes do Brightpearl e não devolve estoque, status de pedidos nem resultados de fulfillment ao Brightpearl. Continue cuidando disso no próprio Brightpearl, ou nos sistemas onde o trabalho realmente acontece.

Perguntas frequentes#

O teste falha com 401: o problema é o token

O Brightpearl não aceitou o access token enviado com o teste. O token no campo access_token está errado, incompleto ou não foi obtido para esta conta pelo fluxo Authorization Code Grant: o teste lê os dados de referência de status de pedidos como verificação do token Bearer, e um token que o Brightpearl não consegue aceitar falha ali primeiro.

Execute a autorização novamente a partir de https://oauth.brightpearl.com/authorize/{account} com seu próprio código de conta, conclua o fluxo Authorization Code Grant, cole o novo access token inteiro e copie datacenter novamente dessa mesma resposta do token como api_domain. Salve e teste novamente.

O teste falha com 403: um problema de permissão

Isso é diferente do 401: o token foi aceito, mas o app ou a conta por trás dele não tem permissão para ler os dados de referência de status de pedidos usados pelo teste. Executar a autorização novamente com o mesmo app e o mesmo acesso continuará retornando 403.

Verifique no Brightpearl o que o app identificado por app_ref pode acessar para esta conta, e confira se dev_ref e app_ref são o par exato usado com o token. Dê ao app o acesso de leitura de que a conexão precisa, ou use um app que já o tenha, depois autorize novamente, atualize os campos a partir da nova resposta do token e teste novamente.

O teste para antes de enviar uma solicitação e informa um campo ausente

Um dos cinco campos obrigatórios (account, datacenter, app_ref, dev_ref ou access_token) está vazio. O teste verifica os cinco primeiro, porque o endereço da solicitação precisa de account e datacenter, e os cabeçalhos precisam de app_ref, dev_ref e do token.

Preencha o campo ausente a partir da sua própria fonte: account do seu endereço do Brightpearl, app_ref e dev_ref do portal de desenvolvedores, e access_token mais datacenter da resposta do token OAuth. Salve e teste novamente.

Preenchi o subdomínio da conta como datacenter e o teste falha

account e datacenter são valores diferentes e com formatos diferentes. account é o subdomínio do seu endereço do Brightpearl, por exemplo acme. datacenter é o api_domain retornado na resposta do token OAuth, no formato de use1.brightpearlconnect.com. Com o valor de account no campo datacenter, a solicitação de teste vai para o endereço errado.

Volte à resposta do token da sua autorização OAuth, copie o valor api_domain exatamente no campo datacenter, deixe account apenas como o subdomínio, salve e teste novamente.

Conectado, mas nenhum pedido de venda chega

A conexão está funcionando (o teste leu os dados de referência de status de pedidos com sucesso), mas não há nada novo para trazer: o Brightpearl não tem pedidos de venda novos no intervalo de extração para esta conta, ou esses pedidos estão em uma conta diferente do código de conta da conexão.

Crie ou confirme um pedido de venda no Brightpearl sob o mesmo código de conta da conexão, execute uma extração manual e confirme que o pedido aparece na prévia ou em Runs / Logs.

A consulta de estoque não retorna disponibilidade para um produto

A conexão consegue ler a disponibilidade de produtos no Brightpearl, mas esse produto não tem um registro de disponibilidade correspondente para ler, ou o código do produto no mapping não corresponde ao produto no Brightpearl. O teste pode aprovar enquanto um produto específico continua sem nada para retornar.

Verifique primeiro o produto e sua disponibilidade no Brightpearl, depois verifique o código do produto desse item no mapping e corrija para corresponder ao Brightpearl. Execute a consulta de estoque novamente só para esse produto.