## 🔐 Autenticação

### Tipo de Autenticação

A API utiliza API Key via header Authorization.

### Como usar a API Key

Inclua a API Key no header Authorization de todas as requisições:

Authorization: sua-api-key-aqui

## 🚦Limites de Requisições (Rate Limit)

Para garantir a estabilidade do serviço, aplicamos os seguintes limites:

| Periodo | Limite |
| -------- | -------- |
| 24 horas | 500 Requisições |

Importante: Se você exceder qualquer um desses limites, receberá um erro 429 Too
Many Requests e precisará aguardar antes de fazer novas requisições

## 🚀 Endpoint

Criar Pedidos

POST /external-integration/order/create

Headers Obrigatórios

Content-Type: application/json
Authorization: sua-api-key-aqui

## 📝 Estrutura de Requisição

### Campos Obrigatórios

| Campo | Tipo | Descrição |
| -------- | -------- | -------- |
| company_id | string (UUID) | ID único da empresa/restaurante |
| payment_code | string (enum) | Código do método de pagamento |
| company_id | object | Dados completos do cliente |

### Campos Opcionais

| Campo | Tipo | Descrição |
| -------- | -------- | -------- |
| value | number | Valor total do pedido |
| details | string | Observações ou detalhes do pedido |
| external_order_id | string | ID do pedido no seu sistema |

## 💳 Códigos de Pagamento Disponíveis

| Código | Descrição |
| -------- | -------- |
| ONLINE | Pagamento online/pré-pago |
|MONEY | Dinheiro |
|CARD | Cartão de crédito |
|DEBIT | Cartão de débito |
|PIX | PIX |

## 👤 Estrutura do Cliente

### Campos Obrigatórios do Cliente

| Campo | Tipo | Descrição |
| -------- | -------- | -------- |
| name | string | Nome completo do cliente |
| phone | string | Telefone do cliente |
| address | object | Endereço completo do cliente |

### Estrutura do Endereço

| Campo | Tipo | Obrigatório |Descrição
| -------- | -------- | -------- |--------
| name | string | ✅ |Nome/apelido do endereço
| street_name | string | ✅ | Nome da rua
| number | string | ✅ |Número do endereço
| neighborhood | string | ✅ | Bairro
| city | string | ✅ |Cidade
| state | string | ✅ |Estado (UF)
| zipCode | string | ✅ |CEP
| complement | string | ❌ |Complemento
| latitude | number | ❌ |Latitude (coordenada)
| longitude | number | ❌ | Longitude (coordenada)

## 📚 Exemplo de Requisição

{
    "company_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_code": "ONLINE",
    "value": 2500,
    "details": "Pizza grande de calabresa, sem cebola",
    "external_order_id": "PED-2024-001",
    "customer": {
    "name": "João Silva",
    "phone": "11999887766",
    "address": {
    "name": "Casa",
    "street_name": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01234-567",
    "latitude": -23.5505,
    "longitude": -46.6333
    }
  }
}

Requisição caso o endereço de coleta seja diferente do
endereço da empresa:

{
    "company_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_code": "ONLINE",
    "value": 2500,
    "details": "Pizza grande de calabresa, sem cebola",
    "external_order_id": "PED-2024-001",
    "customer": {
    "name": "João Silva",
    "phone": "11999887766",
    "address": {
    "name": "Casa",
    "street_name": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01234-567",
    "latitude": -23.5505,
    "longitude": -46.6333
  }
},
"origin_address": {
    "street_name": "Avenida Arno Carlos Gracher",
    "neighborhood": "Centro 2",
    "complement": "Casa",
    "zipCode": "88350310",
    "city": "Brusque",
    "state": "SC",
    "number": "662",
    "name": "Gabriel origin",
    "latitude": -27.132851,
    "longitude": -42.017300
  }
}

## ✅ Exemplo de Resposta de Sucesso

{
    "msg": "Order created successfully",
    "order_id": "8f58da53-f923-43fa-a771-66beba5a39f8",
}

## ❌ Códigos de Erro

| Código | Descrição | Solução |
| -------- | -------- | -------- |
| 400 | Dados inválidos | Verifique se todos os campos obrigatórios estão preenchidos corretamente |
| 401 | Não autorizado | Verifique se a API Key está correta no header Authorization |
| 404 | Empresa não encontrada | Verifique se o company_id está correto |
| 429 | Limite de requisições excedido | Aguarde antes de fazer nova requisição |
| 500 | Erro interno do servidor | Tente novamente em alguns minutos |

### Exemplo de Erro de Validação

{
    "statusCode": 400,
    "message": [
        "company_id must be a UUID",
        "payment_code must be one of the following values: ONLINE, MONEY, CARD,
        DEBIT, PIX",
        "customer.name should not be empty"
    ],
    "error": "Bad Request"
}

## 🟢 Status do Pedido

### 🚦Limites de Requisições (Rate Limit)

Para garantir a estabilidade do serviço, aplicamos os seguintes limites:

| Período | Limite |
| -------- | -------- |
| Por dia | 5000 requisições |

Importante: Se você exceder qualquer um desses limites, receberá um erro **429 Too
Many Requests** e precisará aguardar antes de fazer novas requisições.

### Atualização de Status:

Rota PUT: /external-integration/order/status

Body:

{
    "order_id": "d8955eae-9c08-4853-9940-61bf3e3681b3",
    "status": "READY"
}

Resultado: Status 200

| Status | Descrição |
| -------- | -------- |
| READY | Para prontificar o pedidos, informando que o entregador pode ir retirar |
| CANCELED | Para cancelar um pedido cadastrado |

### Consulta Status:

Rota GET: /external-integration/order/status/:order_id

Resultado:

{
    "order_id": "d8955eae-9c08-4853-9940-61bf3e3681b3",
    "status": "READY"
}

| Status | Descrição |
| -------- | -------- |
| PENDING | Pedidos aguardando prontificação |
| READY | Pedido pronto para retirada |
| DISPATCHED | Pedido despachado para entregador |
| ON_WAY_TO_PICKUP | Entregador a caminho da retirada |
| ON_STORE | Entregador no estabelecimento |
| PICKED_UP | Entregador em rota de entrega |
| ON_CLIENT | Entregador no cliente |
| DELIVERED | Pedido entregue |
| CANCELED | Pedido cancelado |

## 🔧 Dicas de Implementação

1. **Validação de UUID**
O company_id deve ser um UUID válido. Exemplo:
123e4567-e89b-12d3-a456-426614174000
2. **Formato do Telefone**
Envie o telefone apenas com números: 11999887766
3. **Coordenadas (Opcional)**
Se disponível, envie latitude e longitude para melhor precisão na entrega.
4. **Rate Limit**
Implemente um sistema de controle de requisições para não exceder os limites