# API do LYMOS ERP

Versão 1, atualizada em 22 de outubro de 2026. Documentação: https://lymos.com.br/api-erp. OpenAPI 3.0: https://app.lymos.com.br/api/v1/integracao/openapi.json.

API REST **somente de leitura** para consultar produtos e estoque, clientes, pedidos de venda e de delivery e notas de serviço de uma empresa do LYMOS ERP. Não existe rota de escrita nem webhook de saída.

## Conexão e autenticação

- URL base: `https://app.lymos.com.br/api/v1/integracao`
- Cabeçalho em toda chamada: `Authorization: Bearer SEU_TOKEN`
- O token é criado pelo dono da empresa no ERP, em Configurações > Integrações (permissão "Gerenciar integrações"), com escopos e validade. Aparece uma vez. Até 10 tokens ativos por empresa; revogar corta o acesso na hora.
- Cada token só enxerga a empresa que o criou. Nunca coloque o token em código de navegador.
- Teste com `GET /perfil`.

### Escopos

- `produtos:ler`: Produtos e estoque disponível.
- `clientes:ler`: Clientes.
- `pedidos:ler`: Pedidos de venda e de delivery. Mostra também o nome do cliente do pedido e, no delivery, o telefone.
- `nfse:ler`: Notas de serviço. Mostra também o nome do tomador.

## Convenções

- Lista: `{ "data": [...], "meta": { "pagina", "por_pagina", "total", "ultima_pagina" } }`. Detalhe: `{ "data": {...} }`.
- Paginação: `?pagina=2&por_pagina=50` (padrão 25, máximo 100). Percorra até `ultima_pagina`.
- Sincronização incremental: `?atualizado_desde=` em produtos e clientes (AAAA-MM-DD ou ISO 8601). Os outros filtros de data aceitam só AAAA-MM-DD.
- Valores em reais são números com ponto decimal. Horários em ISO 8601.
- Limites: 120 requisições por minuto por token e 600 por minuto por IP; excedeu: 429 com `Retry-After`.
- Pedidos de venda exigem o módulo Comércio, delivery o módulo Food e notas de serviço Comércio, Oficina ou CellTECH.

## GET /perfil: Testar a conexão

Escopo: qualquer. Módulo do plano: nenhum.

Mostra a empresa dona do token, os escopos dele e quais recursos o plano do ERP oferece. Funciona com qualquer escopo. Use para conferir o token antes de integrar.

Campos da resposta:

- `empresa` (texto): Nome da empresa.
- `token` (objeto): nome e expira_em do token.
- `escopos` (lista): O que o token pode ler.
- `recursos` (objeto): produtos, clientes, pedidos_venda, pedidos_delivery e notas_servico, cada um true ou false.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/perfil' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": {
    "empresa": "Pizzaria do Zé",
    "token": {
      "nome": "CRM",
      "expira_em": "2027-01-20T00:00:00-03:00"
    },
    "escopos": [
      "produtos:ler",
      "clientes:ler",
      "pedidos:ler"
    ],
    "recursos": {
      "produtos": true,
      "clientes": true,
      "pedidos_venda": false,
      "pedidos_delivery": true,
      "notas_servico": false
    }
  }
}
```

## GET /produtos: Listar produtos

Escopo: produtos:ler. Módulo do plano: nenhum.

Produtos com preço de venda e estoque disponível. Por padrão só vêm os ativos. Custo, margem, fornecedor e dados fiscais não saem.

Parâmetros de consulta:

- `busca` (texto): Parte do nome, do SKU ou do código de barras.
- `ativo` (texto): 1 (padrão) só os ativos; 0 só os inativos.
- `atualizado_desde` (data): Só o que mudou desde então. AAAA-MM-DD ou ISO 8601, como 2026-10-23T10:00:00-03:00.
- `pagina` (inteiro): Página, começando em 1.
- `por_pagina` (inteiro): Itens por página, de 1 a 100. Padrão 25.

Campos da resposta:

- `id` (inteiro): Identificador do produto.
- `nome` (texto): Nome do produto.
- `descricao` (texto): Descrição, quando houver.
- `sku` (texto): Código interno.
- `codigo_barras` (texto): Código de barras principal.
- `unidade` (texto): Unidade de venda, como UN ou KG.
- `categoria` (texto): Nome da categoria.
- `preco_venda` (número): Preço de venda, em reais.
- `preco_atacado` (número): Preço de atacado, em reais, quando houver.
- `ativo` (booleano): Se o produto está à venda.
- `controla_estoque` (booleano): Se o ERP controla o estoque deste produto.
- `estoque_disponivel` (número): Quantidade menos a reservada, nunca negativa. null quando não controla estoque.
- `atualizado_em` (data e hora): Última alteração, em ISO 8601.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/produtos?busca=calabresa' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": [
    {
      "id": 318,
      "nome": "Pizza grande de calabresa",
      "descricao": null,
      "sku": "PZ-CAL-G",
      "codigo_barras": null,
      "unidade": "UN",
      "categoria": "Pizzas",
      "preco_venda": 54.9,
      "preco_atacado": null,
      "ativo": true,
      "controla_estoque": false,
      "estoque_disponivel": null,
      "atualizado_em": "2026-10-20T15:42:10-03:00"
    }
  ],
  "meta": {
    "pagina": 1,
    "por_pagina": 25,
    "total": 1,
    "ultima_pagina": 1
  }
}
```

## GET /produtos/{id}: Ver um produto

Escopo: produtos:ler.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/produtos/318' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": {
    "id": 318,
    "nome": "Pizza grande de calabresa",
    "descricao": null,
    "sku": "PZ-CAL-G",
    "codigo_barras": null,
    "unidade": "UN",
    "categoria": "Pizzas",
    "preco_venda": 54.9,
    "preco_atacado": null,
    "ativo": true,
    "controla_estoque": false,
    "estoque_disponivel": null,
    "atualizado_em": "2026-10-20T15:42:10-03:00"
  }
}
```

## GET /clientes: Listar clientes

Escopo: clientes:ler. Módulo do plano: nenhum.

Nome, contato e cidade. CPF e CNPJ não saem: para ligar um cliente a outro sistema, use o telefone, o e-mail ou o nome.

Parâmetros de consulta:

- `busca` (texto): Nome, e-mail ou telefone, com ou sem máscara. Aceita também o formato internacional, como 5575998765432.
- `ativo` (texto): 1 só os ativos; 0 só os inativos. Sem o parâmetro, vêm todos.
- `atualizado_desde` (data): Só o que mudou desde então. AAAA-MM-DD ou ISO 8601, como 2026-10-23T10:00:00-03:00.
- `pagina` (inteiro): Página, começando em 1.
- `por_pagina` (inteiro): Itens por página, de 1 a 100. Padrão 25.

Campos da resposta:

- `id` (inteiro): Identificador do cliente.
- `tipo` (texto): Tipo de pessoa.
- `nome` (texto): Nome.
- `razao_social` (texto): Razão social, para empresa.
- `nome_fantasia` (texto): Nome fantasia, para empresa.
- `email` (texto): E-mail.
- `telefone` (texto): Telefone fixo.
- `celular` (texto): Celular.
- `bairro` (texto): Bairro do endereço.
- `cidade` (texto): Cidade do endereço.
- `uf` (texto): Estado do endereço.
- `ativo` (booleano): Se o cadastro está ativo.
- `criado_em` (data e hora): Criação do cadastro.
- `atualizado_em` (data e hora): Última alteração.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/clientes?busca=5575998765432' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": [
    {
      "id": 27,
      "tipo": "fisica",
      "nome": "Ana Souza",
      "razao_social": null,
      "nome_fantasia": null,
      "email": "ana@exemplo.com.br",
      "telefone": null,
      "celular": "(75) 99876-5432",
      "bairro": "Centro",
      "cidade": "Feira de Santana",
      "uf": "BA",
      "ativo": true,
      "criado_em": "2026-03-02T09:12:00-03:00",
      "atualizado_em": "2026-10-18T14:03:21-03:00"
    }
  ],
  "meta": {
    "pagina": 1,
    "por_pagina": 25,
    "total": 1,
    "ultima_pagina": 1
  }
}
```

## GET /clientes/{id}: Ver um cliente

Escopo: clientes:ler.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/clientes/27' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": {
    "id": 27,
    "tipo": "fisica",
    "nome": "Ana Souza",
    "razao_social": null,
    "nome_fantasia": null,
    "email": "ana@exemplo.com.br",
    "telefone": null,
    "celular": "(75) 99876-5432",
    "bairro": "Centro",
    "cidade": "Feira de Santana",
    "uf": "BA",
    "ativo": true,
    "criado_em": "2026-03-02T09:12:00-03:00",
    "atualizado_em": "2026-10-18T14:03:21-03:00"
  }
}
```

## GET /pedidos-venda: Listar pedidos de venda

Escopo: pedidos:ler. Módulo do plano: Comércio.

Orçamentos e pedidos do módulo Comércio. Os itens só vêm no detalhe.

Parâmetros de consulta:

- `status` (texto): orcamento, enviado, aprovado, recusado, faturado ou cancelado.
- `cliente_id` (inteiro): Só os do cliente com este id.
- `de` (data): Criados a partir deste dia. AAAA-MM-DD.
- `ate` (data): Criados até este dia. AAAA-MM-DD.
- `pagina` (inteiro): Página, começando em 1.
- `por_pagina` (inteiro): Itens por página, de 1 a 100. Padrão 25.

Campos da resposta:

- `id` (inteiro): Identificador do pedido.
- `numero` (texto): Número do pedido.
- `status` (texto): orcamento, enviado, aprovado, recusado, faturado ou cancelado.
- `cliente` (objeto): id e nome do cliente.
- `subtotal, desconto, total` (número): Valores em reais.
- `condicao_pagamento` (texto): Condição combinada.
- `validade` (data): Validade do orçamento.
- `data_entrega` (data): Entrega prevista.
- `venda_id` (inteiro): Venda gerada quando o pedido foi faturado.
- `criado_em` (data e hora): Criação do pedido.
- `itens` (lista): Só no detalhe: produto_id, descricao, quantidade, preco_unitario, desconto e total.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/pedidos-venda?status=aprovado&cliente_id=27' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": [
    {
      "id": 905,
      "numero": "PV-000905",
      "status": "aprovado",
      "cliente": {
        "id": 27,
        "nome": "Ana Souza"
      },
      "subtotal": 480,
      "desconto": 30,
      "total": 450,
      "condicao_pagamento": "30 dias",
      "validade": "2026-10-30",
      "data_entrega": "2026-11-05",
      "venda_id": null,
      "criado_em": "2026-10-19T11:20:00-03:00"
    }
  ],
  "meta": {
    "pagina": 1,
    "por_pagina": 25,
    "total": 1,
    "ultima_pagina": 1
  }
}
```

## GET /pedidos-venda/{id}: Ver um pedido de venda

Escopo: pedidos:ler. Módulo do plano: Comércio.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/pedidos-venda/905' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": {
    "id": 905,
    "numero": "PV-000905",
    "status": "aprovado",
    "cliente": {
      "id": 27,
      "nome": "Ana Souza"
    },
    "subtotal": 480,
    "desconto": 30,
    "total": 450,
    "condicao_pagamento": "30 dias",
    "validade": "2026-10-30",
    "data_entrega": "2026-11-05",
    "venda_id": null,
    "criado_em": "2026-10-19T11:20:00-03:00",
    "itens": [
      {
        "produto_id": 318,
        "descricao": "Pizza grande de calabresa",
        "quantidade": 10,
        "preco_unitario": 48,
        "desconto": 0,
        "total": 480
      }
    ]
  }
}
```

## GET /pedidos-delivery: Listar pedidos de delivery

Escopo: pedidos:ler. Módulo do plano: Food.

Pedidos do cardápio digital do módulo Food, com o endereço de entrega completo, sem as coordenadas do mapa e sem dados de pagamento. Pedidos do iFood não entram.

Parâmetros de consulta:

- `telefone` (texto): Telefone do cliente, com ou sem máscara. No mínimo 4 dígitos; menos que isso responde 422.
- `status` (texto): Situação do pedido, como aceito, em_preparo, saiu_para_entrega, entregue ou cancelado.
- `cliente_id` (inteiro): Só os do cliente com este id.
- `de` (data): Criados a partir deste dia. AAAA-MM-DD.
- `ate` (data): Criados até este dia. AAAA-MM-DD.
- `pagina` (inteiro): Página, começando em 1.
- `por_pagina` (inteiro): Itens por página, de 1 a 100. Padrão 25.

Campos da resposta:

- `id` (inteiro): Identificador do pedido.
- `status` (texto): Situação do pedido, como aceito, em_preparo, saiu_para_entrega, entregue ou cancelado.
- `cliente_id, cliente_nome, cliente_telefone` (inteiro e texto): Quem pediu.
- `endereco_entrega` (objeto): logradouro, numero, complemento, bairro, cidade, uf, cep, referencia e descricao. Sem as coordenadas do mapa.
- `subtotal, desconto, taxa_entrega, total` (número): Valores em reais.
- `forma_pagamento` (texto): Como o cliente paga.
- `pix_confirmado` (booleano): Só para Pix: se o pagamento foi confirmado. null quando não se aplica (dinheiro e cartão na entrega).
- `tempo_estimado_min` (inteiro): Tempo estimado, em minutos.
- `criado_em, aceito_em, saiu_para_entrega_em, entregue_em, cancelado_em` (data e hora): Marcos do pedido. null quando ainda não aconteceu.
- `observacoes, motivo_cancelamento, itens` (texto e lista): Só no detalhe. Cada item traz nome, quantidade, preco_unitario, total e observacao.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/pedidos-delivery?telefone=75998765432' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": [
    {
      "id": 1042,
      "status": "entregue",
      "cliente_id": 27,
      "cliente_nome": "Ana Souza",
      "cliente_telefone": "75998765432",
      "endereco_entrega": {
        "logradouro": "Rua das Flores",
        "numero": "120",
        "complemento": null,
        "bairro": "Centro",
        "cidade": "Feira de Santana",
        "uf": "BA",
        "cep": "44001000",
        "referencia": "Perto da praça",
        "descricao": null
      },
      "subtotal": 54.9,
      "desconto": 0,
      "taxa_entrega": 6,
      "total": 60.9,
      "forma_pagamento": "pix",
      "pix_confirmado": true,
      "tempo_estimado_min": 40,
      "criado_em": "2026-10-21T18:02:11-03:00",
      "aceito_em": "2026-10-21T18:03:40-03:00",
      "saiu_para_entrega_em": "2026-10-21T18:40:05-03:00",
      "entregue_em": "2026-10-21T19:05:12-03:00",
      "cancelado_em": null
    }
  ],
  "meta": {
    "pagina": 1,
    "por_pagina": 25,
    "total": 1,
    "ultima_pagina": 1
  }
}
```

## GET /pedidos-delivery/{id}: Ver um pedido de delivery

Escopo: pedidos:ler. Módulo do plano: Food.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/pedidos-delivery/1042' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": {
    "id": 1042,
    "status": "entregue",
    "cliente_id": 27,
    "cliente_nome": "Ana Souza",
    "cliente_telefone": "75998765432",
    "endereco_entrega": {
      "logradouro": "Rua das Flores",
      "numero": "120",
      "complemento": null,
      "bairro": "Centro",
      "cidade": "Feira de Santana",
      "uf": "BA",
      "cep": "44001000",
      "referencia": "Perto da praça",
      "descricao": null
    },
    "subtotal": 54.9,
    "desconto": 0,
    "taxa_entrega": 6,
    "total": 60.9,
    "forma_pagamento": "pix",
    "pix_confirmado": true,
    "tempo_estimado_min": 40,
    "criado_em": "2026-10-21T18:02:11-03:00",
    "aceito_em": "2026-10-21T18:03:40-03:00",
    "saiu_para_entrega_em": "2026-10-21T18:40:05-03:00",
    "entregue_em": "2026-10-21T19:05:12-03:00",
    "cancelado_em": null,
    "observacoes": null,
    "motivo_cancelamento": null,
    "itens": [
      {
        "nome": "Pizza grande de calabresa",
        "quantidade": 1,
        "preco_unitario": 54.9,
        "total": 54.9,
        "observacao": "Sem cebola"
      }
    ]
  }
}
```

## GET /notas-servico: Listar notas de serviço

Escopo: nfse:ler. Módulo do plano: Comércio, Oficina ou CellTECH.

NFS-e do ERP. Leia o campo ambiente: enquanto a empresa emite na produção restrita do governo, ele vem "teste" e a nota não vale como documento fiscal. Documento do tomador, XML e erros do governo não saem.

Parâmetros de consulta:

- `status` (texto): rascunho, transmitindo, autorizada, rejeitada, cancelada ou pendente_acao.
- `cliente_id` (inteiro): Só os do cliente com este id.
- `competencia_de` (data): Competência a partir deste dia. AAAA-MM-DD.
- `competencia_ate` (data): Competência até este dia. AAAA-MM-DD.
- `pagina` (inteiro): Página, começando em 1.
- `por_pagina` (inteiro): Itens por página, de 1 a 100. Padrão 25.

Campos da resposta:

- `id` (inteiro): Identificador da nota.
- `status` (texto): rascunho, transmitindo, autorizada, rejeitada, cancelada ou pendente_acao.
- `ambiente` (texto): producao ou teste. Nota de teste não vale como documento fiscal.
- `numero_nfse, chave_acesso` (texto): Identificação da nota.
- `cliente_id, tomador_nome` (inteiro e texto): Quem contratou o serviço. Sem o documento do tomador.
- `descricao_servico` (texto): Descrição do serviço.
- `valor_servico, aliquota_iss, valor_iss` (número): Valores em reais e alíquota em %.
- `iss_retido` (booleano): Se o ISS foi retido.
- `data_competencia` (data): Competência da nota.
- `emitida_em, autorizada_em, cancelada_em` (data e hora): Marcos da nota.
- `motivo_cancelamento, rejeitada` (texto e booleano): Cancelamento e se o governo recusou a nota.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/notas-servico?status=autorizada' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": [
    {
      "id": 318,
      "status": "autorizada",
      "ambiente": "producao",
      "numero_nfse": "2026000318",
      "chave_acesso": null,
      "cliente_id": 27,
      "tomador_nome": "Ana Souza",
      "descricao_servico": "Manutenção preventiva de equipamento",
      "valor_servico": 350,
      "aliquota_iss": 2.5,
      "valor_iss": 8.75,
      "iss_retido": false,
      "data_competencia": "2026-10-01",
      "emitida_em": "2026-10-05T10:11:00-03:00",
      "autorizada_em": "2026-10-05T10:11:42-03:00",
      "cancelada_em": null,
      "motivo_cancelamento": null,
      "rejeitada": false
    }
  ],
  "meta": {
    "pagina": 1,
    "por_pagina": 25,
    "total": 1,
    "ultima_pagina": 1
  }
}
```

## GET /notas-servico/{id}: Ver uma nota de serviço

Escopo: nfse:ler. Módulo do plano: Comércio, Oficina ou CellTECH.

Exemplo:

```bash
curl 'https://app.lymos.com.br/api/v1/integracao/notas-servico/318' \
  -H 'Authorization: Bearer SEU_TOKEN'
```

Resposta:

```json
{
  "data": {
    "id": 318,
    "status": "autorizada",
    "ambiente": "producao",
    "numero_nfse": "2026000318",
    "chave_acesso": null,
    "cliente_id": 27,
    "tomador_nome": "Ana Souza",
    "descricao_servico": "Manutenção preventiva de equipamento",
    "valor_servico": 350,
    "aliquota_iss": 2.5,
    "valor_iss": 8.75,
    "iss_retido": false,
    "data_competencia": "2026-10-01",
    "emitida_em": "2026-10-05T10:11:00-03:00",
    "autorizada_em": "2026-10-05T10:11:42-03:00",
    "cancelada_em": null,
    "motivo_cancelamento": null,
    "rejeitada": false
  }
}
```

## Erros

- 401: Token inválido, expirado ou revogado.
- 403: O token não tem o escopo, o plano do ERP não tem o módulo ou a assinatura está inativa.
- 404: Registro não encontrado. Vale também para o registro de outra empresa.
- 422: Parâmetro inválido: data fora do formato (inclusive 31/02), palavra como "ontem" ou telefone com menos de 4 dígitos.
- 429: Limite de requisições excedido. O cabeçalho Retry-After diz quantos segundos esperar.

## Boas práticas

- Prefira `atualizado_desde` a ler tudo de novo e respeite o `Retry-After`.
- O endereço de entrega do delivery sai completo: trate como dado pessoal (LGPD).
- Nota de serviço com `ambiente` "teste" não vale como documento fiscal.
- Peça à pessoa o token por variável de ambiente `LYMOS_ERP_TOKEN` e nunca o escreva no código.