Recursos de desenvolvimento do FarMapp
O FarMapp — plataforma angolana de farmácias próximas, stock e reservas de medicamentos — expõe todos os seus recursos de desenvolvimento em URLs fixos, prontos a consumir por developers e agentes de IA.
Base da API
Todos os recursos abaixo apontam para a API em produção:
https://farmaperto.onrender.com/apiDocumentação técnica
Spec OpenAPI 3.0 (JSON) — /openapi.json. Contrato completo da API FarMapp: 30 operações, 16 schemas, autenticação Bearer e todos os erros documentados.
Documentação de autenticação do FarMapp — /developers/auth. Como obter e usar os tokens Bearer (utilizador, farmácia e Google).
Documentação da API em texto — /api/llms.txt. Referência das rotas em Markdown simples, pensada para agentes de IA.
Integrações e ferramentas
| Recurso | URL previsível / comando | Para quê |
|---|---|---|
| Servidor MCP | npx farmapp-mcp |
Dá a agentes de IA (Claude Desktop, etc.) acesso a farmácias, stock, avaliações e reservas. |
| CLI oficial | npx farmapp-cli |
Linha de comandos para pesquisar farmácias e gerir reservas a partir de scripts. |
| Manifesto function-calling | /api/functions.json |
Capacidades da API no formato de chamada de funções para LLMs (sem $ref, draft-07). |
| api-catalog | /.well-known/api-catalog |
Descoberta automática da API (RFC 9727). |
Descoberta por agents (llms.txt)
llms.txt — /llms.txt (resumo). llms-full.txt — /llms-full.txt (texto integral). docs/llms.txt — documentação das páginas.
Autenticação
As rotas públicas (pesquisa de farmácias, detalhe, avaliações) funcionam sem token. Para reservas e perfil de farmácia usa um token Bearer; vê a documentação de autenticação.
Rate limiting (RFC 9652)
Todas as respostas de /api/* (exceto /api/health) incluem headers de rate-limit no formato draft-7:
RateLimit: limit=120, remaining=119, reset=300
RateLimit-Policy: 120;w=300Limites por IP em janela de 5 minutos: 120 pedidos sem autenticação, 300 autenticado. Endpoints de auth e de trajectória têm limites próprios mais baixos. No limite a API devolve 429 com header Retry-After (segundos) e corpo {"erro": true, "mensagem": "..."}.
Agents: lê RateLimit/RateLimit-Policy de cada resposta e, se remaining for baixo, pausa até reset. No 429, espera Retry-After segundos antes de repetir.
Versionamento e depreciação
O path /api é a versão 1 da API FarMapp. Todas as respostas incluem X-FarMapp-API-Version: 1.
- Mudanças incompatíveis evoluem num path novo (
/api/v2), mantendo a v1 a funcionar durante o período de depreciação. - Rotas em depreciação respondem com
Deprecation: trueeSunset: <data>(RFC 8594). - Período típico de aviso: 6 meses entre
DeprecationeSunset; a rota só é removida na data deSunset. - No OpenAPI (
/openapi.json),info.versioné a versão do documento, não da API — usa sempre o headerX-FarMapp-API-Version.
Testa sem código
Roda a API localmente com o CLI oficial:
npx farmapp-cli farmacias --search-type medicamento --search "amox" --table
npx farmapp-mcp # ou liga ao teu cliente MCP