Guia de Integração Passo a Passo

Este guia apresenta o processo completo para integrar um sistema externo à API Pública do Jão Delivery, desde a geração do token até a realização das primeiras consultas de dados. O objetivo é orientar desenvolvedores na criação de integrações seguras e eficientes com a plataforma.

1. Gerar o token de acesso

Toda integração com a API requer um token de autenticação. Esse token identifica o restaurante e autoriza o acesso aos dados.

Passo 1 — Acessar o painel

1. Faça login no painel administrativo do Jão Delivery.

2. No menu lateral, acesse API Pública.

Passo 2 — Criar um token

1. Clique em Gerar Novo Token.

2. Copie o token gerado e armazene-o em local seguro.

O sistema permite gerar múltiplos tokens para diferentes integrações ou ambientes. Tokens também podem ser revogados a qualquer momento caso seja necessário interromper o acesso de alguma aplicação.

2. Configurar a autenticação nas requisições

Todas as requisições para a API devem incluir o token no header de autorização.

Estrutura do header

Authorization: Bearer <seu_api_token>

Se o token estiver ausente, inválido ou revogado, a API retornará:

401 Unauthorized

Isso garante que apenas sistemas autorizados possam acessar os dados do restaurante.

3. Definir a base da API

Todas as requisições devem utilizar a seguinte base:

https://api.jao.app

Os endpoints são acessados a partir dessa URL base.

Exemplo de endpoint completo:

https://api.jao.app/public/products

4. Realizar a primeira requisição

Para validar a integração, o primeiro teste recomendado é consultar os produtos do cardápio.

Endpoint

GET /public/products

Exemplo de requisição em JavaScript

const token = 'SEU_TOKEN_AQUI';

const response = await fetch('https://api.jao.app/public/products?page=1&limit=10', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Essa requisição retorna uma lista paginada de produtos cadastrados no restaurante.

5. Trabalhar com paginação

As consultas da API utilizam paginação para evitar respostas muito grandes.

Parâmetros disponíveis

Parâmetro

Descrição

Exemplo

GET /public/products?page=1&limit=10

A resposta inclui metadados que ajudam a navegar entre páginas, como total de registros e total de páginas disponíveis.

6. Consultar pedidos

Após validar a conexão com os produtos, o próximo passo é consultar os pedidos do restaurante.

Endpoint

GET /public/requests

Esse endpoint retorna os pedidos realizados no restaurante.

Exemplo de consulta

GET /public/requests?page=1&limit=20

7. Aplicar filtros em pedidos

O endpoint de pedidos permite aplicar filtros que ajudam a refinar as consultas.

Filtro por status

status=all
status=success
status=canceled
status=preparing

Filtro por período

period=today
period=yesterday-today
period=all
period=7

Exemplo de consulta:

GET /public/requests?status=success&period=7

Essa consulta retorna pedidos concluídos dos últimos 7 dias.

8. Buscar produtos pelo nome

O endpoint de produtos permite buscar itens do cardápio utilizando o parâmetro search.

Exemplo

GET /public/products?search=pizza

Essa consulta retorna produtos cujo nome contenha o termo pesquisado.

9. Entender a estrutura das respostas

As respostas da API seguem uma estrutura padronizada que inclui:

• mensagem da operação

• lista de registros

• informações de paginação

• dados agregados quando disponíveis

Exemplo simplificado:

{
  "message": "success",
  "docs": [],
  "totalDocs": 120,
  "limit": 10,
  "page": 1,
  "totalPages": 12,
  "hasPrevPage": false,
  "hasNextPage": true
}

No caso de pedidos, também pode existir um objeto summary, contendo totais e métricas relacionadas aos pedidos retornados.

10. Utilizar a documentação interativa

Para facilitar o desenvolvimento da integração, a API disponibiliza uma documentação interativa baseada em Swagger.

Swagger UI

https://api.jao.app/api-public

OpenAPI JSON

https://api.jao.app/api-public-json

O Swagger permite:

• visualizar todos os endpoints disponíveis

• testar requisições diretamente no navegador

• verificar schemas de request e response

• validar parâmetros antes de implementar a integração no código.

Boas práticas de integração

Para garantir uma integração estável e segura, recomenda-se:

• armazenar tokens em variáveis de ambiente

• nunca expor tokens no frontend público

• implementar tratamento de erros HTTP

• utilizar paginação para grandes volumes de dados

• validar respostas antes de processar dados

Conclusão

A integração com a API Pública do Jão Delivery é simples e segue um modelo padrão de APIs REST modernas.

Com autenticação via token, endpoints organizados e documentação Swagger disponível, desenvolvedores podem rapidamente integrar sistemas externos para acessar dados de pedidos e produtos, permitindo automação, análise e integração com outras ferramentas do ecossistema digital do restaurante.