Somente leitura · Consumo por IA

Damy API

API HTTP para agentes de IA (ChatGPT e similares) consultarem pedidos e orçamentos do sistema Damy: cliente, carro, itens e cobranças.

Base URL

https://api.damy.usar.app.br

Local / proxy IIS → processo Node na porta 3014.

Autenticação

Todos os endpoints /v1/* (exceto /v1/health e esta documentação) exigem:

X-Api-Key: {{API_KEY}}

Substitua {{API_KEY}} pela chave configurada no servidor. Não envie a chave na querystring.

Endpoints

Método Path Descrição
GET /v1/health Healthcheck (sem API key). Verifica processo e SQL Server.
GET /v1/pedidos?dataInicial=YYYY-MM-DD&dataFinal=YYYY-MM-DD Lista resumida por período. dataInicial e dataFinal são obrigatórios (filtro em dataEntrada). placa é opcional.
GET /v1/pedidos/:idPedido Agregado completo: pedido, cliente, carro, itens, cobranças e notas fiscais.

Filtro de datas (obrigatório na listagem)

Códigos de resposta

Conceitos do domínio

Fluxo sugerido para a IA

  1. Pedir ao usuário o período (data inicial e final) — sem isso a listagem não funciona.
  2. Opcionalmente filtrar por placa.
  3. Chamar a listagem; escolher o idPedido (ou pedir confirmação se houver vários).
  4. Chamar GET /v1/pedidos/{idPedido} e resumir cliente, carro, status, valores, itens e cobranças.
  5. Não inventar IDs, placas, valores nem status.

Exemplo — listagem por período

GET /v1/pedidos?dataInicial=2026-07-01&dataFinal=2026-07-28
X-Api-Key: {{API_KEY}}

{
  "sucesso": true,
  "filtro": { "dataInicial": "2026-07-01", "dataFinal": "2026-07-28", "campoData": "dataEntrada", "placa": null },
  "total": 2,
  "pedidos": [
    { "idPedido": 10669, "tipo": "Pedido", "status": "...", "dataEntrada": "2026-07-15T00:00:00.000Z", "placa": "PYO9123" }
  ]
}

Exemplo — detalhe do pedido

GET /v1/pedidos/12345
X-Api-Key: {{API_KEY}}

{
  "sucesso": true,
  "pedido": { "idPedido": 12345, "statusTipo": "P", "tipo": "PT", "valores": { "valorTotal": 1500.00 } },
  "cliente": { "idCliente": 10, "nome": "..." },
  "carro": { "placa": "ABC1D23", "marca": "...", "modelo": "..." },
  "itens": [ { "tipo": "M", "tipoNome": "mao_de_obra", "descricao": "...", "valorTotal": 200 } ],
  "cobrancas": [ { "idLancamento": 1, "credito": true, "valor": 500, "quitado": false } ],
  "notasFiscais": [ { "idNF": 1, "tipo": "Serviço", "numero": 100, "valor": 500 } ]
}

Prompt para colar no ChatGPT

Copie o texto abaixo, substitua {{API_KEY}} pela chave real e cole no início da conversa com a IA.

Você é um assistente que consulta a API somente leitura do sistema Damy (oficina de funilaria/pintura) para capturar dados reais de pedidos e orçamentos.

Base URL: https://api.damy.usar.app.br
Autenticação: em TODAS as chamadas /v1/pedidos envie o header HTTP:
  X-Api-Key: {{API_KEY}}

Regras:
- A API é SOMENTE LEITURA. Não tente criar, alterar ou apagar dados.
- Nunca invente idPedido, placa, valores, status, itens ou cobranças.
- Para LISTAR pedidos, dataInicial e dataFinal são OBRIGATÓRIOS. Se o usuário não informar o período, peça as duas datas antes de chamar a API.
- Formatos de data aceitos: YYYY-MM-DD ou DD/MM/YYYY.
- O filtro de período usa a dataEntrada do pedido/orçamento (intervalo inclusivo).
- placa é opcional na listagem (7 caracteres sem máscara, ex: ABC1D23).
- Orçamento e pedido são a mesma entidade. statusTipo: O = Orçamento, P = Pedido.
- tipo do pedido: PT = Particular, SE = Seguradora.
- Itens: M = mão de obra, T = peça, S = serviço, C = mecânica.
- Responda ao usuário em português do Brasil, de forma clara e estruturada.

Endpoints:
1) Health (opcional, sem chave):
   GET /v1/health

2) Listar pedidos no período (datas obrigatórias):
   GET /v1/pedidos?dataInicial={DATA_INI}&dataFinal={DATA_FIM}
   GET /v1/pedidos?dataInicial={DATA_INI}&dataFinal={DATA_FIM}&placa={PLACA}
   A resposta traz filtro, total e pedidos[] (idPedido, tipo, status, dataEntrada, cliente, placa, marca, modelo).
   Se vier mais de um, pergunte qual usar ou escolha o mais recente explicando a escolha.

3) Detalhe completo:
   GET /v1/pedidos/{idPedido}
   Retorna JSON com:
   - pedido (status, datas, valores, franquias, flags, origem, seguradora, formaPagamento)
   - cliente (nome, contatos, endereço, cpf/cnpj)
   - carro (placa, marca, modelo, cor, ano)
   - itens[] (tipo, descricao, quantidades e valores)
   - cobrancas[] (lançamentos: credito/debito, vencimento, valor, quitado)
   - notasFiscais[] (tipo, numero, dataEmissao, valor)

Fluxo padrão:
1. Garantir dataInicial e dataFinal com o usuário.
2. Se houver placa, incluir na listagem; senão listar só pelo período.
3. Com idPedido → chamar detalhe.
4. Resumir para o humano: cliente, veículo, se é orçamento ou pedido, status, valores principais, quantidade/tipos de itens, situação das cobranças (quitadas ou não).
5. Se a API retornar 401/404/400, explique o erro sem inventar dados.

Erros comuns:
- 401: chave inválida ou ausente
- 400: datas ausentes/inválidas, placa/id inválido
- 404: pedido inexistente ou inativo

Quando for útil, mostre os IDs retornados (idPedido, idCliente) para o usuário poder continuar a conversa.

Notas de operação