Farmatch API Docs

Visão geral

Os endpoints de estoque operam sempre no tenant resolvido pela x-api-key.

GET /stock é otimizado para sincronização incremental e cache condicional.
POST /stock/snapshot aplica atualização em lote de preço/estoque.

GET/api/v1/stock

Consulta estoque da loja autenticada com filtros, busca textual e paginação por cursor.

Headers

Headers aceitos para leitura de estoque.

Nome	Tipo	Obrigatório	Descrição
`x-api-key`	string	Sim	Chave de autenticação da loja.
`if-none-match`	string	Não	ETag da última resposta para cache condicional.

Query Params

Parâmetros com validação de formato e limites.

Nome	Tipo	Obrigatório	Descrição
`limit`	number	Não	Inteiro entre 1 e 200. Padrão: 50.
`cursor`	number	Não	Inteiro maior ou igual a 0. Ex.: 0, 50, 100.
`q`	string	Não	Busca textual (máximo de 120 caracteres).
`ean13`	string	Não	Busca exata por EAN13.
`inStock`	boolean	Não	Aceita somente true ou false.
`updatedSince`	string\|number	Não	Timestamp (ms) ou data ISO válida.

Exemplo de request

GET /api/v1/stock?limit=50&cursor=0&q=dipirona&inStock=true

Respostas

Status retornados pela consulta de estoque.

200Consulta concluída304Not Modified (ETag)400Parâmetros inválidos401API key ausente ou inválida403Loja inativa ou chave revogada

Response 200

{
  "requestId": "de03e7dd-5470-43ef-bfa8-e95fd00ea7ef",
  "items": [
    {
      "storeProductId": "j97f4q1s9mxhgr6sbyb6zz0f3d7j4x1x",
      "templateId": "j57f8r8r9k0m1n2p3q4r5s6t7u8v9w0x",
      "ean13": "7891234567890",
      "name": "Dipirona 500mg",
      "brand": "Genérico",
      "price": 1290,
      "originalPrice": 1490,
      "stock": 42,
      "updatedAt": 1739543807123,
      "requiresPrescription": false,
      "tags": ["analgésico", "dor"],
      "photoUrl": "https://cdn.farmatch.com/produtos/dipirona.png"
    }
  ],
  "pagination": {
    "limit": 50,
    "cursor": "0",
    "nextCursor": "50",
    "hasMore": true,
    "total": 231
  },
  "filters": {
    "q": "dipirona",
    "ean13": null,
    "inStock": true,
    "updatedSince": null
  },
  "latestUpdatedAt": 1739543807123
}

Cache HTTP (ETag)

A resposta inclui ETag, Cache-Control e Vary.
Quando o If-None-Match enviado corresponde ao ETag atual, o endpoint retorna 304 Not Modified sem body.
Esse fluxo é recomendado para polling frequente de catálogo.

Erros específicos do GET /stock

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_cursor`	400	Não	cursor não é inteiro válido maior ou igual a 0.
`invalid_in_stock`	400	Não	inStock diferente de true/false.
`invalid_updated_since`	400	Não	updatedSince não é data ISO nem timestamp válido.
`invalid_query`	400	Não	q acima do limite de 120 caracteres.
`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.

POST/api/v1/stock/snapshot

Atualiza preço/estoque para a loja autenticada com lote de itens.

Headers

Headers obrigatórios para envio de snapshot.

Nome	Tipo	Obrigatório	Descrição
`x-api-key`	string	Sim	Chave de autenticação da loja.
`content-type`	application/json	Sim	Tipo de payload aceito no endpoint.

Body

Schema de entrada para atualização em lote.

Nome	Tipo	Obrigatório	Descrição
`items`	array	Sim	Lista com pelo menos um item.
`items[].ean13`	string	Sim	EAN13 com mínimo de 8 caracteres.
`items[].name`	string	Não	Obrigatório para criar template novo.
`items[].brand`	string	Não	Marca do produto (opcional).
`items[].description`	string	Não	Descrição comercial (opcional).
`items[].bula`	string	Não	Informação de bula (opcional).
`items[].price`	number	Sim	Preço em centavos (>= 0).
`items[].stock`	number	Sim	Quantidade inteira em estoque (>= 0).
`items[].requiresPrescription`	boolean	Não	Define exigência de receita.
`items[].tags`	string[]	Não	Tags de busca e categorização.

Body exemplo

{
  "items": [
    {
      "ean13": "7891234567890",
      "name": "Dipirona 500mg",
      "brand": "Genérico",
      "description": "Analgésico e antitérmico.",
      "bula": "Uso adulto e pediátrico conforme orientação médica.",
      "price": 1290,
      "stock": 42,
      "requiresPrescription": false,
      "tags": ["analgésico", "dor"]
    }
  ]
}

Regras de processamento

Comportamento do backend durante o snapshot.

Nome	Tipo	Obrigatório	Descrição
`templatesCreated`	number	Não	Quantidade de templates novos criados.
`productsCreated`	number	Não	Quantidade de storeProducts criados.
`productsUpdated`	number	Não	Quantidade de storeProducts atualizados.
`skipped`	number	Não	Itens ignorados no processamento.
`processed`	number	Não	Total de itens recebidos no payload.

Respostas

Status retornados no processamento do snapshot.

200Snapshot processado400Validação de entrada401API key ausente ou inválida403Loja inativa ou chave revogada

Response 200

{
  "requestId": "8d1a4ce0-2bc0-4ae4-ae5d-7b23d39d1f89",
  "success": true,
  "templatesCreated": 0,
  "productsCreated": 1,
  "productsUpdated": 0,
  "skipped": 0,
  "processed": 1
}

Erros específicos do POST /stock/snapshot

Códigos estáveis definidos no backend.

Nome	Tipo	Obrigatório	Descrição
`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).

Estoque

Visão geral

Headers

Query Params

Exemplo de request

Respostas

Response 200

Cache HTTP (ETag)

Erros específicos do GET /stock

Headers

Body

Body exemplo

Regras de processamento

Respostas

Response 200

Erros específicos do POST /stock/snapshot

On this page