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 preliminarComo 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.
Alinhamento. Compartilhe a documentação da sua API, ambientes, capacidades, modelo comercial e contatos técnicos.
Credenciamento. Defina as farmácias e filiais autorizadas, autenticação, permissões e credenciais de teste.
Mapeamento. Acorde identificadores, campos, filtros, paginação, atualização de dados e regras de pedidos.
Homologação. Execute os cenários abaixo em ambiente de teste e registre as evidências.
Ativação. Autorize cada farmácia, configure monitoramento e acompanhe o primeiro fluxo em produção.
Escopo da integração
| Capacidade | Por que precisamos | Prioridade para alinhamento |
|---|---|---|
| Produtos | Encontrar e identificar o item correto, inclusive por código de barras. | Essencial |
| Estoque e preços | Informar disponibilidade e valor da filial selecionada. | Essencial |
| Pedidos | Enviar a venda para processamento pelo PDV e consultar seu resultado. | Essencial para envio de pedidos |
| Clientes | Identificar ou associar o cliente, quando necessário e autorizado. | Conforme fluxo |
| Notificações | Receber 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.
| Dado | Uso |
|---|---|
| Identificador estável do produto | Referenciar o item em consultas e pedidos; informar seu escopo. |
| Descrição e código de barras | Localização e conferência. Informe se há múltiplos códigos. |
| Apresentação, marca e unidade | Diferenciar produtos, concentração, embalagem e quantidade. |
| Ativo/inativo e última alteração | Evitar oferta de cadastro indisponível e sincronizar alterações. |
| Indicadores e regras de receita | Quando 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ção | Informações necessárias |
|---|---|
| Requisição inválida | Código, mensagem e campos inválidos sem expor dados sensíveis. |
| Autenticação / permissão | Como diferenciar credencial expirada de acesso não autorizado. |
| Limite de uso | Limites por credencial e janela, além de orientação para nova tentativa. |
| Falha temporária / timeout | Política de retry com espera progressiva; em escritas, consultar antes de reenviar. |
| Produto, filial ou cliente ausente | Erro 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.