Visão geral

O Boleto Híbrido PagHiper é uma extensão desenvolvida pela MT Soluções para o Zoho Marketplace que integra o Zoho Books à API da PagHiper, permitindo a emissão, consulta e cancelamento de boletos híbridos (Boleto + QR Code PIX) diretamente a partir de Faturas (Invoices), Pedidos de Venda (Sales Orders) e Faturas de Adiantamento (Retainer Invoices), sem a necessidade de acessar o portal da PagHiper.

Empresas brasileiras precisam de métodos de pagamento locais integrados nativamente ao seu fluxo de cobrança. Essa extensão elimina o trabalho manual de gerar cobranças fora do sistema e disponibiliza automaticamente o link e a linha digitável do boleto nos campos da fatura, prontos para envio ao cliente. Quando o pagamento é realizado — via código de barras ou PIX — o status da fatura é atualizado diretamente no Zoho Books, reduzindo a inadimplência e o tempo do time financeiro.

Este guia mostra como configurar a extensão e como utilizá-la no dia a dia.

1. Ter a extensão Boleto Híbrido PagHiper instalada na sua organização do Zoho Books.
2. Ter uma conta ativa na PagHiper. (Vendedor ou Empresarial)
3. Ter em mãos a API Key e o Token da sua conta PagHiper.
   

Onde obter a API Key e o Token: No painel da PagHiper, acesse Minha Conta → Credenciais. Copie a API Key (começa com apk_) e o Token. Se o token ainda não existir, clique no botão laranja "Gerar token". Confira o tutorial da Como conseguir seu ApiKey e Token PagHiper 

Passo 1 — Configurar o emissor (credenciais PagHiper)

Essa configuração é feita uma única vez e vale para toda a organização.

1.    No menu da extensão, abra o módulo de configuração “Configuração Boletos PH”.

2.    Clique em criar um novo registro de configuração.

3.    Preencha os campos com os dados da sua empresa e da sua conta PagHiper.

4.    Salve o registro.

Campos a preencher:

1. CNPJ Emissor: o CNPJ da sua empresa cadastrado na PagHiper.
2. API Key: a API Key da PagHiper (começa com apk_).
3. Token: o Token da PagHiper.
4. Dias de Vencimento Padrão: quantos dias até o vencimento do boleto (ex.: 5). Máximo de 400 dias.
5. Multa por Atraso (%): Percentual de multa em caso de atraso. Aceite apenas valores inteiros: 1% ou 2%.
6. Aplicar juros: Marque para aplicar 1% de juros ao mês (0,033% por dia de atraso).
   
7. Frase Fixa: marque para exibir no boleto a frase pré-configurada no painel da PagHiper, Se desmarcado, nenhuma frase fixa  será exibida. A frase é configurada diretamente no painel da PagHiper e passa por análise prévia antes de ser aprovada.

Importante: Mantenha apenas uma configuração cadastrada. O sistema utiliza o primeiro registro de configuração encontrado.

Passo 2 — Preparar o cadastro do cliente

Antes de gerar um boleto, o cliente precisa ter alguns dados preenchidos no cadastro (Contacts).

•       Tipo de Pessoa:  Selecione Física ou Jurídica.

•       CPF: Preencha se o cliente for Pessoa Física.

•       CNPJ: Preencha se o cliente for Pessoa Jurídica.

•       E-mail: Obrigatório para gerar o boleto.

Cadastro do cliente mostrando os campos Tipo de Pessoa, CPF/CNPJ e E-mail preenchidos.

Passo 3 — Conferir o endereço de cobrança

O boleto exige o endereço do pagador. Confira se todos os campos estão preenchidos no registro (Fatura, Pedido ou Adiantamento).

•       Endereço (rua): Primeira linha do endereço.

•       Número: Informe o número no campo Linha 2 (Street 2) do endereço.

•       Cidade e UF: Cidade e a sigla do estado (ex.: SP).

•       CEP: Informe um CEP válido (o sistema usa o CEP para localizar o bairro automaticamente).

Atenção ao número: O sistema lê o número do endereço a partir do campo Linha 2. Se o número não estiver ali, a emissão será bloqueada.

Dica importante: O endereço da fatura é copiado do cliente no momento em que a fatura é criada. Se você preencher o endereço no cliente depois, edite o endereço diretamente na fatura (ou crie a fatura novamente).

Passo 4 — Gerar o boleto

1.    Abra a Fatura (ou Pedido de Venda / Fatura de Adiantamento) desejada.

2.    Clique no botão “Gerar Boleto”.

3.    Aguarde a confirmação de sucesso.

Após a emissão, o sistema preenche automaticamente os campos do boleto no registro e anexa o PDF:

•       Boleto ID, Boleto Link e Boleto Linha Digitável.

•       Status = “Aguardando Pagamento”.

•       O PDF do boleto fica anexado ao registro.

Menu/ação com o botão “Gerar Boleto” em uma Fatura.

Registro após a emissão: campos do boleto preenchidos e o PDF anexado.

Passo 5 — Consultar o status do boleto

Use este botão para verificar se o boleto já foi pago e atualizar o status no registro.

1.    Abra o registro que já possui um boleto emitido.

2.    Clique no botão “Consultar Boleto”.

O sistema atualiza o campo Status e registra um comentário no histórico do registro, mostrando o status anterior e o status atual.

Botão “Consultar Boleto” e o comentário de status registrado no histórico do registro.

Passo 6 — Cancelar o boleto

1.    Abra o registro que possui o boleto a ser cancelado.

2.    Clique no botão “Cancelar Boleto”.

Ao cancelar, o sistema limpa os campos do boleto (ID, Link, Linha Digitável e Status) e registra um comentário no histórico com a data e o ID do boleto cancelado.

Atenção: Só é possível cancelar boletos que ainda não foram pagos. Boletos já pagos não podem ser cancelados.

Botão “Cancelar Boleto” e o comentário de cancelamento no histórico do registro.

Mensagens de erro comuns e como resolver

Dúvidas frequentes

Posso gerar boleto em Faturas, Pedidos de Venda e Adiantamentos?

Sim. Os três botões (Gerar, Consultar e Cancelar) estão disponíveis nesses três módulos.

Onde fica o PDF do boleto?

O PDF é anexado automaticamente ao próprio registro após a emissão.

O status atualiza sozinho?

Não, Use o botão “Consultar Boleto” para atualizar o status quando quiser verificar o pagamento.