Cielo
A integração com o Cielo conecta a sua conta ao idworks e sincroniza os fluxos correspondentes ao canal — credenciais, regras de sincronização de produtos, importação de pedidos, conciliação financeira e demais ações específicas dele. A configuração reúne 13 parâmetros distribuídos em 3 grupo(s).
Antes de configurar, ative a integração em Configurações → Integrações (aba Integrações Disponíveis), preencha o nome interno e (quando o tipo exigir) passe pelo fluxo de autenticação. A partir daí, os parâmetros abaixo ficam disponíveis na Configuração (ícone de engrenagem) da integração.
Categoria no catálogo do idworks: Adquirente.
Índice
Conceito
Cadastro e autenticação
Parâmetros por grupo
Cobrança e conciliação
- O que acontece quando o cartão do cliente é recusado no link de pagamento?
- O que acontece quando o pagamento é confirmado?
- Como funciona a conciliação automática?
Referência rápida
O que é a integração Cielo?
É a conexão entre o canal Cielo e o idworks. Ela controla como dados fluem entre os dois sistemas — depende do tipo da integração (a categoria neste caso é Adquirente), mas em geral cobre uma combinação de credenciais, regras de sincronização, gatilhos automáticos e parâmetros de conciliação.
A integração serve a duas finalidades:
| Para que serve | Como funciona |
|---|---|
| Cobrar o cliente | Ao gerar uma cobrança usando a integração Cielo, o idworks cria um link de pagamento da Cielo em vez de um boleto com código de barras. O cliente abre esse endereço e paga na tela da própria Cielo. O link expira na data de vencimento da cobrança. Se o cartão do cliente for recusado e a cobrança estiver ligada a um pedido, a tentativa fica registrada no pedido (veja como). |
| Conciliar o financeiro | O idworks importa as transações da Cielo e tenta casá-las automaticamente com os recebimentos já lançados, separando a taxa da adquirente. |
📍 Onde: menu lateral → Configurações → Integrações → aba Integrações Disponíveis → Cielo.
Como ativar a integração?
- Acesse Configurações → Integrações.
- Na aba Integrações Disponíveis, busque por Cielo e clique no botão +.
- Preencha:
- Conta (apenas multi-conta) — empresa dona da integração.
- Nome da Integração — texto livre. Útil para distinguir várias instâncias do mesmo tipo.
- Clique em Salvar.
A integração aparece imediatamente em Minhas Integrações. Dependendo do tipo, o status inicial é Ativo (quando só requer credencial fixa) ou Não Autenticado (quando depende de autenticação externa).
Pré-requisito: privilégio Criar parametrizações empresa.
Como autenticar e validar as credenciais?
Preencha o grupo Credenciais de Acesso (ver tabela abaixo). Quando a integração pede uma autorização externa (o canal abre a tela de login dele para você liberar o acesso), clique em Autenticar Integração na linha da integração (ícone de cadeado) — uma nova aba abre o login do canal e, ao confirmar, a conexão fica liberada. Para integrações com credencial fixa (usuário/senha/chave), basta preencher os campos e salvar.
Depois de salvar, use a ação Validar credenciais (quando disponível) para confirmar que o canal responde. O status na listagem reflete o resultado: Ativo = OK, Erro = credencial inválida ou revogada, Não Autenticado = falta concluir o fluxo de autorização.
Pré-requisito: privilégio Editar parametrizações empresa.
Credenciais de Acesso
3 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| ClientID | Texto | ClientID obtido no portal da Cielo |
| ClientSecret | Senha | ClientSecret obtido no portal da Cielo |
| Url notificação e status | Cópia | Url notificação e status para configurar no painel da Cielo |
Conciliação
8 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Número do estabelecimento na Cielo | Texto | Caso tenha mais de uma empresa, coloque separado por vírgula. O código é semelhante a 1103536703 |
| Ativar conciliação | Sim/Não | Ativar a conciliação para importar as transações |
| Plano de contas taxa | Lista | Plano de contas para lançamento da taxa adquirente |
| Tipo documento taxa | Lista | Tipo documento para lançamento da taxa adquirente |
| Centro de custo taxa | Lista | Centro de custo para lançamento da taxa adquirente |
| Diferença dias data venda para conciliação automática | Inteiro | Quantidade de dias a mais e a menos permitido na conciliação automática |
| Diferença valor para conciliação automática | Decimal | Diferença de valor a maior e a menor permitido na conciliação automática |
| Plano de contas antecipação | Lista | Plano de contas para lançamento de antecipação adquirente |
Configurações Gerais
2 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Mudar pedido para status após pago | Lista | Selecione um status, se desejar, para mudar o pedido após o pagamento ser efetuado |
| Desmembrar pagamento em parcelas | Sim/Não | Ao ativar, o pagamento vai ser desmembrado na quantidade de parcelas ao receber a confirmação da CIELO |
O que acontece quando o cartão do cliente é recusado no link de pagamento?
Quando o cliente tenta pagar o link da Cielo e o cartão é recusado, o idworks, ao consultar a cobrança, registra cada tentativa negada no histórico do pedido e, quando houver um pagamento do pedido ligado a essa cobrança, também nos Comentários dele:
- Histórico do pedido: o evento Pagamento negado, com resultado Problema. Aparece na aba Timeline (Logs) da ficha do pedido e na tela Log Pedidos.
- Comentários do pagamento do pedido ligado a essa cobrança: o mesmo texto, acrescentado ao que já estiver lá. Se o pedido não tiver mais esse pagamento (por exemplo, o pagamento foi refeito depois da recusa), se o pagamento tiver sido substituído ou se o texto acumulado passar de 2.000 caracteres, só o histórico do pedido recebe o registro. Quando o pagamento é confirmado com Desmembrar pagamento em parcelas em Sim, o Comentários vai junto para cada parcela.
O texto da tentativa segue este formato:
Cielo: pagamento negado em 16/10/2026 15:01 (R$ 1.250,00, Master final 1234, 6x, NSU 123456): código 51 - SALDO/LIMITE INSUFICIENTE
[tentativa 0123456789abcdef0123]
| Parte do texto | O que mostra |
|---|---|
| Data e hora | Quando o cliente tentou pagar, no horário de Brasília. |
| Valor, bandeira e final do cartão | O valor da tentativa e os 4 últimos dígitos do cartão, que distinguem duas tentativas de mesmo valor e bandeira. |
| Parcelas | Aparecem só quando a tentativa foi em mais de uma parcela. |
| NSU | O número que a Cielo pede para localizar a transação. |
| Código de retorno e motivo | O código devolvido na autorização do cartão e o motivo, tirado da tabela de códigos de retorno padrão ABECS da Cielo para a bandeira ou, se não estiver lá, dos códigos próprios da Cielo. Na Amex o código é o da própria Amex (como A5), não o numérico da ABECS. Bandeira sem tabela própria (como Hipercard e Diners) só tem motivo quando o código significa o mesmo nas outras bandeiras. Código sem texto aparece com "(sem descrição na tabela ABECS da Cielo)"; tentativa sem código aparece como "sem código de retorno". |
[tentativa …] | Identifica a tentativa na Cielo. O idworks lê essa marca no histórico do pedido para não registrar a mesma tentativa duas vezes. |
Vale apenas para cobrança ligada a um pedido: numa cobrança avulsa, sem pedido, as tentativas negadas não são consultadas nem registradas.
O que acontece quando o pagamento é confirmado?
Quando o idworks consulta a cobrança e a Cielo confirma o pagamento, os dois parâmetros de Configurações Gerais entram em ação. Eles valem apenas para cobranças ligadas a um pedido.
Desmembrar pagamento em parcelas
| Situação | O que o idworks faz |
|---|---|
| Parâmetro em Não, ou venda em 1 parcela | Atualiza o recebimento que já existe no pedido com o número da transação, o comprovante e a forma de pagamento devolvidos pela Cielo. |
| Parâmetro em Sim e venda parcelada | Substitui os recebimentos anteriores daquele pedido por um recebimento para cada parcela, com os mesmos dados da transação. |
Nos dois casos, a forma de pagamento devolvida pela Cielo (tipo + bandeira) é convertida pela regra de/para de pagamentos cadastrada na integração.
Mudar pedido para status após pago
- O idworks soma o valor de todas as cobranças pagas daquele pedido.
- A troca de status só acontece quando essa soma bate exatamente com o valor total do pedido — pagamento parcial não muda o status.
- Se o pedido ainda estiver como orçamento, ele primeiro passa para Aberto.
- A troca respeita as regras de transição entre status. Se o caminho não for permitido, nada muda e o histórico do pedido registra "Problema ao alterar status mediante pagamento efetuado, alteração não permitida para status:
<status>". - Dando certo, o histórico registra "Status alterado mediante pagamento efetuado para
<status>".
Quando o status escolhido é Fechado, o pedido entra no fluxo normal de fechamento em vez de apenas trocar de status. Deixe o parâmetro sem status selecionado se não quiser que o pagamento mexa no status do pedido.
Como funciona a conciliação automática?
A importação das transações só roda quando Ativar conciliação está em Sim e o Número do estabelecimento na Cielo está preenchido. Com mais de um estabelecimento, informe todos separados por vírgula.
Para o idworks tentar casar a transação sozinho, Plano de contas taxa e Tipo documento taxa precisam estar preenchidos e a conta bancária do recebimento precisa estar definida. Sem isso, a transação é apenas importada e fica aguardando conciliação manual.
O casamento automático procura um recebimento que atenda a todas as condições abaixo:
- Mesmo número de transação ou mesmo comprovante da venda.
- Mesma parcela.
- Data dentro da janela de Diferença dias data venda para conciliação automática — a data da venda mais e menos essa quantidade de dias.
- Valor dentro da janela de Diferença valor para conciliação automática — o valor da transação mais e menos essa diferença.
Se nada for encontrado com a janela de valor, o idworks repete a busca sem ela, para alcançar lançamentos que foram divididos em vários recebimentos.
Encontrado o recebimento, a taxa da adquirente é lançada com o Plano de contas taxa, o Tipo documento taxa e — quando preenchido — o Centro de custo taxa. O Plano de contas antecipação separa a taxa de antecipação da taxa comum: com ele preenchido, as duas viram lançamentos distintos; em branco, a antecipação é somada à taxa.
Privilégios da tela
Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Quando o usuário não tem o privilégio, a ação correspondente fica desabilitada na tela.
| Privilégio | Libera |
|---|---|
| Visualizar integrações | Acesso à tela de Integrações e a esta página de configuração. |
| Criar parametrizações empresa | Ativar a integração (botão + no catálogo). |
| Editar parametrizações empresa | Abrir a Configuração (engrenagem), editar nome e status e validar credenciais. |
| Deletar parametrizações empresa | Excluir a integração. |