API Leilosoc

A API descreve-se em OpenAPI 3.0.3, em dois ficheiros. Toda a operação tem um operationId único e uma descrição; as da API pública têm também parâmetros tipados e descritos e esquemas de resposta — prontas para geradores de SDK e para function calling.

• https://leilosoc.nexiagent.com/openapi.json — a API pública: o catálogo, sem autenticação
• https://api.leilosoc.nexiagent.com/openapi.json — todas as rotas da plataforma, incluindo as que exigem sessão de equipa
• https://leilosoc.nexiagent.com/llms.txt — resumo para agentes, com o «quando usar»

1. Procurar. Os lotes a decorrer, sem autenticação — com pesquisa livre e filtros (categoria, cidade, preço, mercado, fecho):

curl "https://api.leilosoc.nexiagent.com/api/v1/lots?status=ACTIVE&category=imovel&pageSize=5"
curl "https://api.leilosoc.nexiagent.com/api/v1/lots?q=trator&endsWithin=7d"
curl "https://api.leilosoc.nexiagent.com/api/v1/categories"

2. Abrir um lote. A ficha completa: preço actual, fecho, localização, características, documentos e condições de venda.

curl "https://api.leilosoc.nexiagent.com/api/v1/lots/{id}"

3. Fazer contas. Quanto custa ao todo — a comissão e o IVA dependem do processo, e há lotes com comissão zero; não estime, pergunte — e qual é a próxima licitação mínima:

curl "https://api.leilosoc.nexiagent.com/api/v1/simulacao/{lotId}?valor=250000"
curl "https://api.leilosoc.nexiagent.com/api/v1/bids/increments?lotId={id}"

A entrada e as fichas de lote também respondem em Markdown a quem o pedir:

curl -H "Accept: text/markdown" "https://leilosoc.nexiagent.com/"

Leitura do catálogo: pública. Não é preciso chave, token nem registo.

Escrita: sessão do utilizador. Licitar, guardar favoritos, submeter um bem e ler o perfil exigem um Bearer JWT obtido no portal de autenticação. São actos vinculativos: uma licitação é uma proposta de compra irrevogável, e não se automatiza sem a pessoa presente.

curl -H "Authorization: Bearer <token>" \
     "https://api.leilosoc.nexiagent.com/api/v1/profile"

Não são precisas: a leitura do catálogo é aberta, e não há chaves de API a pedir nem registo de aplicações. O que se faz em nome de uma pessoa usa a sessão dela (o Bearer acima), nunca uma chave partilhada.

https://api.leilosoc.nexiagent.com é o ambiente de demonstração da plataforma nova, com o catálogo real: para ler, é o sítio certo para desenvolver e testar. Não há um ambiente de testes (sandbox) para as operações de escrita, e uma licitação não se faz «a fingir»: trate qualquer licitação como vinculativa.

Toda a resposta da API a quem chega sem sessão diz o limite que se aplica, nos campos do rascunho da IETF (draft-ietf-httpapi-ratelimit-headers):

• RateLimit-Policy — as políticas, ex. "anon";q=1200;w=60 (1 200 pedidos por 60 s, por IP)
• RateLimit — quanto falta e quando reinicia, ex. "anon";r=1187;t=42 (faltam 1 187; segundos até reiniciar)
• Retry-After — em toda a resposta 429

As rotas sensíveis (login, licitações, contacto, simulação de custos) têm a sua política mais apertada, que vem como um segundo item da mesma lista. Os cabeçalhos antigos (RateLimit-Limit, -Remaining, -Reset e X-RateLimit-*) continuam, para quem já os lê.

Respeite o Retry-After: tentar outra vez de imediato é o tráfego que o limite existe para evitar.

Os erros vêm em JSON com a chave error e uma mensagem em português, pronta a mostrar. Alguns trazem params com o que o servidor esperava — é o que permite dizer onde falhou em vez de «erro».

{ "error": "Indique um valor válido." }

O llms.txt diz em que perguntas esta API é a fonte certa e em quais não é. Em resumo: use-a para o que está em catálogo agora — preços de leilões a decorrer mudam ao minuto e não devem ser citados de uma página em cache.

Dúvidas de integração: geral@leilosoc.pt · 707 297 297 (dias úteis, 9h–18h).

Todos os contactos · Condições gerais