Integração via API¶

Referência da API de Integração do AlugueiMais (/api/v1) para sistemas externos (ERP, e-commerce, PDV) sincronizarem cadastros e consultarem documentos fiscais.

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

A API de Integração popula cadastros (produtos, clientes e serviços) e consulta documentos emitidos (NF-e, NFC-e, NFS-e) e seus XMLs.

A emissão de notas continua sendo feita dentro do AlugueiMais (app/painel). 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 produtos, clientes e serviços (POST), que são criados/atualizados no AlugueiMais.
O usuário emite as notas normalmente pelo AlugueiMais.
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 AlugueiMais)¶

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

Dê um nome à chave (ex.: Loja Virtual, ERP) 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 AlugueiMais.

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) ou ISO (YYYY-MM-DDTHH:MM:SS).
Valores monetários/numéricos com ponto decimal (9.90).

Formato de erro¶

{ "error": "descrição do problema" }

Lote e upsert (cadastros)¶

Os endpoints de cadastro (POST /produtos, /clientes, /servicos) 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": "ncm obrigatorio" }
  ]
}

Campo do resultado	Descrição
`indice`	Posição do item no array enviado
`acao`	`criado`, `atualizado` ou `erro`
`codigo`	ID do registro no AlugueiMais (quando criado/atualizado)
`erro`	Mensagem, quando `acao = erro`

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¶

Produtos¶

POST /api/v1/produtosGET /api/v1/produtosGET /api/v1/produtos/:id

Cria ou atualiza produtos (objeto único ou array).

Chave de upsert: codigo (ID) › codigo_barras › codigo_interno.

curl -X POST https://api.alugueimais.com.br/api/v1/produtos \
  -H "Authorization: Bearer $ALUGUEI_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "codigo_interno": "SKU-001",
      "codigo_barras": "7890000000017",
      "descricao": "CAMISETA BRANCA P",
      "ncm": "61091000",
      "cfop_padrao": "5102",
      "csosn": "102",
      "origem": "0",
      "unidade": "UN",
      "preco_venda": 49.90
    }
  ]'

Lista os produtos da empresa.

curl "https://api.alugueimais.com.br/api/v1/produtos?busca=camiseta&pagina=1&por_pagina=30" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Query: busca, so_ativos (true/false), pagina, por_pagina.

Retorna um produto pelo ID.

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

Campos do produto

Campo	Tipo	Obrig.	Observação
`codigo` / `id`	int		Enviar para forçar atualização por ID
`codigo_interno`	string		Código do produto no sistema de origem (chave de upsert)
`codigo_barras`	string		EAN/GTIN (chave de upsert)
`descricao`	string	✔
`ncm`	string	✔	Exatamente 8 dígitos
`cest`	string
`cfop_padrao`	string		Default `5102`
`csosn`	string		Default `102`
`origem`	string		Default `0`
`unidade`	string		Default `UN`
`preco_venda`	number		`>= 0`
`status`	string		`A` (ativo) / `I` (inativo). Default `A`
`embalagem_id`	int		Embalagem cadastrada (opcional)

Clientes¶

POST /api/v1/clientesGET /api/v1/clientesGET /api/v1/clientes/:id

Cria ou atualiza clientes (objeto único ou array).

Chave de upsert: codigo (ID) › cpf_cnpj.

curl -X POST https://api.alugueimais.com.br/api/v1/clientes \
  -H "Authorization: Bearer $ALUGUEI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_pessoa": "J",
    "cpf_cnpj": "11222333000181",
    "nome": "ACME COMERCIO LTDA",
    "email": "[email protected]",
    "uf": "SC",
    "codigo_municipio_ibge": "4205407",
    "nome_municipio": "Florianopolis"
  }'

curl "https://api.alugueimais.com.br/api/v1/clientes?busca=acme" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Query: busca, so_ativos, pagina, por_pagina.

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

Campos do cliente

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
`indicador_ie`	int		`1` contribuinte, `2` isento, `9` não contribuinte. Default `9`
`email`	string
`fone`	string
`cep`	string		Só dígitos
`logradouro`, `numero`, `complemento`, `bairro`	string		Endereço
`codigo_municipio_ibge`	string		Código IBGE (7 dígitos)
`nome_municipio`	string
`uf`	string		2 letras
`status`	string		`A` / `I`. Default `A`
`iss_retido`	bool		Para NFS-e
`iss_substituto_tributario`	bool		Para NFS-e

Serviços (catálogo NFS-e)¶

POST /api/v1/servicosGET /api/v1/servicosGET /api/v1/servicos/:id

Cria ou atualiza itens do catálogo de serviços (objeto único ou array).

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

curl -X POST https://api.alugueimais.com.br/api/v1/servicos \
  -H "Authorization: Bearer $ALUGUEI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "descricao": "DESENVOLVIMENTO DE SOFTWARE",
    "cod_trib_nacional": "010701",
    "aliquota_iss": 2.0,
    "discriminacao_padrao": "Servico de desenvolvimento de sistemas"
  }'

curl "https://api.alugueimais.com.br/api/v1/servicos?busca=software" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Query: busca, status.

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

Campos do serviço

Campo	Tipo	Obrig.	Observação
`codigo` / `id`	int		Enviar para forçar atualização por ID
`descricao`	string	✔
`cod_trib_nacional`	string	✔	Código de tributação nacional (LC 116)
`codigo_interno`	string
`item_nbs`	string
`cnae`	string
`caso_especial_iss`	bool
`valor_unitario`	number		Valor padrão do serviço
`aliquota_iss`	number		Alíquota ISS (%)
`iss_retido`	bool
`exigibilidade_iss`	int
`iss_substituicao`	bool
`discriminacao_padrao`	string		Texto padrão da discriminação
`status`	string		`A` / `I`

Documentos (consulta)¶

Leitura das notas emitidas e dos XMLs autorizados. O segmento :modelo aceita:

`:modelo`	Documento
`55` ou `nfe`	NF-e
`65` ou `nfce`	NFC-e
`nfse`	NFS-e

GET /api/v1/documentosGET /api/v1/documentos/:modelo/:idGET /api/v1/documentos/:modelo/:id/xml

Lista os documentos. Use modelo para escolher o tipo.

# NFC-e do mês
curl "https://api.alugueimais.com.br/api/v1/documentos?modelo=65&data_inicio=2026-08-01&data_fim=2026-08-31" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

# NFS-e
curl "https://api.alugueimais.com.br/api/v1/documentos?modelo=nfse" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

Query	Descrição
`modelo`	`55`, `65` ou `nfse`. Sem `modelo`, lista notas de produto (NF-e/NFC-e)
`busca`	Texto (destinatário, número…)
`status`	Filtra por status
`data_inicio`, `data_fim`	`YYYY-MM-DD`
`pagina`, `por_pagina`	Paginação

Detalhe de um documento.

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

Baixa o XML autorizado (application/xml).

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

Campos principais do item (NF-e/NFC-e)

Campo	Descrição
`codigo`	ID do documento no AlugueiMais
`modelo`	`55` ou `65`
`serie`, `numero`	Série e número da nota
`chave`	Chave de acesso (44 dígitos) quando autorizada
`protocolo`	Protocolo de autorização
`data_emissao`	Data/hora
`ambiente`	`1` produção, `2` homologação
`dest_cpf_cnpj`, `dest_nome`	Destinatário
`valor_total`	Valor total
`status`	Situação (ver abaixo)
`motivo_status`	Descrição do status/rejeição

Status da nota

`status`	Significado
`E`	Emitida / autorizada
`X`	Rejeitada
`C`	Cancelada

XML disponível apenas para notas autorizadas

O endpoint de XML retorna 404 quando a nota não tem XML autorizado (ainda não emitida, rejeitada, etc.).

Fluxo típico (exemplo completo)¶

export ALUGUEI_KEY="aluguei_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE="https://api.alugueimais.com.br/api/v1"

# 1) Sincroniza clientes e produtos (lote)
curl -X POST "$BASE/clientes" -H "Authorization: Bearer $ALUGUEI_KEY" \
  -H "Content-Type: application/json" -d @clientes.json

curl -X POST "$BASE/produtos" -H "Authorization: Bearer $ALUGUEI_KEY" \
  -H "Content-Type: application/json" -d @produtos.json

# 2) (usuário emite as notas no AlugueiMais)

# 3) Consulta as NFC-e do dia e baixa os XMLs
curl "$BASE/documentos?modelo=65&data_inicio=2026-08-20&data_fim=2026-08-20" \
  -H "Authorization: Bearer $ALUGUEI_KEY"

curl -OJ "$BASE/documentos/65/184/xml" -H "Authorization: Bearer $ALUGUEI_KEY"

Códigos de status HTTP¶

Código	Significado
`200 OK`	Consulta bem-sucedida
`201 Created`	—
`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 e observações¶

Idempotência do sync: reenviar o mesmo lote é seguro — vira atualização (upsert). Prefira uma chave estável (codigo_interno para produtos, cpf_cnpj para clientes).
Uma chave por integração: gere chaves separadas por sistema/finalidade para poder revogar isoladamente.
NCM/CFOP/CSOSN corretos: produtos com fiscal incompleto podem impedir a emissão posterior no AlugueiMais.
UTF-8: envie o corpo em UTF-8 para não corromper acentos.