Farmatch API Docs

Visão geral

Os endpoints de pedidos operam com isolamento por tenant e permitem controle de idempotência para evitar duplicações.

A criação (POST /orders) valida catálogo, disponibilidade na loja e estoque.
A listagem e a consulta retornam apenas pedidos da loja autenticada.
A atualização de status registra evento de timeline internamente.

POST/api/v1/orders

Cria pedido externo para a loja autenticada com controle de idempotência por provedor.

Headers

Headers aceitos para criação de pedido.

Nome	Tipo	Obrigatório	Descrição
`x-api-key`	string	Sim	Chave pública da loja.
`x-idempotency-key`	string	Não	Opcional. Se enviado, deve ter no máximo 120 caracteres.
`content-type`	application/json	Sim	Tipo do payload enviado.

Body: campos de topo

Estrutura principal do payload.

Nome	Tipo	Obrigatório	Descrição
`provider`	string	Sim	Origem do pedido (2..64, permitido: letras, números, . _ -).
`externalOrderId`	string	Não	Identificador externo do pedido (recomendado para idempotência).
`sourceChannel`	string	Não	Canal de origem do pedido.
`customer`	object	Não	Cliente do pedido. Quando enviado: name e phone são obrigatórios.
`paymentMethod`	string	Sim	Forma de pagamento.
`changeFor`	number	Não	Troco em centavos (>= 0).
`items`	array	Sim	Lista de itens com EAN13 e quantidade.
`delivery`	object	Sim	Bloco de entrega (inclui taxa em centavos).

Body: itens

Regras para cada item do array items.

Nome	Tipo	Obrigatório	Descrição
`items[].ean13`	string	Sim	EAN13 com mínimo de 8 caracteres.
`items[].quantity`	number	Sim	Quantidade inteira positiva.

Body: entrega

Campos do objeto delivery.

Nome	Tipo	Obrigatório	Descrição
`delivery.type`	string	Sim	Tipo de entrega.
`delivery.address`	string	Sim	Endereço completo em formato livre.
`delivery.zipCode`	string	Não	CEP (mínimo de 3 caracteres).
`delivery.street`	string	Não	Logradouro.
`delivery.number`	string	Não	Número.
`delivery.complement`	string	Não	Complemento.
`delivery.neighborhood`	string	Não	Bairro.
`delivery.city`	string	Não	Cidade.
`delivery.state`	string	Não	UF/estado.
`delivery.fee`	number	Sim	Taxa de entrega em centavos (>= 0).
`delivery.etaMinutes`	number	Não	Previsão de entrega em minutos (inteiro positivo).

Body exemplo

{
  "provider": "erp_x",
  "externalOrderId": "PEDIDO-ERP-123",
  "sourceChannel": "marketplace_b2b",
  "customer": {
    "name": "Maria Souza",
    "phone": "21999998888"
  },
  "paymentMethod": "pix",
  "changeFor": 5000,
  "items": [
    {
      "ean13": "7891234567890",
      "quantity": 2
    },
    {
      "ean13": "7894561239876",
      "quantity": 1
    }
  ],
  "delivery": {
    "type": "delivery",
    "address": "Rua Exemplo, 123 - Centro, Rio de Janeiro - RJ, 20000-000",
    "zipCode": "20000-000",
    "street": "Rua Exemplo",
    "number": "123",
    "neighborhood": "Centro",
    "city": "Rio de Janeiro",
    "state": "RJ",
    "fee": 750,
    "etaMinutes": 45
  }
}

Regras de idempotência

Comportamento para evitar pedidos duplicados.

Nome	Tipo	Obrigatório	Descrição
`externalOrderId`	string	Não	Quando enviado, é usado como chave idempotente por loja + provider.
`x-idempotency-key`	string	Não	Pode substituir externalOrderId. Se ambos forem enviados, precisam ser iguais.
`idempotentReplay`	boolean	Não	true quando a API retorna um pedido já existente (sem recriar).

Respostas

Status possíveis na criação de pedido.

201Pedido criado200Replay idempotente400Validação e regras de negócio401API key ausente ou inválida403Loja inativa ou chave revogada409Estoque insuficiente

Response 201 (novo pedido)

{
  "requestId": "1998af95-488f-47b0-a1f8-ecfd56b1200a",
  "success": true,
  "created": true,
  "idempotentReplay": false,
  "orderId": "j57f8r8r9k0m1n2p3q4r5s6t7u8v9w0x",
  "status": "created",
  "total": 3330,
  "provider": "erp_x",
  "externalOrderId": "PEDIDO-ERP-123"
}

Response 200 (replay idempotente)

{
  "requestId": "be6e0944-b6ad-4144-ab42-c34c610522ea",
  "success": true,
  "created": false,
  "idempotentReplay": true,
  "orderId": "j57f8r8r9k0m1n2p3q4r5s6t7u8v9w0x",
  "status": "created",
  "total": 3330,
  "provider": "erp_x",
  "externalOrderId": "PEDIDO-ERP-123"
}

Erros específicos do POST /orders

Códigos estáveis definidos no backend.

Nome	Tipo	Obrigatório	Descrição
`invalid_idempotency_key`	400	Não	x-idempotency-key acima de 120 caracteres.
`idempotency_key_mismatch`	400	Não	externalOrderId e x-idempotency-key diferentes.
`payment_method_not_available`	400	Não	Forma de pagamento não permitida na loja.
`invalid_ean13`	400	Não	EAN13 vazio ou inválido no payload.
`product_not_found`	400	Não	EAN13 não encontrado no catálogo global.
`product_not_available_in_store`	400	Não	Produto não disponível na loja autenticada.
`order_creation_failed`	400	Não	Falha genérica de criação sem código específico.
`insufficient_stock`	409	Não	Estoque insuficiente para um ou mais itens.
`missing_api_key`	401	Não	Header x-api-key não enviado.
`invalid_api_key`	401	Não	API key não encontrada.
`revoked_api_key`	403	Não	API key revogada.
`store_not_active`	403	Não	Loja da API key está inativa.
`Validação de schema (Zod)`	400	Não	Falha de validação de body pelo schema Zod (sem error.code estável garantido).

GET/api/v1/orders

Lista pedidos da loja autenticada com filtro de status e limite.

Query Params

Parâmetros aceitos na listagem.

Nome	Tipo	Obrigatório	Descrição
`status`	string	Não	created \| confirmed \| preparing \| ready \| delivering \| delivered \| canceled
`limit`	number	Não	Inteiro entre 1 e 200 (padrão: 100).

Exemplo de request

GET /api/v1/orders?status=created&limit=20

Response 200

{
  "requestId": "5ec44e09-2c35-4dc2-97d2-5be3d510f352",
  "orders": [
    {
      "id": "j57f8r8r9k0m1n2p3q4r5s6t7u8v9w0x",
      "storeId": "loja_abc123",
      "status": "created",
      "paymentMethod": "pix",
      "total": 3330,
      "sourceProvider": "erp_x",
      "sourceExternalOrderId": "PEDIDO-ERP-123",
      "createdAt": 1739543807123
    }
  ]
}

Erros do GET /orders

Códigos estáveis definidos no backend.

Nome	Tipo	Obrigatório	Descrição
`invalid_limit`	400	Não	limit fora do intervalo de 1 a 200.
`invalid_status`	400	Não	status fora da lista de valores aceitos.
`missing_api_key`	401	Não	Header x-api-key não enviado.
`invalid_api_key`	401	Não	API key não encontrada.
`revoked_api_key`	403	Não	API key revogada.
`store_not_active`	403	Não	Loja da API key está inativa.

GET/api/v1/orders/:orderId

Retorna um pedido específico da loja autenticada.

Path Params

Parâmetro de rota obrigatório.

Nome	Tipo	Obrigatório	Descrição
`orderId`	string	Sim	Identificador do pedido.

Exemplo de request

GET /api/v1/orders/j57f8r8r9k0m1n2p3q4r5s6t7u8v9w0x

Response 200

{
  "requestId": "16a9b445-3f58-4c13-a0cb-96bc1ec4e1a2",
  "order": {
    "id": "j57f8r8r9k0m1n2p3q4r5s6t7u8v9w0x",
    "storeId": "loja_abc123",
    "status": "created",
    "paymentMethod": "pix",
    "total": 3330,
    "items": [
      {
        "templateId": "j57f8r8r9k0m1n2p3q4r5s6t7u8v9w0x",
        "name": "Dipirona 500mg",
        "price": 1290,
        "quantity": 2
      }
    ],
    "delivery": {
      "type": "delivery",
      "address": "Rua Exemplo, 123 - Centro, Rio de Janeiro - RJ",
      "fee": 750
    },
    "createdAt": 1739543807123
  }
}

Erros do GET /orders/:orderId

Códigos estáveis definidos no backend.

Nome	Tipo	Obrigatório	Descrição
`order_not_found_in_tenant`	404	Não	Pedido não encontrado para a loja da API key.
`missing_api_key`	401	Não	Header x-api-key não enviado.
`invalid_api_key`	401	Não	API key não encontrada.
`revoked_api_key`	403	Não	API key revogada.
`store_not_active`	403	Não	Loja da API key está inativa.

PATCH/api/v1/orders/:orderId

Atualiza o status de um pedido e registra evento de status.

Body

Payload aceito para atualização de status.

Nome	Tipo	Obrigatório	Descrição
`status`	string	Sim	created \| confirmed \| preparing \| ready \| delivering \| delivered \| canceled

Body exemplo

{
  "status": "confirmed"
}

Response 200

{
  "requestId": "1998af95-488f-47b0-a1f8-ecfd56b1200a",
  "success": true,
  "orderId": "j57f8r8r9k0m1n2p3q4r5s6t7u8v9w0x",
  "status": "confirmed"
}

Erros do PATCH /orders/:orderId

Códigos estáveis definidos no backend.

Nome	Tipo	Obrigatório	Descrição
`order_not_found_in_tenant`	404	Não	Pedido não encontrado para a loja da API key.
`missing_api_key`	401	Não	Header x-api-key não enviado.
`invalid_api_key`	401	Não	API key não encontrada.
`revoked_api_key`	403	Não	API key revogada.
`store_not_active`	403	Não	Loja da API key está inativa.
`Validação de schema (Zod)`	400	Não	Falha de validação de body pelo schema Zod (sem error.code estável garantido).

Pedidos

Visão geral

Headers

Body: campos de topo

Body: itens

Body: entrega

Body exemplo

Regras de idempotência

Respostas

Response 201 (novo pedido)

Response 200 (replay idempotente)

Erros específicos do POST /orders

Query Params

Exemplo de request

Response 200

Erros do GET /orders

Path Params

Exemplo de request

Response 200

Erros do GET /orders/:orderId

Body

Body exemplo

Response 200

Erros do PATCH /orders/:orderId

On this page