Gestão AiqEntrega

Visão Geral para o Integrador

O aiqentrega é o ecossistema de logística oficial da plataforma, projetado para oferecer uma solução de entrega completa e automatizada para os lojistas. Para você, parceiro integrador, este módulo permite que o seu sistema monitore, em tempo real, cada etapa do deslocamento do pedido, desde a chamada do entregador até a finalização no destino.

Chamar Entregador

Este endpoint é utilizado para solicitar um entregador para um ou mais pedidos. Ao ser acionado, o ecossistema aiqentrega inicia a busca pelo "robner" (entregador) mais qualificado e próximo da região. Assim que a corrida é aceita, o entregador é designado para coletar o pedido na loja e realizar a entrega ao cliente final.

POST

/ride/call

Exemplo de Payload

{
  "store_id": 54185,
  "minutes": 11,
  "orders": [
    {
      "type": "standalone",
      "id": 68653557
    }
  ],
  "auto_grouping_enabled": true
}

Detalhamento dos Campos (Payload)

Campo	Obrigatório	Descrição
store_id	✅	ID único da loja onde o pedido foi realizado.
minutes	❌	Tempo (em minutos) que o sistema deve aguardar para disparar a chamada ao entregador. Útil para sincronizar com o tempo de preparo.
orders	✅	Lista de objetos contendo os pedidos que farão parte desta corrida.
orders[].type	✅	Origem do pedido: normal (Marketplace aiqfome) ou standalone (pedido avulso criado pelo Seller).
orders[].id	✅	ID identificador do pedido.
auto_grouping_enabled	❌	Se true, o sistema permite agrupar pedidos com rotas próximas. Se desejar agrupar manualmente, os IDs devem estar na lista de orders.

Comportamento do Fluxo

• Solicitação: O integrador envia o POST para chamar o entregador.
• Busca: O sistema processa a requisição e busca robners disponíveis no app.
• Aceite: Assim que um entregador aceita, o status da corrida (objeto aiqentrega no pedido) mudará para refletir que a entrega está em andamento.
• Monitoramento: A partir deste ponto, o integrador pode acompanhar os status (como checking, collecting e delivering) via endpoint de detalhes do pedido (Show Order).

Regras de Negócio Importantes

• Habilitação: Este endpoint só terá sucesso se a loja possuir o recurso aiqentrega_active: true (pode ser validado no endpoint GET /store). O Aiqentrega precisa estar habilitado para a loja pelo time do Aiqfome.
• Cancelamento: Caso a corrida precise ser cancelada após a chamada, deve-se utilizar o endpoint específico de cancelamento de corrida (Ride Cancel).
• Cancelamento Automático: No momento da criação de uma corrida, o sistema agenda automaticamente um job de monitoramento. Caso nenhum entregador aceite a oferta dentro do tempo limite de busca estabelecido, a corrida será cancelada de forma automática por timeout.
• Configuração: Esta regra é definida por Cidade (e não por loja) usando o Raimundo e pode ser configurada apenas pelo time Aiqfome.
• Comportamento: O tempo de expiração varia conforme a configuração da praça onde a entrega foi solicitada (Exemplo: 03m 20s).

Cotar Custo da Corrida

Este endpoint permite simular o valor do frete para um ou mais pedidos. Ele é especialmente útil para pedidos do tipo standalone (avulsos), onde o lojista precisa saber o custo logístico para repassar ao cliente ou decidir pela viabilidade da entrega via aiqentrega.

POST

/ride/quote

Exemplo de Payload

{
  "store_id": 16,
  "orders": [
    {
      "type": "normal",
      "id": 19
    }
  ]
}

Detalhamento dos Campos (Payload)

Campo	Obrigatório	Descrição
store_id	✅	ID único da loja que solicita a cotação.
orders	✅	Lista de pedidos para os quais o frete será calculado.
orders[].type	✅	Origem do pedido: normal (Marketplace) ou standalone (avulso).
orders[].id	✅	ID identificador do pedido.

Detalhamento do Retorno

Campo	Descrição
success	Indica se a cotação foi realizada com sucesso.
data.cost	O valor monetário do frete calculado para a corrida (no exemplo, R$ 5,50). Este valor leva em conta a distância entre a loja e o(s) ponto(s) de entrega.

Reagendar Corrida

Este endpoint permite alterar o tempo de espera (minutes) que o sistema deve aguardar para disparar a chamada ao entregador

POST

/ride/{ride_id}/reschedule

Exemplo de Payload

{
  "minutes": 18
}

Detalhamento dos Campos (Payload)

Campo	Obrigatório	Descrição
minutes	✅	Novo tempo (em minutos) para o disparo da chamada.

Cancelar Corrida Agendada

Este endpoint é utilizado para cancelar uma corrida que foi solicitada via Ride Call, que ainda não foi alocada para o entregador.

POST

/ride/{ride_id}/cancel

Listar Pedidos Avulsos

Este endpoint retorna a lista de pedidos avulsos criados pelo lojista. Ele permite o acompanhamento simplificado de pedidos que entraram por canais próprios (balcão, telefone, etc.) e foram integrados à plataforma para fins de logística.

GET

/standalone-orders

Filtros de Consulta (Query Params)

Parâmetro	Obrigatório	Descrição
filter[store_id]	❌	Filtra os pedidos de uma unidade específica. Na API V2 somente é possível consultar dados da loja o que está autorizado.
filter[order_id]	❌	Busca um pedido avulso específico pelo seu ID.
filter[ride_id]	❌	Filtra pedidos vinculados a uma corrida (entrega) específica.

Exemplo de Resposta

{
  "data": [
    {
      "order_id": 68653557,
      "channel": "avulso",
      "client_name": "João Silva",
      "phone": "+5542999999999",
      "created_at": "2025-09-22 14:30:00",
      "delivery_id": 987654,
      "store_id": 43,
      "store_name": "Paladinos Burguer"
    }
  ]
}

Estrutura do Retorno (Campos do Objeto)

Campo	Descrição
order_id	Identificador único do pedido avulso.
channel	Canal de origem (Fixo como "avulso" neste endpoint).
client_name	Nome do cliente final.
phone	Telefone de contato do cliente.
created_at	Data e hora da criação do pedido.
delivery_id	ID do registro de entrega vinculado ao pedido.
store_id	ID da loja proprietária do pedido.
store_name	Nome fantasia da loja.

Criar Pedido Avulso

Este endpoint permite registrar um pedido externo no ecossistema do aiqfome para que ele possa ser vinculado a uma corrida de entrega. Ao criar o pedido avulso, o sistema gera um order_id que será utilizado posteriormente no Ride Call.

POST

/standalone-orders

Detalhamento dos Campos (Payload)

Objeto / Campo	Obrigatório	Descrição
store_id	✅	ID da loja proprietária do pedido.
orders	✅	Array de objetos contendo os dados do pedido.
orders[].channel	❌	Nome do canal de origem (ex: "WhatsApp", "Telefone").
orders[].client_name	✅	Nome completo do cliente.
orders[].phone	❌	Telefone de contato do cliente.
orders[].address	✅	Objeto contendo o endereço completo de entrega
orders[].payment	✅	Detalhes do pagamento (método, valor total e troco).
orders[].items	❌	Lista de itens que compõem o pedido (nome, quantidade e tamanho).
orders[].observation	❌	Observações adicionais para a entrega ou produção.

Detalhamento: Objeto address

Este objeto define o local exato onde o entregador deve realizar a entrega.

Campo	Obrigatório	Descrição
street_name	✅	Nome do logradouro (Rua, Avenida, etc).
number	✅	Número do local.
complement	❌	Apartamento, bloco ou detalhes adicionais.
neighborhood	✅	Bairro do destino.
reference	❌	Ponto de referência para auxiliar o entregador.
zip_code	✅	CEP formatado ou apenas números.
latitude	❌	Latitude em formato decimal (Ex: -23.4209).
longitude	❌	Longitude em formato decimal (Ex: -51.9331).

Detalhamento: Objeto payment

Informa ao entregador como o pedido foi ou será pago e se há necessidade de levar troco.

Campo	Obrigatório	Descrição
method	✅	ID do método de pagamento (Ex: 1 para Dinheiro, 2 para Cartão).
total_value	✅	Valor total bruto do pedido (itens + frete, se houver).
change	❌	Valor do troco solicitado pelo cliente (apenas para dinheiro).

Detalhamento: Objeto items

Lista de produtos que compõem o pedido avulso para conferência na coleta e entrega.

Campo	Obrigatório	Descrição
name	❌	Nome descritivo do produto.
quantity	❌	Quantidade de unidades deste item no pedido.
size	❌	Descrição do tamanho ou variação (Ex: "G", "500ml", "1kg").

Detalhar Pedido Avulso

Este endpoint retorna todas as informações de um pedido avulso específico. Ele é o principal canal para consultar o status da logística, permitindo saber se um entregador já foi designado, quem ele é e em qual etapa da entrega o pedido se encontra.

GET

/standalone-orders/{id}

Detalhamento dos Campos de Retorno

Objeto / Campo	Descrição
id	Identificador único do pedido avulso.
ride_id	ID da corrida vinculada (nulo se o entregador ainda não foi chamado).
delivery_time	Estimativa de tempo de entrega (em minutos).
total	Valor total do pedido.
payment_method	Descrição do método de pagamento.
const_quote	Valor de custo do frete calculado para esta corrida.
store.id	ID da loja proprietária do pedido.
store.name	Nome fantasia da unidade.
store.phones	Telefones de contato da loja.
store.store_mobile_number	Celular de contato direto da loja.
store.preparation_time	Tempo de preparo configurado para o pedido.
user.name	Nome do cliente final.
user.mobile_phone	Telefone celular do cliente final.
address.street_name	Nome do logradouro de destino.
address.number	Número do endereço de entrega.
address.complement	Detalhes adicionais (Apt, Bloco, etc).
address.cep	Código de Endereçamento Postal (CEP).
address.city_name	Nome da cidade de destino.
address.uf	Sigla do Estado (Unidade Federativa).
address.neighborhood_name	Nome do bairro de entrega.
address.latitude / address.longitude	Coordenadas geográficas do destino.
ride.id	ID interno da logística.
ride.driver_name	Nome do entregador (Robner) designado.
ride.driver_phone	Telefone de contato do entregador.
ride.current_status	Status atual da entrega (collecting, delivering, etc).
timeline.created_at	Data e hora da criação do pedido avulso.
timeline.pickup_at	Data e hora em que o entregador coletou o pedido na loja.
timeline.delivered_at	Data e hora da finalização da entrega ao cliente.
timeline.canceled_at	Data e hora caso o pedido/corrida tenha sido cancelado.

Excluir Pedido Avulso

Este endpoint permite remover um pedido avulso do sistema.

DELETE

/standalone-orders/{id}

Regras e Observações Importantes

• Ordem de Cancelamento: Se o pedido já tiver uma corrida vinculada (ride_id), recomenda-se primeiro cancelar a corrida via endpoint de Ride Cancel antes de tentar excluir o registro do pedido avulso. Só é possível cancelar a corrida se a mesma não tiver sido chamada.
• Persistência: Uma vez excluído via DELETE, o pedido não poderá mais ser consultado ou recuperado. Para fins de histórico, se o pedido foi apenas cancelado pelo cliente mas você deseja manter o registro, utilize o fluxo de alteração de status (se disponível) em vez da exclusão física.
• Identificação: O :id deve ser o identificador numérico retornado no momento da criação do pedido avulso.

Configurar Chamada Automática

Este endpoint permite habilitar ou desabilitar a inteligência de chamada automática do entregador. Ao ativar essa função, o sistema aciona o entregador automaticamente e ao desativar, o integrador ganha controle total sobre o momento exato de mobilizar o entregador "robner".

PATCH

/store/{store_id}/aiqentrega-delivery-settings

Detalhamento dos Campos (Payload)

Campo	Tipo	Descrição
autocalldelivery	Boolean	Define o comportamento da chamada de logística (veja as regras abaixo).

Regras de Funcionamento

• true (Habilitado): Assim que o Seller realizar a leitura do pedido (status read), o sistema disparará automaticamente uma requisição para o aiqentrega solicitando um entregador.
• false (Desabilitado): O sistema não tomará nenhuma ação automática. O parceiro integrador assume a responsabilidade de acionar a logística manualmente através da rota de Ride Call (POST /api/v2/ride/call) no momento que julgar mais adequado.