Uso da API

Uso da API 🚀

A API da Food2C oferece acesso a uma vasta gama de dados da plataforma. Este guia detalhado irá orientá-lo sobre como realizar consultas e obter os dados necessários de forma eficiente.

Fluxo de Consulta 🔄

1. Parâmetros da Requisição 📝

Para realizar uma consulta, forneça os seguintes parâmetros na requisição:

  • source: string (Fonte dos dados)

    A fonte dos dados que você deseja consultar. Pode ser, por exemplo, o nome de um banco de dados como MEU_ECOMMERCE_FOOD2C.

  • collection: string (Coleção específica)

    A coleção específica dentro da fonte de dados que você deseja acessar. Por exemplo, uma tabela de clientes customer.

  • page_number: integer (Número da página, padrão: 0)

    O número da página que você deseja acessar. A paginação é usada para dividir grandes conjuntos de dados em partes menores. O valor padrão é 0, que representa a primeira página.

  • page_size: integer (Tamanho da página, padrão: 10)

    O número de registros que você deseja obter por página. O valor padrão é 10, o que significa que cada página retornará até 10 registros.

  • parameters: object (Parâmetros adicionais, opcional)

    Um objeto contendo parâmetros adicionais que podem ser usados para filtrar ou modificar a consulta, baseado nas buscas do MongoDB. Este campo é opcional e pode incluir critérios específicos para refinar os resultados.

⚠️ Atenção: Dependendo do usuário, os acessos às coleções podem estar restritos. Certifique-se de que o usuário autenticado possui as permissões necessárias para acessar as coleções desejadas.

2. Cabeçalho da requisição 📋

Antes de enviar a requisição, é fundamental preparar o cabeçalho adequadamente. O cabeçalho deve conter a autorização necessária para acessar a API. A autorização é fornecida no formato Authorization: jwt_token, onde jwt_token deve ser substituído pelo token JWT obtido durante o processo de autenticação. Aqui está um exemplo detalhado de como estruturar o cabeçalho:

3. Especificações da Saída 📄

A resposta da API para uma consulta bem-sucedida incluirá os seguintes campos:

  • items: List[dict] (Lista de itens)

    Uma lista de dicionários, onde cada dicionário representa um registro da coleção consultada. Cada item contém os dados específicos da coleção.

  • total: int (Total de registros)

    O número total de registros que correspondem à consulta, sem considerar a paginação.

  • page_number: int (Número da página)

    O número da página atual dos resultados retornados. Este valor corresponde ao parâmetro page_number enviado na requisição.

  • page_size: int (Tamanho da página)

    O número de registros retornados por página. Este valor corresponde ao parâmetro page_size enviado na requisição.

4. Envie uma requisição 🚀

Aqui está um exemplo de como fazer uma requisição HTTP para consultar dados da API:

Requisição:

POST /api-data HTTP/1.1
Host: api.food2c.com.br
Content-Type: application/json
Authorization: jwt_token

Neste exemplo, usamos POST para enviar os parâmetros da consulta ao servidor. O cabeçalho Content-Type: application/json indica que o corpo da requisição está em JSON. Inclua o token JWT no cabeçalho Authorization como jwt_token, substituindo jwt_token pelo token real recebido após a autenticação.

Corpo da Requisição:

{
  "source": "MEU_ECOMMERCE_FOOD2C",
  "collection": "customer",
  "page_number": 0,
  "page_size": 10,
  "parameters": {
    "created_dt": {
      "$gt": { "$date": "2024-01-01T00:00:00.000000"  }
    }
  }
}

Este exemplo de corpo de requisição demonstra a utilização de todos os parâmetros mencionados anteriormente, além de incluir um filtro adicional baseado na data de criação dos clientes. A consulta segue o padrão do MongoDB, oferecendo grande flexibilidade na filtragem dos resultados.

Pontos importantes:

📌 Parâmetros da consulta:

  • source: "MEU_ECOMMERCE_FOOD2C" (fonte dos dados)
  • collection: "customer" (coleção específica)
  • page_number: 0 (primeira página)
  • page_size: 10 (10 registros por página)

🔍 Filtro avançado:

  • Utiliza o operador $gt (greater than) do MongoDB
  • Filtra clientes criados após 1º de setembro de 2024

💡 Dica: Esta estrutura permite consultas complexas e precisas, adaptando-se às necessidades específicas de cada aplicação.

📚 Nota: Para explorar todo o potencial das queries do MongoDB e conhecer outros operadores disponíveis, consulte a documentação oficial do MongoDB (opens in a new tab).

Resposta:

{
  "data": [
    {
      "id": "12345",
      "name": "João Silva",
      "email": "joao.silva@exemplo.com",
      "city": "São Paulo"
    },
    // ... mais registros ...
  ],
  "total_count": 150,
  "page_number": 0,
  "page_size": 10
}

A resposta inclui os dados solicitados, bem como informações sobre a paginação e o total de registros encontrados.

💡 Dica: Ajuste os parâmetros da consulta conforme necessário para obter os dados específicos que você precisa.

5. Referências entre tabelas 🔗

Às vezes, uma tabela pode conter referências a dados em outra tabela. Nesses casos, será necessário realizar uma nova busca para obter as informações completas.

Por exemplo, se a tabela "pedidos" contiver uma referência ao ID do cliente, você precisará fazer uma consulta adicional à tabela "clientes" para obter os detalhes completos do cliente.

Exemplo de consulta para obter detalhes do pedido:

{
  "source": "MEU_ECOMMERCE_FOOD2C",
  "collection": "pedidos",
  "page_number": 0,
  "page_size": 1,
  "parameters": {
    "id": "123456"
  }
}

Resposta:

{
  "data": [
    {
      "id": "123456",
      "cliente_id": "789",
      "valor_total": 150.00,
      "data_pedido": "2024-03-15T14:30:00.000Z"
    }
  ],
  "total_count": 1,
  "page_number": 0,
  "page_size": 1
}

Para obter os detalhes do cliente, você precisará fazer uma nova consulta:

{
  "source": "MEU_ECOMMERCE_FOOD2C",
  "collection": "clientes",
  "page_number": 0,
  "page_size": 1,
  "parameters": {
    "id": "789"
  }
}

💡 Dica: Planeje suas consultas de forma eficiente para minimizar o número de requisições necessárias e otimizar o desempenho da sua aplicação.

AutenticaçãoModelos