====== Ello POS ======

Ello POS é um aplicativo que pode ser instalado em "maquininhas" possibilitando a integração dos recebimentos via meio eletrônico com o Ello.

Os recebimentos feitos na maquininha são registrados no Ello pelo [[gollum|Gollum]].

Disponibilidade do Ello POS:

^ Maquininha ^ Disponível ^ Biblioteca ^
| Rede       | ✅ | mSitef |
| Caixa      | ✅ | mSitef |
|BIN         | ✅ | mSitef |
| Stone      | ✅ | Direto com Stone |
| Getnet     | ❌ | |
| C6         | ❌ | |
| Pagbank    | ❌ | |
| Sicredi    | ✅ | mSitef |
| Sipag      | ❌ | |
| Cielo      | ❌ | |

  * [[pos:ello_pos:msitef|Instruções para implantação do Ello POS com ACBr]]
  * [[integracoes:stone|Instruções para implantação do Ello POS com Stone]]
  * [[pos:ello_pos:fiserv|Instruções para implantação do Ello POS Fiserv]]

\\
====== Como o Ello POS funciona ======

O Ello POS é o aplicativo que fica na maquininha. Ele **não faz a venda**: a venda é feita no Ello (retaguarda) ou no PDV, e o valor a receber no cartão ou Pix vira uma **cobrança** que aguarda na fila. A maquininha busca essas cobranças, o operador escolhe uma, o cliente paga e o resultado volta para o Ello, que dá a baixa automaticamente.

Quem faz a ponte entre a maquininha e o Ello é o [[gollum|Gollum]], um aplicativo que fica ligado no computador da loja. Por isso a maquininha precisa estar no mesmo Wi-Fi (rede) do computador onde o Gollum está em execução.

===== Resumo do caminho de uma cobrança =====

  - No Ello, a venda é faturada com a forma **POS Com Integração**. Isso cria a cobrança.
  - A maquininha consulta o Gollum de tempos em tempos e mostra as cobranças na lista.
  - O operador toca na cobrança. A maquininha pede ao Gollum para **reservá-la**: assim, se a loja tiver mais de uma maquininha, duas não recebem a mesma cobrança.
  - O pagamento é feito no próprio aplicativo de cartões da maquininha (insere/aproxima o cartão ou lê o Pix).
  - Aprovado o pagamento, a maquininha imprime o comprovante e avisa o Gollum. O Gollum grava o recebimento no Ello com valor, forma de pagamento, parcelas, bandeira, rede e número de autorização.
  - Se o pagamento não acontecer (cliente desistiu, cartão recusado), a maquininha avisa o Gollum e a cobrança volta para a fila.

===== Conversa entre a maquininha e o Gollum =====

O diagrama mostra as mensagens trocadas entre a maquininha e o Gollum durante um recebimento.

<uml>
actor Operador
participant "Maquininha\n(Ello POS)" as POS
participant "Gollum" as G
database "Ello\n(Retaguarda)" as ERP

== Atualização da lista (automática a cada 40 segundos) ==
POS -> G: Quais cobranças existem para esta maquininha?\n(envia a identificação da maquininha)
G -> ERP: Busca cobranças em aberto
alt maquininha liberada
  G --> POS: Lista de cobranças\n(vazia se não houver nenhuma)
else maquininha bloqueada, pendente de aprovação\nou com identificação repetida
  G --> POS: Recusa, informando o motivo
  POS -> Operador: Exibe o aviso na tela
end

== Recebimento ==
Operador -> POS: Escolhe a cobrança
POS -> G: Reservar esta cobrança para mim
G -> ERP: Confere e marca a cobrança como em uso
alt reserva concedida
  G --> POS: Reservada
  POS -> Operador: Abre a tela de cartões (valor, crédito/débito, parcelas)
  Operador -> POS: Cliente paga e a operadora responde
  alt pagamento aprovado
    POS -> Operador: Imprime o comprovante
    POS -> G: Pagamento efetuado\n(valor, forma, parcelas, bandeira, rede, nº de autorização)
    G -> ERP: Registra o recebimento e dá baixa na cobrança
    G --> POS: Atualizado com sucesso
  else pagamento recusado ou cancelado
    POS -> G: Liberar a cobrança
    G -> ERP: Devolve a cobrança para a fila
    G --> POS: Liberada
  end
else reserva negada
  G --> POS: Negada (já recebida, em uso em outra maquininha,\nenviada a outra maquininha ou cancelada no Ello)
  POS -> Operador: Informa o motivo e não cobra o cliente
end

== Se o Gollum não responder ao avisar o pagamento ==
POS -> POS: Guarda o pagamento no aparelho
loop a cada 40 segundos até dar certo
  POS -> G: Pagamento efetuado (reenvio)
  G --> POS: Atualizado (um reenvio nunca gera lançamento duplicado)
end
</uml>

===== Cancelamento de cobrança =====

Quando alguém cancela, no Ello, uma cobrança que já foi enviada para a maquininha, a maquininha descobre isso sozinha:

<uml>
actor Operador
participant "Maquininha\n(Ello POS)" as POS
participant "Gollum" as G
database "Ello\n(Retaguarda)" as ERP

ERP -> ERP: Cobrança marcada como\n"aguardando cancelamento"
loop a cada 60 segundos
  POS -> G: Existe cobrança cancelada?
  G -> ERP: Busca cobranças aguardando cancelamento
  G --> POS: Lista de cobranças a cancelar
end
alt cobrança ainda não foi paga na maquininha
  POS -> POS: Marca a cobrança como cancelada
  POS -> G: Cancelamento efetuado
  G -> ERP: Atualiza a cobrança como cancelada
else cobrança já foi paga na maquininha
  POS -> Operador: Mantém a cobrança na lista\npara o cancelamento ser feito manualmente
  Operador -> POS: Toca na cobrança e confirma o estorno
  POS -> Operador: Estorna a transação no cartão e imprime o comprovante
  POS -> G: Cancelamento efetuado
  G -> ERP: Atualiza a cobrança como cancelada
end
</uml>

====== Tela principal ======

  * **Lista de cobranças:** mostra as cobranças a receber. É atualizada sozinha a cada 40 segundos e também ao tocar em **Atualizar**.
  * **Indicador do Gollum** (bolinha na barra superior):
    * **Verde:** o Gollum respondeu na última conversa.
    * **Vermelha** (com o texto //Gollum off//): a maquininha não conseguiu falar com o Gollum.
    * **Cinza:** ainda não houve nenhuma conversa desde que o aplicativo abriu.
    * Tocando na bolinha, aparece uma janela com a situação, o endereço do servidor, o horário e o motivo da última comunicação, além do botão **Testar agora**.
  * **Menu (três pontos):** //Configurar// e //Limpar cobranças// pedem a senha de manutenção (fornecida pelo suporte). //Menu administrativo// abre as funções da operadora de cartões (por exemplo reimpressão de comprovante e cancelamento de Pix). //Sair// fecha o aplicativo.

====== Configuração da maquininha ======

A tela de configuração é aberta pelo menu, com a senha de manutenção. Os principais campos são:

^ Campo ^ Para que serve ^
| IP e porta do Gollum | Endereço do computador onde o Gollum está em execução e a porta de comunicação (normalmente 7000). |
| Identificação da maquininha | Nome único desta maquininha (por exemplo "Balcão 1"). O Ello usa esse nome para saber qual maquininha está recebendo cada cobrança e para bloquear ou aprovar maquininhas. **Duas maquininhas não podem ter a mesma identificação.** |
| CNPJ da loja | Usado só se a cobrança não trouxer o CNPJ da empresa. |
| Empresa e terminal (SiTef) | Dados fornecidos pela operadora de pagamentos. Em maquininhas já ativadas, o terminal pode ficar em branco. |
| Impressão | Escolhe se imprime a via do estabelecimento, a via do cliente ou se pergunta ao operador. |
| Acessibilidade | Liga os recursos de acessibilidade visual na tela de cartões. |
| Modo laboratório | Campos extras que só devem ser usados em testes e homologação, a pedido do suporte. |

Depois de salvar, o aplicativo passa a usar o novo endereço imediatamente.

====== Problemas comuns ======

^ O que acontece ^ Causa provável ^ O que fazer ^
| Bolinha vermelha / "Gollum off" | A maquininha não alcança o computador do Gollum. | Veja se o Wi-Fi está conectado, se o Gollum está aberto no computador e se o IP e a porta estão corretos. Toque na bolinha e em **Testar agora**. |
| Nenhuma cobrança na lista | Não há cobranças em aberto, ou a cobrança foi enviada a outra maquininha. | Confira no Ello se a venda foi faturada como **POS Com Integração** e toque em **Atualizar**. |
| "Esta maquininha está bloqueada no Ello" | A maquininha foi bloqueada no cadastro do Ello. | Procure o responsável para liberá-la no Ello. |
| "Esta maquininha ainda não foi aprovada no Ello" | Maquininha nova, que ainda não foi liberada no cadastro do Ello. | Peça para aprovar a maquininha no Ello. |
| "Outra maquininha já usa esta identificação" | Duas maquininhas com o mesmo nome. | Altere a identificação nas configurações. |
| "Maquininha sem identificação" | O campo de identificação está vazio. | Preencha nas configurações. |
| "Esta cobrança está em uso na maquininha X" | Outra maquininha já reservou a cobrança. | Aguarde ela concluir, ou cancele o recebimento nela. |
| "O Gollum pode estar numa versão antiga" | O Gollum não conhece as mensagens da versão atual do Ello POS (por exemplo, a reserva). | Atualize o Gollum e reinicie-o. |
| Pagamento aprovado, mas "falha ao confirmar com o servidor" | O pagamento foi feito, mas o Gollum não respondeu na hora. | Não cobre de novo. O aplicativo reenvia sozinho a cada 40 segundos e o recebimento aparece no Ello assim que o Gollum voltar. |

====== Recebimento com Ello POS ======

  - Realize a venda no Ello/Retaguarda
  - Ao faturar, selecione **POS Com Integração**
  - confirme o valor

A tela abaixo será apresentada:

{{:pos:ellopos_vendaello.png?nolink&400|}}

Na naquininha aparecerá a cobrança:

{{:pos:ellopos_recebimento.png?nolink&300|}}

Após selecionado a cobrança siga com o recebimento, em modo teste sempre selecione um cliente com CPF valido 
 

\
====== Mais informações ======

  * [[gollum|Gollum]]: aplicativo que faz a ponte entre as maquininhas e o Ello.
  * [[ello_pdv|Ecossistema PDV]]

====== Manutenção ======

  * [[ello_pos:deletar_cobrancas_pendentes|Deletar cobranças pendentes (por status)]]