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
`cnpj`	`text`	Não	`12.345.678/0001-49`	CNPJ da loja. Recomendamos enviar para facilitar o vínculo.
`codloja`	`bigint`	Sim	`23`	Código da Loja.
`ean`	`bigint`	Sim	`7891058011222`	EAN principal
`departamento`	`text`	Sim	`ETICO OTC`	Agregação máxima dos produtos. Não deve ser preenchido caso o cliente utilize o GC da Proffer.
`categoria`	`text`	Sim	`DOR E FEBRE OTC`	Segundo nível de agregação. Não deve ser preenchido caso o cliente utilize o GC da Proffer. Caso tenha GC próprio, e só tenha o nível de departamento, preencher essa coluna com a mesma informação do departamento.
`subcategoria`	`text`	Não	`DOR E FEBRE OTC`	Terceiro nível de agregação. Não deve ser preenchido caso o cliente utilize o GC da Proffer. Caso tenha GC próprio, e só tenha o nível de categoria, preencher essa coluna com a mesma informação do categoria.
`segmento`	`text`	Não	`ANALGESICO OTC`	Quarto nível de agregação. Não deve ser preenchido caso o cliente utilize o GC da Proffer. Caso tenha GC próprio, e só tenha o nível de subcategoria, preencher essa coluna com a mesma informação do subcategoria.
`subsegmento`	`text`	Não	`ANALGESICO OTC`	Quinto nível de agregação. Não deve ser preenchido caso o cliente utilize o GC da Proffer. Caso tenha GC próprio, e só tenha o nível de segmento, preencher essa coluna com a mesma informação do segmento.
`familiapreco`	`text`	Não	`NOVALGINA 1G 4CPR`	Família de preços. Agrupa produtos que devem ter o mesmo preço em uma loja. Caso o Produto não pertencer a uma Família de preços, esse campo será NULO.
`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 ultima entrada do produto (Custo Unitário).
`customedio`	`double`	Sim	`4,83`	Custo médio do produto
`pmc`	`double`	Sim	`7,00`	Preço máximo ao consumidor (unitário). Se o produto não tiver PMC, preencher com NULL.
`precoregular`	`double`	Sim	`5,80`	Preço regular unitário do produto.
`precopromocional`	`double`	Sim	`5,30`	Preço promocional unitário do produto. Se houver preço promocional, enviar.
`zonapreco`	`int`	Não	`1`	Se não há diferenciação de preço por loja tudo = 1
`zonaprecodescricao`	`text`	Não	`ZONA NORTE`	Descrição de Zona de Preço.
`qtdembalagem`	`int`	Não	`6`	Quantidade de itens dentro da embalagem
`unidmedembalagem`	`text`	Não	`CPR`	Unidade de medida da quantidade da embalagem
`formulacao`	`text`	Não	`—`	Formulação do produto
`estoque`	`bigint`	Sim	`150`	Estoque atual do produto em loja

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

Campo	Tipo	Obrig.	Exemplo	Descrição
`codproduto`	`bigint`	Sim	`5155`	Código interno do Produto
`cnpj`	`text`	Não	`12.345.678/0001-49`	CNPJ da loja. Recomendamos enviar para facilitar o vínculo.
`ean`	`bigint`	Sim	`7891058011222`	EAN principal
`pbm`	`text`	Sim	`N`	É PBM? (S/N)
`farmaciapopular`	`text`	Sim	`N`	Possui Farmácia Popular? (S/N)
`idtipovenda`	`bigint`	Sim	`1`	ID da venda (1-Regular, 2-Promocional, 3-Queimão/Liquidação, 4-Farmácia Popular, 5-PBM, 6-Devolução, 7-Convênio, 8-Outros).
`desctipovenda`	`text`	Não	`Regular`	Descricao do tipo de venda.
`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`	Preço máximo ao consumidor (unitário). Se o produto não tiver PMC, preencher com NULL.
`precovenda`	`double`	Sim	`5,80`	Preço unitário efetivo de venda do produto.
`qtdvendida`	`bigint`	Sim	`3`	Quantidade vendida.
`impostos`	`double`	Sim	`0,43`	Valor do imposto total cobrado na operação.
`faturamento`	`double`	Não	`15,47`	Total da receita da venda (normalmente basta fazer precovenda * qtdvendida - imposto). Porém existem casos como de indenização da indústria que podem alterar esse valor. Caso não seja preenchido, será feito a multiplicação de precovenda*qtdvendida para encontrar o faturamento.
`margembruta`	`double`	Não	`0,34`	Margem bruta da operação. Caso não seja preenchida, iremos calcular a margem bruta como (precovenda-custo-impostos)/precovenda.
`cidade`	`text`	Sim	`São Paulo`	Cidade onde a transação ocorreu.
`codcidade`	`int`	Sim	`3550308`	Código IBGE da cidade onde a transação ocorreu.
`estado`	`text`	Sim	`SP`	Estado onde a transação ocorreu.
`codestado`	`int`	Sim	`35`	Código IBGE do estado onde a transação ocorreu.
`idtransacao`	`bigint`	Sim	`48536678`	ID único da transação
`canalvenda`	`text`	Não	`Loja_Fisica`	Qual canal por onde ocorreu a venda.

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/api/mock      ← testes, credenciais sandbox
#   Produção: https://parceiros.apiproffer.com/parceiros ← dados reais, credenciais do parceiro
#   Integração V2: https://api-extrator-83653875001.us-central1.run.app ← envio de dados, signed URL

import requests

BASE = "https://sandbox.apiproffer.com/api/mock"
INTEGRACAO = "https://api-extrator-83653875001.us-central1.run.app"

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

# 2. Enviar produtos por loja (V2 — validação síncrona)
produtos = [
    {
        "codproduto": 5155,
        "codloja": 23,
        "ean": 7891058011222,
        "descricao": "NOVALGINA 1G 4CPR",
        "departamento": "Medicamentos",
        "categoria": "Genéricos",
        "custo": 4.82,
        "pmc": 7.00,
        "precoregular": 5.80,
        "estoque": 150,
    }
]

r = requests.post(
    f"{INTEGRACAO}/integracao/v2/produtoloja",
    json={"records": produtos},
    headers=headers,
)
print(r.json())

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

Testar rotas no Playground