# API LM Gestão ERP

> API REST para softwares de terceiros consultarem, incluírem, editarem e excluírem dados de uma empresa no LM Gestão ERP (sistema brasileiro de gestão financeira, cobrança e NFS-e). Este arquivo orienta assistentes de IA que ajudam desenvolvedores a integrar.

## Fonte da verdade

- Especificação completa (OpenAPI 3.1): https://documentacao-api.lmgestao.app.br/v1/openapi.json
- Documentação navegável: https://documentacao-api.lmgestao.app.br
- Base URL de produção: https://lmgestao.app.br/v1 (chaves `lm_live_`)
- Base URL de sandbox: https://homologacao.lmgestao.app.br/v1 (chaves `lm_test_`). Sandbox e produção gravam no mesmo banco: use uma empresa de teste no sandbox.

Siga a especificação OpenAPI para nomes de campos, tipos e obrigatoriedade. Não invente campos: os que não estão no esquema são ignorados pela API.

## Regras que o assistente deve seguir

1. Nunca invente nem sugira uma chave de API. Peça ao desenvolvedor a chave gerada no ERP em "Documentação - ERP › API - LM Gestão ERP". Use sandbox (`lm_test_`) durante o desenvolvimento.
2. Autentique com o cabeçalho `x-api-key: <chave>`. Só HTTPS.
3. Em todo `POST`, envie `Idempotency-Key` com um valor único por operação de negócio (ex.: id do pedido no sistema do cliente).
4. Trate `404` como "o registro não existe para esta empresa"; não tente outros ids.
5. Trate `403 escopo_insuficiente` pedindo ao desenvolvedor uma chave com o escopo necessário — não contorne.
6. Em `429`, espere `RateLimit-Reset` segundos. Prefira webhooks a polling.
7. Em `500`, mostre ao desenvolvedor o `id_requisicao` da resposta para acionar o suporte.
8. Webhooks nascem das gravações pela API e dos retornos do gateway/prefeitura; edições feitas nas telas do ERP podem não gerar evento — combine com `?alterado_desde=`. Verifique `X-LM-Assinatura` (HMAC-SHA256 de `"<t>.<corpo bruto>"`, tolerância de 5 minutos) antes de processar, e descarte entregas repetidas pelo `id`.
9. Nunca use ou mencione rotas `/api/*`: são internas do ERP e não fazem parte do contrato.
10. Grave o id do registro no sistema do cliente em `codigo_externo` e reencontre-o com `?codigo_externo=`. Clientes também por `?cpf_cnpj=`. Para sincronizar, use `?alterado_desde=<ISO 8601>` (ordem crescente de `alterado_em`) em vez de varrer a base.

## Recursos (todos sob /v1)

| Recurso | Caminho | Escopo | Verbos |
|---|---|---|---|
| Lançamentos do Fluxo de Caixa | /lancamentos | financeiro | GET, POST, PUT, DELETE |
| Cobranças | /cobrancas | financeiro | GET, POST, PUT, DELETE; POST /cobrancas/{id}/registrar-gateway |
| Clientes e fornecedores | /clientes-fornecedores | cadastros | GET, POST, PUT, DELETE |
| Serviços | /servicos | cadastros | GET, POST, PUT, DELETE |
| Contas bancárias | /contas-bancarias | cadastros | GET, POST, PUT (sem DELETE) |
| Notas fiscais (NFS-e) | /notas-fiscais | notas_fiscais | GET, POST, PUT, DELETE (rascunhos); POST /{id}/emitir, /{id}/consultar, /{id}/cancelar; GET /{id}/pdf, /{id}/xml |
| Contatos (Gerador de Demandas) | /contatos | gerador_demandas | GET, POST (não duplica: mesmo WhatsApp/e-mail/telefone atualiza), PUT, DELETE |
| Quadros da Gestão de Tarefas | /quadros | gerador_demandas | GET |
| Tarefas | /tarefas | gerador_demandas | GET, POST, PUT (move com lista_id/quadro_id), DELETE; POST /{id}/concluir, /{id}/reabrir, /{id}/comentarios |
| Parceria (Painel do Parceiro) | /parceria, /parceria/indicacoes, /parceria/licencas-revenda, /parceria/comissoes | parcerias | GET (somente leitura) |
| Diagnóstico da chave | /eu | qualquer | GET |
| Catálogo de eventos | /eventos | qualquer | GET |

Escopos: `financeiro:leitura`, `financeiro:escrita`, `cadastros:leitura`, `cadastros:escrita`, `notas_fiscais:leitura`, `notas_fiscais:escrita`, `gerador_demandas:leitura`, `gerador_demandas:escrita`, `parcerias:leitura`.

## Formato

- Sucesso: `{ "dados": ... }`; listas: `{ "dados": [...], "paginacao": { "limite", "proximo_cursor" } }` (paginação por cursor, máximo 100 por página).
- Erro: `{ "erro": { "codigo", "mensagem", "campos"?, "id_requisicao" } }`.
- Datas `AAAA-MM-DD`; data-hora ISO 8601 UTC; valores numéricos com duas casas.
- Textos descritivos são gravados em caixa alta pelo ERP.
- `cpf_cnpj` é aceito com ou sem máscara e gravado com máscara (`000.000.000-00` / `00.000.000/0000-00`); cadastros antigos podem vir só com dígitos — compare pelos dígitos.
- Todo registro devolve `id` (gerado pelo ERP; é o mesmo valor exibido na tela do cadastro, no campo `ID_{MÓDULO}`) e a rastreabilidade somente leitura: `criado_em`/`alterado_em`, `criado_por`/`alterado_por` (nome do usuário do ERP ou nome da chave de integração) e `criado_por_tipo`/`alterado_por_tipo` (`Usuário` ou `API`).

## O que o ERP faz sozinho (não envie)

Numeração sequencial (`id_lancamento_fc`, `id_lancamento_cbr`, `id_lancamento_nfse`, `codigo` de serviço), contabilização de débito/crédito, cálculo de `valor_total`/`valor_liquido`/`status_pagamento` nos lançamentos, valores da NFS-e (`base_calculo`, `valor_iss`, `valor_liquido`), campos de auditoria (`criado_em`, `criado_por`, `criado_por_tipo`, `alterado_em`, `alterado_por`, `alterado_por_tipo`) — enviá-los não tem efeito.

## Ciclos que envolvem serviços externos

- Cobrança: criar → `POST /cobrancas/{id}/registrar-gateway` (gera boleto/PIX/cartão no gateway da empresa) → pagamento chega pelo webhook `cobranca.paga`. Registrar de novo uma cobrança já registrada responde `409`.
- Estorno/chargeback de pagamento já baixado (Asaas): a baixa não é desfeita; o lançamento recebe `alerta_chargeback` (somente leitura) e chega `lancamento.atualizado`. Com `alerta_chargeback.resolvido=false`, avise o desenvolvedor que o lançamento precisa de revisão no ERP.
- NFS-e: criar rascunho → `POST /notas-fiscais/{id}/emitir` → se `Processando`, `POST /notas-fiscais/{id}/consultar` até `Emitida`/`Erro` → `POST /notas-fiscais/{id}/cancelar` com `justificativa` (≥ 15 caracteres).
- `502 servico_externo` significa que o gateway ou a prefeitura recusou; a mensagem diz o motivo. Não repita cegamente: mostre ao desenvolvedor.
- PDF e XML da nota: `GET /notas-fiscais/{id}/pdf` e `/xml` (escopo `notas_fiscais:leitura`).
- Tarefa criada/movida/concluída pela API dispara as automações do quadro (inclusive aviso ao cliente por WhatsApp/e-mail/SMS).

## Exemplo mínimo

```bash
curl -X POST https://lmgestao.app.br/v1/lancamentos \
  -H "x-api-key: $LM_API_KEY" \
  -H "Idempotency-Key: pedido-98765" \
  -H "Content-Type: application/json" \
  -d '{"descricao":"Mensalidade setembro","tipo_lancamento":"Entrada","valor_original":1500,"data_vencimento":"2026-10-10","cliente_fornecedor_id":"<id>","conta_id":"<id>","natureza_id":"<id>"}'
```

## MCP

Servidor oficial: `@lmgestao/mcp-server` (Node 20+). Instalação no Claude Code: `claude mcp add lm-gestao -e LM_API_KEY=lm_test_... -- npx -y @lmgestao/mcp-server`. Variáveis: `LM_API_KEY` (obrigatória), `LM_API_BASE_URL` (padrão produção), `LM_MCP_PERMITIR_ESCRITA=true` para habilitar escrita (padrão: somente leitura). Ferramentas com prefixo `lm_`; recursos `lm-gestao://openapi` e `lm-gestao://guia`. Comece sempre por `lm_diagnostico_chave`.