Guia de Integração e Documentação de APIs

Aprenda a integrar sistemas externos de plantio ambiental, créditos verdes e auditar registros de forma programática utilizando nossa API REST.

1. Autenticação

Todas as requisições de gravação e mineração para seus projetos requerem autorização. Cada projeto gerado no Painel do Desenvolvedor possui uma credencial de autenticação chamada Token de API (Bearer Token).

Você pode autenticar suas requisições de duas formas:

Enviando o token pelo Header HTTP padrão:
Authorization: Bearer <TOKEN_DO_PROJETO> (Altamente Recomendado)
Enviando o parâmetro pro_hash diretamente no corpo JSON ou POST da requisição.

2. Referência de Endpoints (REST API)

Nossos endpoints retornam exclusivamente respostas estruturadas no padrão JSON (UTF-8).

POST /api/registrar.php

Envia uma nova transação ou registro (ex: evento de plantio) para a piscina de transações aguardando mineração (Mempool).

Parâmetros da Requisição (JSON Body)

Campo	Tipo	Obrigatório	Descrição
remetente	String	Sim	Nome ou ID do sistema externo (ex: "App Plantio SP").
dados	JSON/Array	Sim	Payload de metadados customizados do evento (espécie da árvore, coordenadas, etc).
pro_hash	String	Opcional	Token de API do projeto (pode ser enviado via Header Bearer).

Exemplo de Resposta de Sucesso (HTTP 201)

{
  "sucesso": true,
  "mensagem": "Transação adicionada à Mempool com sucesso!",
  "transacao": {
    "id": 12,
    "remetente": "App Plantio 42",
    "dados": {
      "evento": "Plantio Ambiental de Árvore",
      "especie": "Ipê Amarelo",
      "qty": 1
    },
    "hash": "8a798b3f2...",
    "timestamp": "2026-05-09 10:30:00",
    "status": "pendente"
  }
}

POST /api/minerar.php

Agrupa todas as transações pendentes na Mempool vinculadas a um projeto, executa o cálculo da Merkle Root e resolve o algoritmo de Proof of Work (Dificuldade: 4 zeros) para criar um novo bloco válido.

Exemplo de Resposta de Sucesso (HTTP 200)

{
  "sucesso": true,
  "mensagem": "Novo bloco minerado e adicionado à cadeia com sucesso!",
  "bloco": {
    "indice": 5,
    "hash": "0000a891f7...",
    "hash_anterior": "0000bc712d...",
    "merkle_root": "4a73e81ff...",
    "nonce": 4218,
    "dificuldade": 4,
    "total_transacoes": 3,
    "timestamp": "2026-05-09 10:32:00",
    "status": "valido"
  }
}

GET /api/blocos.php

Retorna todos os blocos já minerados no ledger unificado da blockchain.

Query String Opcional: ?incluir_transacoes=true (retorna todas as transações de cada bloco).

GET /api/validar.php

Realiza uma auditoria computacional criptográfica de ponta a ponta na blockchain. Verifica se algum bloco foi modificado ilegalmente no banco de dados recalculando os hashes matemáticos e validando o encadeamento.

3. Exemplo Prático de Integração (PHP Curl)

Veja como é simples enviar um registro de plantio de árvore diretamente de uma aplicação PHP externa para o simulador:

<?php
$token = "SEU_TOKEN_DE_API_GERADO_NO_PAINEL";
$url = "http://localhost/blockchain/api/registrar.php";

$dadosPlantio = [
    "remetente" => "Dispositivo IoT 104",
    "dados" => [
        "evento" => "Plantio de Árvore",
        "especie" => "Araucária",
        "coordenadas" => [
            "lat" => -23.5505,
            "lng" => -46.6333
        ],
        "qtd" => 1
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($dadosPlantio));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . $token
]);

$response = curl_exec($ch);
curl_close($ch);

echo "Retorno: " . $response;
?>