FoodCRM API

Integração REST para enviar pedidos à FoodCRM. Um endpoint, autenticação por API key.

API key

Gere sua chave no painel da FoodCRM:

1. Acesse Integrações
2. Crie ou copie a API key da sua loja
3. Guarde a chave completa: ela é exibida apenas uma vez

Todas as requisições devem incluir o header:

x-api-key: fcrm_abcd1234_SEU_SECRET_AQUI

POST /v1/orders

Envia um pedido para a loja vinculada à API key.

Método	POST
Path	/v1/orders
Content-Type	application/json
Auth	Header x-api-key

Exemplo

curl -X POST "https://api.foodcrm.com.br/v1/orders" \
  -H "Content-Type: application/json" \
  -H "x-api-key: fcrm_abcd1234_SEU_SECRET_AQUI" \
  -d '{
    "externalOrderId": "order-ext-12345",
    "displayId": 12345,
    "status": "closed",
    "orderType": "delivery",
    "orderTiming": "instant",
    "deliveryFee": 5,
    "serviceFee": 0,
    "additionalFee": 0,
    "total": 55.9,
    "customer": {
      "name": "João Silva",
      "phone": "41997269435"
    },
    "items": [
      {
        "itemId": 100,
        "name": "X-Burger",
        "quantity": 2,
        "unitPrice": 25,
        "totalPrice": 50,
        "kind": "item",
        "status": "confirmed"
      }
    ],
    "payments": [
      {
        "total": 55.9,
        "paymentType": "online",
        "status": "paid",
        "paymentMethod": "credit_card",
        "paymentFee": 0
      }
    ],
    "createdAt": "2026-06-18T18:30:00.000Z",
    "updatedAt": "2026-06-18T18:45:00.000Z"
  }'

Campos obrigatórios

Campo	Tipo	Descrição
externalOrderId	string	ID único do pedido no seu sistema
displayId	number	Número da comanda
status	string	closed, cancelled, pending, confirmed, preparing, ready, delivered
orderType	string	delivery, takeout, dine_in, indoor, pickup
orderTiming	string	instant ou scheduled
deliveryFee	number	Taxa de entrega
serviceFee	number	Taxa de serviço
additionalFee	number	Taxas adicionais
total	number	Valor total
customer	object	Nome + phone ou cpf
createdAt	string	ISO 8601
updatedAt	string	ISO 8601

Campos opcionais comuns: items, payments, deliveryAddress, salesChannel, observation.

Respostas de sucesso

202 Pedido recebido

{
  "status": "queued",
  "jobId": "company-uuid:order-ext-12345",
  "externalOrderId": "order-ext-12345"
}

200 Pedido já enviado

Reenviar o mesmo externalOrderId não cria duplicata:

{
  "status": "already_received",
  "externalOrderId": "order-ext-12345",
  "orderId": "550e8400-e29b-41d4-a716-446655440000"
}

Erros

Formato padrão:

{
  "statusCode": 400,
  "message": "Descrição do erro",
  "error": "Bad Request"
}

401 Autenticação

message	Causa
API key ausente	Header x-api-key não enviado
API key inválida	Formato ou chave incorreta
API key revogada	Chave desativada
API key expirada	Chave expirada
Empresa inativa	Loja inativa

400 Payload inválido

{
  "statusCode": 400,
  "message": "Informe pelo menos um entre phone ou cpf do cliente",
  "error": "Bad Request"
}

Validações comuns: campos obrigatórios ausentes, enums inválidos, partnerId inexistente.

503 Indisponível

{
  "statusCode": 503,
  "message": "Fila de ingestão indisponível no momento",
  "error": "Service Unavailable"
}

Recomendado: retry com backoff exponencial.

Resumo

Código	Situação
202	Pedido novo sucesso
200	Pedido duplicado tratar como sucesso
400	Corrigir payload
401	Verificar API key em Integrações
503	Tentar novamente