# Integra com Asaas ou Sicoob

> Você conecta o Asaas (chave de API e chave Pix) ou o Sicoob (Client ID e chave Pix) em Configurações, na área Integrações, ou no passo 5 da criação do pré-lançamento. A cada reserva, a IDX gera um Pix de 15 minutos com a chave Pix da sua conta, e o pagamento confirmado muda as unidades para Reservado.

Publicado em 30 de outubro de 2026. Endereço: https://idxbr.com/blog/integracao-asaas-e-sicoob

## Pontos principais

- O Asaas pede chave de API e chave Pix; o Sicoob pede Client ID e chave Pix
- O Pix é gerado com as credenciais e a chave Pix da empresa dona do pré-lançamento
- Cada reserva gera um Pix com prazo de 15 minutos, no valor de reserva vezes o número de unidades
- Pago dentro do prazo, as unidades viram Reservado; vencido o prazo, voltam a Disponível
- A desconexão é recusada enquanto algum pré-lançamento usar aquele gateway

## O que o Asaas e o Sicoob fazem na IDX

O Asaas e o Sicoob geram o Pix das reservas do pré-lançamento. Quando um corretor ou um cliente reserva unidades, a IDX gera o Pix pelo gateway do pré-lançamento, espera a confirmação do banco e marca as unidades como reservadas.

O Pix sai com as credenciais e a chave Pix que a sua empresa cadastrou. Na IDX, os dois gateways servem só para isso: gerar o Pix da reserva e receber a confirmação do pagamento. A IDX não envia devolução de Pix a nenhum dos dois.

Os dados ficam guardados na conta da imobiliária ou da construtora dona do pré-lançamento. Um membro da equipe com permissão configura o gateway da empresa, e não um gateway próprio.

> [!IMPORTANTE] Não é a cobrança da sua assinatura
> A assinatura da IDX fica em outra área das Configurações, **Assinatura e cobrança**. Conectar o seu Asaas aqui não muda nada na sua assinatura, e a assinatura não usa a sua chave.

Veja todas as integrações disponíveis no [guia de integrações da IDX](/blog/integracoes-da-idx). Para ver o pré-lançamento por inteiro, conheça os [Lançamentos da IDX](/lancamentos).

## Asaas ou Sicoob: o que muda

Os dois fazem a mesma coisa na IDX. A diferença está no que cada um pede para conectar e no que vai para o banco junto com o Pix.

| Item                         | Asaas                                     | Sicoob                                  |
| ---------------------------- | ----------------------------------------- | --------------------------------------- |
| O que você informa           | **Chave de API** e **Chave PIX**          | **Client ID** e **Chave PIX**           |
| Tipo de Pix gerado           | QR code com valor fixo e um pagamento só  | Cobrança imediata                       |
| Dados do comprador no Pix    | Não vão para o Asaas                      | Nome e CPF ou CNPJ vão na cobrança      |
| Uso da chave Pix ao conectar | Não é usada: entra só na primeira reserva | Entra no registro do aviso de pagamento |
| Prazo do Pix                 | 15 minutos                                | 15 minutos                              |

Na reserva feita pelo próprio cliente, a diferença também aparece no cadastro dele. Com o Sicoob, a IDX confere se o CPF ou CNPJ é válido, com 11 ou 14 dígitos, antes de gerar o Pix. Com o Asaas, basta o documento estar preenchido.

## O que preparar antes de conectar

Você precisa de uma conta no Asaas ou no Sicoob com uma chave Pix cadastrada. A IDX não cria conta nem chave Pix para você. As telas da IDX resumem o que trazer de cada um:

- **Asaas**: "Gere sua chave de API e sua chave PIX no painel do Asaas e cole aqui."
- **Sicoob**: "Gere o Client ID na API do Sicoob e cadastre sua chave PIX. Depois, cole os dois aqui."

Na IDX, quem conecta precisa:

- Ter acesso para editar as Configurações, que é o que abre a área Integrações
- Ter permissão de criar pré-lançamentos, que é o que a IDX confere ao salvar o gateway

Quem não pode editar as Configurações vê, no lugar do formulário, "Você não tem permissão para gerenciar integrações. Peça a quem administra a conta para liberar a edição de configurações no seu cargo."

A chave de API do Asaas e o Client ID do Sicoob são credenciais da sua conta no banco. Guarde-as como uma senha.

## Os campos, um por um

O diálogo de conexão tem um bloco, **Dados de recebimento**, com dois campos. O primeiro muda de nome conforme o gateway.

| Campo            | Gateway | O que colar                                | O que a IDX recusa      |
| ---------------- | ------- | ------------------------------------------ | ----------------------- |
| **Chave de API** | Asaas   | A chave de API gerada no painel do Asaas   | Campo vazio ao conectar |
| **Client ID**    | Sicoob  | O Client ID gerado na API do Sicoob        | Campo vazio ao conectar |
| **Chave PIX**    | Os dois | A chave Pix cadastrada na conta do gateway | Campo vazio, sempre     |

As mensagens de campo vazio são "Informe a chave de API.", "Informe o Client ID." e "Informe a chave PIX.".

Alguns detalhes valem para os dois campos:

- Espaços antes e depois do texto são removidos ao salvar
- A chave de API e o Client ID ficam mascarados enquanto você digita
- Depois de salvos, a chave de API e o Client ID não voltam para a tela. Você vê só os quatro últimos caracteres, como "Chave salva: ****a91f"
- A chave Pix volta inteira, para você editar sem redigitar a outra chave

## Como conectar em Configurações

Você conecta o Asaas e o Sicoob na área de Integrações, cada um no seu cartão.

1. Abra o menu da conta, no pé da barra lateral, e clique em **Configurações**.
2. Clique em **Integrações** e abra o cartão do **Asaas** ou do **Sicoob**.
3. Clique em **Conectar**.
4. Em **Dados de recebimento**, preencha **Chave de API** (no Asaas) ou **Client ID** (no Sicoob) e a **Chave PIX**.
5. Clique em **Conectar** e espere a mensagem **Asaas conectado** ou **Sicoob conectado**.

Antes de salvar, a IDX fala com o banco. Veja o que ela confere na seção sobre [o que a IDX confere ao conectar](#o-que-a-idx-confere-ao-conectar).

## Como conectar na criação do pré-lançamento

Você também conecta o gateway durante a criação do pré-lançamento, sem passar por Configurações. É o passo 5 de 6, **Escolha onde você vai receber os pagamentos**.

1. Na criação do pré-lançamento, avance até o **Passo 5/6**.
2. Clique no cartão do **Sicoob** ou do **Asaas**.
3. No painel **Integrar com Sicoob** (ou **Integrar com Asaas**), preencha **Client ID** (ou **API Key**) e **Chave PIX**.
4. Clique em **Integrar**.
5. Espere a mensagem **Integração realizada com sucesso**. A IDX escolhe esse gateway para o pré-lançamento e segue para o passo 6.

Se o gateway já estiver conectado, o cartão mostra **Usado anteriormente** e **Dados salvos**, com a chave mascarada e a chave Pix. Um clique no cartão escolhe esse gateway e avança. O lápis ao lado de **Dados salvos** abre o painel para trocar os dados.

Nesse painel, o campo do Asaas se chama **API Key**. É o mesmo dado que a área Integrações chama de **Chave de API**. O painel também traz um quadro **Passo a Passo** com o caminho para gerar os dados em cada gateway.

## O que a IDX confere ao conectar

Antes de salvar, a IDX registra no gateway o aviso de pagamento, o webhook. É por ele que a confirmação do Pix chega à IDX. Se o registro falha, nada é salvo e você vê o motivo.

O aviso é registrado de um jeito em cada gateway:

- **Asaas**: na conta, com a chave de API. A IDX cria um webhook com o nome "idxbrasil" para o evento de pagamento recebido. Se o Asaas responder que ele já existe, a IDX aceita e segue
- **Sicoob**: na chave Pix. A IDX primeiro pede um acesso ao Sicoob com o seu Client ID e depois registra o aviso na sua chave Pix

As mensagens que podem aparecer:

| Mensagem                                                                                  | Onde olhar                          |
| ----------------------------------------------------------------------------------------- | ----------------------------------- |
| "Não foi possível validar as credenciais do Sicoob. Confira o Client ID."                 | O Client ID                         |
| "Erro ao integrar com o Sicoob:" seguido do motivo                                        | A chave Pix e o motivo informado    |
| "Erro ao integrar com o Asaas:" seguido do motivo                                         | A chave de API e o motivo informado |
| "Não foi possível falar com o Asaas. Tente novamente."                                    | Tentar de novo                      |
| "URL pública do sistema não configurada. Fale com o suporte antes de conectar o gateway." | Falar com o suporte da IDX          |
| "Configuração já existe para o ASAAS" (ou SICOOB)                                         | Usar **Gerenciar integração**       |

## O que acontece numa reserva

Cada reserva gera um Pix com prazo de 15 minutos. Pago dentro do prazo, as unidades ficam reservadas; vencido, voltam a ficar disponíveis.

### Quem gera o Pix

A reserva pode partir de três lugares, e todos usam o gateway escolhido no pré-lançamento:

- O corretor convidado, no mapa de unidades do pré-lançamento, dentro da IDX
- O corretor que entra pela página pública do evento
- O cliente, na área dele no evento

Antes do Pix, a IDX confere o limite de reservas de quem reserva e a condição comercial escolhida para cada unidade. Uma escolha inválida não gera Pix.

### Valor e prazo

O valor do Pix é o **Valor da Reserva** definido no pré-lançamento, vezes o número de unidades escolhidas. Várias unidades na mesma reserva saem num Pix só.

> [!EXEMPLO]
> Com valor de reserva de R$ 2.000 e três unidades escolhidas, o Pix sai com R$ 6.000.

O Pix é gerado com prazo de 15 minutos, tanto no Asaas quanto no Sicoob. No momento em que o Pix é gerado, as unidades ficam bloqueadas para outras reservas até o prazo acabar.

### Dados do comprador

A reserva sempre guarda nome, telefone e CPF ou CNPJ do comprador. Se o gateway não gerar a cobrança, o corretor vê "Não foi possível criar a cobrança. Confira o CPF/CNPJ informado." e as unidades são liberadas na hora.

No fluxo do cliente, se faltar nome, CPF ou CNPJ ou WhatsApp no cadastro dele, a IDX responde "Complete seu cadastro para gerar o PIX." e pede os campos que faltam.

### Confirmação do pagamento

Quando o gateway avisa que o Pix foi pago, a IDX:

1. Marca a reserva e cada unidade dela como paga.
2. Muda as unidades para **Reservado**.
3. Atualiza as telas do pré-lançamento de quem estiver com elas abertas, sem recarregar.
4. Mostra **Pagamento confirmado!** para o corretor que fez a reserva, com as unidades e o comprador.

No Sicoob, se a IDX falhar antes de gravar o pagamento, ela responde com erro ao Sicoob em vez de dar a confirmação como recebida.

### Expiração

Se o prazo acabar sem pagamento, a reserva vira **Expirado** e as unidades voltam a **Disponível**. A IDX faz essa liberação quando o contador da tela de pagamento zera e quando alguém abre a página de pagamento ou o mapa de unidades.

A confirmação que chega depois do prazo é ignorada. A IDX aceita só 2 segundos além do vencimento.

### Status da unidade em cada momento

| Momento                     | No mapa de unidades  | No histórico de reservas |
| --------------------------- | -------------------- | ------------------------ |
| Antes da reserva            | **Disponível**       | Nada                     |
| Pix gerado, esperando       | **Aguardando pgto.** | **Aguardando pagamento** |
| Pago dentro do prazo        | **Reservado**        | **Pago**                 |
| Prazo vencido sem pagamento | **Disponível**       | **Expirado**             |

## O que o comprador vê

O comprador vê o QR code, o código Pix para copiar e um contador de 15 minutos. Cada reserva tem uma página pública de pagamento, que o corretor abre em **Página de pagamento**.

A página mostra "Escaneie ou copie o código PIX", o aviso "O prazo para pagamento é de 15 minutos.", o **Valor da reserva** e o botão **Copiar código PIX**. Ela muda sozinha conforme o estado:

- Paga, mostra **Pagamento confirmado!** e o número de imóveis reservados
- Vencida, mostra **Pagamento expirado**

## O que a equipe vê

A equipe acompanha as reservas nas abas do pré-lançamento, que se atualizam a cada reserva e a cada pagamento.

- **Unidades**: o mapa, com cada unidade em **Disponível**, **Aguardando pgto.**, **Reservado** ou **Vendido**
- **Histórico de reservas**: cada reserva com comprador, telefone, CPF ou CNPJ, valor e status
- **Minhas reservas**: as reservas feitas por quem está logado, separadas em **Aguardando pagamento** e **Reservados**

O corretor que reservou vê o painel **Aguardando pagamento** enquanto o Pix está aberto, com "A reserva será confirmada após o pagamento. O prazo é de 15 minutos." e os botões **Página de pagamento** e **Copiar código PIX**.

## O que o status da integração quer dizer

O cartão do Asaas e o do Sicoob mostram um de três status, lidos das configurações salvas na conta.

| Status                  | O que significa                              | O que fazer            |
| ----------------------- | -------------------------------------------- | ---------------------- |
| **Conectado**           | Há dados salvos para este gateway            | Nada                   |
| **Desconectado**        | Nenhum dado salvo                            | Clicar em **Conectar** |
| **Status indisponível** | A IDX não conseguiu ler a configuração agora | Recarregar a página    |

O status vem só dos dados salvos. A IDX não consulta o banco para montar o cartão: se a chave deixar de valer no gateway, o cartão continua **Conectado**, e a falha aparece quando a IDX tenta gerar um Pix.

## Como trocar os dados, trocar de gateway ou desconectar

Você muda os dados e desconecta em **Gerenciar integração**, no cartão do gateway.

### Trocar a chave de API, o Client ID ou a chave Pix

1. Clique em **Gerenciar integração**.
2. Deixe **Chave de API** (ou **Client ID**) em branco para manter a chave salva, ou cole a nova.
3. Mude a **Chave PIX**, se for o caso.
4. Clique em **Salvar alterações** e espere **Dados de recebimento salvos**.

O botão **Salvar alterações** só libera quando algo muda. A IDX registra o aviso de pagamento de novo quando precisa: no Asaas, só se a chave de API mudar; no Sicoob, se o Client ID ou a chave Pix mudar. Se o registro falhar, nada muda.

A troca vale para todos os pré-lançamentos que usam aquele gateway. Os Pix já gerados continuam como foram criados.

### Trocar o gateway de um pré-lançamento

Cada pré-lançamento usa um gateway. Para trocar:

1. Na edição do pré-lançamento, clique no cartão da instituição financeira, que mostra o gateway atual.
2. Em **Escolha onde você vai receber os pagamentos**, clique no outro gateway. O atual aparece com **Selecionado**.

Se o outro gateway ainda não estiver conectado, o clique abre o painel **Integrar com** para você conectar ali.

### Desconectar

1. Clique em **Gerenciar integração**.
2. Clique em **Desconectar**.
3. Em **Desconectar o Asaas?** (ou **Desconectar o Sicoob?**), clique em **Desconectar** de novo.
4. Espere a mensagem **Asaas desconectado** ou **Sicoob desconectado**.

A IDX recusa a desconexão enquanto algum pré-lançamento usar o gateway, com "Este gateway ainda está em uso em pré-lançamentos". Entram nessa conta todos os pré-lançamentos ligados ao gateway, no ar ou não. Os pagamentos já registrados não mudam.

Como o pré-lançamento só troca para um gateway conectado, desconectar o único gateway da conta exige conectar o outro antes e trocar a instituição financeira em cada pré-lançamento.

## Como Asaas e Sicoob se conectam com o resto da IDX

O gateway liga a reserva do pré-lançamento ao Pix na conta da sua empresa. Veja cada ligação:

- **Pré-lançamento**: cada pré-lançamento usa um gateway, escolhido no passo 5 da criação ou na edição. Não há pré-lançamento sem gateway
- **Imóveis e unidades**: o Pix bloqueia as unidades por 15 minutos, e o pagamento as muda para **Reservado**. Veja como [cadastrar o empreendimento e as unidades](/blog/cadastrar-empreendimento-e-unidades)
- **Condições comerciais**: a reserva guarda a condição comercial escolhida para cada unidade. O valor do Pix, porém, é o valor de reserva, e não o preço da condição
- **Corretores convidados**: o limite de reservas de cada corretor conta as reservas pagas e as que ainda aguardam pagamento
- **Clientes do evento**: o cliente reserva e gera o Pix sozinho, depois de completar o cadastro
- **Membros e permissões**: conectar exige editar as Configurações e criar pré-lançamento; trocar os dados exige editar pré-lançamento, e desconectar exige excluir
- **Tempo real**: reserva nova e pagamento confirmado atualizam as telas do pré-lançamento que estão abertas
- **Auditoria**: conectar, trocar os dados, desconectar e trocar o gateway de um pré-lançamento ficam registrados com quem fez
- **Assinatura da IDX**: não tem ligação. A assinatura fica em **Assinatura e cobrança**

## Qual plano libera o Asaas e o Sicoob

O pré-lançamento e as integrações estão em todos os planos, inclusive no Essencial. Nenhum passo desta integração depende do Profissional ou do Avançado.

Quem cria o pré-lançamento e conecta o gateway é a imobiliária ou a construtora, ou um membro com permissão. O corretor autônomo participa dos pré-lançamentos para os quais é convidado, mas não cria pré-lançamento nem conecta gateway.

## Perguntas frequentes

### O Pix da reserva passa por alguma conta da IDX?

Não. A IDX gera o Pix com a chave de API ou o Client ID e a chave Pix que a sua empresa cadastrou. A assinatura da IDX é outra cobrança, em outra área das Configurações, e não usa esses dados.

### Posso conectar o Asaas e o Sicoob ao mesmo tempo?

Pode. A conta guarda uma configuração de cada. Cada pré-lançamento usa uma delas, escolhida no passo 5 da criação ou depois, na edição do pré-lançamento.

### Por que não consigo desconectar o Asaas ou o Sicoob?

Porque algum pré-lançamento ainda usa aquele gateway. A IDX recusa com a mensagem "Este gateway ainda está em uso em pré-lançamentos". Troque a instituição financeira nesses pré-lançamentos e tente de novo.

### O que acontece se a confirmação do pagamento chegar depois dos 15 minutos?

A IDX não confirma a reserva. Passado o prazo, ela ignora a confirmação que chega do banco, e a reserva fica como expirada, com as unidades livres para outra reserva.

### Trocar a chave Pix afeta as reservas que já estão aguardando pagamento?

Não. Os Pix já gerados ficam como foram criados, e só os próximos saem com a chave nova. No Sicoob, a IDX registra de novo o aviso de pagamento na chave nova antes de salvar a troca.