# TAREVO DEVELOPERS — CONTEXTO TÉCNICO COMPLETO PARA INTEGRAÇÃO > Documentação técnica oficial e autossuficiente da Tarevo Public Partner API V1. ## 1. Índice e Recursos Rápidos - [OpenAPI 3.1 Spec (JSON)](https://developers.tarevo.com.br/openapi.json): Especificação de todas as rotas, parâmetros, cabeçalhos e respostas. - [OpenAPI 3.1 Spec (YAML)](https://developers.tarevo.com.br/openapi.yaml): Versão YAML da especificação de contrato. - [Postman Collection](https://developers.tarevo.com.br/tarevo-partner-api-v1.postman_collection.json): Coleção de requisições prontas com autenticação automatizada. - [Contexto Consolidado (Full)](https://developers.tarevo.com.br/llms-full.txt): Documento unificado de documentação para LLMs de janela longa. --- ## 2. Pacote Canônico de Integração Global (Autossuficiente) # Tarevo Public Partner API V1 — Pacote Técnico Autossuficiente de Integração Versão da API: v1.0.0 Canônica | Snapshot: 2026-09-07 Público-alvo: Agentes de IA e Desenvolvedores de Software integrando sistemas externos (ERP, PDV, CRM, Logística) ao Tarevo. Princípio: Este documento é 100% autossuficiente e offline-ready. Todas as regras, URLs, payloads e contratos estão descritos abaixo. ## 1. Visão Geral da Plataforma, Ambientes & Tenants O Tarevo é uma plataforma SaaS multi-tenant para food service. Parceiros homologados integram seus sistemas para sincronizar pedidos, clientes, cardápio e notificações push em tempo real. - **Base URL Oficial (Produção):** `https://api.tarevo.com.br` - **Base URL (Sandbox):** `https://api.tarevo.com.br` - **Sandbox vs Produção:** Ambientes isolados por credenciais. O token JWT emitido indica o ambiente na claim `environment` (`"SANDBOX"` ou `"PRODUCTION"`). Sandbox não afeta restaurantes nem clientes reais. - **Partner & Application:** Uma Aplicação criada pelo Parceiro detém um par `client_id` e `client_secret`. - **Tenant Authorization & Grants:** A loja concede uma Autorização (Grant) para a aplicação. O identificador do restaurante (`tenant_id`, ex: `TL7K9A`) NUNCA é passado na URL; ele é derivado exclusivamente do token JWT assinado criptograficamente. ## 2. Autenticação & OAuth 2.0 (Client Credentials) Todas as rotas públicas (exceto emissão de token) exigem: `Authorization: Bearer ` ### Obtenção do Token de Acesso ```http POST /partner/auth/token HTTP/1.1 Host: api.tarevo.com.br Content-Type: application/json { "grant_type": "client_credentials", "client_id": "SEU_CLIENT_ID", "client_secret": "SEU_CLIENT_SECRET" } ``` Resposta de Sucesso (200 OK): ```json { "access_token": "eyJhbGciOiJIUzI1Ni...", "token_type": "Bearer", "expires_in": 3600, "scope": "orders:read orders:write catalog:read customers:read merchant:read webhooks:manage", "tenant_id": "TL7K9A", "environment": "SANDBOX" } ``` - O token dura 3600 segundos (1 hora). Implemente cache em memória renovando-o 5 minutos antes do vencimento. - **Segurança Default-Deny:** Tokens ausentes, expirados ou com escopo insuficiente retornam HTTP 401 ou 403. ## 3. Catálogo Canônico de Escopos (OAuth 2.0) - `orders:read` (Ver pedidos): Permite consultar lista e detalhes de pedidos, incluindo itens, valores e status. | Exemplo: GET /public/v1/orders, GET /public/v1/orders/{id} - `orders:write` (Criar e atualizar pedidos): Permite despachar pedidos, atualizar status operacional ou enviar pedidos autorizados. | Exemplo: POST /public/v1/orders, PATCH /public/v1/orders/{id}/status - `customers:read` (Ver clientes): Permite consultar perfis de clientes, histórico de contato e endereços de entrega. | Exemplo: GET /public/v1/customers, GET /public/v1/customers/{id} - `customers:write` (Criar e atualizar clientes): Permite criar e atualizar dados cadastrais de clientes da loja. | Exemplo: POST /public/v1/customers - `catalog:read` (Ver cardápio): Permite consultar categorias, itens, adicionais, preços e disponibilidade. | Exemplo: GET /public/v1/catalog/categories, GET /public/v1/catalog/products - `catalog:write` (Modificar cardápio): Permite alterar preços, descrições e pausar produtos esgotados. | Exemplo: PATCH /public/v1/catalog/products/{id}/status - `merchant:read` (Ver dados da loja): Permite consultar perfil, endereço, horário de funcionamento e configurações públicas. | Exemplo: GET /public/v1/store - `webhooks:manage` (Gerenciar webhooks): Permite cadastrar, testar, listar e remover endpoints de notificações em tempo real. | Exemplo: POST /public/v1/webhooks, GET /public/v1/webhooks/deliveries ## 4. Endpoints Principais da API V1 (OpenAPI 3.1) ### Loja (Merchant) - `GET /public/v1/store` (Escopo: `merchant:read`) - Retorna metadados do restaurante autorizado no token (ID, nome, slug, status, configurações públicas). ### Pedidos (Orders) - `GET /public/v1/orders` (Escopo: `orders:read`) - Parâmetros Query: `limit` (1..100, default 20), `cursor` (ID do último pedido), `status` (PENDING, CONFIRMED, READY, DISPATCHED, DELIVERED, CANCELLED), `updated_since` (ISO 8601). - Retorno: `{"data": [...], "pagination": {"hasMore": boolean, "nextCursor": string | null}}`. - `GET /public/v1/orders/{id}` (Escopo: `orders:read`) - Detalhes do pedido, itens, adicionais fracionados, endereço de entrega, cliente e pagamentos. - `PATCH /public/v1/orders/{id}/status` (Escopo: `orders:write`, Suporta `Idempotency-Key`) - Atualização do status operacional do pedido. - **Ciclo de Vida do Pedido:** `PENDING` → `CONFIRMED` → `PREPARING` → `READY` → `DISPATCHED` → `DELIVERED` (ou `CANCELLED`). ### Clientes (Customers) - `GET /public/v1/customers` (Escopo: `customers:read`) - `GET /public/v1/customers/{id}` (Escopo: `customers:read`) ### Cardápio (Catalog) - `GET /public/v1/catalog/categories` (Escopo: `catalog:read`) - `GET /public/v1/catalog/products` (Escopo: `catalog:read`) - `GET /public/v1/catalog/products/{id}` (Escopo: `catalog:read`) ### Gerenciamento de Webhooks - `POST /public/v1/webhooks` (Escopo: `webhooks:manage`, Suporta `Idempotency-Key`) - Body: `{"url": "https://seu-servidor.com/webhook", "events": ["order.created", "order.delivered"]}` - Retorna dados do endpoint cadastrado e o `secret` (exibido apenas uma vez) para conferência de assinatura. - `GET /public/v1/webhooks` (Escopo: `webhooks:manage`) - `DELETE /public/v1/webhooks/{id}` (Escopo: `webhooks:manage`) - `POST /public/v1/webhooks/{id}/test` (Escopo: `webhooks:manage`) - `GET /public/v1/webhooks/deliveries` (Escopo: `webhooks:manage`) - `POST /public/v1/webhooks/deliveries/{deliveryId}/replay` (Escopo: `webhooks:manage`) ## 5. Webhooks, Validação HMAC-SHA256 & Deduplicação - **Garantia de Entrega:** Transactional Outbox (at-least-once delivery). Mensagens duplicadas podem ocorrer em instabilidades de rede; deduplique mensagens usando o campo obrigatório `eventId`. - **Cabeçalho de Assinatura:** `X-Tarevo-Signature: t=,v1=` - **Algoritmo:** HMAC-SHA256 calculado sobre a string UTF-8 (timestamp + "." + rawBody) antes de qualquer middleware de parsing JSON. - **Validação de Tempo:** Verifique se o timestamp está dentro de uma janela de tolerância de 5 minutos (Math.abs(Date.now() / 1000 - timestamp) <= 300) para evitar replay attacks. - **Código Exemplo de Verificação (Node.js/TypeScript):** ```javascript const crypto = require('crypto'); function isValidTarevoSignature(rawBody: string, signatureHeader: string, webhookSecret: string): boolean { const parts = Object.fromEntries(signatureHeader.split(',').map(p => p.split('='))); const { t: timestamp, v1: signature } = parts; if (!timestamp || !signature) return false; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const hmac = crypto.createHmac('sha256', webhookSecret); const calculated = hmac.update(timestamp + '.' + rawBody).digest('hex'); if (calculated.length !== signature.length) return false; return crypto.timingSafeEqual(Buffer.from(calculated), Buffer.from(signature)); } ``` - **Política de Retentativas e DLQ:** Até 10 tentativas com backoff exponencial (1m, 2m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 16h) antes de mover o evento para a Dead Letter Queue (DLQ). - **Reconciliação:** Em caso de indisponibilidade prolongada, faça reconciliação periódica via `GET /public/v1/orders?updated_since=`. - **Eventos Oficiais:** - `order.created` (Escopo: `orders:read`): Disparado quando um novo pedido é registrado no estabelecimento. - `order.confirmed` (Escopo: `orders:read`): Disparado quando o restaurante confirma o pedido e envia para a cozinha. - `order.ready` (Escopo: `orders:read`): Disparado quando a cozinha finaliza o preparo do pedido. - `order.dispatched` (Escopo: `orders:read`): Disparado quando o pedido sai para entrega com o motoboy. - `order.delivered` (Escopo: `orders:read`): Disparado quando o cliente recebe o pedido e o ciclo é concluído. - `order.cancelled` (Escopo: `orders:read`): Disparado quando o pedido é cancelado pela loja ou pelo cliente. - `customer.created` (Escopo: `customers:read`): Disparado quando um novo cliente realiza seu primeiro pedido. - `catalog.updated` (Escopo: `catalog:read`): Disparado quando produtos, categorias ou preços sofrem alterações. - `webhook.test` (Escopo: `webhooks:manage`): Evento de verificação para validação de endpoint e cálculo de assinatura HMAC. ## 6. Confiabilidade: Idempotência & Rate Limiting ### Idempotência Em operações de mutação (POST / PUT / PATCH), envie o cabeçalho: `Idempotency-Key: ` - Se reenviado com o mesmo payload: retorna exatamente a resposta gravada sem reprocessamento. - Se reenviado com payload divergente: retorna HTTP 409 Conflict (`IDEMPOTENCY_CONFLICT`). Chaves retidas no Redis por 24 horas. ### Rate Limiting (Redis Sliding Window) - **SANDBOX:** 100 requisições / minuto por loja (tenant), 500 req/min global por aplicação. - **PRODUÇÃO:** 600 requisições / minuto por loja (tenant), 3.000 req/min global por aplicação. - **Headers HTTP 429:** `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. Em caso de 429, aguarde o tempo indicado em `Retry-After` aplicando backoff exponencial com jitter aleatório. ## 7. Catálogo Canônico de Erros (Padrão RFC 9457 Problem Details) Todas as respostas de erro possuem formato estruturado padronizado: ```json { "type": "https://developers.tarevo.com.br/errors/RATE_LIMIT_EXCEEDED", "title": "Too Many Requests", "status": 429, "detail": "O limite de chamadas por minuto foi excedido para este tenant.", "instance": "/public/v1/orders", "code": "RATE_LIMIT_EXCEEDED", "retryable": true, "traceId": "req_01J7K..." } ``` - HTTP 400 `INVALID_REQUEST` (Retryable: false): A requisição possui parâmetros inválidos, campos obrigatórios ausentes ou payload mal formatado. → Ação: Revise o corpo da requisição e os parâmetros enviados de acordo com a especificação OpenAPI. - HTTP 401 `UNAUTHORIZED` (Retryable: false): O token JWT de acesso está ausente, expirado, inválido ou a assinatura HMAC é incompatível. → Ação: Solicite um novo access_token chamando POST /partner/auth/token com suas credenciais. - HTTP 403 `FORBIDDEN` (Retryable: false): A credencial não possui o escopo necessário para esta rota, ou o grant com a loja foi revogado. → Ação: Verifique os escopos concedidos à aplicação ou solicite autorização do lojista no painel Tarevo. - HTTP 404 `NOT_FOUND` (Retryable: false): O recurso solicitado (pedido, cliente, produto) não existe ou pertence a outro tenant. → Ação: Confirme se o identificador pertence ao estabelecimento autorizado no token JWT. - HTTP 409 `IDEMPOTENCY_CONFLICT` (Retryable: false): Uma requisição anterior utilizou a mesma Idempotency-Key porém com parâmetros ou corpo divergente. → Ação: Gere um novo UUID para a Idempotency-Key caso deseje realizar uma nova mutação diferente. - HTTP 422 `UNPROCESSABLE_ENTITY` (Retryable: false): A requisição está sintaticamente correta, mas viola regras semânticas de negócio da loja. → Ação: Inspecione a lista de violações no objeto details retornado e corrija os dados informados. - HTTP 429 `RATE_LIMIT_EXCEEDED` (Retryable: true): O limite de chamadas por minuto para este tenant ou aplicação foi atingido. → Ação: Respeite o cabeçalho Retry-After retornado e implemente backoff exponencial antes de reenviar. - HTTP 500 `INTERNAL_SERVER_ERROR` (Retryable: true): Ocorreu uma falha inesperada nos servidores do Tarevo. → Ação: Aguarde alguns segundos e tente novamente com backoff exponencial. Informe o traceId ao suporte. - HTTP 503 `SERVICE_UNAVAILABLE` (Retryable: true): Serviço temporariamente sobrecarregado ou em janela de manutenção programada. → Ação: Implemente circuit breaker e aguarde o tempo indicado no Retry-After. ## 8. Ambiente Sandbox, Cenários de Teste & Homologação - **Provisionamento:** Endpoint `POST /public/v1/sandbox/seed` provisiona uma loja fake isolada com categorias, produtos e clientes de teste. - **Gerador de Pedidos em 7 Cenários (`POST /public/v1/sandbox/orders`):** 1. `delivery` (pedido de entrega com frete e endereço completo) 2. `pickup` (retirada no balcão) 3. `scheduled` (entrega futura agendada) 4. `cash` (pagamento na entrega em dinheiro com troco) 5. `online_payment` (pagamento digital aprovado) 6. `with_discount` (pedido com cupom de desconto aplicado) 7. `cancelled` (pedido cancelado pelo restaurante) Cada pedido gerado dispara os eventos de webhook cadastrados para validação do seu sistema receptor. - **Checklist de Homologação para Produção:** 1. Validação de assinatura HMAC com tempo constante e rejeição de timestamps expirados. 2. Deduplicação idempotente de eventos por `eventId`. 3. Tratamento de HTTP 429 respeitando `Retry-After` e jitter. 4. Uso de `Idempotency-Key` (UUID v4) em mutações. 5. Renovação de token JWT com cache local (validade de 3600s). 6. Execução com sucesso de testes nos 7 cenários de pedidos em Sandbox. ## 9. Notas de Segurança - Princípio Default-Deny em todos os recursos. - Credenciais (`client_secret` e webhook `secret`) têm exibição única (show-once) no Developer Console. - NUNCA comite credenciais ou segredos em repositórios de código. Use variáveis de ambiente. --- ### Fontes Canônicas Oficiais & Links Rápidos - Documentação Web: https://developers.tarevo.com.br - Contrato OpenAPI 3.1 (JSON): https://developers.tarevo.com.br/openapi.json - Contrato OpenAPI 3.1 (YAML): https://developers.tarevo.com.br/openapi.yaml - Índice Machine-Readable: https://developers.tarevo.com.br/llms.txt - Contexto Consolidado (Full): https://developers.tarevo.com.br/llms-full.txt - Servidor MCP: https://api.tarevo.com.br/api/mcp --- ## 3. Webhooks & Event-Driven Architecture (Contexto Especializado) # Tarevo Webhooks & Event-Driven Architecture — Contexto Técnico Especializado Snapshot Canônico: 2026-09-07 | Public API v1.0 Finalidade: Implementar um endpoint receptor de Webhooks resiliente e seguro para o Tarevo. ## 1. Arquitetura de Entrega e Garantias - **Transactional Outbox:** Eventos são persistidos no banco de dados na mesma transação que comita a alteração do pedido/cliente. - **At-Least-Once Delivery:** Mensagens podem ser entregues mais de uma vez em caso de timeout de rede ou reinício. Deduplique mensagens usando chave única no banco de dados baseada no campo `eventId`. - **Validação de Assinatura:** O cabeçalho `X-Tarevo-Signature` contém o hash HMAC-SHA256 calculado sobre o **Raw Body** em bytes/string UTF-8. - **Resposta HTTP Requerida:** Seu servidor deve responder com status **2xx (ex: 200 OK ou 202 Accepted)** em até 5 segundos. Qualquer resposta diferente de 2xx ou timeout é considerada falha. - **Política de Retentativas e DLQ:** Até 10 tentativas com backoff exponencial (1m, 2m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 16h). Após 10 falhas, a mensagem vai para a Dead Letter Queue (DLQ) para reenvio manual. ## 2. Implementação do Receptor com Validação HMAC (Node.js/Express/TypeScript) ```javascript const express = require('express'); const crypto = require('crypto'); const app = express(); // IMPORTANTE: Obter o buffer bruto da requisição para o cálculo exato do HMAC app.post('/api/tarevo-webhook', express.raw({ type: 'application/json' }), async (req, res) => { const signature = req.headers['x-tarevo-signature'] as string; const webhookSecret = process.env.TAREVO_WEBHOOK_SECRET!; if (!signature) { return res.status(401).send('Missing X-Tarevo-Signature'); } const hmac = crypto.createHmac('sha256', webhookSecret); const calculatedSignature = hmac.update(req.body).digest('hex'); if (calculatedSignature.length !== signature.length || !crypto.timingSafeEqual(Buffer.from(calculatedSignature), Buffer.from(signature))) { return res.status(401).send('Invalid Signature'); } const event = JSON.parse(req.body.toString('utf-8')); // Deduplicação: verifique se req.body.eventId já foi processado const alreadyProcessed = await checkEventDeduplication(event.eventId); if (alreadyProcessed) { return res.status(200).send('Already processed'); } // Enfileire para processamento assíncrono e responda 200 imediatamente await enqueueTask(event); return res.status(200).json({ received: true }); }); ``` ## 3. Catálogo Canônico de Eventos de Webhook ### Evento: `order.created` - Escopo Requerido: `orders:read` - Descrição: Disparado quando um novo pedido é registrado no estabelecimento. - Ordenação / Ciclo: Primeiro evento do ciclo de vida de um pedido. - Deduplicação: Utilize o campo eventId para deduplicar no seu banco receptor. - Amostra do Payload JSON: ```json { "eventId": "evt_01J7K...", "eventType": "order.created", "timestamp": "2026-09-07T12:00:00Z", "tenantId": "TL7K9A", "data": { "orderId": "ord_123", "orderNumber": 1042, "total": 89.5, "type": "DELIVERY", "status": "PENDING" } } ``` ### Evento: `order.confirmed` - Escopo Requerido: `orders:read` - Descrição: Disparado quando o restaurante confirma o pedido e envia para a cozinha. - Ordenação / Ciclo: Ocorre após order.created. - Deduplicação: Deduplicar por eventId. - Amostra do Payload JSON: ```json { "eventId": "evt_01J7L...", "eventType": "order.confirmed", "timestamp": "2026-09-07T12:02:00Z", "tenantId": "TL7K9A", "data": { "orderId": "ord_123", "status": "CONFIRMED" } } ``` ### Evento: `order.ready` - Escopo Requerido: `orders:read` - Descrição: Disparado quando a cozinha finaliza o preparo do pedido. - Ordenação / Ciclo: Ocorre após order.confirmed. - Deduplicação: Deduplicar por eventId. - Amostra do Payload JSON: ```json { "eventId": "evt_01J7M...", "eventType": "order.ready", "timestamp": "2026-09-07T12:20:00Z", "tenantId": "TL7K9A", "data": { "orderId": "ord_123", "status": "READY" } } ``` ### Evento: `order.dispatched` - Escopo Requerido: `orders:read` - Descrição: Disparado quando o pedido sai para entrega com o motoboy. - Ordenação / Ciclo: Ocorre após order.ready para pedidos tipo DELIVERY. - Deduplicação: Deduplicar por eventId. - Amostra do Payload JSON: ```json { "eventId": "evt_01J7N...", "eventType": "order.dispatched", "timestamp": "2026-09-07T12:25:00Z", "tenantId": "TL7K9A", "data": { "orderId": "ord_123", "status": "DISPATCHED" } } ``` ### Evento: `order.delivered` - Escopo Requerido: `orders:read` - Descrição: Disparado quando o cliente recebe o pedido e o ciclo é concluído. - Ordenação / Ciclo: Evento terminal positivo do pedido. - Deduplicação: Deduplicar por eventId. - Amostra do Payload JSON: ```json { "eventId": "evt_01J7P...", "eventType": "order.delivered", "timestamp": "2026-09-07T12:45:00Z", "tenantId": "TL7K9A", "data": { "orderId": "ord_123", "status": "DELIVERED" } } ``` ### Evento: `order.cancelled` - Escopo Requerido: `orders:read` - Descrição: Disparado quando o pedido é cancelado pela loja ou pelo cliente. - Ordenação / Ciclo: Evento terminal de cancelamento. - Deduplicação: Deduplicar por eventId. - Amostra do Payload JSON: ```json { "eventId": "evt_01J7Q...", "eventType": "order.cancelled", "timestamp": "2026-09-07T12:05:00Z", "tenantId": "TL7K9A", "data": { "orderId": "ord_123", "status": "CANCELLED", "reason": "Loja sem insumo" } } ``` ### Evento: `customer.created` - Escopo Requerido: `customers:read` - Descrição: Disparado quando um novo cliente realiza seu primeiro pedido. - Ordenação / Ciclo: Independente de pedido. - Deduplicação: Deduplicar por eventId. - Amostra do Payload JSON: ```json { "eventId": "evt_01J7R...", "eventType": "customer.created", "timestamp": "2026-09-07T12:00:00Z", "tenantId": "TL7K9A", "data": { "customerId": "cust_456", "name": "Maria Silva", "phone": "+5511988887777" } } ``` ### Evento: `catalog.updated` - Escopo Requerido: `catalog:read` - Descrição: Disparado quando produtos, categorias ou preços sofrem alterações. - Ordenação / Ciclo: Agregado em janelas de atualização. - Deduplicação: Deduplicar por eventId. - Amostra do Payload JSON: ```json { "eventId": "evt_01J7S...", "eventType": "catalog.updated", "timestamp": "2026-09-07T12:10:00Z", "tenantId": "TL7K9A", "data": { "action": "ITEM_UPDATED", "itemId": "item_789" } } ``` ### Evento: `webhook.test` - Escopo Requerido: `webhooks:manage` - Descrição: Evento de verificação para validação de endpoint e cálculo de assinatura HMAC. - Ordenação / Ciclo: Sob demanda (via POST /public/v1/webhooks/{id}/test). - Deduplicação: Deduplicar por eventId. - Amostra do Payload JSON: ```json { "eventId": "evt_test_01...", "eventType": "webhook.test", "timestamp": "2026-09-07T12:00:00Z", "tenantId": "TL7K9A", "data": { "message": "Webhook test delivery from Tarevo Platform" } } ``` ## 4. Endpoints de Gestão de Webhooks - `POST /public/v1/webhooks` — Cadastra endpoint (Escopo: `webhooks:manage`, suporta `Idempotency-Key`). - `GET /public/v1/webhooks` — Lista endpoints ativos do estabelecimento. - `DELETE /public/v1/webhooks/{id}` — Remove endpoint. - `POST /public/v1/webhooks/{id}/test` — Dispara evento de teste sintético (`webhook.test`). - `GET /public/v1/webhooks/deliveries` — Inspeciona histórico de entregas e erros HTTP. - `POST /public/v1/webhooks/deliveries/{deliveryId}/replay` — Força reenvio de mensagem da DLQ. --- Fontes Oficiais: https://developers.tarevo.com.br/docs/webhooks.md | OpenAPI: https://developers.tarevo.com.br/openapi.json --- ## 4. Ciclo de Vida e Schema de Pedidos (Orders API Especializada) # Tarevo Orders API — Contexto Técnico Especializado Snapshot Canônico: 2026-09-07 | Public API v1.0 Finalidade: Consultar, sincronizar e acompanhar pedidos em tempo real no Tarevo. ## 1. Escopo Obrigatório `orders:read` (necessário em todas as requisições de leitura de pedidos). ## 2. Endpoints Oficiais ### Listagem de Pedidos com Paginação por Cursor `GET /public/v1/orders` - **Headers:** `Authorization: Bearer ` - **Query Params:** - `limit` (integer, 1 a 100, padrão 20) - `cursor` (string, ID do último pedido para buscar a página seguinte) - `status` (string: PENDING, CONFIRMED, READY, DISPATCHED, DELIVERED, CANCELLED) - `updated_since` (data ISO 8601 para reconciliação incremental) Exemplo de Resposta (200 OK): ```json { "data": [ { "id": "ord_01J7K...", "orderNumber": 1050, "status": "CONFIRMED", "type": "DELIVERY", "total": 68.90, "subtotal": 58.90, "deliveryFee": 10.00, "customer": { "id": "cust_123", "name": "Ana Clara", "phone": "+5511999998888" }, "deliveryAddress": { "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "postalCode": "01001-000" }, "items": [ { "id": "item_1", "name": "Smash Burger Duplo", "quantity": 1, "unitPrice": 38.00, "total": 38.00, "notes": "Sem cebola", "additionals": [ { "name": "Bacon Extra", "quantity": 1, "price": 6.00 } ] } ], "payments": [ { "method": "PIX", "status": "APPROVED", "value": 68.90 } ], "createdAt": "2026-09-07T14:30:00Z", "updatedAt": "2026-09-07T14:32:00Z" } ], "pagination": { "hasMore": true, "nextCursor": "ord_01J7K..." } } ``` ### Detalhes de um Pedido Específico `GET /public/v1/orders/{id}` Retorna a entidade completa do pedido identificado por `{id}`. ## 3. Ciclo de Vida e Status do Pedido `PENDING` → `CONFIRMED` → `READY` → `DISPATCHED` → `DELIVERED` (ou `CANCELLED` a qualquer momento). --- Fontes Oficiais: https://developers.tarevo.com.br/docs/orders.md | OpenAPI: https://developers.tarevo.com.br/openapi.json --- ## 5. Autenticação & OAuth 2.0 (Contexto Especializado) # Tarevo Authentication & OAuth 2.0 — Contexto Técnico Especializado Snapshot Canônico: 2026-09-07 | Public API v1.0 Finalidade: Gerenciar credenciais, tokens JWT e isolamento de tenants no Tarevo. ## 1. Protocolo e Credenciais - **Padrão:** OAuth 2.0 Client Credentials Grant. - **Credenciais:** `client_id` (identificador público da aplicação) e `client_secret` (segredo confidencial gerado na criação com exibição única). - **Ambientes:** SANDBOX e PRODUCTION utilizam credenciais distintas. Credenciais de sandbox não acessam restaurantes reais. ## 2. Emissão de Token de Acesso ```http POST /partner/auth/token HTTP/1.1 Host: api.tarevo.com.br Content-Type: application/json { "grant_type": "client_credentials", "client_id": "SEU_CLIENT_ID", "client_secret": "SEU_CLIENT_SECRET" } ``` Resposta (200 OK): ```json { "access_token": "eyJhbGciOiJIUzI1Ni...", "token_type": "Bearer", "expires_in": 3600, "scope": "orders:read catalog:read merchant:read webhooks:manage", "tenant_id": "TL7K9A", "environment": "SANDBOX" } ``` ## 3. Segurança e Modelo de Tenant - **Tenant Isolation:** O `tenant_id` do restaurante é derivado exclusivamente do token JWT assinado criptograficamente. O integrador NUNCA deve tentar enviar o tenantId como parâmetro na URL. - **Segurança Default-Deny:** Qualquer token ausente, expirado ou assinado com chave incompatível retorna **401 Unauthorized**. - **Renovação Automática:** O token dura 1 hora. Recomenda-se implementar cache renovando 5 minutos antes do término. --- Fontes Oficiais: https://developers.tarevo.com.br/docs/authentication.md --- ## 6. Especificação OpenAPI 3.1 Completa (YAML) ```yaml openapi: 3.1.0 info: title: Tarevo Public Partner API version: 1.0.0 description: 'API pública do Tarevo para parceiros integradores. Permite acesso a dados de lojas, pedidos, clientes e catálogo mediante autorização OAuth2. ' 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 — 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 ```