O ciclo de uma venda: reservar ao criar o pedido, liquidar quando o pagamento for confirmado, aposentar quando o comprador compensar.
POST/api/v1/reservas
Reservar créditos
Segura créditos de uma carteira enquanto a venda acontece. Sem saldo disponível, 409 saldo_insuficiente. Validade padrão de 7 dias, máximo 30.
escopo custodia:escritaexige Idempotency-Key
Requisição
curl -X POST "$RCGI/api/v1/reservas" \
-H "Authorization: Bearer $RCGI_CHAVE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"carteira":"cart_A1B2C3D4E5","lote":"RCGI-0001-2025-01","qtdKg":10000,"referenciaExterna":"pedido-1042","validadeHoras":168}'
Resposta 201
{
"dados": {
"codigo": "res_2Q4MPA7KX9",
"estado": "ativa",
"carteira": "cart_A1B2C3D4E5",
"lote": "RCGI-0001-2025-01",
"quantidade": {
"kg": 10000,
"toneladas": 10
},
"referenciaExterna": "pedido-1042",
"expiraEm": "2026-10-09T14:00:00.000Z"
}
}
Erros específicos: invalido, nao_encontrado, saldo_insuficiente, idempotency_key.
GET/api/v1/reservas/{codigo}
Estado da reserva
Inclui a transferência, depois de liquidada, com o estado da confirmação na blockchain.
escopo leitura
- codigo (caminho)
- Código da reserva
Requisição
curl -X GET "$RCGI/api/v1/reservas/RCGI-0001-2025-01" \
-H "Authorization: Bearer $RCGI_CHAVE"
Resposta 200
{
"dados": {
"codigo": "res_2Q4MPA7KX9",
"estado": "liquidada",
"quantidade": {
"kg": 10000,
"toneladas": 10
},
"referenciaExterna": "pedido-1042",
"expiraEm": "2026-10-09T14:00:00.000Z",
"transferencia": {
"codigo": "trf_7KX92Q4MPA",
"estado": "confirmado",
"txHash": "0x9f…"
}
}
}
Erros específicos: nao_encontrado.
POST/api/v1/reservas/{codigo}/liquidar
Liquidar reserva
A venda fechou: transfere os créditos reservados para a carteira do comprador. A transferência nasce pendente e confirma com a blockchain.
escopo custodia:escritaexige Idempotency-Key
- codigo (caminho)
- Código da reserva
Requisição
curl -X POST "$RCGI/api/v1/reservas/RCGI-0001-2025-01/liquidar" \
-H "Authorization: Bearer $RCGI_CHAVE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"carteiraDestino":"cart_F6G7H8J9K2"}'
Resposta 200
{
"dados": {
"codigo": "res_2Q4MPA7KX9",
"estado": "liquidada"
}
}
Erros específicos: nao_encontrado, conflito, invalido, idempotency_key.
POST/api/v1/reservas/{codigo}/cancelar
Cancelar reserva
Devolve os créditos ao disponível. Cancelar de novo não é erro.
escopo custodia:escritaexige Idempotency-Key
- codigo (caminho)
- Código da reserva
Requisição
curl -X POST "$RCGI/api/v1/reservas/RCGI-0001-2025-01/cancelar" \
-H "Authorization: Bearer $RCGI_CHAVE" \
-H "Idempotency-Key: $(uuidgen)"
Resposta 200
{
"dados": {
"codigo": "res_2Q4MPA7KX9",
"estado": "cancelada"
}
}
Erros específicos: nao_encontrado, conflito, idempotency_key.
POST/api/v1/aposentadorias
Aposentar créditos
Tira créditos de circulação para sempre, em nome de um beneficiário, e gera o certificado público. O documento do beneficiário entra no hash do certificado, nunca em texto aberto.
escopo custodia:escritaexige Idempotency-Key
Requisição
curl -X POST "$RCGI/api/v1/aposentadorias" \
-H "Authorization: Bearer $RCGI_CHAVE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"carteira":"cart_F6G7H8J9K2","lote":"RCGI-0001-2025-01","qtdKg":5000,"beneficiarioNome":"Comprador Exemplo Ltda.","beneficiarioDocumento":"98.765.432/0001-10","motivo":"Compensação das emissões de escopo 1 de 2025","anoCompensado":2025}'
Resposta 201
{
"dados": {
"certificado": "RCGI-APO-7KX9-2Q4M",
"lote": "RCGI-0001-2025-01",
"quantidade": {
"kg": 5000,
"toneladas": 5
},
"beneficiario": "Comprador Exemplo Ltda.",
"anoCompensado": 2025,
"hashCertificado": "3f9a…",
"evento": "ret_PA7KX92Q4M",
"estado": "pendente",
"urlVerificacao": "https://registro.exemplo/verificar/RCGI-APO-7KX9-2Q4M"
}
}
Erros específicos: invalido, nao_encontrado, saldo_insuficiente, idempotency_key.
GET/api/v1/aposentadorias/{codigo}
Obter certificado
O certificado de aposentadoria, com o estado da confirmação e o hash.
escopo leitura
- codigo (caminho)
- Código RCGI-APO-…
Requisição
curl -X GET "$RCGI/api/v1/aposentadorias/RCGI-0001-2025-01" \
-H "Authorization: Bearer $RCGI_CHAVE"
Resposta 200
{
"dados": {
"certificado": "RCGI-APO-7KX9-2Q4M",
"estado": "confirmado",
"lote": "RCGI-0001-2025-01",
"quantidade": {
"kg": 5000,
"toneladas": 5
}
}
}
Erros específicos: nao_encontrado.