Documentação da API

Toda a operação da Agent Library está disponível como API REST versionada sob /api/v1. A leitura de catálogo é pública e não exige autenticação. Criar pedido, mandato e pagamento exige um token OAuth com o escopo correspondente. A especificação completa está em /openapi.json.

Descoberta

Um agente que chega neste domínio pela primeira vez pode se orientar por quatro arquivos:

/llms.txt, índice em texto de todos os recursos legíveis por máquina
/openapi.json, especificação OpenAPI 3.1 de todos os endpoints
/.well-known/agent-layer.json, perfil da organização e capacidades declaradas
/auth.md, escopos de autorização e como obter um token

O fluxo completo de compra

A sequência abaixo é o caminho suportado do início ao fim. Cada passo é uma chamada independente e o estado fica no servidor.

1. Encontrar o livro

GET /api/v1/books?q=liber+null

200 OK
{
  "items": [
    {
      "sku": "AGL-OCU-001",
      "isbn13": "9788590010012",
      "title": "Liber Null & Psychonaut",
      "price": { "amount": 6800, "currency": "BRL" },
      "availability": "InStock",
      "stock": 42,
      "url": "https://agentlibrary.ori.lat/livros/liber-null-e-psychonaut"
    }
  ]
}

2. Cotar o frete

A cotação devolve as quatro modalidades com prazo, preço e o total já somado ao valor dos itens, para que a decisão sob restrição de orçamento não precise de aritmética do lado do cliente.

GET /api/v1/shipping/quote?sku=AGL-OCU-001

200 OK
{
  "itemsTotal": { "amount": 6800, "currency": "BRL" },
  "options": [
    { "code": "expresso",  "name": "Expresso",  "price": 3490,
      "maxDeliveryDays": 1,  "total": 10290 },
    { "code": "rapido",    "name": "Rápido",    "price": 2490,
      "maxDeliveryDays": 3,  "total": 9290 },
    { "code": "padrao",    "name": "Padrão",    "price": 1690,
      "maxDeliveryDays": 7,  "total": 8490 },
    { "code": "economico", "name": "Econômico", "price": 990,
      "maxDeliveryDays": 13, "total": 7790 }
  ]
}

3. Autenticar com escopo

A Agent Library implementa OAuth 2.1 com authorization code e PKCE. Os metadados estão em /.well-known/oauth-authorization-server. Os escopos disponíveis são:

Escopos de autorização
Escopo	Permite
catalog:read	Ler catálogo, preços, estoque e prazos de entrega.
cart:write	Criar e alterar carrinhos.
order:write	Criar pedidos a partir de um carrinho.
mandate:create	Criar mandatos de pagamento com limite de valor e prazo de validade.
payment:execute	Executar cobrança dentro do limite de um mandato válido.
receipt:read	Ler recibos, rastreio e histórico de pedidos.

Para o piloto há um cliente de teste pré-registrado, com identificador agentlibrary-pilot-client e redirecionamento para http://127.0.0.1:8765/callback. O segredo está no README do repositório.

4. Criar o carrinho

POST /api/v1/carts
Authorization: Bearer <token com escopo cart:write>
Content-Type: application/json

{ "items": [ { "sku": "AGL-OCU-001", "quantity": 1 } ],
  "shippingCode": "rapido" }

5. Criar o mandato de pagamento

O mandato é a autorização de gasto. Ele declara quatro coisas: o escopo do que pode ser feito, o limite máximo de valor, a janela de validade e o caminho de revogação. Nenhuma cobrança acontece sem um mandato válido, e uma cobrança acima do limite é recusada.

POST /api/v1/mandates
Authorization: Bearer <token com escopo mandate:create>
Content-Type: application/json

{ "scope": ["order:write", "payment:execute"],
  "limit": { "amount": 10000, "currency": "BRL" },
  "durationMinutes": 60 }

201 Created
{
  "id": "mnd_...",
  "status": "created",
  "scope": ["order:write", "payment:execute"],
  "limit": { "amount": 10000, "currency": "BRL" },
  "consumed": { "amount": 0, "currency": "BRL" },
  "duration": { "from": "...", "until": "..." },
  "revocation": { "method": "DELETE", "href": "/api/v1/mandates/mnd_..." }
}

6. Executar a compra

POST /api/v1/orders
Authorization: Bearer <token com escopo order:write>
Content-Type: application/json

{ "cartId": "crt_...",
  "mandateId": "mnd_...",
  "buyer": { "name": "...", "email": "..." },
  "shipTo": { "postalCode": "01310-100" },
  "payment": { "cardNumber": "4111111111111111",
               "expiry": "12/30", "cvc": "123" } }

Se o total ultrapassar o limite do mandato, a resposta é 422 com o código mandate_limit_exceeded. Se o mandato estiver revogado ou vencido, a resposta é 409. Nos dois casos nenhuma cobrança é feita.

7. Confirmação, recibo e rastreio

GET /api/v1/orders/{id}
GET /api/v1/orders/{id}/receipt
GET /api/v1/orders/{id}/tracking
POST /api/v1/orders/{id}/cancel

Cartões de teste

O processador é um sandbox interno e determinístico. O resultado depende do número informado, o que permite testar os três desfechos sem depender de sorte.

Cartões do ambiente de teste
Número	Resultado
4111 1111 1111 1111	Aprovado
4000 0000 0000 0002	Recusado pelo emissor
4000 0000 0000 3220	Exige desafio adicional

Evidência de execução

Cada compra concluída gera um envelope de evidência, disponível em /api/v1/evidence/runs/{orderId}, reunindo mandato, pagamento, pedido e recibo com um hash do conteúdo. Ele existe para que uma auditoria externa possa verificar o que aconteceu sem depender do que dizemos ter acontecido.

Limites e boas maneiras

Não há limite de taxa aplicado no piloto. Pedimos que agentes se identifiquem com um user-agent descritivo, porque o registro de tráfego é o objeto de pesquisa deste site. O domínio canônico é agentlibrary.ori.lat e todas as respostas são servidas por HTTPS.