Para agentes de IA
llms.txt, llms-full.txt, Markdown por página, especificação OpenAPI e um prompt pronto para começar.
Este portal foi construído para ser lido por pessoas e por agentes de programação. Tudo o que está nas páginas existe também em texto puro, em URLs estáveis, sem HTML no meio. Se você usa Claude Code, Cursor, Codex, ChatGPT ou qualquer agente que consiga buscar uma URL, aponte para os arquivos abaixo e peça a integração.
Arquivos para máquinas
| Arquivo | URL | Uso |
|---|---|---|
Índice llms.txt | https://developer.meupedido.io/llms.txt | Lista todas as páginas com título, URL e descrição. Ponto de partida: o agente decide o que ler. |
Conteúdo completo llms-full.txt | https://developer.meupedido.io/llms-full.txt | Toda a documentação em um único arquivo Markdown. Para contextos grandes ou indexação. |
| Markdown por página | https://developer.meupedido.io/pt-BR/docs/<página>.md | Qualquer página de documentação, acrescentando .md à URL. Ex.: /pt-BR/docs/getting-started/authentication.md. |
| Especificação OpenAPI (YAML) | https://developer.meupedido.io/openapi/open-delivery-v1.yaml | Contrato completo: rotas, parâmetros, esquemas, respostas e erros. Para gerar clientes e validar código. |
| Especificação OpenAPI (JSON) | https://developer.meupedido.io/openapi/open-delivery-v1.json | O mesmo contrato em JSON. |
| Coleção Postman | https://developer.meupedido.io/collections/meupedido-open-delivery.postman.json | Todas as operações prontas para executar, com variáveis para credenciais e ids. |
No topo de cada página de documentação há três ações: Copiar Markdown, que copia a página em texto puro; Abrir no ChatGPT e Abrir no Claude, que abrem o assistente já com a página carregada como contexto.
O que dizer ao agente
A integração mínima tem quatro partes: obter o token, consultar eventos, confirmar os eventos lidos e confirmar o pedido. O prompt abaixo cobre isso e já carrega as regras que mais causam erro em integrações novas (deduplicação, ack obrigatório, datas em UTC, Retry-After). Copie, ajuste a linguagem e o nome da loja de teste, e cole no seu agente.
Você vai implementar uma integração com a API Open Delivery do MeuPedido.
Fontes de verdade, nesta ordem. Leia antes de escrever qualquer código:
1. https://developer.meupedido.io/llms.txt (índice; abra as páginas de Autenticação, Polling, Ações e idempotência, Catálogo de eventos e Boas práticas)
2. https://developer.meupedido.io/openapi/open-delivery-v1.yaml (contrato das rotas e esquemas)
Contexto:
- URL base: https://api.meupedido.io/open-delivery
- Credenciais: client_id e client_secret vêm das variáveis de ambiente MEUPEDIDO_CLIENT_ID e MEUPEDIDO_CLIENT_SECRET. Nunca as escreva no código.
- Linguagem e stack: <sua linguagem, framework e versão>
Entregue um serviço que:
1. Obtém um token em POST /oauth/token com grant_type=client_credentials (form urlencoded), guarda expires_in e renova cerca de 60 s antes de expirar. Em 401 com {"error":"invalid_token"} para e registra que a credencial foi pausada ou revogada, sem tentar de novo.
2. Consulta GET /v1/events:polling?limit=200 em um intervalo fixo de 5 s. A resposta é um array (vazio quando não há eventos). A entrega é at-least-once: o mesmo eventId pode chegar mais de uma vez; deduplique por eventId antes de processar.
3. Para cada evento, busca o pedido em orderURL com o mesmo token (o envelope nunca traz o pedido). Ignora eventType desconhecido, registrando em log, mas confirma o evento mesmo assim.
4. Confirma os eventos processados em POST /v1/events/acknowledgment com corpo [{"id":"<eventId>"}, ...]. Sem essa confirmação o evento volta em toda consulta. Confirme só depois de persistir o que precisava.
5. Ao receber um evento CREATED, confirma o pedido com POST /v1/orders/{orderId}/confirm enviando o header Idempotency-Key com um UUID v4 por tentativa lógica. Trata 202 com status "accepted" e "already_applied" como sucesso, 422 invalid_transition como estado incompatível (não repetir) e 409 idempotency_key_reuse como bug de chave.
6. Trata 429 esperando o valor do header Retry-After antes da próxima chamada e usa backoff exponencial com jitter para 500 e erro de rede. Nunca repete 400, 403, 404, 409 ou 422.
7. Lê todas as datas como UTC (sufixo Z) e só converte para America/Sao_Paulo na exibição.
8. Marca em log os pedidos com "test": true, que vêm da loja de teste.
Regras de qualidade:
- Escreva testes para a deduplicação, para o ack só após persistência e para a renovação do token.
- Não invente campos, rotas ou status que não estejam na spec. Se algo não estiver documentado, pergunte antes.
- Não use travessão em textos e comentários.Dicas
- Dê a spec, não só as páginas. A OpenAPI é o contrato completo. Agentes que geram cliente a partir dela erram menos nomes de campo do que os que leem prosa.
- Peça testes contra a loja de teste. Pedidos feitos no cardápio digital de uma loja de teste chegam com
test: truee passam pelo fluxo completo. É a forma mais barata de validar o serviço antes de ligar em uma loja real. - Mantenha o segredo fora do prompt. Passe
client_ideclient_secretpor variável de ambiente. Um segredo colado em um chat fica no histórico. - Cole a página certa. Para uma dúvida pontual, use Abrir no Claude ou Abrir no ChatGPT na página relevante. É mais preciso do que o
llms-full.txt, que tem tudo.
Próximos passos
- Primeira integração em 10 minutos: o roteiro passo a passo que o prompt acima automatiza.
- Referência de API: downloads da especificação e da coleção Postman.
- Boas práticas: as regras que o prompt pede ao agente, explicadas.