====== Integração NuvemShop ======

O Ello se conecta com a [[https://www.nuvemshop.com.br/|NuvemShop]] (plataforma de lojas virtuais) para sincronizar produtos automaticamente e receber os pedidos feitos na loja online. Com a integração ativa, pedidos que chegam pelo site aparecem diretamente no Ello — sem redigitar nada — e qualquer alteração de produto ou estoque no Ello é refletida na loja em instantes.

===== O que é sincronizado =====

^ Do Ello para a NuvemShop ^ Da NuvemShop para o Ello ^
| Produtos (nome, descrição, preço, fotos, peso, dimensões) | Pedidos de venda |
| Disponibilidade em estoque | Dados dos clientes |
| Categorias de produtos | Status de entrega (rastreio) |
| | Cancelamentos de pedidos |

===== Fluxo geral =====

<uml>
@startuml
skinparam DefaultFontSize 13
skinparam SequenceArrowThickness 1.5
skinparam SequenceBoxBorderColor #5F3A1E
skinparam SequenceLifeLineBorderColor #888888

actor "Cliente da\nloja virtual" as Cliente
participant "NuvemShop\n(loja online)" as NS
participant "Ello" as Ello
actor "Atendente / Equipe" as Operador

Cliente -> NS : Faz um pedido
NS -> Ello : Pedido importado automaticamente\n(a cada ~1 minuto)
Ello -> Operador : Pedido aparece na tela\nde Pedidos NuvemShop

Operador -> Ello : Prepara e embala o pedido
Ello -> NS : Atualiza status → Embalado

Operador -> Ello : Despacha ou solicita motoboy
Ello -> NS : Atualiza status → Despachado
NS -> Cliente : Notifica o cliente

Operador -> Ello : Confirma entrega
Ello -> NS : Atualiza status → Entregue
@enduml
</uml>

===== Configuração =====

A configuração é feita em **Sistema → Parâmetros**, na aba **NuvemShop**. Os dados abaixo são fornecidos pela equipe Ello no momento da ativação da integração:

^ Parâmetro ^ Para que serve ^
| **Token de Acesso** | Senha que autoriza o Ello a se comunicar com a loja NuvemShop |
| **ID da Loja** | Código que identifica a loja na NuvemShop |
| **Catálogo de Produtos** | Qual catálogo do Ello será exibido na loja virtual |
| **Conta para recebimento via PIX** | Conta financeira onde os pagamentos PIX da NuvemShop serão registrados |
| **Operação PIX** | Tipo de lançamento financeiro usado para os recebimentos PIX |

Sem o Token e o ID da Loja preenchidos corretamente, nenhuma sincronização ocorre.

===== Acompanhando pedidos NuvemShop =====

Acesse **Integrações → NuvemShop → Pedidos** para ver todos os pedidos recebidos pela loja virtual.

==== O que aparece na lista ====

^ Coluna ^ O que mostra ^
| **N° Pedido** | Número do pedido dentro do Ello |
| **N° Loja** | Número do pedido na NuvemShop (o que o cliente vê) |
| **Cliente** | Nome do comprador |
| **Data** | Data em que o pedido foi realizado |
| **Valor** | Valor total do pedido |
| **Status** | Fase atual da entrega (veja tabela de status abaixo) |

No topo da tela são exibidos dois resumos: o total de pedidos com seu valor somado, e o total de pedidos cancelados separadamente. Pedidos cancelados aparecem em cinza com o texto riscado.

==== Status de entrega ====

^ Status ^ Significado ^
| **Aguardando Envio** | Pedido importado e aguardando preparação |
| **Embalado** | Pedido preparado e embalado pela equipe |
| **Despachado** | Pedido entregue à transportadora ou ao motoboy |
| **Pronto p/ Retirada** | Pedido pronto para retirada pelo cliente no local |
| **Entregue** | Pedido recebido pelo cliente |
| **Cancelado** | Pedido cancelado, seja pelo cliente ou pela loja |

==== Ações disponíveis na tela ====

  * **Visualizar** — Abre os detalhes completos do pedido (itens, endereço, pagamento e dados do cliente)
  * **Status de Entrega** — Abre a [[#acompanhando_o_status_de_entrega|linha do tempo visual]] com o andamento do pedido
  * **Solicitar Entrega** — Aciona o [[ello_erp:modulos:rota_entregas|Rota Entregas]] para enviar um motoboy (disponível apenas quando esse módulo está habilitado)

===== Acompanhando o status de entrega =====

Ao clicar em **Status de Entrega** na lista de pedidos, o sistema abre uma tela com a linha do tempo do pedido em 4 etapas:

<uml>
@startuml
skinparam DefaultFontSize 13

|<#f5f8f0> Linha do Tempo |

|Linha do Tempo|
start
:Recebido;
note right: Pedido chegou da NuvemShop
:Embalado;
note right: Equipe preparou o pedido
if (Tipo de envio?) then (Entrega em endereço)
  :Despachado;
  note right
    Transportadora informada
    Código de rastreio disponível
  end note
else (Retirada no local)
  :Pronto p/ Retirada;
  note right: Cliente pode ir buscar
endif
:Entregue;
note right: Pedido chegou ao cliente
stop
@enduml
</uml>

A tela mostra também:
  * **Tipo de envio** — se o pedido será entregue no endereço do cliente ou retirado na loja
  * **Transportadora** — empresa responsável pela entrega (quando aplicável)
  * **Código de rastreio** — código para o cliente acompanhar o pacote nos Correios ou transportadora

===== Sincronização de produtos =====

Sempre que um produto do catálogo configurado for criado, alterado ou tiver o estoque modificado no Ello, as informações são enviadas automaticamente para a NuvemShop.

**O que é enviado:**
  * Nome, descrição e marca
  * Preço de venda
  * Quantidade em estoque
  * Código de barras
  * Peso e dimensões (para cálculo de frete)
  * Fotos e imagens
  * Categoria do produto

**Atenção:** Somente produtos que fazem parte do **catálogo NuvemShop configurado** são sincronizados. Produtos fora desse catálogo não aparecem na loja virtual.

===== Clientes importados dos pedidos =====

Quando um pedido chega da NuvemShop, o Ello verifica automaticamente se o CPF ou CNPJ do comprador já está cadastrado. Se sim, o pedido é vinculado ao cliente existente (e o endereço é atualizado se necessário). Se não, um novo cadastro é criado.

===== Resolução de problemas =====

^ Situação ^ Causa provável ^ O que fazer ^
| Pedidos novos não aparecem na tela | Token de acesso inválido ou em branco | Verificar o Token e o ID da Loja nos parâmetros do sistema |
| Pedidos param de entrar após um período | Token revogado na NuvemShop | Gerar novo token na NuvemShop e atualizar nos parâmetros |
| Produto alterado no Ello não atualiza na loja | Produto não está no catálogo configurado | Incluir o produto no catálogo NuvemShop dentro do Ello |
| Pagamento via PIX não aparece no financeiro | Conta ou Operação PIX não configurados nos parâmetros | Preencher os campos de PIX na configuração da integração |
| Status de entrega aparece em branco | Nenhuma atualização de status foi registrada ainda | Normal para pedidos recém-chegados; aguardar primeira atualização |
| Pedido cancelado na NuvemShop não cancela no Ello | Período financeiro fechado no momento do cancelamento | Ello cria uma devolução no lugar do cancelamento; verificar em Devoluções |

===== Veja também =====

  * [[ello_erp:modulos:rota_entregas|Rota Entregas — Solicitar Motoboy]]
  * [[ello_erp:modulos|Módulos do Ello ERP]]