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#

6 endpoints nesta área.

GET/v1/leads/{id}Ver um leadver detalhes
exige ler leads

Um lead pelo id, no mesmo formato da listagem.

Parâmetros

  • idId do registro.

Requisição

curl -X GET "https://api.basimob.app/v1/leads/REGISTRO_ID" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "id": "cmd9x2v4k0001",
  "nome": "Maria Silva",
  "email": "maria@exemplo.com",
  "celular": "11999998888",
  "status": "NOVO",
  "origem": "SITE",
  "arquivado": false,
  "cidade": "Porto Alegre",
  "estado": "RS",
  "tags": [
    "Investidor"
  ],
  "responsavel": {
    "id": "cmd6u1p2z0003",
    "nome": "João Corretor"
  },
  "equipe": {
    "id": "cmeq1v2n3",
    "nome": "Vendas"
  },
  "imoveisDeInteresseIds": [
    "cmd7a1b2c0004"
  ],
  "empreendimentosDeInteresseIds": [
    "cmdb1c2d3"
  ],
  "criadoEm": "2026-07-25T13:40:02.118Z",
  "atualizadoEm": "2026-07-26T09:12:44.530Z"
}
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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • statusFiltra pela chave da coluna do funil.
  • celularFiltra por celular (só dígitos, casamento parcial).
  • emailFiltra por e-mail exato.
  • nomeFiltra por parte do nome, sem diferenciar acento nem maiúsculas.
  • arquivados`excluir` (padrão), `incluir` ou `apenas`.

Requisição

curl -X GET "https://api.basimob.app/v1/leads?limite=50&atualizadoDesde=2026-07-24T00%3A00%3A00Z&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",
      "arquivado": false,
      "cidade": "Porto Alegre",
      "estado": "RS",
      "tags": [
        "Investidor"
      ],
      "responsavel": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "equipe": {
        "id": "cmeq1v2n3",
        "nome": "Vendas"
      },
      "imoveisDeInteresseIds": [
        "cmd7a1b2c0004"
      ],
      "empreendimentosDeInteresseIds": [
        "cmdb1c2d3"
      ],
      "criadoEm": "2026-07-25T13:40:02.118Z",
      "atualizadoEm": "2026-07-26T09:12:44.530Z"
    }
  ],
  "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).
  • 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",
      "vendaId": null,
      "imovelId": null,
      "empreendimentoId": null,
      "unidadeId": null,
      "autor": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "criadoEm": "2026-07-25T14:02:11.482Z"
    }
  ],
  "proximoCursor": null
}

Portfólio#

12 endpoints nesta área.

GET/v1/imoveis/{id}Ver um imóvelver detalhes
exige ler imóveis

Um imóvel pelo id, no mesmo formato da listagem.

Parâmetros

  • idId do registro.

Requisição

curl -X GET "https://api.basimob.app/v1/imoveis/REGISTRO_ID" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "id": "cmd7a1b2c0004",
  "codigo": "AP-1042",
  "titulo": "Apartamento 2 quartos no Centro",
  "tipo": "APARTAMENTO",
  "subtipo": "APARTAMENTO",
  "finalidade": "VENDA",
  "status": "DISPONIVEL",
  "visivelNoSite": true,
  "precoVenda": 450000,
  "precoAluguel": null,
  "taxaCondominio": 520,
  "iptu": 95,
  "custosPersonalizados": [
    {
      "id": "gas",
      "nome": "Gás",
      "valor": 60
    }
  ],
  "area": 68,
  "quartos": 2,
  "suites": 1,
  "banheiros": 2,
  "vagasGaragem": 1,
  "aceitaPet": true,
  "mobilia": "SEMI_MOBILIADO",
  "aceitaPermuta": false,
  "endereco": {
    "cep": "90010-000",
    "rua": "Rua dos Andradas",
    "numero": "1200",
    "complemento": "Apto 804",
    "bairro": "Centro",
    "cidade": "Porto Alegre",
    "estado": "RS"
  },
  "fotos": [
    "https://exemplo.com/fotos/ap-1042-sala.avif"
  ],
  "proprietarios": [
    {
      "proprietarioId": "cmdc1d2e3",
      "percentual": 100
    }
  ],
  "criadoEm": "2026-06-02T11:20:00.000Z",
  "atualizadoEm": "2026-07-20T16:45:10.221Z"
}
GET/v1/empreendimentos/{id}Ver um empreendimentover detalhes
exige ler empreendimentos

Um empreendimento pelo id, no mesmo formato da listagem.

Parâmetros

  • idId do registro.

Requisição

curl -X GET "https://api.basimob.app/v1/empreendimentos/REGISTRO_ID" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "id": "cmdb1c2d3",
  "nome": "Residencial Aurora",
  "codigo": "EMP-12",
  "tipo": "RESIDENCIAL_VERTICAL",
  "construtora": "Construtora Horizonte",
  "statusObra": "EM_OBRAS",
  "ondeSeVisita": "DECORADO",
  "previsaoEntrega": "2027-12-01T03:00:00.000Z",
  "precoMinimo": 320000,
  "precoMaximo": 780000,
  "unidadesCadastradas": 96,
  "ativo": true,
  "visivelNoSite": true,
  "endereco": {
    "cep": "90480-000",
    "bairro": "Petrópolis",
    "cidade": "Porto Alegre",
    "estado": "RS"
  },
  "criadoEm": "2026-03-14T12:00:00.000Z",
  "atualizadoEm": "2026-07-18T10:05:33.900Z"
}
GET/v1/proprietarios/{id}Ver um proprietáriover detalhes
exige ler proprietários

Um proprietário pelo id, no mesmo formato da listagem.

Parâmetros

  • idId do registro.

Requisição

curl -X GET "https://api.basimob.app/v1/proprietarios/REGISTRO_ID" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "id": "cmdc1d2e3",
  "nome": "Carlos Pereira",
  "email": "carlos@exemplo.com",
  "celular": "51988887777",
  "tipoPessoa": "FISICA",
  "documento": "52998224725",
  "imoveis": 2,
  "criadoEm": "2026-02-10T15:30:00.000Z",
  "atualizadoEm": "2026-07-01T08:00:00.000Z"
}
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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • 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&atualizadoDesde=2026-07-24T00%3A00%3A00Z&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",
      "visivelNoSite": true,
      "precoVenda": 450000,
      "precoAluguel": null,
      "taxaCondominio": 520,
      "iptu": 95,
      "custosPersonalizados": [
        {
          "id": "gas",
          "nome": "Gás",
          "valor": 60
        }
      ],
      "area": 68,
      "quartos": 2,
      "suites": 1,
      "banheiros": 2,
      "vagasGaragem": 1,
      "aceitaPet": true,
      "mobilia": "SEMI_MOBILIADO",
      "aceitaPermuta": false,
      "endereco": {
        "cep": "90010-000",
        "rua": "Rua dos Andradas",
        "numero": "1200",
        "complemento": "Apto 804",
        "bairro": "Centro",
        "cidade": "Porto Alegre",
        "estado": "RS"
      },
      "fotos": [
        "https://exemplo.com/fotos/ap-1042-sala.avif"
      ],
      "proprietarios": [
        {
          "proprietarioId": "cmdc1d2e3",
          "percentual": 100
        }
      ],
      "criadoEm": "2026-06-02T11:20:00.000Z",
      "atualizadoEm": "2026-07-20T16:45:10.221Z"
    }
  ],
  "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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • cidadeFiltra pela cidade.
  • ativo`true` ou `false`.

Requisição

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

Resposta

200 {
  "dados": [
    {
      "id": "cmdb1c2d3",
      "nome": "Residencial Aurora",
      "codigo": "EMP-12",
      "tipo": "RESIDENCIAL_VERTICAL",
      "construtora": "Construtora Horizonte",
      "statusObra": "EM_OBRAS",
      "ondeSeVisita": "DECORADO",
      "previsaoEntrega": "2027-12-01T03:00:00.000Z",
      "precoMinimo": 320000,
      "precoMaximo": 780000,
      "unidadesCadastradas": 96,
      "ativo": true,
      "visivelNoSite": true,
      "endereco": {
        "cep": "90480-000",
        "bairro": "Petrópolis",
        "cidade": "Porto Alegre",
        "estado": "RS"
      },
      "criadoEm": "2026-03-14T12:00:00.000Z",
      "atualizadoEm": "2026-07-18T10:05:33.900Z"
    }
  ],
  "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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.

Requisição

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

Resposta

200 {
  "dados": [
    {
      "id": "cmdc1d2e3",
      "nome": "Carlos Pereira",
      "email": "carlos@exemplo.com",
      "celular": "51988887777",
      "tipoPessoa": "FISICA",
      "documento": "52998224725",
      "imoveis": 2,
      "criadoEm": "2026-02-10T15:30:00.000Z",
      "atualizadoEm": "2026-07-01T08:00:00.000Z"
    }
  ],
  "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/empreendimentosCadastrar empreendimentover detalhes
exige cadastrar e editar empreendimentosaceita Idempotency-Key

Cadastra empreendimento com as mesmas regras da tela: código gerado, pessoa, equipe e captador conferidos nesta conta.

O empreendimento nasce fora do site (`visivelNoSite` falso) e sem fotos — a galeria, as tipologias e as unidades são cadastradas pela tela. Divide o limite de imóveis do plano: estourado, volta 403 limite_do_plano.

Corpo

  • nomeobrigatórioNome do empreendimento (3 a 200 caracteres).
  • descricaoDescrição do empreendimento. Aceita HTML simples, que é saneado.
  • construtoraNome da construtora ou incorporadora.
  • tipoRESIDENCIAL_VERTICAL, RESIDENCIAL_HORIZONTAL, LOTEAMENTO, COMERCIAL ou MISTO.
  • statusObraPRE_LANCAMENTO, LANCAMENTO, EM_OBRAS, PRONTO ou ENTREGUE.
  • ondeSeVisitaDECORADO, EMPREENDIMENTO ou SEM_VISITA.
  • previsaoEntregaPrevisão de entrega, como dia de calendário (AAAA-MM-DD).
  • totalUnidadesTotal de unidades declarado (inteiro).
  • precoMinimoMenor preço, em reais (número).
  • precoMaximoMaior preço, em reais (número).
  • destaquesDiferenciais do empreendimento, lista de textos (até 50).
  • cepobrigatórioCEP, com ou sem hífen.
  • ruaLogradouro.
  • numeroNúmero.
  • complementoComplemento.
  • bairroBairro.
  • cidadeobrigatórioCidade.
  • estadoobrigatórioUF com 2 letras.
  • codigoInternoCódigo próprio da imobiliária, buscável no CRM.
  • ativoEmpreendimento ativo na carteira (booleano). Padrão: verdadeiro.
  • visivelNoSitePublicar no site já no cadastro (booleano). Padrão: falso.
  • captadorIdCaptador do empreendimento.
  • 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/empreendimentos" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "nome": "Residencial Aurora",
    "construtora": "Construtora Horizonte",
    "tipo": "RESIDENCIAL_VERTICAL",
    "statusObra": "EM_OBRAS",
    "cep": "90480-000",
    "bairro": "Petrópolis",
    "cidade": "Porto Alegre",
    "estado": "RS"
  }'

Corpo enviado

{
  "nome": "Residencial Aurora",
  "construtora": "Construtora Horizonte",
  "tipo": "RESIDENCIAL_VERTICAL",
  "statusObra": "EM_OBRAS",
  "cep": "90480-000",
  "bairro": "Petrópolis",
  "cidade": "Porto Alegre",
  "estado": "RS"
}

Resposta

201 {
  "success": true,
  "empreendimentoId": "cmdb1c2d3",
  "codigo": "EMP-012"
}
PATCH/v1/empreendimentos/{id}Atualizar empreendimentover detalhes
exige cadastrar e editar empreendimentosaceita Idempotency-Key

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

Corpo

  • nomeNovo nome.
  • descricaoDescrição do empreendimento. Aceita HTML simples, que é saneado.
  • construtoraNome da construtora ou incorporadora.
  • tipoRESIDENCIAL_VERTICAL, RESIDENCIAL_HORIZONTAL, LOTEAMENTO, COMERCIAL ou MISTO.
  • statusObraPRE_LANCAMENTO, LANCAMENTO, EM_OBRAS, PRONTO ou ENTREGUE.
  • ondeSeVisitaDECORADO, EMPREENDIMENTO ou SEM_VISITA.
  • previsaoEntregaPrevisão de entrega, como dia de calendário (AAAA-MM-DD).
  • totalUnidadesTotal de unidades declarado (inteiro).
  • precoMinimoMenor preço, em reais (número).
  • precoMaximoMaior preço, em reais (número).
  • destaquesDiferenciais do empreendimento, lista de textos (até 50).
  • cepCEP.
  • ruaLogradouro.
  • numeroNúmero.
  • complementoComplemento.
  • bairroBairro.
  • cidadeCidade.
  • estadoUF com 2 letras.
  • codigoInternoCódigo próprio da imobiliária.
  • ativoAtivar ou desativar na carteira (booleano).
  • visivelNoSitePublicar ou tirar do site (booleano).
  • captadorIdCaptador.
  • responsavelIdPessoa responsável. Não envie junto de `equipeId`.
  • equipeIdEquipe responsável. Não envie junto de `responsavelId`.

Parâmetros

  • idId do empreendimento (de GET /v1/empreendimentos).

Requisição

curl -X PATCH "https://api.basimob.app/v1/empreendimentos/EMPREENDIMENTO_ID" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "nome": "Residencial Aurora — Torre B"
  }'

Corpo enviado

{
  "nome": "Residencial Aurora — Torre B"
}

Resposta

200 {
  "success": true,
  "empreendimentoId": "cmdb1c2d3",
  "codigo": "EMP-012"
}
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).

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.

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#

4 endpoints nesta área.

GET/v1/vendas/{id}Ver uma vendaver detalhes
exige ler vendas e propostas

Uma venda pelo id, no mesmo formato da listagem.

Parâmetros

  • idId do registro.

Requisição

curl -X GET "https://api.basimob.app/v1/vendas/REGISTRO_ID" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "id": "cmdd1e2f3",
  "numero": "V-1042",
  "status": "EM_ANALISE",
  "etapa": "PROPOSTA",
  "valor": 450000,
  "entrada": 90000,
  "condicoesPagamento": "Entrada de 20% e saldo financiado",
  "arquivado": false,
  "lead": {
    "id": "cmd9x2v4k0001",
    "nome": "Maria Silva"
  },
  "imovelId": "cmd7a1b2c0004",
  "unidadeId": null,
  "corretor": {
    "id": "cmd6u1p2z0003",
    "nome": "João Corretor"
  },
  "vendidoEm": null,
  "concluidoEm": null,
  "criadoEm": "2026-07-22T17:10:00.000Z",
  "atualizadoEm": "2026-07-24T09:30:12.004Z"
}
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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • 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&atualizadoDesde=2026-07-24T00%3A00%3A00Z" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdd1e2f3",
      "numero": "V-1042",
      "status": "EM_ANALISE",
      "etapa": "PROPOSTA",
      "valor": 450000,
      "entrada": 90000,
      "condicoesPagamento": "Entrada de 20% e saldo financiado",
      "arquivado": false,
      "lead": {
        "id": "cmd9x2v4k0001",
        "nome": "Maria Silva"
      },
      "imovelId": "cmd7a1b2c0004",
      "unidadeId": null,
      "corretor": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "vendidoEm": null,
      "concluidoEm": null,
      "criadoEm": "2026-07-22T17:10:00.000Z",
      "atualizadoEm": "2026-07-24T09:30:12.004Z"
    }
  ],
  "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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • statusStatus da simulação.
  • leadIdSó as simulações deste lead.

Requisição

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

Resposta

200 {
  "dados": [
    {
      "id": "cmde1f2g3",
      "status": "APROVADA",
      "origem": "SITE",
      "nomeCliente": "Maria Silva",
      "valorImovel": 450000,
      "entrada": 90000,
      "prazoDesejado": 360,
      "rendaCliente": 12000,
      "leadId": "cmd9x2v4k0001",
      "criadoEm": "2026-07-21T19:44:08.310Z",
      "atualizadoEm": "2026-07-21T19:44:09.120Z"
    }
  ],
  "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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • 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&atualizadoDesde=2026-07-24T00%3A00%3A00Z&de=2026-07-25T00%3A00%3A00Z" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdf1g2h3",
      "titulo": "Visita — Apto 2 quartos no Centro",
      "descricao": null,
      "tipo": "VISITA",
      "status": "AGENDADO",
      "iniciaEm": "2026-07-28T17:00:00.000Z",
      "terminaEm": "2026-07-28T18:00:00.000Z",
      "diaInteiro": false,
      "local": "Rua dos Andradas, 1200",
      "responsavel": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "equipe": {
        "id": "cmeq1v2n3",
        "nome": "Vendas"
      },
      "leadId": "cmd9x2v4k0001",
      "imovelId": "cmd7a1b2c0004",
      "empreendimentoId": null,
      "vendaId": null,
      "criadoEm": "2026-07-25T14:10:00.000Z",
      "atualizadoEm": "2026-07-25T14:10:00.000Z"
    }
  ],
  "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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • 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&atualizadoDesde=2026-07-24T00%3A00%3A00Z" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdg1h2i3",
      "titulo": "Enviar proposta revisada",
      "descricao": null,
      "status": "PENDENTE",
      "prioridade": "ALTA",
      "dataVencimento": "2026-07-29T12:00:00.000Z",
      "concluidoEm": null,
      "responsavel": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "equipe": {
        "id": "cmeq1v2n3",
        "nome": "Vendas"
      },
      "leadId": "cmd9x2v4k0001",
      "imovelId": null,
      "empreendimentoId": null,
      "vendaId": "cmdd1e2f3",
      "criadoEm": "2026-07-25T14:20:00.000Z",
      "atualizadoEm": "2026-07-25T14:20:00.000Z"
    }
  ],
  "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.
  • empreendimentoIdVincula a um empreendimento (de GET /v1/empreendimentos).
  • 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.
  • empreendimentoIdVincula a um empreendimento (de GET /v1/empreendimentos) — a visita ao decorado ou ao estande.
  • 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#

9 endpoints nesta área.

GET/v1/contratos/{id}Ver um contrato de aluguelver detalhes
exige ler contratos de aluguel

Um contrato pelo id, no mesmo formato da listagem.

Parâmetros

  • idId do registro.

Requisição

curl -X GET "https://api.basimob.app/v1/contratos/REGISTRO_ID" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "id": "cmdh1i2j3",
  "numero": "LOC-000204",
  "status": "ATIVO",
  "imovelId": "cmd7a1b2c0004",
  "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
    }
  ],
  "valorAluguel": 2500,
  "taxaCondominio": 520,
  "iptu": 95,
  "iptuParcelas": null,
  "iptuPrimeiroMes": null,
  "percentualTaxaAdm": 10,
  "descontoPontualidade": {
    "diasAntes": 0,
    "itens": [
      {
        "alvo": "CONDOMINIO",
        "tipo": "FIXO",
        "valor": 50
      }
    ]
  },
  "iniciaEm": "2026-01-10T03:00:00.000Z",
  "terminaEm": "2027-01-09T03:00:00.000Z",
  "diaVencimento": 10,
  "proximoReajusteEm": "2027-01-10T03:00:00.000Z",
  "assinadoEm": "2026-01-08T03:00:00.000Z",
  "criadoEm": "2026-01-05T14:00:00.000Z",
  "atualizadoEm": "2026-07-10T11:22:31.870Z"
}
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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • statusStatus do contrato (ex.: ATIVO).
  • imovelIdSó os contratos deste imóvel.

Requisição

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

Resposta

200 {
  "dados": [
    {
      "id": "cmdh1i2j3",
      "numero": "LOC-000204",
      "status": "ATIVO",
      "imovelId": "cmd7a1b2c0004",
      "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
        }
      ],
      "valorAluguel": 2500,
      "taxaCondominio": 520,
      "iptu": 95,
      "iptuParcelas": null,
      "iptuPrimeiroMes": null,
      "percentualTaxaAdm": 10,
      "descontoPontualidade": {
        "diasAntes": 0,
        "itens": [
          {
            "alvo": "CONDOMINIO",
            "tipo": "FIXO",
            "valor": 50
          }
        ]
      },
      "iniciaEm": "2026-01-10T03:00:00.000Z",
      "terminaEm": "2027-01-09T03:00:00.000Z",
      "diaVencimento": 10,
      "proximoReajusteEm": "2027-01-10T03:00:00.000Z",
      "assinadoEm": "2026-01-08T03:00:00.000Z",
      "criadoEm": "2026-01-05T14:00:00.000Z",
      "atualizadoEm": "2026-07-10T11:22:31.870Z"
    }
  ],
  "proximoCursor": null
}
GET/v1/pagamentosListar cobranças de aluguelver detalhes
exige ler cobranças de aluguel

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

Área de locação: exige o plano com gestão de aluguel. `ATRASADO` é derivado do vencimento no fuso da imobiliária: a parcela entra em atraso sem que `atualizadoEm` mude, então quem sincroniza por `atualizadoDesde` consulta também o filtro `status` com `ATRASADO`.

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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • venceDeVencimento a partir de (ISO 8601).
  • venceAteVencimento até (ISO 8601).
  • statusStatus do pagamento: PENDENTE, ATRASADO, PARCIAL, PAGO, CANCELADO ou ISENTO.
  • contratoIdSó as parcelas deste contrato.

Requisição

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

Resposta

200 {
  "dados": [
    {
      "id": "cmdi1j2k3",
      "contratoId": "cmdh1i2j3",
      "status": "PAGO",
      "numeroParcela": 7,
      "mesReferencia": 8,
      "anoReferencia": 2026,
      "valorTotal": 3115,
      "valorPago": 3177.3,
      "valorMulta": 62.3,
      "juros": 0,
      "desconto": 0,
      "dataVencimento": "2026-08-10T03:00:00.000Z",
      "pagoEm": "2026-08-12T03:00:00.000Z",
      "estornadoEm": null,
      "metodoPagamento": "PIX",
      "criadoEm": "2026-01-10T12:00:00.000Z",
      "atualizadoEm": "2026-08-12T13:05:47.300Z"
    }
  ],
  "proximoCursor": null
}
GET/v1/ocorrenciasListar ocorrênciasver detalhes
exige ler ocorrências

Ocorrências dos contratos de aluguel — manutenção, reclamação, sinistro — com a situação, quem responde por ela e os custos.

Á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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • contratoIdSó as ocorrências deste contrato.
  • statusABERTA, EM_ANDAMENTO, AGUARDANDO, RESOLVIDA ou CANCELADA.
  • tipoMANUTENCAO, RECLAMACAO, VISTORIA, SINISTRO ou OUTROS.

Requisição

curl -X GET "https://api.basimob.app/v1/ocorrencias?limite=50&atualizadoDesde=2026-07-24T00%3A00%3A00Z&status=ABERTA" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdo1p2q3",
      "contratoId": "cmdh1i2j3",
      "imovelId": "cmd7a1b2c0004",
      "tipo": "MANUTENCAO",
      "status": "ABERTA",
      "titulo": "Vazamento na pia da cozinha",
      "descricao": "O locatário avisou que o sifão da pia está pingando desde ontem.",
      "responsavel": "LOCADOR",
      "custoEstimado": 180,
      "custoReal": null,
      "observacoes": null,
      "resolvidoEm": null,
      "criadoEm": "2026-08-14T13:25:10.000Z",
      "atualizadoEm": "2026-08-14T13:25:10.000Z"
    }
  ],
  "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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • statusStatus do laudo.
  • tipoENTRADA ou SAIDA.
  • contratoIdSó as vistorias deste contrato.

Requisição

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

Resposta

200 {
  "dados": [
    {
      "id": "cmdj1k2l3",
      "tipo": "ENTRADA",
      "status": "CONCLUIDA",
      "estadoGeral": "BOM",
      "situacaoAceite": "ACEITA",
      "imovelId": "cmd7a1b2c0004",
      "contratoId": "cmdh1i2j3",
      "ambientes": 6,
      "criadoEm": "2026-01-09T13:00:00.000Z",
      "atualizadoEm": "2026-01-09T18:40:00.000Z"
    }
  ],
  "proximoCursor": null
}
POST/v1/contratosCriar contrato de aluguel (rascunho)ver detalhes
exige criar e editar contratos em rascunhoaceita Idempotency-Key

Cria o contrato de locação pelo mesmo caminho da tela: número sequencial, imóvel, locatários, proprietários e fiadores conferidos nesta conta, datas no fuso da imobiliária e o webhook `Contrato criado`.

O contrato nasce SEMPRE em rascunho: ativar, gerar cobranças e coletar assinaturas são feitos no CRM. Rascunho não aparece em GET /v1/contratos — guarde o `contratoId` da resposta. Sem `responsavelId`, o contrato fica na fila da imobiliária. Campo fora desta lista (situação, etapa, assinatura) volta 422 dados_invalidos. Exige o plano com gestão de aluguel.

Corpo

  • imovelIdobrigatórioImóvel alugado (de GET /v1/imoveis).
  • locatarioIdsobrigatórioQuem aluga: o id de um lead (de GET /v1/leads) ou a lista de ids, na ordem em que assinam. O primeiro é o locatário principal — é dele o documento das cobranças.
  • locadoresProprietários que alugam (de GET /v1/proprietarios), na ordem, com a parte de cada um no aluguel: `[{ proprietarioId, percentual }]`. As partes somam 100.
  • fiadoresFiadores (leads), na ordem em que assinam: `[{ leadId, percentualResponsabilidade }]`. O percentual é opcional.
  • responsavelIdPessoa responsável pelo contrato (de GET /v1/equipe). Sem ela, o contrato fica na fila da imobiliária.
  • valorAluguelAluguel mensal em reais.
  • taxaCondominioCondomínio mensal em reais (número).
  • iptuIPTU em reais (número): por mês, ou o valor de cada parcela quando o contrato tem `iptuParcelas`.
  • iptuParcelasIPTU só nos meses do carnê: em quantas parcelas por ano (1 a 12). Vai junto com `iptuPrimeiroMes`; os dois `null` = todo mês.
  • iptuPrimeiroMesMês da primeira parcela do IPTU (1 a 12). As parcelas cabem no mesmo ano: o mês + parcelas − 1 vai até 12.
  • tipoTaxaAdmComo a taxa de administração é cobrada: PERCENTUAL ou FIXO.
  • percentualTaxaAdmTaxa de administração em % (quando o tipo é PERCENTUAL).
  • valorTaxaAdmTaxa de administração em reais (quando o tipo é FIXO).
  • descontoPontualidadeDesconto para pagamento até `diasAntes` dias antes do vencimento (0 = até o vencimento), em toda mensalidade: `{ diasAntes, itens: [{ alvo, tipo, valor }] }`. `alvo` é ALUGUEL, CONDOMINIO, IPTU ou `taxa:<id>` de uma taxa cobrada do locatário; `tipo` é FIXO (reais por mês) ou PERCENTUAL (do item). `null` tira o desconto.
  • iniciaEmInício da locação, como dia de calendário (AAAA-MM-DD).
  • terminaEmFim do prazo da locação (AAAA-MM-DD).
  • primeiroVencimentoEmData do primeiro vencimento (AAAA-MM-DD). O dia dela vira o dia de vencimento das mensalidades.
  • regimePagamentoANTECIPADO (paga o mês que vai usar; padrão) ou POSTECIPADO (paga o mês que usou).
  • cobrarProporcionalCobrar por dia o mês que não é inteiro (booleano; padrão falso).
  • renovacaoO que acontece no fim do prazo: ADITIVO ou INDETERMINADA.
  • tipoReajusteIGPM (padrão), IPCA, INPC, INCC, NEGOCIADO ou SEM_REAJUSTE.
  • periodicidadeReajusteMesesDe quantos em quantos meses o aluguel reajusta (mínimo legal 12; padrão 12).
  • primeiroReajusteEmData do primeiro reajuste (AAAA-MM-DD). Sem ela, é o início mais a periodicidade.
  • tipoGarantiaCAUCAO, FIADOR, SEGURO_FIANCA, TITULO_CAPITALIZACAO, OUTRA ou SEM_GARANTIA (padrão).
  • valorGarantiaValor da garantia em reais (número).
  • percentualMultaMulta por atraso, em % do aluguel.
  • taxaJurosMensalJuros de mora, em % ao mês.
  • diasCarenciaDias de tolerância depois do vencimento antes de a mora contar (inteiro).
  • observacoesObservações internas.
  • clausulasAdicionaisCláusulas adicionais do contrato, em texto.

Requisição

curl -X POST "https://api.basimob.app/v1/contratos" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "imovelId": "IMOVEL_ID",
    "locatarioIds": "LEAD_ID",
    "valorAluguel": "2500",
    "iniciaEm": "2026-11-01",
    "terminaEm": "2029-04-30"
  }'

Corpo enviado

{
  "imovelId": "IMOVEL_ID",
  "locatarioIds": "LEAD_ID",
  "valorAluguel": "2500",
  "iniciaEm": "2026-11-01",
  "terminaEm": "2029-04-30"
}

Resposta

201 {
  "success": true,
  "contratoId": "cmdh1i2j3",
  "numero": "LOC-000205"
}
PATCH/v1/contratos/{id}Atualizar contrato em rascunhover detalhes
exige criar e editar contratos em rascunhoaceita Idempotency-Key

Atualização parcial do rascunho: só os campos enviados mudam, com as regras e as conferências da tela.

Só contrato em rascunho pode ser editado pela API: o que já saiu do rascunho volta 422 dados_invalidos. As listas (`locatarioIds`, `locadores`, `fiadores`) SUBSTITUEM as gravadas. Concluir o cadastro, ativar e assinar são feitos no CRM.

Corpo

  • imovelIdImóvel alugado (de GET /v1/imoveis).
  • locatarioIdsQuem aluga: o id de um lead (de GET /v1/leads) ou a lista de ids, na ordem em que assinam. O primeiro é o locatário principal — é dele o documento das cobranças.
  • locadoresProprietários que alugam (de GET /v1/proprietarios), na ordem, com a parte de cada um no aluguel: `[{ proprietarioId, percentual }]`. As partes somam 100.
  • fiadoresFiadores (leads), na ordem em que assinam: `[{ leadId, percentualResponsabilidade }]`. O percentual é opcional.
  • responsavelIdPessoa responsável pelo contrato (de GET /v1/equipe). Sem ela, o contrato fica na fila da imobiliária.
  • valorAluguelAluguel mensal em reais.
  • taxaCondominioCondomínio mensal em reais (número).
  • iptuIPTU em reais (número): por mês, ou o valor de cada parcela quando o contrato tem `iptuParcelas`.
  • iptuParcelasIPTU só nos meses do carnê: em quantas parcelas por ano (1 a 12). Vai junto com `iptuPrimeiroMes`; os dois `null` = todo mês.
  • iptuPrimeiroMesMês da primeira parcela do IPTU (1 a 12). As parcelas cabem no mesmo ano: o mês + parcelas − 1 vai até 12.
  • tipoTaxaAdmComo a taxa de administração é cobrada: PERCENTUAL ou FIXO.
  • percentualTaxaAdmTaxa de administração em % (quando o tipo é PERCENTUAL).
  • valorTaxaAdmTaxa de administração em reais (quando o tipo é FIXO).
  • descontoPontualidadeDesconto para pagamento até `diasAntes` dias antes do vencimento (0 = até o vencimento), em toda mensalidade: `{ diasAntes, itens: [{ alvo, tipo, valor }] }`. `alvo` é ALUGUEL, CONDOMINIO, IPTU ou `taxa:<id>` de uma taxa cobrada do locatário; `tipo` é FIXO (reais por mês) ou PERCENTUAL (do item). `null` tira o desconto.
  • iniciaEmInício da locação, como dia de calendário (AAAA-MM-DD).
  • terminaEmFim do prazo da locação (AAAA-MM-DD).
  • primeiroVencimentoEmData do primeiro vencimento (AAAA-MM-DD). O dia dela vira o dia de vencimento das mensalidades.
  • regimePagamentoANTECIPADO (paga o mês que vai usar; padrão) ou POSTECIPADO (paga o mês que usou).
  • cobrarProporcionalCobrar por dia o mês que não é inteiro (booleano; padrão falso).
  • renovacaoO que acontece no fim do prazo: ADITIVO ou INDETERMINADA.
  • tipoReajusteIGPM (padrão), IPCA, INPC, INCC, NEGOCIADO ou SEM_REAJUSTE.
  • periodicidadeReajusteMesesDe quantos em quantos meses o aluguel reajusta (mínimo legal 12; padrão 12).
  • primeiroReajusteEmData do primeiro reajuste (AAAA-MM-DD). Sem ela, é o início mais a periodicidade.
  • tipoGarantiaCAUCAO, FIADOR, SEGURO_FIANCA, TITULO_CAPITALIZACAO, OUTRA ou SEM_GARANTIA (padrão).
  • valorGarantiaValor da garantia em reais (número).
  • percentualMultaMulta por atraso, em % do aluguel.
  • taxaJurosMensalJuros de mora, em % ao mês.
  • diasCarenciaDias de tolerância depois do vencimento antes de a mora contar (inteiro).
  • observacoesObservações internas.
  • clausulasAdicionaisCláusulas adicionais do contrato, em texto.

Parâmetros

  • idId do contrato (o `contratoId` devolvido na criação).

Requisição

curl -X PATCH "https://api.basimob.app/v1/contratos/CONTRATO_ID" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "valorAluguel": "2650",
    "terminaEm": "2029-05-31"
  }'

Corpo enviado

{
  "valorAluguel": "2650",
  "terminaEm": "2029-05-31"
}

Resposta

200 {
  "success": true,
  "contratoId": "cmdh1i2j3",
  "numero": "LOC-000205"
}
POST/v1/pagamentos/{id}/baixaRegistrar pagamento de uma parcelaver detalhes
exige registrar pagamentos de aluguelaceita Idempotency-Key

Dá baixa na parcela pelo mesmo caminho da tela: calcula multa e juros do atraso pelo contrato, registra na timeline, envia o recibo ao locatário quando o contrato manda e dispara o webhook `Pagamento registrado`.

O `valorPago` é o que entrou AGORA: menor que o total, a parcela fica PARCIAL, e uma nova chamada soma ao que já entrou. Parcela já paga, isenta ou cancelada volta 422 dados_invalidos — estornar e corrigir pagamento são feitos no CRM. Boleto ou Pix ainda aberto no gateway é cancelado antes do registro; se o gateway não confirmar, a baixa é recusada e nada é gravado. Completar uma parcela PARCIAL que já tinha repasse ao proprietário desfaz esse repasse, como na tela. O cabeçalho `Idempotency-Key` é OBRIGATÓRIO nesta rota: sem ele a chamada volta 422, porque repetir uma baixa parcial somaria o valor de novo.

Corpo

  • valorPagoobrigatórioValor recebido agora, em reais.
  • pagoEmobrigatórioDia do pagamento, como dia de calendário (AAAA-MM-DD). É por ele que o atraso é contado.
  • metodoPagamentoobrigatórioPIX, BOLETO, TRANSFERENCIA, DINHEIRO, CARTAO ou CHEQUE.
  • descontoDesconto concedido nesta parcela, em reais (número). Não pode deixar o total negativo.
  • observacoesObservações do pagamento.

Parâmetros

  • idId da parcela (de GET /v1/pagamentos).

Requisição

curl -X POST "https://api.basimob.app/v1/pagamentos/PAGAMENTO_ID/baixa" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "valorPago": "3115",
    "pagoEm": "2026-08-10",
    "metodoPagamento": "PIX",
    "observacoes": "Pago no balcão"
  }'

Corpo enviado

{
  "valorPago": "3115",
  "pagoEm": "2026-08-10",
  "metodoPagamento": "PIX",
  "observacoes": "Pago no balcão"
}

Resposta

200 {
  "success": true,
  "pagamentoId": "cmdi1j2k3",
  "status": "PAGO",
  "valorPago": 3115
}
POST/v1/ocorrenciasAbrir ocorrênciaver detalhes
exige abrir ocorrênciasaceita Idempotency-Key

Abre uma ocorrência no contrato pelo mesmo caminho da tela: entra na timeline do contrato e dispara o webhook `Ocorrência criada`.

O imóvel da ocorrência é o do contrato. Acompanhar, anotar e resolver a ocorrência são feitos no CRM. Exige o plano com gestão de aluguel.

Corpo

  • contratoIdobrigatórioContrato da ocorrência (de GET /v1/contratos).
  • tipoobrigatórioMANUTENCAO, RECLAMACAO, VISTORIA, SINISTRO ou OUTROS.
  • tituloobrigatórioTítulo, com pelo menos 3 caracteres.
  • descricaoobrigatórioO que aconteceu, com pelo menos 10 caracteres.
  • responsavelobrigatórioQuem responde pela ocorrência: LOCATARIO, LOCADOR, IMOBILIARIA ou SEGURO.
  • custoEstimadoCusto estimado em reais (número).
  • observacoesObservações internas.

Requisição

curl -X POST "https://api.basimob.app/v1/ocorrencias" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "contratoId": "CONTRATO_ID",
    "tipo": "MANUTENCAO",
    "titulo": "Vazamento na pia da cozinha",
    "descricao": "O locatário avisou que o sifão da pia está pingando desde ontem.",
    "responsavel": "LOCADOR"
  }'

Corpo enviado

{
  "contratoId": "CONTRATO_ID",
  "tipo": "MANUTENCAO",
  "titulo": "Vazamento na pia da cozinha",
  "descricao": "O locatário avisou que o sifão da pia está pingando desde ontem.",
  "responsavel": "LOCADOR"
}

Resposta

201 {
  "success": true,
  "ocorrenciaId": "cmdo1p2q3"
}

Gestão#

7 endpoints nesta área.

GET/v1/contaVer a conta da chavever detalhes
exige só uma chave válida

Diz de qual imobiliária é a chave e o que ela pode fazer. Serve para testar a conexão e dar nome a ela: responde para qualquer chave válida, sem permissão própria.

Requisição

curl -X GET "https://api.basimob.app/v1/conta" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "organizacao": {
    "id": "cmo1r2g3a4",
    "nome": "Imobiliária Exemplo"
  },
  "chave": {
    "nome": "Zapier",
    "escopos": [
      "leads:read",
      "webhooks:write"
    ]
  },
  "versaoApi": "1"
}
GET/v1/webhooksListar assinaturas de eventosver detalhes
exige ler assinaturas de eventos

As assinaturas criadas por esta chave. Os destinos cadastrados no painel não aparecem aqui.

Requisição

curl -X GET "https://api.basimob.app/v1/webhooks" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmw1e2b3h",
      "url": "https://hooks.zapier.com/hooks/standard/123/abc/",
      "eventos": [
        "LEAD_CREATED"
      ],
      "aplicativo": "Zapier",
      "criadoEm": "2026-11-01T13:40:02.118Z"
    }
  ],
  "proximoCursor": null
}
POST/v1/webhooksAssinar eventosver detalhes
exige assinar eventosaceita Idempotency-Key

Faz os eventos escolhidos chegarem à URL informada, na hora. É o que um conector como o Zapier ou o Make chama ao ligar um fluxo. Repetir a mesma URL com a mesma chave atualiza os eventos da assinatura e responde 200.

A chave só assina eventos de uma área que ela pode ler: LEAD_CREATED exige `leads:read`, por exemplo. Quem assina por aqui recebe o registro em `recurso`, no formato da leitura, e em `data` só o id. O contrato em rascunho, que a leitura não mostra, chega em CONTRATO_CREATED quando é concluído. A assinatura não ocupa vaga de webhook do plano, some quando a chave é revogada e deixa de receber o evento da permissão que a chave perdeu. Se o destino responder 410, a assinatura é apagada.

Corpo

  • urlobrigatórioEndereço HTTPS público que recebe os eventos.
  • eventosobrigatórioLista de eventos a assinar, com as chaves da documentação de webhooks.
  • aplicativoNome da ferramenta, para o painel dizer de onde veio.

Requisição

curl -X POST "https://api.basimob.app/v1/webhooks" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4f2a9c" \
  -d '{
    "url": "https://hooks.zapier.com/hooks/standard/123/abc/",
    "eventos": [
      "LEAD_CREATED"
    ],
    "aplicativo": "Zapier"
  }'

Corpo enviado

{
  "url": "https://hooks.zapier.com/hooks/standard/123/abc/",
  "eventos": [
    "LEAD_CREATED"
  ],
  "aplicativo": "Zapier"
}

Resposta

201 {
  "id": "cmw1e2b3h",
  "url": "https://hooks.zapier.com/hooks/standard/123/abc/",
  "eventos": [
    "LEAD_CREATED"
  ],
  "aplicativo": "Zapier",
  "criadoEm": "2026-11-01T13:40:02.118Z"
}
DELETE/v1/webhooks/{id}Cancelar assinaturaver detalhes
exige assinar eventos

Cancela uma assinatura criada por esta chave. Pode ser repetido: quem já saiu responde igual.

Parâmetros

  • idId da assinatura.

Requisição

curl -X DELETE "https://api.basimob.app/v1/webhooks/ASSINATURA_ID" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

204 (sem corpo)
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).
  • atualizadoDesdeSó registros criados OU alterados a partir desta data (ISO 8601) — use na sincronização incremental, com a data da sua última leitura.
  • 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&atualizadoDesde=2026-07-24T00%3A00%3A00Z" \
  -H "Authorization: Bearer SUA_CHAVE"

Resposta

200 {
  "dados": [
    {
      "id": "cmdk1l2m3",
      "tipo": "DESPESA",
      "descricao": "Anúncio no portal",
      "valor": 389.9,
      "data": "2026-07-05T03:00:00.000Z",
      "categoria": {
        "id": "cmcat1a2b3",
        "nome": "Marketing"
      },
      "criadoEm": "2026-07-05T12:30:00.000Z",
      "atualizadoEm": "2026-07-05T12:30:00.000Z"
    }
  ],
  "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).
  • 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.br",
      "papel": "CORRETOR",
      "ativo": true,
      "criadoEm": "2026-01-02T12:00:00.000Z",
      "equipes": [
        {
          "id": "cmeq1v2n3",
          "nome": "Vendas"
        }
      ]
    }
  ],
  "proximoCursor": null
}
GET/v1/metasListar metasver detalhes
exige ler metas

As metas do mês — da imobiliária, das equipes e das pessoas — com o valor, o feito, o atingimento e a situação, contados como na página Metas.

Parâmetros

  • limiteQuantos registros por página (1 a 100; padrão 50).
  • cursorContinua da página seguinte — use o `proximoCursor` da resposta anterior.
  • mesO mês, no formato AAAA-MM. Sem ele, o mês atual no fuso da imobiliária.
  • alvoIMOBILIARIA, EQUIPE ou PESSOA.

Requisição

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

Resposta

200 {
  "dados": [
    {
      "id": "cmmeta1a2b3",
      "medida": "contatos",
      "nome": "Contatos novos",
      "unidade": "quantidade",
      "alvo": "PESSOA",
      "equipe": null,
      "pessoa": {
        "id": "cmd6u1p2z0003",
        "nome": "João Corretor"
      },
      "mes": "2026-10",
      "periodo": "MENSAL",
      "valor": 12,
      "feito": 9,
      "atingimento": 0.75,
      "situacao": "no_ritmo",
      "faltam": 3,
      "estado": "aberto"
    }
  ],
  "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 foi criado ou alterado desde a sua última leitura
GET /v1/leads?atualizadoDesde=2026-07-24T00:00:00Z

Use atualizadoDesde com a data da última sincronização em vez de varrer tudo de novo: ele traz o que nasceu e o que mudou — a parcela paga, o contrato encerrado, o lead que trocou de etapa. desde olha só a data de criação.

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. Antes da chave há um teto de 3.000 chamadas por minuto por IP, só contra enxurrada: ele não aparece nos cabeçalhos de quem chama com chave.

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.
  • 403feature_indisponivelO plano da conta não inclui a área do endpoint (locação, vistoria) — o escopo existe, o recurso não.
  • 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