Downloads - Coleções API

Faça o download das coleções de API prontas para uso com o Piloto Esteio.

📦 Arquivos Disponíveis

🚀 Coleção Postman

Arquivo: Esteio-Pilot-API.postman_collection.json

Coleção completa do Postman para testes e desenvolvimento:

✨ O que está incluído:

• ✅ 4 endpoints baseados na documentação oficial
• ✅ Autenticação pré-configurada com API key
• ✅ Testes automatizados para cada endpoint
• ✅ Variáveis dinâmicas para dados de teste
• ✅ Exemplos de resposta realísticos
• ✅ Documentação embebida em cada request

📥 Download Postman Collection

---

📋 Especificação OpenAPI

Arquivo: esteio-pilot-openapi.yaml

Especificação OpenAPI 3.0.3 completa para integração e documentação:

✨ O que está incluído:

• ✅ Especificação OpenAPI 3.0.3 completa
• ✅ Schemas detalhados para validação de dados
• ✅ Exemplos práticos para cada endpoint
• ✅ Documentação embebida baseada no Docusaurus
• ✅ Compatibilidade com Swagger UI e outras ferramentas
• ✅ Tipos e constraints para todos os campos

📥 Download OpenAPI Specification

---

🛠️ Como Usar

Para Postman

1. Baixe o arquivo Esteio-Pilot-API.postman_collection.json
2. Abra o Postman
3. Clique em "Import" no canto superior esquerdo
4. Selecione o arquivo baixado
5. Use a chave API já configurada: dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf
6. Execute os testes!

Pronto para Usar

A coleção já vem configurada com:

• API Key: dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf (já configurada)
• Base URL: https://defarm-mvp.onrender.com/api (já configurado)

Não precisa configurar nada adicional!

Para OpenAPI/Swagger

Opção 1: Swagger Editor Online

1. Baixe o arquivo esteio-pilot-openapi.yaml
2. Acesse editor.swagger.io
3. Copie o conteúdo do arquivo
4. Cole no editor online
5. Explore a documentação interativa!

Opção 2: Swagger UI Local (Docker)

# Após fazer o download do arquivo
docker run -p 8080:8080 \
  -v $(pwd)/esteio-pilot-openapi.yaml:/usr/share/nginx/html/openapi.yaml \
  -e API_URL=openapi.yaml \
  swaggerapi/swagger-ui

# Acesse: http://localhost:8080

Opção 3: Integração em Projetos

# Para projetos Node.js
npm install swagger-ui-express

# Para projetos Python
pip install flask-restx

---

📋 Endpoints Cobertos

As coleções incluem todos os endpoints documentados:

Método	Endpoint	Descrição
GET	/test	Verificar API Key e permissões
POST	/assets	Endpoint único para criação/atualização/enriquecimento
GET	/assets	Listar assets com filtros avançados
GET	/assets/{id}	Consultar asset específico com detalhes

Conceito do Endpoint Único

O POST /assets é o coração do sistema e funciona para:

• 🆕 Criação - Sistema detecta animal novo via SISBOV
• 📝 Atualização - Sistema identifica animal existente e enriquece dados
• 🔄 Deduplicação - Automática por SISBOV/ear_tag
• 🔗 Tokenização - Blockchain + IPFS automáticos
• 📊 Dashboard - Atualização em tempo real

---

🧪 Testes Incluídos

Validações Automáticas

Cada request do Postman inclui testes que verificam:

• ⏱️ Performance: Tempo de resposta < 10 segundos
• ✅ Formato: JSON válido em todas as respostas
• 🔍 Estrutura: Campos obrigatórios presentes
• 🔗 Encadeamento: Dados salvos para próximos requests

Exemplos de Testes

// Validação básica
pm.test('Response time is reasonable', function () {
    pm.expect(pm.response.responseTime).to.be.below(10000);
});

// Validação específica para assets
pm.test('Asset submitted successfully', function () {
    pm.expect(pm.response.code).to.be.oneOf([200, 201]);
    const data = pm.response.json();
    pm.expect(data.data).to.have.property('id');
    pm.expect(data.data).to.have.property('status');
});

---

📊 Dados de Teste

Variáveis Dinâmicas

O Postman gera automaticamente:

Variável	Exemplo	Descrição
random_sisbov	123456789012345	SISBOV válido de 15 dígitos
random_ear_tag	ESTEIO-001	Brinco com padrão Esteio
test_weight	450	Peso entre 300-600kg
timestamp	2024-08-29T...	Data/hora atual ISO

Exemplo de Payload Mínimo

{
  "valuechain_type": "livestock",
  "category": "cattle",
  "identifiers": {
    "sisbov": "{{random_sisbov}}"
  }
}

Exemplo de Payload Completo

{
  "valuechain_type": "livestock",
  "category": "cattle",
  "asset_name": "{{random_ear_tag}}",
  "identifiers": {
    "sisbov": "{{random_sisbov}}",
    "ear_tag": "{{random_ear_tag}}"
  },
  "characteristics": {
    "breed": "Nelore",
    "gender": "male",
    "current_weight": {{test_weight}}
  },
  "location": {
    "farm_name": "Fazenda Esteio Piloto",
    "municipality": "Esteio", 
    "state": "RS"
  }
}

---

🔧 Configurações Avançadas

Variáveis de Ambiente

Para diferentes ambientes, configure:

{
  "BASE_URL": "https://defarm-mvp.onrender.com/api",
  "API_KEY": "dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf",
  "TIMEOUT": 30000
}

Headers Personalizados

Adicione headers customizados se necessário:

{
  "X-API-Key": "dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf",
  "Content-Type": "application/json",
  "X-Request-Source": "esteio-pilot",
  "X-Request-Version": "1.0"
}

---

🔍 Filtros e Consultas

Parâmetros Suportados

Para GET /assets, use os seguintes filtros:

Parâmetro	Valor	Descrição
valuechain_type	livestock	Sempre "livestock" para animais
category	cattle	Categoria específica
sisbov	123456789012345	Busca por SISBOV exato
search	esteio	Busca textual em qualquer campo
page	1	Número da página
limit	20	Itens por página (máx 100)

Exemplos de URLs

# Todos os bovinos
GET /assets?valuechain_type=livestock&category=cattle

# Buscar por SISBOV específico  
GET /assets?sisbov=123456789012345

# Busca textual por "esteio"
GET /assets?search=esteio

# Paginação
GET /assets?page=2&limit=50

---

📚 Documentação Relacionada

• 📖 Introdução ao Piloto Esteio - Visão geral e arquitetura
• 🔧 API Guide - Guia detalhado de uso da API
• 🌐 Dashboard Esteio - Interface web

---

✅ Validação e Testes

Status das Coleções

• ✅ JSON válido - Postman collection
• ✅ YAML válido - OpenAPI specification
• ✅ Testes funcionais - Todos os endpoints validados
• ✅ Consistência - Ambos os formatos sincronizados
• ✅ Compatibilidade - Ferramentas padrão do mercado

Ambiente Testado

• URL Base: https://defarm-mvp.onrender.com/api
• Versão API: v1.0.0
• Organização: Government (Esteio)
• Rate Limit: 100 requests/hora

---

🆘 Suporte

Problemas com as coleções?

1. Confirme que a API key dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf está sendo usada
2. Confirme se o rate limit não foi excedido (100 req/hora)
3. Teste primeiro com GET /test para validar conectividade
4. Consulte o API Guide para exemplos detalhados

Versão das Coleções

Postman Collection: v1.0.0
OpenAPI Specification: v1.0.0
Última atualização: 29 de Agosto de 2025