{ "openapi": "3.1.0", "info": { "title": "Tarevo Public Partner API", "version": "1.0.0", "description": "API p\u00fablica do Tarevo para parceiros integradores.\nPermite acesso a dados de lojas, pedidos, clientes e cat\u00e1logo\nmediante autoriza\u00e7\u00e3o OAuth2.\n", "contact": { "name": "Tarevo Developer Support", "email": "dev@tarevo.com.br", "url": "https://developer.tarevo.com.br" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.tarevo.com.br", "description": "Production" }, { "url": "https://sandbox.api.tarevo.com.br", "description": "Sandbox" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "OAuth2 token management" }, { "name": "Store", "description": "Establishment/merchant data" }, { "name": "Orders", "description": "Order management" }, { "name": "Customers", "description": "Customer data" }, { "name": "Catalog", "description": "Menu categories and products" }, { "name": "Webhooks", "description": "Webhook endpoint management" }, { "name": "Sandbox", "description": "Sandbox environment management" } ], "paths": { "/partner/auth/token": { "post": { "tags": [ "Authentication" ], "summary": "Generate access token", "description": "OAuth2 Client Credentials flow", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" }, "example": { "grant_type": "client_credentials", "client_id": "tarevo_test_abc123", "client_secret": "tsk_abc123def456" } } } }, "responses": { "200": { "description": "Access token generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "operationId": "createToken" } }, "/public/v1/store": { "get": { "tags": [ "Store" ], "summary": "Get store information", "description": "Returns the authorized store's public information", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Store data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "BearerAuth": [ "merchant:read" ] } ], "operationId": "getStore" } }, "/public/v1/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "description": "Returns paginated list of orders for the authorized store", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated order list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrders" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "BearerAuth": [ "orders:read" ] } ], "operationId": "listOrders" } }, "/public/v1/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get order details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "BearerAuth": [ "orders:read" ] } ], "operationId": "getOrderById" } }, "/public/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/RequestId" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated customer list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCustomers" } } } } }, "security": [ { "BearerAuth": [ "customers:read" ] } ], "operationId": "listCustomers" } }, "/public/v1/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Customer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "BearerAuth": [ "customers:read" ] } ], "operationId": "getCustomerById" } }, "/public/v1/catalog/categories": { "get": { "tags": [ "Catalog" ], "summary": "List categories", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Category list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } } }, "security": [ { "BearerAuth": [ "catalog:read" ] } ], "operationId": "listCategories" } }, "/public/v1/catalog/products": { "get": { "tags": [ "Catalog" ], "summary": "List products", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Paginated product list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProducts" } } } } }, "security": [ { "BearerAuth": [ "catalog:read" ] } ], "operationId": "listProducts" } }, "/public/v1/catalog/products/{id}": { "get": { "tags": [ "Catalog" ], "summary": "Get product details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "Product details with variations and additionals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "BearerAuth": [ "catalog:read" ] } ], "operationId": "getProductById" } }, "/public/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "responses": { "200": { "description": "Webhook endpoint list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "security": [ { "BearerAuth": [ "webhooks:manage" ] } ], "operationId": "listWebhookEndpoints" }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpoint" } } } }, "responses": { "201": { "description": "Webhook endpoint created (secret shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } } } }, "security": [ { "BearerAuth": [ "webhooks:manage" ] } ], "operationId": "createWebhookEndpoint" } }, "/public/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook endpoint details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook endpoint details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } }, "security": [ { "BearerAuth": [ "webhooks:manage" ] } ], "operationId": "getWebhookEndpointById" }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Endpoint deleted" } }, "security": [ { "BearerAuth": [ "webhooks:manage" ] } ], "operationId": "deleteWebhookEndpoint" } }, "/public/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send test event to webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Test event sent" } }, "security": [ { "BearerAuth": [ "webhooks:manage" ] } ], "operationId": "testWebhookEndpoint" } }, "/public/v1/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "responses": { "200": { "description": "Recent deliveries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } }, "security": [ { "BearerAuth": [ "webhooks:manage" ] } ], "operationId": "listWebhookDeliveries" } }, "/public/v1/webhooks/deliveries/{deliveryId}/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Replay a webhook delivery", "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delivery replayed" } }, "security": [ { "BearerAuth": [ "webhooks:manage" ] } ], "operationId": "replayWebhookDelivery" } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Partner API access token from /partner/auth/token" } }, "parameters": { "Cursor": { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, "RequestId": { "name": "X-Request-Id", "in": "header", "description": "Unique request ID for tracing", "schema": { "type": "string", "format": "uuid" } } }, "responses": { "Unauthorized": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "example": { "type": "https://api.tarevo.com.br/errors/INVALID_TOKEN", "title": "Invalid Token", "status": 401, "detail": "Invalid or expired token", "code": "INVALID_TOKEN" } } } }, "Forbidden": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" }, "example": { "type": "https://api.tarevo.com.br/errors/INSUFFICIENT_SCOPE", "title": "Insufficient Scope", "status": 403, "detail": "Required scope orders:read not granted", "code": "INSUFFICIENT_SCOPE" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } } }, "schemas": { "TokenRequest": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } } }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "bearer" ] }, "expires_in": { "type": "integer", "example": 3600 }, "scope": { "type": "string" } } }, "Store": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayId": { "type": "string" }, "status": { "type": "string" }, "totalAmount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object" } }, "customer": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } } } }, "PaginatedOrders": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "PaginatedCustomers": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Category": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "position": { "type": "integer" } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "price": { "type": "number" }, "image": { "type": "string", "nullable": true }, "categoryId": { "type": "string" }, "isActive": { "type": "boolean" } } }, "PaginatedProducts": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Pagination": { "type": "object", "properties": { "cursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "FAILED" ] }, "secretPrefix": { "type": "string" }, "lastSuccessAt": { "type": "string", "format": "date-time", "nullable": true }, "failureCount": { "type": "integer" } } }, "WebhookEndpointCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "description": "HMAC signing secret. Store securely \u2014 shown only once." }, "secretPrefix": { "type": "string" }, "message": { "type": "string" } } }, "CreateWebhookEndpoint": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.created", "order.confirmed", "order.preparing", "order.ready", "order.dispatched", "order.delivered", "order.cancelled", "order.completed", "customer.created", "customer.updated", "catalog.updated", "store.updated" ] } } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "DELIVERED", "FAILED", "DEAD_LETTER" ] }, "httpStatus": { "type": "integer", "nullable": true }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": "string", "format": "date-time", "nullable": true }, "nextAttemptAt": { "type": "string", "format": "date-time", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "requestDurationMs": { "type": "integer", "nullable": true } } }, "ProblemDetail": { "type": "object", "description": "RFC 9457 Problem Details", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object" } } } } } } }