Pular para o conteúdo principal

API Guide - Piloto Esteio

Visão Geral​

O sistema DeFarm processa todos os dados através do endpoint /assets. Este endpoint trata criação, atualização e eventos de forma unificada.

Funcionamento​

  • O sistema identifica automaticamente se é um asset novo ou existente via SISBOV/ear_tag
  • Dados duplicados são consolidados automaticamente
  • O processamento inclui verificação, tokenização e atualização do dashboard

Endpoints Disponíveis​

Processamento de Assets​

Utilitários​

Base URL​

https://defarm-mvp.onrender.com/api

Autenticação​

X-API-Key: dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf

Verificar API Key​

Endpoint​

GET /test

Resposta (200 OK)​

{
  "success": true,
  "message": "API key is valid and working!",
  "apiKey": {
    "organizationType": "government",
    "permissions": { "read": true, "admin": false }
  }
}

Enviar Dados​

Endpoint Único - POST /assets​

POST /assets

Como a DeFarm Processa Automaticamente:

  1. Recebimento → Dados vão para asset_incoming_data (status: pending)
  2. Verificação → Pipeline processa dados automaticamente
  3. Asset novo → Gera DFID + vai para asset_source_data
  4. Asset existente → Enriquece dados existentes por SISBOV/ear_tag
  5. Tokenização → Blockchain + IPFS automáticos
  6. Dashboard → Atualização em tempo real

Headers​

Content-Type: application/json
X-API-Key: dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf

Parâmetros Obrigatórios​

ParâmetroValorDescrição
valuechain_typelivestockTipo de cadeia produtiva
categorycattleCategoria do animal (cattle/sheep/goat/pig/poultry)
identifiersobjetoPelo menos um identificador (SISBOV, ear_tag, etc.)

Parâmetros Opcionais​

Todos os demais campos são opcionais e podem ser enviados gradualmente:

  • asset_name - Auto-gerado se não fornecido
  • characteristics - Raça, sexo, peso, saúde, etc.
  • location - Estado, município, coordenadas, etc.
  • ownership - Proprietário, tipo, contato, etc.
  • compliance - Status sanitário, certificações, etc.

Exemplo 1 - Criação Mínima​

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

Exemplo 2 - Criação com Mais Dados​

{
  "valuechain_type": "livestock",
  "category": "cattle",
  "asset_name": "GOV-PILOT-001", 
  "identifiers": {
    "sisbov": "123456789012345",
    "ear_tag": "GOV-PILOT-001"
  },
  "characteristics": {
    "breed": "Nelore",
    "gender": "male",
    "current_weight": 480
  }
}

Exemplo 3 - Enriquecimento Gradual​

{
  "identifiers": {
    "sisbov": "123456789012345"
  },
  "characteristics": {
    "current_weight": 495,
    "health_records": [
      {
        "event_type": "vaccination", 
        "vaccine_type": "Aftosa",
        "date": "2024-08-28",
        "veterinarian": "Dr. João Santos"
      }
    ]
  }
}

Resposta - Sucesso (201/200)​

{
  "success": true,
  "data": {
    "id": "abc-123-def-456",
    "status": "pending", // ou "enriched" se foi agregação
    "valuechain_type": "livestock",
    "asset_name": "GOV-PILOT-001"
  },
  "message": "Asset submitted to verification pipeline successfully"
}

Listar Assets​

Endpoint​

GET /assets

Visibilidade Completa do Pipeline​

O endpoint retorna assets de duas fontes:

  • pipeline_stage: 'incoming' - Dados em asset_incoming_data (pendentes de verificação)
  • pipeline_stage: 'processed' - Dados em asset_source_data (com DFID atribuído)

Isso permite rastrear completamente o status de processamento.

Parâmetros Opcionais​

?valuechain_type=livestock&category=cattle&sisbov=123456789012345&search=nelore

Filtragem Inteligente​

  • valuechain_type=livestock - Filtra por tipo de cadeia (sempre livestock para animais)
  • category=cattle - Filtra por categoria de animal
  • sisbov=123456789012345 - Busca por SISBOV específico
  • search=termo - Busca textual em nome, raça, etc.

Resposta (200 OK)​

{
  "success": true,
  "data": [
    {
      "id": "abc-123",
      "pipeline_stage": "incoming",
      "status": "pending",
      "valuechain_type": "livestock",
      "category": "cattle",
      "asset_name": "AUTO-777777-564329",
      "identifiers": {
        "sisbov": "777777777777777",
        "ear_tag": "FINAL-PIPELINE-TEST"
      },
      "dfid": null,
      "created_at": "2024-08-28T16:30:00Z"
    },
    {
      "id": "def-456", 
      "pipeline_stage": "processed",
      "status": "tokenized",
      "valuechain_type": "livestock",
      "category": "cattle",
      "asset_name": "GOV-PILOT-001",
      "identifiers": {
        "sisbov": "123456789012345",
        "ear_tag": "GOV-PILOT-001"
      },
      "dfid": "DFID-LIV-CTL-00000001",
      "created_at": "2024-08-28T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

Consultar Asset​

Endpoint​

GET /assets/{id}

Parâmetros​

  • {id} - ID único do asset retornado pelo sistema DeFarm

Resposta (200 OK)​

{
  "success": true,
  "data": {
    "id": "abc-123",
    "asset_name": "GOV-PILOT-001",
    "identifiers": {
      "sisbov": "123456789012345", 
      "ear_tag": "GOV-PILOT-001"
    },
    "characteristics": {
      "breed": "Nelore",
      "current_weight": 495,
      "health_records": [...]
    },
    "blockchain": {
      "status": "tokenized",
      "nft_token": "DFIDASDF1234",
      "ipfs_cid": "QmXXXXXXXXX",
      "transaction_hash": "0xABC123..."
    },
    "enrichment_history": [
      {
        "enriched_at": "2024-08-28T14:00:00Z",
        "fields_added": ["health_records"],
        "source": "API"
      }
    ]
  }
}

Fluxo Simplificado​

Para Qualquer Operação:​

# 1. SEMPRE use POST /assets
curl -X POST https://defarm-mvp.onrender.com/api/assets \
  -H "X-API-Key: dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf" \
  -H "Content-Type: application/json" \
  -d '{...dados...}'

# 2. DeFarm processa automaticamente:
# Detecta se é animal novo ou existente
# Cria/enriquece dados conforme necessário  
# Atualiza IPFS com nova versão
# Registra na blockchain
# Atualiza dashboard

# 3. Consulte o resultado:
curl -H "X-API-Key: dfm_aLjDovXA4m7kEPG3kjqc4Rq4fDHVI2Qf" \
  https://defarm-mvp.onrender.com/api/assets

Arquitetura​

Cliente (Esteio):​

  • POST /assets para todas as operações
  • Não requer controle se é criação, atualização ou evento
  • Sistema determina o fluxo baseado nos dados enviados
  • Trata duplicatas automaticamente via SISBOV/ear_tag

Sistema DeFarm:​

  • Pipeline unificado para verificação
  • Detecção de duplicatas por SISBOV/ear_tag
  • Versionamento IPFS para histórico
  • Tokenização blockchain automática

Esteio (Governança):​

  • Endpoint único para monitoramento
  • Dados consolidados sem fragmentação
  • Rastreabilidade via blockchain e IPFS
  • Validação SISBOV obrigatória

Regras Importantes​

  1. SISBOV obrigatório - Sempre inclua o número SISBOV (15 dígitos)
  2. Dados incrementais - Cada POST pode adicionar informações
  3. Não deletar dados - Sistema mantém histórico completo
  4. Rate limit - 100 requests/hora por organização
  5. Processamento assíncrono - Status "pending" → "tokenized"

Monitoramento do Piloto Esteio​

Status e Verificações​

# 1. Status da API e validação da chave
GET /test

# 2. Todos os assets do piloto livestock
GET /assets?valuechain_type=livestock

# 3. Filtrar apenas bovinos de Esteio
GET /assets?valuechain_type=livestock&category=cattle&search=esteio

# 4. Asset específico com histórico completo
GET /assets/{id}

Pipeline de Processamento​

  • Recebimento: Imediato (API)
  • Verificação: 10-30 segundos (pipeline DeFarm)
  • Tokenização: 30-90 segundos (blockchain)
  • Dashboard: Atualização automática após tokenização

Status Possíveis​

  • pending → Aguardando verificação
  • processing → Na pipeline de verificação
  • tokenized → Processamento completo + blockchain