---
# System prepended metadata

title: ' API de Integração Externa - Criação de Pedidos'

---



## 🔐 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