{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Library API",
    "version": "1.0.0",
    "summary": "Compra de livros por agentes autônomos, do catálogo ao recibo.",
    "description": "API REST da Agent Library. A leitura de catálogo é pública. Criar carrinho, mandato, pedido e pagamento exige um token OAuth 2.1 com o escopo correspondente. Nenhuma cobrança acontece sem um mandato de pagamento válido, que declara escopo, limite de valor, prazo de validade e caminho de revogação.",
    "contact": {
      "name": "Agent Library",
      "email": "contato@agentlibrary.ori.lat",
      "url": "https://agentlibrary.ori.lat/contato"
    },
    "license": {
      "name": "Uso permitido para pesquisa",
      "url": "https://agentlibrary.ori.lat/politicas/termos"
    }
  },
  "servers": [
    {
      "url": "https://agentlibrary.ori.lat/api/v1",
      "description": "Produção do piloto"
    }
  ],
  "externalDocs": {
    "description": "Guia do fluxo de compra",
    "url": "https://agentlibrary.ori.lat/docs"
  },
  "tags": [
    {
      "name": "catalog",
      "description": "Catálogo, busca e disponibilidade. Público."
    },
    {
      "name": "shipping",
      "description": "Cotação de frete. Público."
    },
    {
      "name": "cart",
      "description": "Carrinhos."
    },
    {
      "name": "mandate",
      "description": "Mandatos de pagamento."
    },
    {
      "name": "order",
      "description": "Pedidos, recibo, rastreio e cancelamento."
    },
    {
      "name": "observability",
      "description": "Tráfego de agentes e evidência de execução."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "observability"
        ],
        "operationId": "getHealth",
        "summary": "Verificação de disponibilidade",
        "security": [],
        "responses": {
          "200": {
            "description": "Serviço disponível.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "examples": [
                        "ok"
                      ]
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/books": {
      "get": {
        "tags": [
          "catalog"
        ],
        "operationId": "listBooks",
        "summary": "Listar ou buscar livros",
        "description": "Sem parâmetros, devolve o catálogo completo. Com q, busca por título, subtítulo, autoria, editora e tema, ignorando acentos e maiúsculas.",
        "security": [],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Termo de busca.",
            "example": "liber null"
          },
          {
            "name": "theme",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Slug do tema.",
            "example": "ocultismo-e-magia"
          },
          {
            "name": "available",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Quando true, devolve apenas títulos em estoque."
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de livros.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "items"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Book"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/books/{sku}": {
      "get": {
        "tags": [
          "catalog"
        ],
        "operationId": "getBook",
        "summary": "Ler um livro por SKU ou ISBN-13",
        "security": [],
        "parameters": [
          {
            "name": "sku",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "SKU do catálogo ou ISBN-13 com 13 dígitos.",
            "example": "AGL-OCU-001"
          }
        ],
        "responses": {
          "200": {
            "description": "O livro.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Book"
                }
              }
            }
          },
          "404": {
            "description": "Nenhum livro com esse identificador.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/shipping/quote": {
      "get": {
        "tags": [
          "shipping"
        ],
        "operationId": "quoteShipping",
        "summary": "Cotar as modalidades de entrega",
        "description": "Devolve as quatro modalidades ordenadas da mais rápida para a mais lenta, com preço, prazo em dias úteis e o total já somado ao valor dos itens. Informe budget para receber também qual é a opção mais rápida que cabe no orçamento.",
        "security": [],
        "parameters": [
          {
            "name": "sku",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "SKU para calcular o total. Pode repetir para múltiplos itens."
          },
          {
            "name": "cartId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Alternativa ao sku: cota sobre o conteúdo de um carrinho."
          },
          {
            "name": "budget",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Orçamento total em centavos, incluindo o frete.",
            "example": 10000
          }
        ],
        "responses": {
          "200": {
            "description": "Cotação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShippingQuote"
                }
              }
            }
          },
          "404": {
            "description": "SKU ou carrinho não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/carts": {
      "post": {
        "tags": [
          "cart"
        ],
        "operationId": "createCart",
        "summary": "Criar um carrinho",
        "security": [
          {
            "oauth2": [
              "cart:write"
            ]
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "sku"
                      ],
                      "properties": {
                        "sku": {
                          "type": "string"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 10,
                          "default": 1
                        }
                      }
                    }
                  },
                  "shippingCode": {
                    "type": "string",
                    "enum": [
                      "economico",
                      "padrao",
                      "rapido",
                      "expresso"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Carrinho criado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cart"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente ou inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Item inválido, sem estoque ou modalidade desconhecida.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/carts/{id}": {
      "get": {
        "tags": [
          "cart"
        ],
        "operationId": "getCart",
        "summary": "Ler um carrinho",
        "security": [
          {
            "oauth2": [
              "cart:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "O carrinho.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cart"
                }
              }
            }
          },
          "404": {
            "description": "Carrinho não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "cart"
        ],
        "operationId": "updateCart",
        "summary": "Alterar itens ou modalidade de entrega",
        "security": [
          {
            "oauth2": [
              "cart:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "sku",
                        "quantity"
                      ],
                      "properties": {
                        "sku": {
                          "type": "string"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 10,
                          "description": "Zero remove o item."
                        }
                      }
                    }
                  },
                  "shippingCode": {
                    "type": "string",
                    "enum": [
                      "economico",
                      "padrao",
                      "rapido",
                      "expresso"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Carrinho atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cart"
                }
              }
            }
          },
          "404": {
            "description": "Carrinho não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Alteração inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/mandates": {
      "post": {
        "tags": [
          "mandate"
        ],
        "operationId": "createMandate",
        "summary": "Criar um mandato de pagamento",
        "description": "O mandato é a autorização de gasto. Declara escopo, limite máximo em centavos, janela de validade e o caminho de revogação. Sem um mandato válido nenhuma cobrança é possível.",
        "security": [
          {
            "oauth2": [
              "mandate:create"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "limit"
                ],
                "properties": {
                  "scope": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "default": [
                      "order:write",
                      "payment:execute"
                    ]
                  },
                  "limit": {
                    "type": "object",
                    "required": [
                      "amount",
                      "currency"
                    ],
                    "properties": {
                      "amount": {
                        "type": "integer",
                        "description": "Valor em centavos.",
                        "examples": [
                          6800
                        ]
                      },
                      "currency": {
                        "type": "string",
                        "examples": [
                          "BRL"
                        ]
                      }
                    }
                  },
                  "durationMinutes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10080,
                    "default": 60
                  }
                }
              },
              "example": {
                "scope": [
                  "order:write",
                  "payment:execute"
                ],
                "limit": {
                  "amount": 10000,
                  "currency": "BRL"
                },
                "durationMinutes": 60
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mandato criado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mandate"
                }
              }
            }
          },
          "401": {
            "description": "Token ausente ou inválido.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Limite, moeda ou validade inválidos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "mandate"
        ],
        "operationId": "listMandates",
        "summary": "Listar os mandatos do titular",
        "security": [
          {
            "oauth2": [
              "mandate:create"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Mandatos do titular.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Mandate"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/mandates/{id}": {
      "get": {
        "tags": [
          "mandate"
        ],
        "operationId": "getMandate",
        "summary": "Ler um mandato",
        "security": [
          {
            "oauth2": [
              "mandate:create"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "O mandato.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mandate"
                }
              }
            }
          },
          "404": {
            "description": "Mandato não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "mandate"
        ],
        "operationId": "revokeMandate",
        "summary": "Revogar um mandato",
        "description": "Efeito imediato. Qualquer cobrança posterior é recusada com 409.",
        "security": [
          {
            "oauth2": [
              "mandate:create"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Mandato revogado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mandate"
                }
              }
            }
          },
          "403": {
            "description": "O mandato pertence a outro titular.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Mandato não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders": {
      "post": {
        "tags": [
          "order"
        ],
        "operationId": "placeOrder",
        "summary": "Executar a compra",
        "description": "Valida o carrinho, autoriza contra o mandato, cobra no processador de teste e registra o pedido. A autorização acontece antes da cobrança: um valor acima do limite é recusado sem que o processador seja acionado.",
        "security": [
          {
            "oauth2": [
              "order:write",
              "payment:execute"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "cartId",
                  "payment"
                ],
                "properties": {
                  "cartId": {
                    "type": "string"
                  },
                  "mandateId": {
                    "type": "string"
                  },
                  "buyer": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string",
                        "format": "email"
                      }
                    }
                  },
                  "shipTo": {
                    "type": "object",
                    "properties": {
                      "postalCode": {
                        "type": "string",
                        "examples": [
                          "01310-100"
                        ]
                      }
                    }
                  },
                  "payment": {
                    "type": "object",
                    "required": [
                      "cardNumber",
                      "expiry",
                      "cvc"
                    ],
                    "properties": {
                      "cardNumber": {
                        "type": "string",
                        "examples": [
                          "4111111111111111"
                        ]
                      },
                      "expiry": {
                        "type": "string",
                        "examples": [
                          "12/30"
                        ]
                      },
                      "cvc": {
                        "type": "string",
                        "examples": [
                          "123"
                        ]
                      },
                      "holder": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pedido criado e pago.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "mandate": {
                      "$ref": "#/components/schemas/Mandate"
                    },
                    "evidenceUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Pagamento recusado ou com desafio pendente.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Escopo insuficiente ou mandato de outro titular.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Carrinho ou mandato não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Mandato revogado ou vencido, ou estoque insuficiente.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Carrinho vazio ou valor acima do limite do mandato (mandate_limit_exceeded).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "order"
        ],
        "operationId": "listOrders",
        "summary": "Listar os pedidos do titular",
        "security": [
          {
            "oauth2": [
              "receipt:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Pedidos do titular.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Order"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "tags": [
          "order"
        ],
        "operationId": "getOrder",
        "summary": "Ler um pedido",
        "security": [
          {
            "oauth2": [
              "receipt:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "O pedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "404": {
            "description": "Pedido não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}/receipt": {
      "get": {
        "tags": [
          "order"
        ],
        "operationId": "getReceipt",
        "summary": "Obter o recibo",
        "security": [
          {
            "oauth2": [
              "receipt:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recibo do pedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "404": {
            "description": "Pedido não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}/tracking": {
      "get": {
        "tags": [
          "order"
        ],
        "operationId": "getTracking",
        "summary": "Rastrear o pedido",
        "security": [
          {
            "oauth2": [
              "receipt:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Situação logística.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orderId": {
                      "type": "string"
                    },
                    "trackingCode": {
                      "type": "string"
                    },
                    "carrier": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "estimate": {
                      "type": "string"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "status": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Pedido não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}/cancel": {
      "post": {
        "tags": [
          "order"
        ],
        "operationId": "cancelOrder",
        "summary": "Cancelar o pedido",
        "description": "Cancela e estorna o valor ao mandato, liberando o limite consumido.",
        "security": [
          {
            "oauth2": [
              "order:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pedido cancelado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "403": {
            "description": "O pedido pertence a outro titular.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Pedido não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "O pedido não está em um estado cancelável.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/evidence/runs/{orderId}": {
      "get": {
        "tags": [
          "observability"
        ],
        "operationId": "getEvidence",
        "summary": "Envelope de evidência de uma execução",
        "description": "Reúne mandato, pagamento, pedido e recibo em um único documento com hash do conteúdo, para auditoria externa do que de fato aconteceu.",
        "security": [
          {
            "oauth2": [
              "receipt:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Envelope de evidência.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Evidence"
                }
              }
            }
          },
          "404": {
            "description": "Pedido não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "message"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Código estável do erro."
                    },
                    "message": {
                      "type": "string",
                      "description": "Descrição legível, em português."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/observability/agent-traffic": {
      "get": {
        "tags": [
          "observability"
        ],
        "operationId": "getAgentTraffic",
        "summary": "Tráfego agregado de agentes",
        "description": "Registro público e agregado de quais agentes acessam o site e o que leem. Sem IP bruto e sem qualquer dado pessoal.",
        "security": [],
        "responses": {
          "200": {
            "description": "Agregados de tráfego.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "agents": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "paths": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "aiBotPaths": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "days": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1, authorization code com PKCE obrigatório. Detalhes em /auth.md.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://agentlibrary.ori.lat/oauth/authorize",
            "tokenUrl": "https://agentlibrary.ori.lat/oauth/token",
            "refreshUrl": "https://agentlibrary.ori.lat/oauth/token",
            "scopes": {
              "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."
            }
          }
        }
      }
    },
    "schemas": {
      "Money": {
        "type": "object",
        "required": [
          "amount",
          "currency"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "description": "Valor em centavos.",
            "examples": [
              6800
            ]
          },
          "currency": {
            "type": "string",
            "examples": [
              "BRL"
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Código estável do erro."
          },
          "message": {
            "type": "string",
            "description": "Descrição legível, em português."
          }
        }
      },
      "Book": {
        "type": "object",
        "required": [
          "sku",
          "isbn13",
          "title",
          "price",
          "availability"
        ],
        "properties": {
          "sku": {
            "type": "string",
            "examples": [
              "AGL-OCU-001"
            ]
          },
          "isbn13": {
            "type": "string",
            "examples": [
              "9788590010012"
            ]
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "publisher": {
            "type": "string"
          },
          "year": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          },
          "language": {
            "type": "string"
          },
          "themes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "price": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "listPrice": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "availability": {
            "type": "string",
            "enum": [
              "InStock",
              "OutOfStock",
              "PreOrder"
            ]
          },
          "stock": {
            "type": "integer"
          },
          "summary": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ShippingOption": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "economico",
              "padrao",
              "rapido",
              "expresso"
            ]
          },
          "name": {
            "type": "string"
          },
          "price": {
            "type": "integer",
            "description": "Frete em centavos."
          },
          "minDeliveryDays": {
            "type": "integer"
          },
          "maxDeliveryDays": {
            "type": "integer"
          },
          "deliveryEstimate": {
            "type": "string"
          },
          "total": {
            "type": "integer",
            "description": "Itens mais frete, em centavos."
          },
          "withinBudget": {
            "type": "boolean"
          }
        }
      },
      "ShippingQuote": {
        "type": "object",
        "properties": {
          "itemsTotal": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "currency": {
            "type": "string"
          },
          "budget": {
            "type": "integer",
            "nullable": true
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShippingOption"
            }
          },
          "fastestWithinBudget": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ShippingOption"
              },
              {
                "type": "null"
              }
            ],
            "description": "A modalidade mais rápida cujo total cabe no orçamento informado. Null quando nenhuma cabe ou quando budget não foi informado."
          }
        }
      },
      "Cart": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "shipping": {
            "$ref": "#/components/schemas/ShippingOption"
          },
          "itemsTotal": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "shippingTotal": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "grandTotal": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          }
        }
      },
      "Mandate": {
        "type": "object",
        "required": [
          "id",
          "scope",
          "limit",
          "duration",
          "revocation",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "mnd_8Kd2..."
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "authorized",
              "consumed",
              "revoked",
              "expired"
            ]
          },
          "scope": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limit": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "consumed": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "remaining": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "duration": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "until": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "revocation": {
            "type": "object",
            "properties": {
              "method": {
                "type": "string",
                "examples": [
                  "DELETE"
                ]
              },
              "href": {
                "type": "string"
              }
            }
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "paid",
              "cancelled",
              "failed"
            ]
          },
          "mandateId": {
            "type": "string",
            "nullable": true
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "itemsTotal": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "shipping": {
            "type": "object"
          },
          "grandTotal": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "trackingCode": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Receipt": {
        "type": "object",
        "properties": {
          "receiptId": {
            "type": "string"
          },
          "orderId": {
            "type": "string"
          },
          "issuedAt": {
            "type": "string",
            "format": "date-time"
          },
          "issuer": {
            "type": "object"
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "total": {
            "type": "object",
            "required": [
              "amount",
              "currency"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Valor em centavos.",
                "examples": [
                  6800
                ]
              },
              "currency": {
                "type": "string",
                "examples": [
                  "BRL"
                ]
              }
            }
          },
          "payment": {
            "type": "object"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "Evidence": {
        "type": "object",
        "properties": {
          "runId": {
            "type": "string"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "hash": {
            "type": "string",
            "description": "SHA-256 do payload canonicalizado."
          },
          "mandate": {
            "$ref": "#/components/schemas/Mandate"
          },
          "order": {
            "$ref": "#/components/schemas/Order"
          },
          "payment": {
            "type": "object"
          },
          "receipt": {
            "$ref": "#/components/schemas/Receipt"
          }
        }
      }
    }
  }
}