API Farmatch v1
Referência oficial da API pública v1 autenticada exclusivamente por x-api-key.
Escopo da API
A API pública v1 do Farmatch foi projetada para integração de estoque e pedidos entre sistemas externos e a loja vinculada à x-api-key.
- A URL não usa
slug. - O tenant é resolvido internamente pela chave ativa.
- Uma API key de uma loja nunca acessa dados de outra.
Base URL
https://api.farmatch.com.br/api/v1Header obrigatório
Autenticação
Header exigido em todas as chamadas da API pública.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
x-api-key | string | Sim | Chave pública da loja autorizada. |
Convenções globais
Contrato transversal
Regras válidas para todos os endpoints da v1.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
requestId | string (UUID) | Sim | Identificador de rastreio retornado em respostas de sucesso e erro. |
timestamps | number | Sim | Campos de data/hora retornam epoch em milissegundos. |
valores monetários | number (int) | Sim | Todos os valores financeiros usam centavos. Ex.: 1290 = R$ 12,90. |
idempotência | externalOrderId | x-idempotency-key | Não | Em criação de pedido, use identificador idempotente para evitar duplicidade. |
cache condicional | ETag + If-None-Match | Não | Disponível em GET /stock para reduzir tráfego de sincronização. |
Endpoints principais
GET
/api/v1/stockConsulta o estoque da loja autenticada com filtros, busca, cursor e ETag.
POST
/api/v1/stock/snapshotAtualiza preço e estoque da loja autenticada por lote de itens.
POST
/api/v1/ordersCria pedido externo no Farmatch com suporte à idempotência por provedor.
GET
/api/v1/ordersLista pedidos da loja autenticada com filtro de status e limite.
GET
/api/v1/orders/:orderIdConsulta um pedido específico da loja autenticada.
PATCH
/api/v1/orders/:orderIdAtualiza o status de um pedido e registra evento de timeline.
Fluxo recomendado de integração
- Valide a autenticação com
GET /api/v1/stock. - Sincronize estoque usando paginação por cursor e
If-None-Match. - Envie pedidos com
externalOrderId(oux-idempotency-key) para evitar duplicidade. - Atualize status do pedido via
PATCH /api/v1/orders/:orderIdconforme o fluxo operacional.
Boas práticas
- Sempre registre o
requestIdem logs de integração. - Trate respostas
304 Not Modifiedcomo sucesso de cache. - Padronize o tratamento financeiro em centavos para evitar erro de arredondamento.
- Consulte a página de erros para mapear respostas por código.