> ## Documentation Index > Fetch the complete documentation index at: https://docs.cardapioweb.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar pedido > Cria um novo pedido associado à empresa autenticada. **Autenticação**: Este endpoint requer dupla autenticação via headers `X-API-KEY` e `X-PARTNER-KEY`. Os pedidos criados via API iniciam sempre no status `waiting_confirmation`, com `order_timing` igual a `immediate` e `sales_channel` igual a `integration`. Atualmente não aceitamos pedidos agendados via API. O ID retornado é o identificador único do pedido no sistema e deve ser utilizado nos endpoints de detalhes do pedido e mudanças de status. Para obter os `item_id` e `option_id` disponíveis, utilize o endpoint `GET /api/partner/v1/catalog`. Para obter os `payment_method_id` e `brand_id`, utilize o endpoint `GET /api/partner/v1/merchant/payment_methods`. ### Regras de validação **Totais:** `order_amount` deve corresponder exatamente a `sum(items.total_price) + delivery_fee + additional_fee - discounts`. **Itens:** `total_price` de cada item deve corresponder a `(unit_price + sum(options.quantity × options.unit_price)) × quantity`. **Pagamentos:** a soma de todos os valores `total` deve ser exatamente igual ao `order_amount`. O `payment_method_id` e o `brand_id` (quando informado) devem estar ativos no estabelecimento. ## OpenAPI ````yaml /reference/api-pedidos.json post /api/partner/v1/orders openapi: 3.1.0 info: title: API Pedidos version: '1.0' contact: email: integracao@cardapioweb.com name: Cardápio Web url: https://cardapioweb.com description: >- A API de pedidos é responsável pelo acompanhamento dos pedidos de um estabelecimento e pelas mudanças de status deles. servers: - url: https://integracao.sandbox.cardapioweb.com description: Sandbox - url: https://integracao.cardapioweb.com description: Produção security: - apiKey: [] paths: /api/partner/v1/orders: parameters: [] post: summary: Criar pedido description: >- Cria um novo pedido associado à empresa autenticada. **Autenticação**: Este endpoint requer dupla autenticação via headers `X-API-KEY` e `X-PARTNER-KEY`. Os pedidos criados via API iniciam sempre no status `waiting_confirmation`, com `order_timing` igual a `immediate` e `sales_channel` igual a `integration`. Atualmente não aceitamos pedidos agendados via API. O ID retornado é o identificador único do pedido no sistema e deve ser utilizado nos endpoints de detalhes do pedido e mudanças de status. Para obter os `item_id` e `option_id` disponíveis, utilize o endpoint `GET /api/partner/v1/catalog`. Para obter os `payment_method_id` e `brand_id`, utilize o endpoint `GET /api/partner/v1/merchant/payment_methods`. ### Regras de validação **Totais:** `order_amount` deve corresponder exatamente a `sum(items.total_price) + delivery_fee + additional_fee - discounts`. **Itens:** `total_price` de cada item deve corresponder a `(unit_price + sum(options.quantity × options.unit_price)) × quantity`. **Pagamentos:** a soma de todos os valores `total` deve ser exatamente igual ao `order_amount`. O `payment_method_id` e o `brand_id` (quando informado) devem estar ativos no estabelecimento. operationId: create-order requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrder' examples: Pedido delivery: value: order_id: PEDIDO_12345 display_id: '001' created_at: '2025-01-15T14:30:00-03:00' observation: Observação geral sobre o pedido order_type: delivery customer: phone: '11998989898' name: João Silva email: joao@email.com document_number: '12345678909' totals: order_amount: 106 delivery_fee: 10 additional_fee: 2 discounts: 5 delivery_address: state: CE city: Fortaleza neighborhood: Meireles street: Av. da Abolição number: '2456' complement: Apto 000 reference: Casa de portão verde postal_code: '60125160' coordinates: latitude: -3.7263942 longitude: -38.4981303 items: - item_id: PIZZA_001 external_code: SKU_PIZZA_001 name: Pizza Margherita quantity: 2 unit_price: 35 total_price: 90 observation: Sem cebola options: - option_id: OPT_001 external_code: SKU_EXTRA_QUEIJO name: Extra queijo quantity: 2 unit_price: 5 - item_id: BEBIDA_001 name: Coca-Cola 350ml quantity: 2 unit_price: 4.5 total_price: 9 payments: - total: 56 payment_method_id: 102 change_for: 100 - total: 50 payment_method_id: 103 responses: '201': description: Pedido criado com sucesso. content: application/json: schema: $ref: '#/components/schemas/CreatedOrder' examples: Sucesso: value: id: 1001 status: waiting_confirmation order_type: delivery order_timing: immediate sales_channel: integration created_at: '2025-01-15T14:30:00-03:00' updated_at: '2025-01-15T14:30:00-03:00' '401': $ref: '#/components/responses/Unauthorized' '422': description: Dados inválidos ou falha no processamento. content: application/json: schema: $ref: '#/components/schemas/ValidationErrors' examples: Erros de validação: value: errors: - Order already exists - Customer phone must have a valid format - >- Totals order_amount (87.0) does not match calculation: items(99.0) + delivery(10.0) + additional(2.0) - discounts(5.0) = 106.0 - >- Payments[0] payment_method not found or inactive for this company - Delivery address state CW does not exist '429': $ref: '#/components/responses/TooManyRequests' components: schemas: CreateOrder: type: object title: Criar pedido required: - order_id - display_id - order_type - totals - items - payments properties: order_id: type: string description: >- Identificador único do pedido na plataforma integradora. Deve ser único. display_id: type: string description: 'Identificador visível para o cliente (ex: número sequencial).' order_type: type: string enum: - delivery - takeout - onsite description: Tipo do pedido. customer: type: object nullable: true allOf: - $ref: '#/components/schemas/CreateOrderCustomer' description: Dados do cliente. Obrigatório para delivery. totals: $ref: '#/components/schemas/CreateOrderTotals' delivery_address: $ref: '#/components/schemas/CreateOrderDeliveryAddress' description: 'Endereço de entrega. Obrigatório para `order_type: delivery`.' items: type: array minItems: 1 maxItems: 50 description: Lista de itens do pedido. Mínimo 1, máximo 50 itens. items: $ref: '#/components/schemas/CreateOrderItem' payments: type: array maxItems: 5 description: >- Formas de pagamento. Máximo 5 pagamentos. A soma dos `total` deve ser igual ao `order_amount`. items: $ref: '#/components/schemas/CreateOrderPayment' created_at: type: string format: date-time description: Data/hora da criação do pedido (ISO 8601). Não pode ser futura. observation: type: string description: Observações gerais do pedido. CreatedOrder: type: object title: Pedido criado description: Resposta retornada após a criação bem-sucedida de um pedido via API. properties: id: type: integer description: >- ID único do pedido no sistema. Utilizado nos endpoints de detalhes do pedido e mudanças de status. status: type: string enum: - waiting_confirmation description: >- Status atual do pedido. Pedidos criados via API iniciam sempre em `waiting_confirmation`. order_type: type: string enum: - delivery - takeout - onsite description: Tipo do pedido. order_timing: type: string enum: - immediate description: >- Momento de entrega do pedido. Atualmente sempre `immediate` para pedidos criados via API. sales_channel: type: string enum: - integration description: Canal de venda. Sempre `integration` para pedidos criados via API. created_at: type: string format: date-time description: Data/hora de criação (ISO 8601). updated_at: type: string format: date-time description: Data/hora da última atualização (ISO 8601). required: - id - status - order_type - order_timing - sales_channel - created_at - updated_at ValidationErrors: type: object title: Erros de validação properties: errors: type: array description: Lista de mensagens de erro. items: type: string required: - errors CreateOrderCustomer: type: object title: Cliente description: >- Dados do cliente. Obrigatório apenas para pedidos do tipo `delivery`. Para pedidos `takeout` ou `onsite`, pode ser omitido ou enviado como `null`. Quando informado, o cliente é identificado exclusivamente pelo campo `phone`. Se não existir um cliente com o telefone informado, um novo cliente será criado. Se já existir, apenas campos vazios serão atualizados — campos já preenchidos não serão sobrescritos. required: - phone properties: phone: type: string description: Telefone do cliente. Apenas números, exatamente 11 dígitos. example: '11998989898' name: type: string description: Nome completo do cliente. email: type: string format: email description: E-mail do cliente. Formato válido se presente. document_number: type: string description: CPF ou CNPJ. 11 ou 14 dígitos se presente. example: '12345678909' CreateOrderTotals: type: object title: Totais description: >- Valores totais do pedido. O order_amount deve corresponder exatamente ao cálculo: order_amount = sum(items.total_price) + delivery_fee + additional_fee - discounts required: - order_amount properties: order_amount: type: number minimum: 0 description: >- Valor total do pedido. Deve corresponder ao cálculo: sum(items.total_price) + delivery_fee + additional_fee - discounts. delivery_fee: type: number minimum: 0 description: >- Taxa de entrega. Obrigatória para `delivery`, deve ser 0 para outros tipos. additional_fee: type: number minimum: 0 description: Taxas adicionais. discounts: type: number minimum: 0 description: Valor total de descontos. CreateOrderDeliveryAddress: type: object title: Endereço de entrega description: 'Obrigatório para `order_type: delivery`.' required: - state - city - neighborhood - street - postal_code - coordinates properties: state: type: string description: Estado (UF). example: CE city: type: string description: Cidade conforme cadastro do IBGE. example: Fortaleza neighborhood: type: string description: Bairro. street: type: string description: Logradouro. number: type: string description: Número do endereço. complement: type: string description: Complemento (apto, bloco, etc.). reference: type: string description: Ponto de referência. postal_code: type: string description: CEP. Exatamente 8 dígitos. example: '60125160' coordinates: $ref: '#/components/schemas/CreateOrderCoordinates' CreateOrderItem: type: object title: Item do pedido description: >- Item do pedido. O sistema tentará associar o produto seguindo esta ordem: 1) item_id, 2) external_code, 3) sem associação. A vinculação pode ser feita posteriormente pelo estabelecimento no portal administrativo. O total_price deve corresponder ao cálculo: total_price = (unit_price + sum(options.quantity × options.unit_price)) × quantity required: - name - quantity - unit_price - total_price properties: name: type: string description: Nome do produto. quantity: type: integer minimum: 1 description: Quantidade. unit_price: type: number minimum: 0 description: Preço unitário do produto sem complementos. total_price: type: number minimum: 0 description: Preço total do item. item_id: type: string description: ID do produto no sistema Cardápio Web. external_code: type: string description: 'Código de referência no sistema externo (ex: SKU, Código PDV).' observation: type: string description: Observações do item. options: type: array maxItems: 20 description: Opções do item. Máximo de 20 opções. items: $ref: '#/components/schemas/CreateOrderItemOption' CreateOrderPayment: type: object title: Pagamento description: >- Forma de pagamento. A soma de todos os valores `total` deve ser exatamente igual ao `order_amount` do pedido. O `payment_method_id` e o `brand_id` (quando informado) devem estar ativos no estabelecimento. required: - total - payment_method_id properties: total: type: number exclusiveMinimum: 0 description: Valor pago neste método. payment_method_id: type: integer description: >- ID do método de pagamento. Obtido via `GET /api/partner/v1/merchant/payment_methods`. brand_id: type: integer description: >- ID da bandeira do pagamento. Corresponde ao `id` no array `brands` do método de pagamento. change_for: type: number description: >- Valor para troco. Apenas para pagamento em dinheiro. Deve ser maior que o `total`. Unauthorized: type: object x-stoplight: id: 5cdf37ldhxqd8 examples: - code: 4010 message: Token inválido title: Unauthorized x-internal: false properties: code: type: integer description: Código interno de identificação do erro message: type: string description: Mensagem de resumo do erro required: - code - message CreateOrderCoordinates: type: object title: Coordenadas required: - latitude - longitude properties: latitude: type: number description: Latitude do endereço. longitude: type: number description: Longitude do endereço. CreateOrderItemOption: type: object title: Opção do item description: >- Opção do item. O sistema tentará associar a opção seguindo esta ordem: 1) `option_id`, 2) `external_code`, 3) sem associação. A vinculação pode ser feita posteriormente pelo estabelecimento no portal administrativo. required: - name - quantity - unit_price properties: name: type: string description: Nome da opção. quantity: type: integer minimum: 1 description: Quantidade. unit_price: type: number minimum: 0 description: Preço unitário. option_id: type: string description: ID da opção no sistema Cardápio Web. external_code: type: string description: Código da opção no sistema externo. responses: Unauthorized: description: >- Não autorizado. Não foi enviado o token no header "X-API-KEY" ou ele é inválido. content: application/json: schema: $ref: '#/components/schemas/Unauthorized' TooManyRequests: description: >- Muitas requisições foram feitas em um curto período. Verifique nossas regras de rate limit. content: {} securitySchemes: apiKey: name: X-API-KEY type: apiKey in: header description: >- Token específico do estabelecimento integrado. Disponível na seção de integrações do Portal do estabelecimento. ````