API v2

Tempero PDV para desenvolvedores

Cardápio, pedidos, mesas, vendas, clientes e reservas do seu restaurante, direto no seu sistema. Disponível nos planos Pro e Enterprise, com liberação pelo nosso time.

Introdução

A API do Tempero PDV deixa o seu restaurante conversar com o site próprio, um app de delivery, o chatbot do WhatsApp ou a planilha do contador. É REST com JSON, base https://pdv-restaurante-saas.vercel.app/api/v2. Dinheiro sempre em centavos (inteiro) e datas no fuso de São Paulo.

Assine o plano Pro ou Enterprise.
Em Painel → API, conte o que vai integrar e peça o acesso. O time do Tempero PDV revisa e libera.
Crie uma chave com só os escopos necessários. Ela aparece uma única vez: guarde num cofre ou variável de ambiente.
Chame GET /api/v2/me para testar.

Especificação OpenAPI 3.1 (Postman, Insomnia, geradores de SDK): /api/v2/openapi.json

Autenticação

Envie a chave no cabeçalho Authorization. Nunca coloque a chave em código que roda no navegador ou no app do cliente: chame a API do seu servidor.

Authorization: Bearer mf_live_xxxxxxxxxxxxxxxxxxxxxxxx

Chave vazou? Revogue em Painel → API e crie outra. Guardamos só o hash; nem o suporte vê a chave.

Limites

Plano	Por minuto	Por dia	Chaves
Pro	60	5.000	3
Enterprise	300	50.000	20

Os limites valem por restaurante (somando as chaves). Toda resposta traz X-RateLimit-Remaining-Minute e X-RateLimit-Remaining-Day; o 429 traz Retry-After em segundos.

Escopos

cardapio:ler

Categorias, produtos, preços e disponibilidade.

cardapio:escrever

Disponibilidade e preço dos produtos.

mesas:ler

Mesas e ocupação.

pedidos:ler

Comandas, itens e totais.

pedidos:escrever

Abrir comanda e lançar itens (preço sempre do cardápio).

vendas:ler

Resumo de faturamento por período.

clientes:ler

Clientes cadastrados (dados pessoais: trate pela LGPD).

reservas:ler

Reservas por data.

reservas:escrever

Registrar reservas vindas do seu site.

Erros

{
  "error": {
    "code": "insufficient_scope",
    "message": "A chave não tem o escopo pedidos:escrever.",
    "escopo": "pedidos:escrever"
  }
}

400	db_error	Dado recusado pelo banco.
401	unauthorized / invalid_key	Chave ausente, inválida ou revogada.
402	plan_required	O plano do restaurante não inclui a API.
403	insufficient_scope / api_disabled	A chave não tem o escopo ou a API foi suspensa.
404	not_found / route_not_found	Recurso ou rota inexistente.
409	unavailable	Produto indisponível.
422	invalid_*	Parâmetro inválido (a mensagem diz qual).
429	rate_limited	Limite por minuto ou por dia. Respeite o Retry-After.
500	internal_error	Falha nossa. Tente de novo com backoff.

GET/api/v2/mecardapio:ler

Testar a chave

Restaurante, escopos da chave e limites. Use para validar a integração.

Resposta 200

{
  "data": {
    "restaurante": {
      "id": "9b1…",
      "name": "Pedacinho do Céu"
    },
    "chave": {
      "nome": "Site",
      "prefixo": "mf_live_AbC123",
      "escopos": [
        "cardapio:ler"
      ]
    },
    "limites": {
      "minuto": 60,
      "dia": 5000
    }
  }
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/me" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

GET/api/v2/cardapiocardapio:ler

Cardápio completo

Categorias com os produtos, preço vigente (promoção), complementos e opções de remover.

Resposta 200

{
  "data": [
    {
      "id": "c1…",
      "name": "Lanches",
      "produtos": [
        {
          "id": "p1…",
          "name": "X-Bacon",
          "price": 3290,
          "preco_vigente": 2990,
          "available": true,
          "complementos": [
            {
              "nome": "Ovo",
              "preco": 300
            }
          ],
          "remover": [
            "tomate"
          ]
        }
      ]
    }
  ],
  "sem_categoria": []
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/cardapio" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

GET/api/v2/produtoscardapio:ler

Listar produtos

Lista plana de produtos.

Parâmetro	Onde	Descrição
`disponivel` boolean	query	true = só os disponíveis.
`limit` integer	query	Até 1000 (padrão 200).

Resposta 200

{
  "data": [
    {
      "id": "p1…",
      "name": "Suco de laranja",
      "price": 1200,
      "preco_vigente": 1200,
      "available": true,
      "stock": null
    }
  ]
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/produtos?disponivel=true&limit=50" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

GET/api/v2/produtos/{id}cardapio:ler

Um produto

Produto com complementos e preço vigente.

Parâmetro	Onde	Descrição
`id`obrigatório uuid	path	ID do produto.

Resposta 200

{
  "data": {
    "id": "p1…",
    "name": "X-Bacon",
    "price": 3290,
    "preco_vigente": 3290,
    "complementos": [],
    "remover": []
  }
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/produtos/ID_AQUI" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

PATCH/api/v2/produtos/{id}cardapio:escrever

Alterar disponibilidade, preço ou estoque

Pausar um item esgotado, ajustar preço (centavos) ou estoque.

Parâmetro	Onde	Descrição
`id`obrigatório uuid	path	ID do produto.
`available` boolean	body	Disponível no cardápio.
`price` integer	body	Preço em centavos.
`stock` integer\|null	body	Estoque (null = sem controle).

Resposta 200

{
  "data": {
    "id": "p1…",
    "name": "X-Bacon",
    "price": 3290,
    "available": false,
    "stock": null
  }
}

curl -X PATCH "https://pdv-restaurante-saas.vercel.app/api/v2/produtos/ID_AQUI" \
  -H "Authorization: Bearer $MESAFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"available":false}'

GET/api/v2/mesasmesas:ler

Mesas e ocupação

Status de cada mesa (livre, ocupada, fechando, reservada, limpeza).

Resposta 200

{
  "data": [
    {
      "id": "m1…",
      "number": 4,
      "seats": 4,
      "status": "ocupada",
      "people": 3,
      "opened_at": "2026-09-26T19:02:11Z"
    }
  ]
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/mesas" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

GET/api/v2/pedidospedidos:ler

Listar pedidos

Comandas criadas no período (dia de São Paulo).

Parâmetro	Onde	Descrição
`de` date	query	AAAA-MM-DD (padrão hoje).
`ate` date	query	AAAA-MM-DD (padrão hoje).
`status` string	query	aberta, fechada ou cancelada.
`limit` integer	query	Até 500 (padrão 100).

Resposta 200

{
  "data": [
    {
      "id": "o1…",
      "table_number": 4,
      "status": "fechada",
      "subtotal": 8900,
      "service_fee": 890,
      "discount": 0,
      "total": 9790,
      "payment_method": "pix"
    }
  ],
  "de": "2026-09-26",
  "ate": "2026-09-26"
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/pedidos?de=2026-09-26&ate=2026-09-26" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

GET/api/v2/pedidos/{id}pedidos:ler

Um pedido com itens

Comanda com os itens e a etapa de produção de cada um.

Parâmetro	Onde	Descrição
`id`obrigatório uuid	path	ID do pedido.

Resposta 200

{
  "data": {
    "id": "o1…",
    "status": "aberta",
    "subtotal": 6580,
    "itens": [
      {
        "name": "X-Bacon + Ovo",
        "qty": 2,
        "price": 3290,
        "notes": "sem tomate",
        "status": "preparo"
      }
    ]
  }
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/pedidos/ID_AQUI" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

POST/api/v2/pedidospedidos:escrever

Criar pedido

Abre (ou reaproveita a comanda aberta da mesa) e lança os itens. O preço vem sempre do cardápio; complementos e remoções têm de existir no cadastro do produto.

Parâmetro	Onde	Descrição
`mesa` integer	body	Número da mesa (opcional; sem mesa vira comanda de balcão).
`cliente` string	body	Nome do cliente.
`itens`obrigatório array	body	[{ product_id, qty, complementos?: string[], remover?: string[], obs? }] (até 50).
`enviar_producao` boolean	body	true = imprime a via na cozinha/bar.

Resposta 201

{
  "data": {
    "order_id": "o1…",
    "subtotal": 6580,
    "itens": 1
  }
}

curl -X POST "https://pdv-restaurante-saas.vercel.app/api/v2/pedidos" \
  -H "Authorization: Bearer $MESAFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mesa":4,"itens":[{"product_id":"p1…","qty":2,"complementos":["Ovo"],"remover":["tomate"]}],"enviar_producao":true}'

GET/api/v2/vendas/resumovendas:ler

Resumo de vendas

Faturamento, contas, ticket, taxa de serviço, descontos, por dia e por forma de pagamento (até 92 dias).

Parâmetro	Onde	Descrição
`de` date	query	AAAA-MM-DD.
`ate` date	query	AAAA-MM-DD.

Resposta 200

{
  "data": {
    "de": "2026-09-01",
    "ate": "2026-09-26",
    "total": 4521300,
    "contas": 612,
    "ticket_medio": 7388,
    "por_forma": {
      "pix": 2100000,
      "credito": 1800000
    }
  }
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/vendas/resumo?de=2026-09-26&ate=2026-09-26" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

GET/api/v2/clientesclientes:ler

Clientes

Clientes cadastrados. Dados pessoais: use só para a finalidade informada (LGPD).

Parâmetro	Onde	Descrição
`limit` integer	query	Até 1000 (padrão 100).

Resposta 200

{
  "data": [
    {
      "id": "c1…",
      "name": "Maria",
      "phone": "48999990000",
      "visits": 7,
      "total_spent": 64200
    }
  ]
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/clientes?limit=50" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

GET/api/v2/reservasreservas:ler

Reservas do dia

Reservas de uma data.

Parâmetro	Onde	Descrição
`data` date	query	AAAA-MM-DD (padrão hoje).

Resposta 200

{
  "data": [
    {
      "id": "r1…",
      "customer_name": "João",
      "people": 6,
      "date": "2026-09-27",
      "time": "20:00",
      "status": "confirmada"
    }
  ],
  "data_consulta": "2026-09-27"
}

curl -X GET "https://pdv-restaurante-saas.vercel.app/api/v2/reservas?data=2026-09-26" \
  -H "Authorization: Bearer $MESAFLOW_KEY"

POST/api/v2/reservasreservas:escrever

Criar reserva

Registra uma reserva vinda do seu site ou chatbot.

Parâmetro	Onde	Descrição
`nome`obrigatório string	body	Nome do cliente.
`telefone` string	body	Com DDD.
`data`obrigatório date	body	AAAA-MM-DD (hoje ou depois).
`hora`obrigatório string	body	HH:MM.
`pessoas` integer	body	1 a 200 (padrão 2).
`obs` string	body	Observação.

Resposta 201

{
  "data": {
    "id": "r1…",
    "customer_name": "João",
    "date": "2026-09-27",
    "time": "20:00",
    "people": 6,
    "status": "confirmada"
  }
}

curl -X POST "https://pdv-restaurante-saas.vercel.app/api/v2/reservas" \
  -H "Authorization: Bearer $MESAFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nome":"João","telefone":"48999990000","data":"2026-09-27","hora":"20:00","pessoas":6}'