Pular para conteúdo

Integração via API

Referência da API de Integração do aluguei+ (/api/v1) para sistemas externos (ERP imobiliário, gestão de contratos, portais) sincronizarem cadastros e consultarem as NFS-e de locação emitidas.

O que a API faz — e o que não faz

A API de Integração popula cadastros (locatários, imóveis e contratos de locação) e consulta as NFS-e de locação emitidas e seus XMLs.

A emissão das notas continua sendo feita dentro do aluguei+ — de forma avulsa ou pela emissão automática mensal dos contratos. A API não emite nem cancela notas.


Visão geral

Base URL https://api.alugueimais.com.br
Prefixo /api/v1
Formato JSON, UTF-8
Autenticação API key por empresa (header)

Um sistema externo tipicamente:

  1. Sincroniza cadastros — envia seus locatários, imóveis e contratos (POST), que são criados/atualizados no aluguei+.
  2. O usuário (ou o agendador mensal) emite as NFS-e de locação no aluguei+.
  3. O sistema externo consulta as notas emitidas e baixa os XMLs (GET).

Autenticação

Toda chamada a /api/v1/* exige uma API key da empresa.

1. Gerar a chave (no aluguei+)

No app/painel: Configurações → Minha conta → Integração (API) → “Gerar chave de API”.

  • Dê um nome à chave (ex.: ERP, Portal) e escolha o ambiente.
  • O token é exibido uma única vez na criação. Copie e guarde com segurança — ele não será mostrado novamente.
  • Chaves podem ser revogadas a qualquer momento na mesma tela.

O token tem o formato aluguei_live_xxxxxxxx… (produção) ou aluguei_test_xxxxxxxx… (homologação).

Guarde a chave como um segredo

A API key dá acesso aos cadastros e documentos da empresa. Não a exponha em código público, apps client-side ou repositórios. Se vazar, revogue e gere outra.

2. Enviar a chave nas requisições

Use um dos dois headers:

Authorization: Bearer aluguei_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

ou

X-API-Key: aluguei_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Respostas de autenticação

Status Situação
401 Unauthorized Chave ausente, inválida ou revogada
403 Forbidden Empresa inativa
{ "error": "API key invalida ou revogada." }

Ambientes

O ambiente da chave (live/test) é apenas um rótulo. A emissão real usa o ambiente configurado na empresa (Produção ou Homologação) no cadastro do aluguei+.


Convenções

Requisição e resposta

  • Corpo e resposta são JSON (Content-Type: application/json), UTF-8.
  • Datas em texto no formato YYYY-MM-DD (filtros e competências) ou ISO.
  • Valores monetários/numéricos com ponto decimal (1500.00).

Lote e upsert (cadastros)

Os endpoints de cadastro (POST /locatarios, /imoveis, /contratos) aceitam um objeto único ou um array (lote). O comportamento é upsert: se o registro já existe (pela chave natural), é atualizado; senão, é criado.

Em lote, um erro em um item não aborta os demais — cada item reporta seu próprio resultado:

{
  "total": 3,
  "criados": 2,
  "atualizados": 0,
  "falhas": 1,
  "resultados": [
    { "indice": 0, "acao": "criado", "codigo": 12 },
    { "indice": 1, "acao": "criado", "codigo": 13 },
    { "indice": 2, "acao": "erro", "erro": "cod_mun_ibge invalido" }
  ]
}

Paginação (listagens)

Parâmetros de query pagina (default 1) e por_pagina (default 30). As listagens retornam:

{ "total": 124, "pagina": 1, "por_pagina": 30, "items": [ /* ... */ ] }

Cadastros

Locatários

Cria ou atualiza locatários (objeto único ou array).

Chave de upsert: codigo (ID) › cpf_cnpj.

curl -X POST https://api.alugueimais.com.br/api/v1/locatarios \
  -H "Authorization: Bearer $ALUGUEI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_pessoa": "J",
    "cpf_cnpj": "11222333000181",
    "nome": "ACME COMERCIO LTDA",
    "email": "[email protected]",
    "cep": "88010000",
    "logradouro": "RUA CENTRAL",
    "numero": "100",
    "bairro": "CENTRO",
    "codigo_municipio_ibge": "4205407",
    "nome_municipio": "Florianopolis",
    "uf": "SC"
  }'
curl "https://api.alugueimais.com.br/api/v1/locatarios?busca=acme" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Query: busca, so_ativos, pagina, por_pagina.

Campos do locatário

Campo Tipo Obrig. Observação
codigo / id int Enviar para forçar atualização por ID
tipo_pessoa string ✔ F (física) ou J (jurídica)
cpf_cnpj string ✔ Só dígitos. 11 se F, 14 se J (chave de upsert)
nome string ✔ Razão social / nome
nome_fantasia string
ie string Inscrição estadual (opcional)
email, fone string
cep, logradouro, numero, complemento, bairro string ✔ Endereço
codigo_municipio_ibge string ✔ Código IBGE (7 dígitos)
nome_municipio, uf string ✔
status string A / I. Default A

Imóveis

Cria ou atualiza imóveis do locador (objeto único ou array).

Chave de upsert: codigo (ID) › cib › matricula.

curl -X POST https://api.alugueimais.com.br/api/v1/imoveis \
  -H "Authorization: Bearer $ALUGUEI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apelido": "Sala 302 - Centro",
    "tipo": 2,
    "inscricao_imobiliaria": "123456",
    "cib": "12345678",
    "cep": "88010000",
    "logradouro": "RUA CENTRAL",
    "numero": "302",
    "bairro": "CENTRO",
    "cidade": "Florianopolis",
    "uf": "SC",
    "cod_mun_ibge": "4205407"
  }'
curl "https://api.alugueimais.com.br/api/v1/imoveis?status=A" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Campos do imóvel

Campo Tipo Obrig. Observação
codigo / id int Enviar para forçar atualização por ID
apelido string ✔ Identificação do imóvel
tipo int 1 Residencial, 2 Comercial, 3 Terreno, 4 Galpão, 5 Outro
inscricao_imobiliaria string Inscrição do IPTU
cib string Cadastro Imobiliário Brasileiro — 8 dígitos (NT 009)
matricula string Matrícula no cartório
cep, logradouro, numero, complemento, bairro, cidade, uf string Endereço
cod_mun_ibge string ✔ IBGE (7 dígitos) — local de incidência do IBS/CBS
status string A / I. Default A

Contratos de locação

Cria ou atualiza contratos (objeto único ou array). Contratos com status: "A" entram na emissão automática mensal.

Chave de upsert: codigo (ID) — sem ID, é inserido.

curl -X POST https://api.alugueimais.com.br/api/v1/contratos \
  -H "Authorization: Bearer $ALUGUEI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imovel_id": 12,
    "cliente_id": 34,
    "operacao": 1,
    "cod_trib_nacional": "990301",
    "valor_mensal": 2500.00,
    "dia_vencimento": 10,
    "competencia_inicio": "2026-12-01",
    "pct_copropriedade": 100,
    "ibscbs_cst": "200",
    "ibscbs_cclasstrib": "200027",
    "ajustes": [
      { "tp_ajuste": 3, "v_ajuste": 300.00 }
    ]
  }'
curl "https://api.alugueimais.com.br/api/v1/contratos?status=A" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Campos do contrato

Campo Tipo Obrig. Observação
codigo / id int Enviar para forçar atualização por ID
imovel_id int ✔ ID do imóvel
cliente_id int ✔ ID do locatário
operacao int ✔ 1 Locação, 2 Cessão onerosa, 3 Arrendamento
cod_trib_nacional string 990301 / 990302 / 990303 (segue a operação)
valor_mensal number ✔ Valor do aluguel
dia_vencimento int Dia do vencimento (default 10)
competencia_inicio string ✔ YYYY-MM-01
competencia_fim string YYYY-MM-01 (vazio = indeterminado)
pct_copropriedade number 0–100. vServ = % × valor (default 100)
ibscbs_cst string Tratamento IBS/CBS: 200 (redução 70%), 210 (redutor social), 000 (integral)
ibscbs_cclasstrib string cClassTrib correspondente (200027 / 210003 / 000001)
discriminacao_padrao string Texto padrão da nota
ajustes array Parcelas fora da base (NT 009 / gAjusteBCLocImoveis)
status string A Ativo, E Encerrado, S Suspenso

Item de ajustes (parcela fora da base)

Campo Tipo Observação
tp_ajuste int 1 Tributos (IPTU/melhoria), 2 Emolumento, 3 Condomínio, 4 Redutor social, 99 Outras
x_tp_ajuste string Descrição (obrigatória quando tp_ajuste = 99)
v_ajuste number Valor deduzido da base do IBS/CBS

Documentos (consulta)

Leitura das NFS-e de locação emitidas e dos XMLs autorizados.

Lista as NFS-e de locação.

curl "https://api.alugueimais.com.br/api/v1/documentos?data_inicio=2026-12-01&data_fim=2026-12-31" \
  -H "Authorization: Bearer $ALUGUEI_KEY"
Query Descrição
busca Texto (tomador, número…)
status E, X, C, P
data_inicio, data_fim YYYY-MM-DD
pagina, por_pagina Paginação

Detalhe de uma NFS-e.

curl https://api.alugueimais.com.br/api/v1/documentos/184 \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Baixa o XML autorizado (application/xml).

curl -OJ https://api.alugueimais.com.br/api/v1/documentos/184/xml \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Campos principais do documento

Campo Descrição
codigo ID do documento no aluguei+
numero_nfse Número da NFS-e (atribuído pelo portal)
numero_dps Número do RPS/DPS (sequencial do emitente)
chave_acesso Chave de acesso quando autorizada
link_nfse Link do DANFSe no portal
data_emissao Data/hora
ambiente 1 produção, 2 homologação
tom_razao_social Tomador (locatário)
valor_servico Valor do serviço (locação)
status Situação (ver abaixo)

Status da nota

status Significado
E Emitida / autorizada
X Rejeitada
C Cancelada
P Processando

XML disponível apenas para notas autorizadas/canceladas

O endpoint de XML retorna 404 quando a nota não tem XML disponível (processando ou rejeitada).


Códigos de status HTTP

Código Significado
200 OK Consulta bem-sucedida
400 Bad Request JSON inválido ou parâmetro obrigatório ausente
401 Unauthorized API key ausente/ inválida/ revogada
403 Forbidden Empresa inativa
404 Not Found Recurso/documento/XML não encontrado
500 Erro interno

Em cadastros em lote, o HTTP é 200 mesmo com falhas parciais — verifique o campo falhas e cada item em resultados.


Boas práticas

  • Idempotência do sync: reenviar o mesmo lote é seguro — vira atualização (upsert). Prefira uma chave estável (cpf_cnpj para locatários, cib para imóveis).
  • Uma chave por integração: gere chaves separadas por sistema para poder revogar isoladamente.
  • Cadastro completo: contrato só emite se o imóvel tiver cod_mun_ibge e o locatário tiver endereço completo.
  • UTF-8: envie o corpo em UTF-8 para não corromper acentos.