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:
- Sincroniza cadastros — envia seus locatários, imóveis e contratos (
POST), que são criados/atualizados no aluguei+. - O usuário (ou o agendador mensal) emite as NFS-e de locação no aluguei+.
- 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_cnpjpara locatários,cibpara 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_ibgee o locatário tiver endereço completo. - UTF-8: envie o corpo em UTF-8 para não corromper acentos.