✳Venda Farma / developersDocumentação para parceiros
Guia para fornecedores de PDV & ERP

Uma integração.
Mais possibilidades para a farmácia.

Conecte seu sistema aos serviços de IA da Venda Farma para que o atendimento consulte produtos, preços e estoque e encaminhe pedidos à loja certa.

Guia de integração · versão preliminar
Como usar este guia. Este documento apresenta requisitos e exemplos de referência para negociação e homologação. Os caminhos, campos e formatos demonstrados são ilustrativos: não representam uma API pública já disponível nem substituem o contrato acordado com cada fornecedor.

Como integrar

A Venda Farma atua como consumidora das capacidades disponibilizadas pelo fornecedor. A implementação concreta é definida por um adaptador e pelo contrato validado entre as equipes.

1

Alinhamento. Compartilhe a documentação da sua API, ambientes, capacidades, modelo comercial e contatos técnicos.

2

Credenciamento. Defina as farmácias e filiais autorizadas, autenticação, permissões e credenciais de teste.

3

Mapeamento. Acorde identificadores, campos, filtros, paginação, atualização de dados e regras de pedidos.

4

Homologação. Execute os cenários abaixo em ambiente de teste e registre as evidências.

5

Ativação. Autorize cada farmácia, configure monitoramento e acompanhe o primeiro fluxo em produção.

Escopo da integração

CapacidadePor que precisamosPrioridade para alinhamento
ProdutosEncontrar e identificar o item correto, inclusive por código de barras.Essencial
Estoque e preçosInformar disponibilidade e valor da filial selecionada.Essencial
PedidosEnviar a venda para processamento pelo PDV e consultar seu resultado.Essencial para envio de pedidos
ClientesIdentificar ou associar o cliente, quando necessário e autorizado.Conforme fluxo
NotificaçõesReceber mudanças de situação sem depender apenas de consultas.Desejável; pode haver consulta periódica

O escopo exato, incluindo reservas, descontos, entregas, pagamentos e dados de receita, depende das capacidades e regras de cada PDV.

Acesso e segurança

  • Disponibilize HTTPS e um mecanismo de autenticação documentado; informe como emitir, renovar e revogar credenciais.
  • Restrinja cada credencial às farmácias, filiais e operações autorizadas. Uma filial nunca deve consultar ou alterar dados de outra sem autorização.
  • Informe endereços dos ambientes, limites de uso, política de expiração, contatos de incidente e eventuais requisitos de rede.
  • Use dados fictícios na homologação. Não inclua tokens, dados pessoais ou informações de receitas em exemplos públicos, URLs ou logs desnecessários.
  • Defina com a Venda Farma as responsabilidades de tratamento, retenção e acesso aos dados pessoais aplicáveis à integração.

Produtos e catálogo

A consulta deve permitir localizar produtos pelo menos pelo identificador do fornecedor e, quando disponível, código de barras e descrição. Informe como acessar o catálogo completo e identificar alterações e inativações.

DadoUso
Identificador estável do produtoReferenciar o item em consultas e pedidos; informar seu escopo.
Descrição e código de barrasLocalização e conferência. Informe se há múltiplos códigos.
Apresentação, marca e unidadeDiferenciar produtos, concentração, embalagem e quantidade.
Ativo/inativo e última alteraçãoEvitar oferta de cadastro indisponível e sincronizar alterações.
Indicadores e regras de receitaQuando disponibilizados, informe o significado e a origem dos dados; a dispensação segue as regras da farmácia.

Exemplo ilustrativo de resposta

{
  "items": [{
    "productId": "PDV-123", "barcode": "7890000000000",
    "description": "Produto exemplo 20 unidades",
    "active": true, "updatedAt": "2026-01-15T12:00:00Z"
  }],
  "nextCursor": null
}

Documente filtros suportados, limites de página, ordenação estável, cursor ou paginação, política de exclusões e se o cadastro é por empresa ou filial. Não assuma OData ou qualquer protocolo sem confirmação do fornecedor.

Estoque e preços

Disponibilize consulta por produto e filial, deixando explícitos o saldo disponível para venda, unidade de medida, preço efetivo e instante da informação. Explique se o saldo inclui reservas e se o preço inclui descontos ou ofertas e suas condições.

{
  "branchId": "LOJA-01", "productId": "PDV-123",
  "availableQuantity": 12, "unit": "UN",
  "price": { "amount": "19.90", "currency": "BRL" },
  "observedAt": "2026-01-15T12:00:00Z"
}

O exemplo usa valor decimal como texto para evitar ambiguidade de precisão; o formato real deve ser acordado. Se o estoque estiver indisponível ou desatualizado, o atendimento não deve afirmar que há saldo. Defina frequência de atualização, consistência e política para falhas.

Clientes

Quando o fluxo exigir identificação, documente consulta, associação ou cadastro, campos obrigatórios, validações e regras de duplicidade. Informe quais identificadores podem ser usados e como tratar cliente não encontrado. Compartilhe apenas os dados necessários e protegidos por autorização adequada.

Pedidos e pagamentos

O fornecedor deve documentar a operação de criação e consulta de pedidos, identificadores aceitos, campos obrigatórios e regras de validação. O pedido deve apontar a filial correta e ter um identificador externo estável para reconciliação.

{
  "externalOrderId": "vf-pedido-exemplo-001",
  "branchId": "LOJA-01",
  "items": [{ "productId": "PDV-123", "quantity": 2,
              "unitPrice": "19.90" }],
  "total": "39.80", "currency": "BRL",
  "fulfillment": "pickup",
  "payment": { "method": "pix", "status": "pending" }
}

O exemplo não define enumerações oficiais. Acorde valores aceitos, cálculo de totais, descontos, frete, retirada ou entrega, dados de cliente, cancelamento, alterações e limites. Informe se o PDV cria orçamento ou venda e quando ocorre baixa de estoque.

Duplicidade e resultado incerto

Defina uma chave de idempotência ou consulta confiável por identificador externo. Para timeout após envio, consulte o resultado antes de repetir: uma resposta ausente não prova que o pedido falhou. Informe o identificador retornado e a estratégia de reconciliação.

Medicamentos e receitas

Documente restrições e os dados estritamente necessários para itens sujeitos a controle, sem compartilhar arquivos ou dados sensíveis em exemplos. A validação e a dispensação seguem as regras aplicáveis e a responsabilidade da farmácia.

Status e notificações

Documente os estados reais do PDV e seu significado, transições, identificação do pedido, data do evento e eventuais notas fiscais. Exemplos de estados a mapear incluem recebido, em separação, faturado, entregue e cancelado; eles não são um contrato de enumeração.

Se houver webhook, combine previamente endereço, autenticação ou assinatura, identificador único do evento, proteção contra repetição, prazo de resposta, política de tentativas, ordenação e procedimento de recuperação. Se não houver, defina consulta periódica e limites. Eventos duplicados ou fora de ordem devem ser reconciliados com a situação atual do pedido.

Erros e resiliência

SituaçãoInformações necessárias
Requisição inválidaCódigo, mensagem e campos inválidos sem expor dados sensíveis.
Autenticação / permissãoComo diferenciar credencial expirada de acesso não autorizado.
Limite de usoLimites por credencial e janela, além de orientação para nova tentativa.
Falha temporária / timeoutPolítica de retry com espera progressiva; em escritas, consultar antes de reenviar.
Produto, filial ou cliente ausenteErro reconhecível e distinção entre ausência confirmada e falha de consulta.

Informe formatos de erro, códigos HTTP efetivos, timeouts, disponibilidade e identificador de correlação. Limites e tempos devem ser acordados por ambiente; este guia não estabelece valores operacionais.

Checklist de homologação

Execute com dados fictícios e registre requisição, resultado esperado, resultado observado e identificador de correlação, sem credenciais.

  • Autenticação válida, expirada e sem acesso à filial; isolamento entre farmácias.
  • Busca por identificador, código de barras e descrição; paginação, alteração e inativação.
  • Preço e estoque por filial, saldo zero, produto ausente e consulta temporariamente indisponível.
  • Pedido válido e pedido com item, preço, quantidade ou filial inválidos; conferência dos totais.
  • Envio repetido e timeout após aceite: demonstrar ausência de duplicidade e reconciliação.
  • Consulta de situação, cancelamento e tratamento de estados desconhecidos.
  • Quando houver webhook: assinatura inválida, evento duplicado, fora de ordem e recuperação após falha.
  • Permissões, proteção de dados, observabilidade, limites e procedimento de suporte.

Entrada em produção

Após homologação, confirme aprovação das equipes, autorização da farmácia, mapeamento de filial, credenciais próprias do ambiente, capacidades habilitadas e responsáveis por suporte. Acompanhe os primeiros pedidos, compare os identificadores nos dois sistemas e defina como suspender a integração e reconciliar operações pendentes.

Suporte e alterações

Para iniciar uma integração, procure seu contato comercial ou técnico da Venda Farma e compartilhe a documentação da API, fluxo de credenciamento, informações do ambiente de testes e exemplos sem dados sensíveis. Endereço de suporte, SLA, canais de incidentes e política de versionamento serão confirmados no acordo de integração.

Comunique previamente alterações de contrato, campos obrigatórios, autenticação, descontinuações e janelas de manutenção. Cada integração deve manter seu mapeamento e evidência de homologação atualizados.

Venda Farma · Documentação para parceiros de tecnologia
Guia preliminar · Conteúdo sujeito à validação técnica e comercial.