Orientações

Os requisitos a seguir constituem uma orientação técnica para a criação de uma API de busca de preços, visando uma integração mais eficiente com nossos serviços. Embora alguns recursos, como Health Check e Autenticação, possam não estar implementados inicialmente, são considerados ideais para garantir a segurança e a confiabilidade do processo.

Sumário

Esta especificação define os requisitos para a construção de uma API RESTful que:

• Usa autenticação OAuth2
• Possui endpoint de health check
• Disponibiliza o recurso price, que recebe parâmetros de entrada e retorna dados de preços e descrição de produto

---

1. Tecnologias Recomendadas

• Plataforma: .NET 6+ / Node.js / Java Spring Boot (escolha conforme stack do seu time)
• Arquitetura: RESTful
• Autenticação: OAuth2 com JWT (Client Credentials Flow)
• Documentação: Swagger (OpenAPI)
• Monitoramento: Health Check (middleware ou lib do framework)

---

2. Autenticação e Segurança

Protocolo

OAuth2 (Client Credentials Flow)

Headers obrigatórios

Authorization: Bearer {access_token}

Fluxo simplificado

1. O consumidor da API realiza uma requisição de token:

POST /oauth/token  
Content-Type: application/x-www-form-urlencoded  

grant_type=client_credentials  
client_id=YOUR_CLIENT_ID  
client_secret=YOUR_CLIENT_SECRET  

2. A API retorna um access_token válido por tempo determinado.
3. O token deve ser enviado nas chamadas subsequentes à API usando o cabeçalho Authorization.

---

3. Health Check

Endpoint

GET /health

Objetivo

Verificar se a API está online e operacional.

Exemplo de resposta

{
  "status": "Healthy",
  "timestamp": "2025-08-08T12:00:00Z"
}

Códigos de Resposta

Código	Significado
200	API operacional
500	Problema detectado

---

4. Recurso: price

Endpoint

GET /api/v1/price

Parâmetros de Consulta (Query String)

Parâmetro	Tipo	Obrigatório	Descrição
ean	string	Sim	Código de barras do produto (EAN)(Somente números, ex.: 7890000000000)
cnpj	string	Sim	CNPJ da filial da rede ou estabelecimento (Somente números, ex.: 00154458723654)
idParceiro	string	Não	Identificador da Funcional (Opcional)

Observação 1:

O idParceiro é opcional e tem o objetivo de identificar a Funcional Health Tech caso necessário. Pode ser substituído também pelo CNPJ caso seja a preferência.

Headers obrigatórios

Authorization: Bearer {access_token}

Exemplo de requisição

GET /api/v1/price?ean=7891234567890&cnpj=12345678000199&idParceiro=17 
Authorization: Bearer eyJhbGciOi...

Exemplo de resposta

{
  "maxConsumerPrice": 19.99,
  "unitPrice": 14.25,
  "productDescription": "Sabonete Líquido 500ml"
}

Códigos de Resposta

Código	Descrição
200	Sucesso
400	Parâmetros inválidos
401	Token inválido ou ausente
404	Produto não encontrado
500	Erro interno do servidor

---

5. Boas Práticas Recomendadas

• Versionamento de API: Utilizar versionamento via path (/api/v1/)
• Validação de entrada: Validar e sanitizar todos os parâmetros de entrada
• Documentação automática: Publicar documentação via Swagger (/swagger)

---

6. Considerações Finais

• A API deverá estar preparada para alta disponibilidade e escalabilidade horizontal.
• O endpoint /price pode ser cacheado por um período curto (ex: 1 minuto), se necessário.
• Validar EAN e CNPJ quanto ao formato, antes de processar a lógica.