Guias de Integração

Manual profundo para desenvolvedores. Entenda os conceitos arquiteturais, regras de segurança e tratamento de erros para uma integração impecável.

Conceitos Técnicos

Glossário de Dados

EAN, codrede, zonapreco, PMC e termos técnicos cruciais.

Quick Start (5 min)

Faça sua primeira chamada autenticada em minutos.

Infraestrutura & Segurança

Autenticação JWT

Rate Limits

Limites de requisições, backoff exponencial e throughput.

Tratamento de Erros

Códigos HTTP e estratégias robustas de debugging.

Dicionário de Dados

O esquema oficial de dados esperado pela inteligência da Proffer. Válido tanto para o payload da API REST quanto para as colunas dos arquivos SFTP.

Objeto: Produto

Campo	Tipo	Obrig.	Exemplo	Descrição
`codproduto`	`bigint`	Sim	`5155`	Código interno do produto no ERP
`codloja`	`bigint`	Sim	`23`	Código da loja/filial
`ean`	`bigint`	Sim	`7891058011222`	EAN principal do produto
`descricao`	`text`	Sim	`NOVALGINA 1G 4CPR`	Descrição completa do produto
`imprimeetiqueta`	`text`	Sim	`S`	Imprime etiqueta? (S/N)
`custo`	`double`	Sim	`4,82`	Custo da última entrada (custo unitário)
`customedio`	`double`	Sim	`4,83`	Custo médio do produto
`pmc`	`double`	Sim	`7,00`	Preço máximo ao consumidor. NULL se não houver.
`precoregular`	`double`	Sim	`5,80`	Preço regular unitário praticado
`estoque`	`bigint`	Sim	`150`	Estoque atual do produto em loja
`departamento`	`text`	Não	`ETICO OTC`	Agregação máxima. Omitir se usar o GC da Proffer.
`categoria`	`text`	Não	`DOR E FEBRE OTC`	Segundo nível. Omitir se usar o GC da Proffer.
`subcategoria`	`text`	Não	`DOR E FEBRE OTC`	Terceiro nível. Omitir se usar o GC da Proffer.
`segmento`	`text`	Não	`ANALGESICO OTC`	Quarto nível. Omitir se usar o GC da Proffer.
`subsegmento`	`text`	Não	`ANALGESICO OTC`	Quinto nível. Omitir se usar o GC da Proffer.
`familiapreco`	`text`	Não	`NOVALGINA 1G 4CPR`	Família de preços. NULL se não houver.
`precopromocional`	`double`	Não	`5,30`	Preço promocional unitário
`zonapreco`	`int`	Não	`1`	Código da zona de preço. Sem diferenciação = 1.
`zonaprecodescricao`	`text`	Não	`ZONA NORTE`	Descrição da zona de preço
`qtdembalagem`	`int`	Não	`6`	Quantidade de itens na embalagem
`unidmedembalagem`	`text`	Não	`CPR`	Unidade de medida da embalagem
`formulacao`	`text`	Não	`—`	Formulação do produto
`estado`	`text`	Não	`SP`	UF da loja
`cnpj`	`text`	Não	`06.990.590/0005-57`	CNPJ da loja

Objeto: Transação (Venda/Devolução)

Campo	Tipo	Obrig.	Exemplo	Descrição
`codproduto`	`bigint`	Sim	`5155`	Código interno do produto
`ean`	`bigint`	Sim	`7891058011222`	EAN principal do produto
`pbm`	`text`	Sim	`N`	É PBM? (S/N)
`farmaciapopular`	`text`	Sim	`N`	Farmácia Popular? (S/N)
`idtipovenda`	`bigint`	Sim	`1`	1=Regular · 2=Promocional · 3=Queimão · 4=Farm. Popular · 5=PBM · 6=Devolução · 7=Convênio · 8=Outros
`datavenda`	`date`	Sim	`2025-03-05`	Data da venda (YYYY-MM-DD)
`codloja`	`bigint`	Sim	`23`	Código da loja
`custo`	`double`	Sim	`4,82`	Custo apurado na venda (custo unitário)
`pmc`	`double`	Sim	`7,00`	PMC na data da venda. NULL se não houver.
`precovenda`	`double`	Sim	`5,80`	Preço unitário efetivo de venda
`qtdvendida`	`bigint`	Sim	`3`	Quantidade vendida. Negativo para devoluções.
`impostos`	`double`	Sim	`0,43`	Valor do imposto total cobrado na operação
`cidade`	`text`	Sim	`São Paulo`	Cidade onde a transação ocorreu
`codcidade`	`int`	Sim	`3550308`	Código IBGE da cidade
`estado`	`text`	Sim	`SP`	Estado onde a transação ocorreu
`idtransacao`	`bigint`	Sim	`48536678`	ID único da transação no ERP
`desctipovenda`	`text`	Não	`Regular`	Descrição do tipo de venda
`precoregular`	`double`	Não	`5,80`	Preço regular na data da venda
`precopromocional`	`double`	Não	`5,30`	Preço promocional na data
`receita_liquida`	`double`	Não	`15,47`	Total da receita (precovenda × qtd − impostos). Calculado automaticamente se omitido.
`margembruta`	`double`	Não	`0,34`	Margem bruta. Calculada automaticamente se omitida.
`codestado`	`int`	Não	`35`	Código IBGE do estado
`canalvenda`	`text`	Não	`Loja_Fisica`	Canal de venda
`zonapreco`	`int`	Não	`1`	Código da zona de preço
`zonaprecodescricao`	`text`	Não	`Zona Norte`	Descrição da zona de preço
`estoque`	`int`	Não	`15`	Estoque remanescente pós-venda
`cnpj`	`text`	Não	`06.990.590/0005-57`	CNPJ da loja vendedora

Conceitos de Negócio (Glossário)

EANEuropean Article Number — código de barras de 13 dígitos que identifica unicamente um produto.

codredeCódigo da rede de farmácias. Agrupa todas as lojas (codloja) de um mesmo grupo.

codlojaCódigo de uma filial/loja individual dentro da rede.

codprodutoID interno do produto no ERP do parceiro. Pode ser diferente do EAN.

zonaprecoAgrupamento geográfico de lojas que compartilham o mesmo preço. Ex: ZONA_SP_CAPITAL.

PMCPreço Máximo ao Consumidor — preço regulatório máximo para medicamentos.

precovendaPreço líquido efetivamente cobrado do cliente na transação.

precosugeridoCampo principal da otimização — preço recomendado pela IA para maximizar margem/competitividade.

D-1Dados do dia anterior. Transações devem ser enviadas com frequência D-1 (ontem).

JWTJSON Web Token — token de autenticação com validade de 1 hora. Use o refresh_token para renovar.

Autenticação JWT

A API utiliza arquitetura robusta via AWS Cognito. A vida útil do access_token é de 1 hora.

1. Handshake Inicial

POST /auth/login com credenciais. Receba tokens de acesso e refresh.

2. Autorização

Adicione o header Authorization: Bearer {token} nas rotas privadas.

3. Renovação (Refresh)

Se o status 401 surgir, chame POST /auth/refresh imediatamente.

4. Validação Proativa

Avalie o tempo de vida (exp) no payload do JWT antes de disparar o request.

Rate Limits e Boas Práticas

Limites definidos para assegurar a alta disponibilidade da infraestrutura (WAF e API Gateway).

Limites Operacionais

Operações Leves (Consultas): 50 requests/segundo.
Operações Pesadas (Ingestão): 10 requests/segundo.

Estratégia de Retry

Recebeu 429 Too Many Requests? Não derrube a conexão. Implemente Exponential Backoff (aguarde 1s, depois 2s, depois 4s).

Otimização de Lotes

Maximizar throughput: envie matrizes JSON de até 1.000 objetos por request ao invés de requisições isoladas por registro.

Tratamento de Erros

HTTP 400 — Bad Request

Falha na validação do Payload (ex: campos obrigatórios ausentes ou tipos incorretos).

HTTP 401 — Unauthorized

Token expirado ou ausente. Requisição barrada no API Gateway.

HTTP 403 — Forbidden

Credenciais válidas, mas sem autorização de escopo para a codrede enviada.

HTTP 422 — Unprocessable

Payload com formato JSON correto, mas sem lógica semântica (ex: EAN inválido).

HTTP 429 — Too Many

Gatilho de proteção ativado. Reduza a concorrência.

HTTP 500 — Server Error

Falha na nossa nuvem. A operação não foi concluída.

Quick Start Code

O ciclo de vida completo (Auth, Envio e Consumo) em poucas linhas de Python.

Python

# Quick Start — Proffer Parceiros API (Python)
#
# Sandbox e Produção são ambientes distintos:
#   Sandbox: https://sandbox.apiproffer.com/parceiros  ← testes, credenciais sandbox
#   Produção: https://parceiros.apiproffer.com/parceiros ← dados reais, credenciais do parceiro

import requests

BASE = "https://sandbox.apiproffer.com/parceiros"

# 1. Autenticar
response = requests.post(
    f"{BASE}/auth/login",
    json={"email": "erp+sandbox@proffer.com.br", "password": "erpsandbox"}
)
token = response.json()["access_token"]

# 2. Enviar mix de produtos
headers = {"Authorization": f"Bearer {token}"}

produtos = [
    {
        "codproduto": 5155,
        "codloja": 23,
        "ean": 7891058011222,
        "descricao": "NOVALGINA 1G 4CPR",
        "imprimeetiqueta": "S",
        "custo": 4.82,
        "customedio": 4.83,
        "pmc": 7.00,
        "precoregular": 5.80,
        "estoque": 150,
        "estado": "SP"
    }
]

r = requests.post(f"{BASE}/integracao/produto", json=produtos, headers=headers)
print(r.json())

# 3. Ler recomendações de preço
r = requests.get(
    f"{BASE}/otimizacao/recomendacoes",
    headers=headers,
    params={"per_page": 10}
)
for rec in r.json()["data"]:
    print(f"{rec['descricao']}: R$ {rec['precosugerido']}")

Testar rotas no Playground