Issue PDV:                            


Objetivo:

O objetivo desta integração é permitir que o sistema de gestão de pedidos (Go Delivery) se comunique corretamente com o PDV, proporcionando a gestão e o acompanhamento em tempo real dos pedidos realizados, desde a criação até a entrega.


Documentação Go Delivery:

https://abrasel-nacional.github.io/docs/#section/How-to-Start-(Setup-Guide)


GET /events:polling -
POST /events/acknowledgment
POST /orderUpdate (WEBHOOK)
GET /orders/{orderId}
POST /orders/{orderId}/confirm
POST /orders/{orderId}/readyForPickup
POST /orders/{orderId}/dispatch
POST /orders/{orderId}/delivered
POST /v1/orders/{orderId}/validateCode
POST /orders/{orderId}/requestCancellation
POST /orders/{orderId}/acceptCancellation
POST /orders/{orderId}/denyCancellation
POST /orders/{orderId}/tracking


Escopo da Integração:

  1. Gestão de Pedidos:

  2. Webhooks:

  3. Autenticação e Configuração:

  4. Processamento de Pedidos:

RETAGUARDA: 


RN001 - Implementar  módulo


RN002 - Receber o pedido

REGRAS:

RN003 - Implementar o aceite automático do pedido no pdv

  1. Quando ativo o parâmetro "Habilitar aceite automático dos pedidos" no retaguarda;
    1. PDV irá receber o pedido e já enviar a confirmação deste para a plataforma Go Delivery.
    2. O pedido ficará exibindo a cor "Cinza" no card;
    3. Caso haja produtos de preparo, também deverá executar a rotina de "Ordem de produção"
    4. Caso haja produtos de preparos na configuração do KDS, também devera exibir o pedido na tela do KDS


RN004 – Exibir na tela status - Utilizar o que já temos hoje.


Status do pedido

Cor do pedido

Pedido NovoRoxa
Pedido aceitoCinza
Pedido concluídoVerde
Pedido em entregaAmarelo
Pedido cancelado ou com erroVermelho




Figura 4.1


RN005 - Cancelamento

1. Endpoint para Cancelamento:  POST /orders/{orderId}/requestCancellation

Finalidade: Permite o cancelamento de um pedido.

Requisição:


POST /orders/ord_123/requestCancellation
Content-Type: application/json
Authorization: Bearer <token>

{
  "reason": "string"
}

Campos:

Campo    Tipo      Obrigatório?                Descrição
reason    string    Sim                        Motivo do cancelamento (texto livre)


RN006 - REGRAS:

Quando posso Receber Cancelamento ou Cancelar:

{
  "eventType": "REQUEST_CANCELLATION",
  "orderId": "123456"
}

Se aceita o cancelamento: POST /orders/{orderId}/acceptCancellation
Se não aceita o cancelamento: POST /orders/{orderId}/denyCancellation

Se o pdv solicita o cancelamento:

POST /orders/{orderId}/requestCancellation


Importante:

Os status vindos da plataforma de deliveries, devem refletir no pedido no PDV.

RN007 - Executar baixas de pedidos

  1. Baixa automática
    1. Quando habilitado o parâmetro "Habilita emissão automática de documento fiscal";
      1. Devera fazer a baixa do pedido e emitir o cupom fiscal(rotina que já temos)
  2. Baixa em lote
    1. Quando habilitado o parâmetro "Habilita baixa de pedidos em lote" no retaguarda;
      1. Devem aparecer na tela de baixa em lote todos os pedidos que estão pendentes de baixa.
  3.  Baixa na entrega: Atualizar status do pedido caso mude para status "delivered"
POST /orders/{orderId}/tracking
{
  "currentStatus": "DISPATCHED",
  "deliveryPerson": {
    "name": "João Motoboy",
    "phone": "+5511999999999"
  }
}

E assim que for entregue:

{
  "currentStatus": "DELIVERED"
}


RN008 - Enviar o pedido para a retaguarda

  1. Implementar a sincronia do pedido delivery para a retaguarda. Hoje já enviamos somente a comanda
    1.  Campos do pedido:
      1.  Data e Hora do pedido;
      2.  Número do pedido;
      3. Cliente;
      4. Status do pedido;
      5. Origem da venda(Ifood, Zé delivery, etc...);
      6. Meio de pagamento;
      7. Taxa de entrega;
      8. Acréscimo;
      9. Desconto;
      10. Total do pedido;
      11. Nº Documento fiscal.
    2. Itens do pedido:
      1. Código;
      2. Descrição;
      3. Qtd;
      4. Valor unit.;
      5. Valor total


REGRAS:


Endpoints:

1. GET /events:polling - Receber eventos(Exemplo: Novos pedidos)


Fluxo Completo:

  1.  GET

  2. Servidor retorna  eventos pendentes

  3. Cliente processa cada evento

  4. Para cada evento processado, cliente envia acknowledgment via POST /events/acknowledgment

Exemplo de Requisição:

GET /events:polling HTTP/1.1
Host: api.opendelivery.com
Authorization: Bearer {access_token}

Exemplo de Resposta (200 OK):

{
  "events": [
    {
      "eventId": "evt_123456789",
      "type": "ORDER_CREATED",
      "createdAt": "2023-04-01T12:00:00Z",
      "data": {
        "orderId": "ord_987654321",
        "status": "RECEIVED",
        "merchantId": "mch_123",
        "customer": {
          "name": "João Silva",
          "phone": "+5511999999999"
        }
      }
    }
  ]
}


Casos de Erro:

2. POST /events/acknowledgment - Confirmação de Eventos

Propósito: Confirmar o processamento bem-sucedido de um evento.

Exemplo de Requisição:

POST /events/acknowledgment HTTP/1.1
Host: api.opendelivery.com
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "eventId": "evt_123456789"
}

Respostas Esperadas:

3. POST /orderUpdate (Webhook) - Atualizações em Tempo Real

Propósito: Receber notificações push sobre mudanças de estado.

Estrutura do Payload:

{
  "orderId": "ord_987654321",
  "status": "READY_FOR_PICKUP",
  "timestamp": "2023-04-01T12:30:00Z",
  "metadata": {
    "readyAt": "2023-04-01T12:25:00Z",
    "estimatedPickupTime": "2023-04-01T12:45:00Z"
  }
}

Resposta Esperada:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "receivedAt": "2023-04-01T12:30:05Z"
}

4. GET /orders/{orderId} - Consulta de Pedido

Exemplo Completo:

GET /orders/ord_987654321 HTTP/1.1
Host: api.opendelivery.com
Authorization: Bearer {access_token}

Resposta Detalhada (200 OK):

{
  "orderId": "ord_987654321",
  "status": "CONFIRMED",
  "createdAt": "2023-04-01T12:00:00Z",
  "confirmedAt": "2023-04-01T12:05:00Z",
  "customer": {
    "name": "João Silva",
    "phone": "+5511999999999",
    "deliveryAddress": {
      "street": "Rua das Flores",
      "number": "123",
      "complement": "Apto 101",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01001000"
    }
  },
  "items": [
    {
      "id": "item_001",
      "name": "Pizza Margherita",
      "quantity": 1,
      "unitPrice": 45.90,
      "totalPrice": 45.90,
      "notes": "Sem cebola"
    }
  ],
  "payment": {
    "method": "CREDIT_CARD",
    "amount": 55.90,
    "deliveryFee": 10.00 -- Taxa de entrega
  },
  "timeline": [
    {
      "status": "RECEIVED",
      "timestamp": "2023-04-01T12:00:00Z"
    },
    {
      "status": "CONFIRMED",
      "timestamp": "2023-04-01T12:05:00Z"
    }
  ]
}

5. POST /orders/{orderId}/confirm - Confirmação de Pedido

Exemplo de Chamada:

POST /orders/ord_987654321/confirm HTTP/1.1
Host: api.opendelivery.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "estimatedPreparationTime": 30,
  "notes": "Pedido confirmado com sucesso"
}

Respostas Possíveis:

{
  "status": "CONFIRMED",
  "updatedAt": "2023-04-01T12:05:00Z"
}

6. POST /orders/{orderId}/readyForPickup - Pronto para Coleta

Payload de Exemplo:

{
  "readyAt": "2023-04-01T12:30:00Z",
  "pickupCode": "A1B2C3",
  "storageLocation": "Balcão Principal"
}

Resposta de Sucesso:

{
  "status": "READY_FOR_PICKUP",
  "pickupCode": "A1B2C3",
  "readyAt": "2023-04-01T12:30:00Z"
}

7. POST /orders/{orderId}/dispatch - Despacho para Entrega

Dados Requeridos:

{
  "dispatchedAt": "2023-04-01T12:40:00Z",
  "deliveryPerson": {
    "name": "Carlos Entregador",
    "phone": "+5511988888888",
    "vehicle": {
      "type": "MOTORCYCLE",
      "plate": "ABC1D23"
    }
  }
}

8. POST /orders/{orderId}/delivered - Confirmação de Entrega

Exemplo Completo:

POST /orders/ord_987654321/delivered HTTP/1.1
Host: api.opendelivery.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "deliveredAt": "2023-04-01T13:00:00Z",
  "receivedBy": "João Silva",
  "confirmationMethod": "SIGNATURE",
  "notes": "Assinatura eletrônica coletada"
}

9. POST /v1/orders/{orderId}/validateCode - Validação de Código

Caso de Uso:


{ "code": "A1B2C3", "validationType": "PICKUP" }

Respostas:

{
  "valid": true,
  "message": "Código validado com sucesso"
}

{
  "valid": false,
  "message": "Código incorreto",
  "attemptsRemaining": 2
}

10-12. Endpoints de Cancelamento

Fluxo Completo:

  1. POST /orders/{orderId}/requestCancellation - Solicitação inicial

{
  "reason": "PRODUCT_UNAVAILABLE",
  "details": "Ingrediente principal esgotado"
}

  1. POST /orders/{orderId}/acceptCancellation - Aceite pelo merchant


{
  "refundAmount": 55.90,
  "refundMethod": "ORIGINAL"
}

  1. POST /orders/{orderId}/denyCancellation - Rejeição pelo merchant

{
  "reason": "PREPARATION_ALREADY_STARTED",
  "alternative": "Podemos oferecer substituição do item"
}

13. POST /orders/{orderId}/tracking - Atualização de Rastreio

Exemplo Completo:

{
  "timestamp": "2023-04-01T12:45:00Z",
  "location": {
    "latitude": -23.5505,
    "longitude": -46.6333
  },
  "status": "IN_TRANSIT",
  "estimatedTimeOfArrival": "2023-04-01T13:00:00Z"
}

Padrões Comuns e Observações

Códigos de Status HTTP


Modelo de Erro Padrão

{
  "error": {
    "code": "ERR_INVALID_STATUS",
    "message": "Cannot transition from current status",
    "details": {
      "currentStatus": "RECEIVED",
      "validTransitions": ["CONFIRMED", "CANCELLED"]
    }
  }
}
Headers Obrigatórios

Fluxo de Pedido Bem-Sucedido

Fluxo de Cancelamento

  1. Evento CANCELLATION_REQUESTED via polling

  2. Merchant avalia e decide (accept/deny)

  3. Se aceito:

  4. Se rejeitado: