BasimobBasimob

Documentação da API

Tudo que um sistema de fora consegue fazer no seu CRM com uma chave de API: consultar sua base e criar registros. Para o caminho contrário — o CRM avisando o outro sistema —, veja a documentação de webhooks.

Nesta página

Começar#

Três passos: gere uma chave, copie o comando abaixo trocando SUA_CHAVE, e rode. Ele cria um lead de verdade no seu funil.

Primeiro comando

curl -X POST "https://api.basimob.app/v1/leads" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "nome": "Maria Silva",
    "celular": "11999998888",
    "email": "maria@exemplo.com",
    "mensagem": "Tenho interesse no apartamento do centro"
  }'
  • · O endereço é sempre o do Basimob (https://api.basimob.app) — a sua conta é identificada pela chave, então você nunca envia o id da organização.
  • · Toda resposta é JSON, com Content-Type: application/json.
  • · Leitura e escrita são permissões separadas: a chave só faz o que você marcou.

Autenticação#

Toda chamada leva a chave no cabeçalho. Guarde-a num cofre de segredos: quem tem a chave age no seu CRM.

Authorization: Bearer SUA_CHAVE

O cabeçalho X-Api-Key: SUA_CHAVE também é aceito, para ferramentas que não deixam escrever Authorization.

  • · A chave pode ter data de expiração: depois dela, toda chamada volta 401 chave_expirada.
  • · A chave pode aceitar só certos IPs: origem fora da lista recebe 403 ip_nao_autorizado. Peça ao time que vai integrar o IP de saída do servidor deles.
  • · Revogar é imediato e não tem volta — a chave revogada passa a responder 401 na hora seguinte.

Leads e atendimento#

5 endpoints nesta área.

GET/v1/leadsListar leadsver detalhes
exige ler leads

Devolve os leads da imobiliária, do mais recente para o mais antigo, com paginação por cursor. A resposta traz `dados` e `proximoCursor` (null na última página).

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • statusFiltra pela chave da coluna do funil.
  • celularFiltra por celular (só dígitos, casamento parcial).
  • emailFiltra por e-mail exato.
  • arquivados`excluir` (padrão), `incluir` ou `apenas`.

Requisição

curl -X GET "https://api.basimob.app/v1/leads?limite=50&status=NOVO" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmd9x2v4k0001",
      "nome": "Maria Silva",
      "email": "maria@exemplo.com",
      "celular": "11999998888",
      "status": "NOVO",
      "origem": "SITE",
      "responsavel": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "equipe": {
        "id": "cmeq1v2n3",
        "nome": "Vendas"
      },
      "criadoEm": "2026-07-25T13:40:02.118Z"
    }
  ],
  "proximoCursor": null
}
POST/v1/leadsCriar leadver detalhes
exige criar leadsaceita Idempotency-Key

Cria um lead pelo mesmo caminho de um lead do site: deduplicação, distribuição para o corretor, notificação e disparo dos webhooks de saída.

Corpo

  • nomeobrigatórioNome do contato.
  • celularobrigatórioDDD + número, só dígitos.
  • emailE-mail do contato.
  • mensagemTexto que o contato enviou — vira a primeira atividade do lead.
  • imovelIdVincula o lead a um imóvel do seu cadastro.
  • empreendimentoIdVincula o lead a um empreendimento.

Requisição

curl -X POST "https://api.basimob.app/v1/leads" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "nome": "Maria Silva",
    "celular": "11999998888",
    "email": "maria@exemplo.com",
    "mensagem": "Tenho interesse no apartamento do centro"
  }'

Corpo enviado

{
  "nome": "Maria Silva",
  "celular": "11999998888",
  "email": "maria@exemplo.com",
  "mensagem": "Tenho interesse no apartamento do centro"
}

Resposta

201 {
  "success": true,
  "leadId": "cmd9x2v4k0001"
}
POST/v1/leads/{id}/atividadesRegistrar nota em um leadver detalhes
exige registrar atividadesaceita Idempotency-Key

Anexa uma nota à linha do tempo de um lead existente.

Corpo

  • descricaoobrigatórioTexto da nota.

Parâmetros

  • idId do lead (o `leadId` devolvido na criação).

Requisição

curl -X POST "https://api.basimob.app/v1/leads/LEAD_ID/atividades" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "descricao": "Cliente respondeu o e-mail e pediu para ligar à tarde"
  }'

Corpo enviado

{
  "descricao": "Cliente respondeu o e-mail e pediu para ligar à tarde"
}

Resposta

201 {
  "success": true,
  "leadId": "cmd9x2v4k0001"
}
POST/v1/leads/{id}/statusMudar a etapa de um leadver detalhes
exige alterar etapa de leadsaceita Idempotency-Key

Move o lead para outra coluna do seu funil e registra a mudança na linha do tempo.

Não altera o responsável do lead — mantém quem já estava. O status precisa ser a chave de uma coluna existente no seu funil.

Corpo

  • statusobrigatórioChave da coluna do funil.
  • noteMotivo da mudança.

Parâmetros

  • idId do lead.

Requisição

curl -X POST "https://api.basimob.app/v1/leads/LEAD_ID/status" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "status": "EM_ATENDIMENTO",
    "note": "Retornou o contato"
  }'

Corpo enviado

{
  "status": "EM_ATENDIMENTO",
  "note": "Retornou o contato"
}

Resposta

200 {
  "success": true,
  "leadId": "cmd9x2v4k0001",
  "status": "EM_ATENDIMENTO"
}
GET/v1/atividadesListar atividadesver detalhes
exige ler atividades

Linha do tempo da imobiliária: notas, mudanças de etapa, visitas e o que mais o CRM registra. Filtre por `leadId` para a timeline de um lead.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • leadIdSó as atividades deste lead.
  • tipoTipo da atividade (ex.: NOTA, LIGACAO, VISITA).

Requisição

curl -X GET "https://api.basimob.app/v1/atividades?limite=50&tipo=NOTA" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmda1b2c3",
      "tipo": "NOTA",
      "descricao": "Cliente pediu para ligar à tarde",
      "leadId": "cmd9x2v4k0001",
      "autor": null,
      "criadoEm": "2026-07-25T14:02:11.482Z"
    }
  ],
  "proximoCursor": null
}

Portfólio#

7 endpoints nesta área.

GET/v1/imoveisListar imóveisver detalhes
exige ler imóveis

Devolve o cadastro de imóveis da imobiliária com preços, características e endereço. Inclui imóvel oculto do site e status não-disponível — é a sua base, não a vitrine pública.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • codigoFiltra pelo código do imóvel.
  • tipoCASA, APARTAMENTO, TERRENO, COMERCIAL ou RURAL.
  • subtipoRecorte fino do tipo (CHACARA, KITNET, GALPAO, LOTE…). Quando informado, dispensa o `tipo`.
  • finalidadeVENDA, LOCACAO ou AMBOS.
  • statusDISPONIVEL, RESERVADO, VENDIDO, ALUGADO ou INATIVO.
  • cidadeFiltra pela cidade (exato, sem diferenciar maiúsculas).

Requisição

curl -X GET "https://api.basimob.app/v1/imoveis?limite=50&tipo=APARTAMENTO&subtipo=COBERTURA" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmd7a1b2c0004",
      "codigo": "AP-1042",
      "titulo": "Apartamento 2 quartos no Centro",
      "tipo": "APARTAMENTO",
      "subtipo": "APARTAMENTO",
      "finalidade": "VENDA",
      "status": "DISPONIVEL",
      "precoVenda": 450000,
      "quartos": 2,
      "endereco": {
        "cidade": "Porto Alegre",
        "estado": "RS",
        "bairro": "Centro"
      }
    }
  ],
  "proximoCursor": "cmd7a1b2c0004"
}
GET/v1/empreendimentosListar empreendimentosver detalhes
exige ler empreendimentos

Empreendimentos com construtora, andamento de obra, faixa de preço e quantas unidades já estão cadastradas. Rascunho não aparece.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • cidadeFiltra pela cidade.
  • ativo`true` ou `false`.

Requisição

curl -X GET "https://api.basimob.app/v1/empreendimentos?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdb1c2d3",
      "nome": "Residencial Aurora",
      "codigo": "AUR",
      "statusObra": "EM_OBRAS",
      "precoMinimo": 380000,
      "unidadesCadastradas": 24,
      "endereco": {
        "cidade": "Porto Alegre",
        "estado": "RS"
      }
    }
  ],
  "proximoCursor": null
}
GET/v1/proprietariosListar proprietáriosver detalhes
exige ler proprietários

Base de proprietários com contato e quantos imóveis cada um tem na sua carteira.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.

Requisição

curl -X GET "https://api.basimob.app/v1/proprietarios?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdc1d2e3",
      "nome": "Carlos Pereira",
      "email": "carlos@exemplo.com",
      "celular": "51999990000",
      "tipoPessoa": "FISICA",
      "imoveis": 3
    }
  ],
  "proximoCursor": null
}
POST/v1/imoveisCadastrar imóvelver detalhes
exige cadastrar e editar imóveisaceita Idempotency-Key

Cadastra imóvel com as mesmas regras da tela: descrição mínima, novo/usado exigido em casa, apartamento e comercial, código gerado pelo tipo e vínculos conferidos nesta conta.

O imóvel nasce fora do site (`visivelNoSite` falso) e sem fotos — a galeria sobe pela tela. Conta no limite de imóveis do plano: estourado, volta 403 limite_do_plano. Sem `responsavelId` nem `equipeId`, o imóvel é de toda a imobiliária.

Corpo

  • tituloobrigatórioTítulo do anúncio (5 a 200 caracteres).
  • descricaoobrigatórioDescrição, com pelo menos 20 caracteres de texto. Aceita HTML simples, que é saneado.
  • tipoobrigatórioCASA, APARTAMENTO, TERRENO, COMERCIAL ou RURAL.
  • subtipoRecorte fino do tipo (ex.: COBERTURA, STUDIO, SOBRADO). Sem ele, vale o subtipo de mesmo nome do tipo.
  • finalidadeobrigatórioVENDA, LOCACAO ou AMBOS.
  • condicaoNOVO ou USADO — exigido em casa, apartamento e comercial; recusado em terreno e rural.
  • cepobrigatórioCEP, com ou sem hífen.
  • ruaLogradouro.
  • numeroNúmero.
  • complementoComplemento (apartamento, bloco).
  • bairroBairro.
  • cidadeobrigatórioCidade.
  • estadoobrigatórioUF com 2 letras.
  • precoVendaPreço de venda em reais (número). Ignorado quando a finalidade é só LOCACAO.
  • precoAluguelAluguel mensal em reais (número). Ignorado quando a finalidade é só VENDA.
  • taxaCondominioCondomínio mensal em reais (número).
  • iptuIPTU mensal em reais (número).
  • custosPersonalizadosOutros custos mensais do imóvel: lista de { id, nome, valor } (valor em reais), até 10.
  • areaÁrea em m² (número).
  • quartosQuartos (inteiro).
  • suitesSuítes (inteiro, no máximo o número de quartos).
  • banheirosBanheiros (inteiro).
  • vagasGaragemVagas de garagem (inteiro).
  • aceitaPetAceita animal de estimação (booleano).
  • mobiliaNAO_MOBILIADO, SEMI_MOBILIADO ou MOBILIADO.
  • aceitaPermutaAceita permuta (booleano).
  • codigoInternoCódigo próprio da imobiliária, buscável no CRM.
  • visivelNoSitePublicar no site já no cadastro (booleano). Padrão: falso.
  • proprietariosDonos do imóvel (de GET /v1/proprietarios), na ordem: `[{ proprietarioId, percentual }]`. Com mais de um, as partes somam 100% ou vão todas nulas.
  • captadorIdCaptador do imóvel.
  • empreendimentoIdEmpreendimento de origem (de GET /v1/empreendimentos).
  • responsavelIdPessoa responsável (de GET /v1/equipe). Não envie junto de `equipeId`.
  • equipeIdEquipe responsável. Não envie junto de `responsavelId`.

Requisição

curl -X POST "https://api.basimob.app/v1/imoveis" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "titulo": "Apartamento 2 dormitórios no Centro",
    "descricao": "Apartamento reformado, com sacada, perto do comércio e do transporte.",
    "tipo": "APARTAMENTO",
    "finalidade": "VENDA",
    "condicao": "USADO",
    "cep": "90010-000",
    "rua": "Rua dos Andradas",
    "numero": "1234",
    "bairro": "Centro Histórico",
    "cidade": "Porto Alegre",
    "estado": "RS"
  }'

Corpo enviado

{
  "titulo": "Apartamento 2 dormitórios no Centro",
  "descricao": "Apartamento reformado, com sacada, perto do comércio e do transporte.",
  "tipo": "APARTAMENTO",
  "finalidade": "VENDA",
  "condicao": "USADO",
  "cep": "90010-000",
  "rua": "Rua dos Andradas",
  "numero": "1234",
  "bairro": "Centro Histórico",
  "cidade": "Porto Alegre",
  "estado": "RS"
}

Resposta

201 {
  "success": true,
  "imovelId": "cmimv1a2b3",
  "codigo": "CA-042"
}
PATCH/v1/imoveis/{id}Atualizar imóvelver detalhes
exige cadastrar e editar imóveisaceita Idempotency-Key

Atualização parcial: só os campos enviados mudam. A validação é a do cadastro da tela — preço que a finalidade não comporta é descartado, e os vínculos são conferidos nesta conta.

O status do imóvel (vendido, alugado, inativo) não muda por aqui: ele tem efeitos no funil e no site, e é alterado pela tela.

Corpo

  • tituloNovo título.
  • descricaoNova descrição (pelo menos 20 caracteres de texto).
  • tipoCASA, APARTAMENTO, TERRENO, COMERCIAL ou RURAL.
  • subtipoRecorte fino do tipo.
  • finalidadeVENDA, LOCACAO ou AMBOS.
  • condicaoNOVO ou USADO.
  • cepCEP.
  • ruaLogradouro.
  • numeroNúmero.
  • complementoComplemento.
  • bairroBairro.
  • cidadeCidade.
  • estadoUF com 2 letras.
  • precoVendaPreço de venda em reais (número).
  • precoAluguelAluguel mensal em reais (número).
  • taxaCondominioCondomínio mensal (número).
  • iptuIPTU mensal (número).
  • custosPersonalizadosOutros custos mensais: a lista enviada SUBSTITUI a gravada; lista vazia apaga.
  • areaÁrea em m² (número).
  • quartosQuartos (inteiro).
  • suitesSuítes (inteiro).
  • banheirosBanheiros (inteiro).
  • vagasGaragemVagas de garagem (inteiro).
  • aceitaPetAceita animal de estimação (booleano).
  • mobiliaNAO_MOBILIADO, SEMI_MOBILIADO ou MOBILIADO.
  • aceitaPermutaAceita permuta (booleano).
  • codigoInternoCódigo próprio da imobiliária.
  • visivelNoSitePublicar ou tirar do site (booleano).
  • proprietariosDonos do imóvel: a lista enviada SUBSTITUI a gravada; lista vazia tira todos.
  • captadorIdCaptador.
  • empreendimentoIdEmpreendimento de origem.
  • responsavelIdPessoa responsável. Não envie junto de `equipeId`.
  • equipeIdEquipe responsável. Não envie junto de `responsavelId`.

Parâmetros

  • idId do imóvel (de GET /v1/imoveis).

Requisição

curl -X PATCH "https://api.basimob.app/v1/imoveis/IMOVEL_ID" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "titulo": "Apartamento 2 dormitórios com sacada"
  }'

Corpo enviado

{
  "titulo": "Apartamento 2 dormitórios com sacada"
}

Resposta

200 {
  "success": true,
  "imovelId": "cmimv1a2b3",
  "codigo": "CA-042"
}
POST/v1/proprietariosCadastrar proprietáriover detalhes
exige cadastrar e editar proprietáriosaceita Idempotency-Key

Cadastra proprietário com deduplicação por CPF/CNPJ. Se vier `leadId`, o lead ganha o papel de proprietário na mesma transação.

Documento já cadastrado volta 409 conflito — a API não cria proprietário duplicado.

Corpo

  • nomeobrigatórioNome do proprietário.
  • emailE-mail de contato.
  • celularCelular de contato.
  • documentoCPF ou CNPJ (com ou sem máscara).
  • tipoPessoaFISICA ou JURIDICA. Derivado do `documento` quando ele vem (11 dígitos = FISICA, 14 = JURIDICA); só é usado quando não há documento.
  • leadIdLead que virou proprietário.
  • dadosBancariosPara onde vai o repasse, guardado cifrado. Pix: `{ metodo: "PIX", pixTipo: "CPF"|"CNPJ"|"EMAIL"|"TELEFONE"|"ALEATORIA", pixChave }`. Conta: `{ metodo: "CONTA", bancoCompe: "341", agencia: "1234", conta: "12345", contaDigito: "6", tipoConta: "CORRENTE"|"POUPANCA" }`. Conta de outra pessoa: `titularidadePropria: false`, `titularNome` e `titularDocumento` (CPF ou CNPJ).
  • taxaAdminCustomTaxa de administração específica deste proprietário (%).

Requisição

curl -X POST "https://api.basimob.app/v1/proprietarios" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "nome": "Carlos Pereira",
    "email": "carlos@exemplo.com",
    "celular": "51999990000"
  }'

Corpo enviado

{
  "nome": "Carlos Pereira",
  "email": "carlos@exemplo.com",
  "celular": "51999990000"
}

Resposta

201 {
  "success": true,
  "proprietarioId": "cmdc1d2e3"
}
PATCH/v1/proprietarios/{id}Atualizar proprietáriover detalhes
exige cadastrar e editar proprietáriosaceita Idempotency-Key

Atualização parcial: só os campos enviados são alterados; o resto permanece como está.

Corpo

  • nomeNovo nome.
  • emailNovo e-mail.
  • celularNovo celular.
  • documentoNovo CPF/CNPJ.
  • tipoPessoaFISICA ou JURIDICA. O `documento` tem precedência — informá-lo já define o tipo.
  • leadIdLead vinculado.
  • dadosBancariosPara onde vai o repasse, no mesmo formato da criação — substitui os atuais.
  • taxaAdminCustomTaxa de administração (%).

Parâmetros

  • idId do proprietário.

Requisição

curl -X PATCH "https://api.basimob.app/v1/proprietarios/PROPRIETARIO_ID" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "nome": "Carlos A. Pereira"
  }'

Corpo enviado

{
  "nome": "Carlos A. Pereira"
}

Resposta

200 {
  "success": true,
  "proprietarioId": "cmdc1d2e3"
}

Comercial#

3 endpoints nesta área.

GET/v1/vendasListar vendas e propostasver detalhes
exige ler vendas e propostas

Vendas/propostas com etapa, valor, lead e corretor responsável.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • statusStatus da venda (ex.: EM_ANDAMENTO).
  • etapaEtapa do fluxo de venda.
  • leadIdSó as vendas deste lead.
  • arquivados`excluir` (padrão), `incluir` ou `apenas`.

Requisição

curl -X GET "https://api.basimob.app/v1/vendas?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdd1e2f3",
      "numero": "V-1042",
      "status": "EM_ANDAMENTO",
      "etapa": "PROPOSTA",
      "valor": 450000,
      "lead": {
        "id": "cmd9x2v4k0001",
        "nome": "Maria Silva"
      },
      "corretor": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      }
    }
  ],
  "proximoCursor": null
}
GET/v1/simulacoesListar simulaçõesver detalhes
exige ler simulações

Simulações de financiamento geradas no CRM ou no seu site, com valor do imóvel, entrada e prazo.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • statusStatus da simulação.
  • leadIdSó as simulações deste lead.

Requisição

curl -X GET "https://api.basimob.app/v1/simulacoes?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmde1f2g3",
      "status": "CONCLUIDA",
      "origem": "SITE",
      "nomeCliente": "Maria Silva",
      "valorImovel": 450000,
      "entrada": 90000,
      "prazoDesejado": 360
    }
  ],
  "proximoCursor": null
}
POST/v1/vendasAbrir proposta de vendaver detalhes
exige abrir propostasaceita Idempotency-Key

Abre a venda na etapa de proposta, como a tela: número sequencial, comissão pré-preenchida pelo empreendimento, pelo padrão do corretor e pelo captador, e a unidade de empreendimento reservada para esta proposta.

Informe imovelId OU unidadeId. Unidade que não está livre volta 409 conflito — de duas propostas simultâneas para a mesma unidade, só a primeira entra. A etapa avança pela tela.

Corpo

  • leadIdobrigatórioCliente comprador (de GET /v1/leads).
  • imovelIdImóvel vendido (de GET /v1/imoveis). Não envie junto de `unidadeId`.
  • unidadeIdUnidade de empreendimento. Não envie junto de `imovelId`.
  • responsavelIdobrigatórioCorretor responsável (de GET /v1/equipe) — a venda tem sempre uma pessoa responsável.
  • valorobrigatórioValor da proposta em reais.
  • condicoesPagamentoCondições de pagamento, em texto.
  • observacoesObservações internas.
  • simulacaoIdSimulação de financiamento vinculada (de GET /v1/simulacoes).

Requisição

curl -X POST "https://api.basimob.app/v1/vendas" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "leadId": "LEAD_ID",
    "imovelId": "IMOVEL_ID",
    "responsavelId": "USUARIO_ID",
    "valor": "350000"
  }'

Corpo enviado

{
  "leadId": "LEAD_ID",
  "imovelId": "IMOVEL_ID",
  "responsavelId": "USUARIO_ID",
  "valor": "350000"
}

Resposta

201 {
  "success": true,
  "vendaId": "cmvnd1a2b3",
  "numero": "VND-000128"
}

Agenda e tarefas#

4 endpoints nesta área.

GET/v1/agendaListar agendaver detalhes
exige ler agenda

Visitas e compromissos da equipe inteira. Use `de`/`ate` para a janela por data de início.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • deInício da janela (ISO 8601), pela data do compromisso.
  • ateFim da janela (ISO 8601).
  • statusStatus do compromisso (ex.: AGENDADO).
  • tipoTipo (ex.: VISITA).
  • responsavelIdSó os compromissos deste membro.
  • leadIdSó os compromissos deste lead.

Requisição

curl -X GET "https://api.basimob.app/v1/agenda?limite=50&de=2026-07-25T00%3A00%3A00Z" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdf1g2h3",
      "titulo": "Visita — Apto Centro",
      "tipo": "VISITA",
      "status": "AGENDADO",
      "iniciaEm": "2026-07-28T17:00:00.000Z",
      "terminaEm": "2026-07-28T18:00:00.000Z",
      "responsavel": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "equipe": {
        "id": "cmeq1v2n3",
        "nome": "Vendas"
      }
    }
  ],
  "proximoCursor": null
}
GET/v1/tarefasListar tarefasver detalhes
exige ler tarefas

Tarefas da equipe com prioridade, prazo e responsável.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • statusStatus (ex.: PENDENTE).
  • prioridadePrioridade (ex.: ALTA).
  • responsavelIdSó as tarefas deste membro.
  • leadIdSó as tarefas deste lead.

Requisição

curl -X GET "https://api.basimob.app/v1/tarefas?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdg1h2i3",
      "titulo": "Enviar proposta revisada",
      "status": "PENDENTE",
      "prioridade": "ALTA",
      "dataVencimento": "2026-07-29T12:00:00.000Z",
      "responsavel": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "equipe": {
        "id": "cmeq1v2n3",
        "nome": "Vendas"
      }
    }
  ],
  "proximoCursor": null
}
POST/v1/tarefasCriar tarefaver detalhes
exige criar tarefasaceita Idempotency-Key

Cria uma tarefa pelo mesmo caminho da tela: notifica o responsável, entra no realtime e dispara o webhook de saída.

Informe `responsavelId` (uma pessoa) OU `equipeId` (uma equipe). Sem os dois, a tarefa fica com toda a imobiliária — via API não existe "quem criou" para herdar a tarefa.

Corpo

  • tituloobrigatórioTítulo da tarefa.
  • descricaoDetalhes.
  • prioridadeBAIXA, MEDIA, ALTA ou URGENTE.
  • statusPENDENTE (padrão), EM_ANDAMENTO ou CONCLUIDA.
  • dataVencimentoPrazo, em ISO 8601 com fuso.
  • lembreteEmQuando lembrar o responsável (ISO 8601).
  • responsavelIdA pessoa que recebe a tarefa.
  • equipeIdA equipe que recebe a tarefa, sem pessoa — quem é dela pega.
  • leadIdVincula a tarefa a um lead.
  • imovelIdVincula a um imóvel.
  • vendaIdVincula a uma venda.

Requisição

curl -X POST "https://api.basimob.app/v1/tarefas" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "titulo": "Enviar proposta revisada",
    "descricao": "Cliente pediu com o desconto aprovado",
    "prioridade": "ALTA"
  }'

Corpo enviado

{
  "titulo": "Enviar proposta revisada",
  "descricao": "Cliente pediu com o desconto aprovado",
  "prioridade": "ALTA"
}

Resposta

201 {
  "success": true,
  "tarefaId": "cmdg1h2i3"
}
POST/v1/agendaAgendar compromissover detalhes
exige agendaraceita Idempotency-Key

Cria visita ou compromisso pelo caminho da tela: notifica o responsável, sincroniza com o Google Agenda quando conectado e dispara o webhook `Visita agendada`.

Informe `responsavelId` (uma pessoa) OU `equipeId` (uma equipe); sem os dois, o compromisso fica com toda a imobiliária. `terminaEm` precisa ser depois de `iniciaEm`.

Corpo

  • tituloobrigatórioTítulo do compromisso.
  • tipoobrigatórioVISITA, REUNIAO, LIGACAO ou OUTROS.
  • iniciaEmobrigatórioInício, em ISO 8601 com fuso.
  • terminaEmobrigatórioFim, em ISO 8601 com fuso.
  • descricaoDetalhes do compromisso.
  • localLocal combinado.
  • enderecoEndereço completo.
  • diaInteiroCompromisso de dia inteiro (padrão false).
  • lembreteLiga o lembrete interno (padrão false).
  • lembrarEmQuando lembrar (ISO 8601).
  • responsavelIdA pessoa que atende o compromisso.
  • equipeIdA equipe que atende o compromisso, sem pessoa.
  • leadIdVincula a um lead.
  • imovelIdVincula a um imóvel.
  • vendaIdVincula a uma venda.

Requisição

curl -X POST "https://api.basimob.app/v1/agenda" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "titulo": "Visita — Apto Centro",
    "tipo": "VISITA",
    "iniciaEm": "2026-08-01T14:00:00Z",
    "terminaEm": "2026-08-01T15:00:00Z",
    "local": "Portaria do edifício"
  }'

Corpo enviado

{
  "titulo": "Visita — Apto Centro",
  "tipo": "VISITA",
  "iniciaEm": "2026-08-01T14:00:00Z",
  "terminaEm": "2026-08-01T15:00:00Z",
  "local": "Portaria do edifício"
}

Resposta

201 {
  "success": true,
  "agendamentoId": "cmdf1g2h3"
}

Locação#

3 endpoints nesta área.

GET/v1/contratosListar contratos de aluguelver detalhes
exige ler contratos de aluguel

Contratos com vigência, valor, taxa de administração e próximo reajuste.

Área de locação: exige o plano com gestão de aluguel. Sem ele, a chamada volta 403 feature_indisponivel.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • statusStatus do contrato (ex.: ATIVO).
  • imovelIdSó os contratos deste imóvel.

Requisição

curl -X GET "https://api.basimob.app/v1/contratos?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdh1i2j3",
      "numero": "C-204",
      "status": "ATIVO",
      "valorAluguel": 2500,
      "diaVencimento": 10,
      "iniciaEm": "2026-01-10T03:00:00.000Z",
      "terminaEm": "2027-01-09T03:00:00.000Z",
      "locatario": {
        "id": "cmd9x2v4k0001",
        "nome": "Maria Silva"
      },
      "locatarios": [
        {
          "id": "cmd9x2v4k0001",
          "nome": "Maria Silva",
          "ordem": 1
        },
        {
          "id": "cmd9x2v4k0002",
          "nome": "João Silva",
          "ordem": 2
        }
      ],
      "proprietarioId": "cmdc1d2e3",
      "locadores": [
        {
          "proprietarioId": "cmdc1d2e3",
          "nome": "Ana Souza",
          "ordem": 1,
          "percentual": 60
        },
        {
          "proprietarioId": "cmdc4f5g6",
          "nome": "Carlos Souza",
          "ordem": 2,
          "percentual": 40
        }
      ]
    }
  ],
  "proximoCursor": null
}
GET/v1/pagamentosListar cobranças de aluguelver detalhes
exige ler cobranças de aluguel

Parcelas com vencimento, valor, multa/juros e data de pagamento. Use `venceDe`/`venceAte` para a régua de cobrança.

Área de locação: exige o plano com gestão de aluguel.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • venceDeVencimento a partir de (ISO 8601).
  • venceAteVencimento até (ISO 8601).
  • statusStatus do pagamento (ex.: PENDENTE, PAGO).
  • contratoIdSó as parcelas deste contrato.

Requisição

curl -X GET "https://api.basimob.app/v1/pagamentos?limite=50&venceDe=2026-07-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdi1j2k3",
      "contratoId": "cmdh1i2j3",
      "status": "PENDENTE",
      "numeroParcela": 7,
      "valorTotal": 2750,
      "dataVencimento": "2026-08-10T03:00:00.000Z",
      "pagoEm": null
    }
  ],
  "proximoCursor": null
}
GET/v1/vistoriasListar vistoriasver detalhes
exige ler vistorias

Laudos de vistoria com tipo, estado geral e situação do aceite bilateral.

Exige o plano com vistoria digital.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • statusStatus do laudo.
  • tipoENTRADA ou SAIDA.
  • contratoIdSó as vistorias deste contrato.

Requisição

curl -X GET "https://api.basimob.app/v1/vistorias?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdj1k2l3",
      "tipo": "ENTRADA",
      "status": "CONCLUIDA",
      "estadoGeral": "BOM",
      "situacaoAceite": "ACEITA",
      "ambientes": 6
    }
  ],
  "proximoCursor": null
}

Gestão#

2 endpoints nesta área.

GET/v1/financeiroListar lançamentos financeirosver detalhes
exige ler financeiro

Lançamentos do financeiro manual da imobiliária, com categoria e data.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • tipoRECEITA ou DESPESA.
  • deData do lançamento a partir de (ISO 8601).
  • ateData do lançamento até (ISO 8601).

Requisição

curl -X GET "https://api.basimob.app/v1/financeiro?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdk1l2m3",
      "tipo": "DESPESA",
      "descricao": "Anúncio no portal",
      "valor": 890,
      "data": "2026-07-20T03:00:00.000Z",
      "categoria": {
        "id": "cmdk9z",
        "nome": "Marketing"
      }
    }
  ],
  "proximoCursor": null
}
GET/v1/equipeListar equipever detalhes
exige ler equipe

Membros da equipe com nome, e-mail de trabalho e papel — para mapear responsáveis num BI.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • desdeSó registros criados a partir desta data (ISO 8601) — sincronização incremental.
  • ativo`true` ou `false`.

Requisição

curl -X GET "https://api.basimob.app/v1/equipe?limite=50" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmd6u1p2z0003",
      "nome": "João Corretor",
      "email": "joao@imobiliaria.com",
      "papel": "CORRETOR",
      "ativo": true
    }
  ],
  "proximoCursor": null
}

Paginação#

As listagens devolvem uma página de dados e o ponteiro da próxima. Repita passando o cursor até ele vir nulo.

# primeira página
GET /v1/leads?limite=100

# seguinte (use o proximoCursor da resposta)
GET /v1/leads?limite=100&cursor=cmd9x2v4k0001

# só o que entrou depois de ontem — sincronização incremental
GET /v1/leads?desde=2026-07-24T00:00:00Z

Use desde com a data da última sincronização em vez de varrer tudo de novo: é mais rápido para você e não gasta a sua cota à toa.

Repetir sem duplicar#

Se a rede cair depois de o lead já ter sido criado, repetir a chamada criaria um segundo. O cabeçalho de idempotência resolve isso.

Idempotency-Key: pedido-4f2a9c

Por 24 horas, a mesma chave devolve a mesma resposta em vez de executar de novo — a repetição vem com Idempotent-Replay: true.

  • · Use uma chave nova por intenção (ex.: o id do envio no outro sistema).
  • · Reutilizar a mesma chave com um corpo diferente é erro (422), não um replay silencioso.
  • · Duas chamadas simultâneas com a mesma chave: a segunda recebe 409.
  • · Erro nosso (500) não fica guardado: pode repetir com a mesma chave.

Limites de uso#

Por chave e por tipo de operação: 120 leituras e 30 escritas por minuto, em contadores independentes — paginar um catálogo não consome a cota de quem está criando registros.

Cabeçalhos presentes em toda resposta

X-RateLimit-Limit: 120       # chamadas na janela (deste tipo)
X-RateLimit-Remaining: 117   # quantas ainda cabem
X-RateLimit-Reset: 1769...   # quando a janela reinicia (epoch ms)

Leia os cabeçalhos em vez de adivinhar o intervalo entre chamadas. Estourou, a resposta é 429 limite_excedido: espere o reset e siga do mesmo cursor.

Erros#

Erro vem sempre como { "error": "…", "codigo": "…" }. Trate pelo código, que é estável — nunca pelo texto da mensagem.

  • 400corpo_invalidoO corpo enviado não é um JSON válido.
  • 401chave_ausenteFaltou o header de autenticação.
  • 401nao_autenticadoChave inválida ou revogada.
  • 401chave_expiradaA chave passou da data de expiração definida no console.
  • 403sem_permissaoA chave não tem a permissão exigida pelo endpoint.
  • 403ip_nao_autorizadoA chave restringe origens e o IP de quem chamou não está na lista.
  • 403limite_do_planoA conta chegou ao limite do plano para este cadastro, ou está com a assinatura bloqueada — quem resolve é o administrador, no plano.
  • 404nao_encontradoO recurso citado no caminho não existe nesta conta.
  • 409conflito_idempotenciaOutra requisição com a mesma Idempotency-Key ainda está em andamento.
  • 422dados_invalidosRequisição bem-formada, mas com dado inválido — a mensagem diz qual.
  • 422chave_idempotencia_reutilizadaA mesma Idempotency-Key foi usada com um corpo diferente.
  • 429limite_excedidoLimite de chamadas da chave excedido — veja os headers X-RateLimit-*.
  • 500erro_internoFalha do nosso lado. Pode repetir com a mesma Idempotency-Key.

Zapier, Make e n8n#

Qualquer ferramenta que faça uma requisição HTTP conversa com o Basimob — basta apontar para o endereço com o cabeçalho de autenticação.

Zapier

Ação “Webhooks by Zapier” → POST, com Headers personalizados

Make

Módulo HTTP → Make a request (POST, body Raw/JSON)

n8n

Nó HTTP Request (POST, Header Auth)

Aponte parahttps://api.basimob.app/v1/leadscom o cabeçalho de autenticação.

Para o caminho inverso — receber eventos do CRM nessas ferramentas — veja adocumentação de webhooks