{"openapi":"3.1.0","info":{"title":"RCGI Carbon Registry — API v1","version":"1.0.0","description":"API para plataformas (marketplaces) lerem o registro e operarem custódia de créditos com autorização das empresas. Quantidades em kg inteiros (1 crédito = 1 tCO₂e = 1000 kg)."},"servers":[{"url":"https://rcgiregister.decodedata.app/"}],"components":{"securitySchemes":{"chave":{"type":"http","scheme":"bearer","description":"Chave de API no formato rcgi_<prefixo>_<segredo>, gerada pelo admin do RCGI."}},"schemas":{},"parameters":{}},"paths":{"/api/v1/projetos":{"get":{"operationId":"listar-projetos","tags":["Registro público"],"summary":"Listar projetos","description":"Projetos públicos do registro: só os validados pelo RCGI-USP. Em análise, reprovados e cancelados não são públicos.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"opcional; só aceita validado (outro valor responde 422)"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":["string","null"]},"slug":{"type":"string"},"nome":{"type":"string"},"status":{"type":"string","enum":["validado"]},"desenvolvedor":{"type":"string"},"protocolo":{"type":"object","properties":{"codigo":{"type":"string"},"nome":{"type":"string"},"versao":{"type":"string"},"setor":{"type":"string"}},"required":["codigo","nome","versao","setor"]},"bioma":{"type":["string","null"]},"uf":{"type":["string","null"]},"municipio":{"type":["string","null"]},"emitido":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"aposentado":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"url":{"type":"string"}},"required":["codigo","slug","nome","status","desenvolvedor","protocolo","bioma","uf","municipio","emitido","aposentado","url"]}}},"required":["dados"],"example":{"dados":[{"codigo":"RCGI-0001","slug":"reflorestamento-fazenda-boa-vista","nome":"Reflorestamento Fazenda Boa Vista","status":"validado","desenvolvedor":"Agro Exemplo S.A.","protocolo":{"codigo":"ARR","nome":"Florestamento e reflorestamento","versao":"v1.0","setor":"Soluções baseadas na natureza"},"bioma":"Cerrado","uf":"MT","municipio":"Sorriso","emitido":{"kg":120000,"toneladas":120},"aposentado":{"kg":5000,"toneladas":5},"url":"https://registro.exemplo/projetos/reflorestamento-fazenda-boa-vista"}]}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/projetos/{codigo}":{"get":{"operationId":"obter-projeto","tags":["Registro público"],"summary":"Obter projeto","description":"Um projeto pelo código (RCGI-0001) ou slug, com os lotes emitidos.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código RCGI-0001 ou slug do projeto"},"required":true,"name":"codigo","in":"path"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":["string","null"]},"slug":{"type":"string"},"nome":{"type":"string"},"status":{"type":"string","enum":["validado"]},"desenvolvedor":{"type":"string"},"protocolo":{"type":"object","properties":{"codigo":{"type":"string"},"nome":{"type":"string"},"versao":{"type":"string"},"setor":{"type":"string"}},"required":["codigo","nome","versao","setor"]},"bioma":{"type":["string","null"]},"uf":{"type":["string","null"]},"municipio":{"type":["string","null"]},"emitido":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"aposentado":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"url":{"type":"string"},"lotes":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"vintage":{"type":"integer"},"quantidade":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"aposentado":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"emitidoEm":{"type":["string","null"]}},"required":["codigo","vintage","quantidade","aposentado","emitidoEm"]}}},"required":["codigo","slug","nome","status","desenvolvedor","protocolo","bioma","uf","municipio","emitido","aposentado","url","lotes"]}},"required":["dados"],"example":{"dados":{"codigo":"RCGI-0001","nome":"Reflorestamento Fazenda Boa Vista","status":"validado","lotes":[{"codigo":"RCGI-0001-2025-01","vintage":2025,"quantidade":{"kg":120000,"toneladas":120},"aposentado":{"kg":5000,"toneladas":5},"emitidoEm":"2026-10-02T14:03:11.000Z"}]}}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/lotes/{codigo}":{"get":{"operationId":"obter-lote","tags":["Registro público"],"summary":"Obter lote","description":"Um lote emitido: quantidade, faixa de seriais (uma por tonelada), projeto e protocolo.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código do lote, ex.: RCGI-0001-2025-01"},"required":true,"name":"codigo","in":"path"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"vintage":{"type":"integer"},"quantidade":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"seriais":{"type":"object","properties":{"inicio":{"type":"integer"},"fim":{"type":"integer"},"unidade":{"type":"string","enum":["tCO2e"]}},"required":["inicio","fim","unidade"]},"projeto":{"type":"object","properties":{"codigo":{"type":["string","null"]},"nome":{"type":"string"},"desenvolvedor":{"type":"string"}},"required":["codigo","nome","desenvolvedor"]},"protocolo":{"type":"object","properties":{"nome":{"type":"string"},"versao":{"type":"string"}},"required":["nome","versao"]},"emitidoEm":{"type":["string","null"]},"url":{"type":"string"}},"required":["codigo","vintage","quantidade","seriais","projeto","protocolo","emitidoEm","url"]}},"required":["dados"],"example":{"dados":{"codigo":"RCGI-0001-2025-01","vintage":2025,"quantidade":{"kg":120000,"toneladas":120},"seriais":{"inicio":1,"fim":120,"unidade":"tCO2e"},"projeto":{"codigo":"RCGI-0001","nome":"Reflorestamento Fazenda Boa Vista","desenvolvedor":"Agro Exemplo S.A."},"protocolo":{"nome":"Florestamento e reflorestamento","versao":"v1.0"},"emitidoEm":"2026-10-02T14:03:11.000Z","url":"https://registro.exemplo/registro/lotes/RCGI-0001-2025-01"}}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/lotes/{codigo}/eventos":{"get":{"operationId":"eventos-lote","tags":["Registro público"],"summary":"Cadeia de custódia do lote","description":"Emissões, transferências e aposentadorias do lote, do mais recente ao mais antigo. Carteira custodiada aparece pela plataforma, nunca pelo nome do comprador.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código do lote"},"required":true,"name":"codigo","in":"path"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"string"},"tipo":{"type":"string","enum":["emissao","transferencia","aposentadoria"]},"estado":{"type":"string","enum":["pendente","confirmado"]},"lote":{"type":"string"},"quantidade":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"de":{"type":["object","null"],"properties":{"codigo":{"type":"string"},"nome":{"type":["string","null"]}},"required":["codigo","nome"]},"para":{"type":["object","null"],"properties":{"codigo":{"type":"string"},"nome":{"type":["string","null"]}},"required":["codigo","nome"]},"certificado":{"type":["string","null"]},"tx":{"type":["object","null"],"properties":{"hash":{"type":"string"},"bloco":{"type":["number","null"]},"url":{"type":"string"}},"required":["hash","bloco","url"]},"criadoEm":{"type":"string"},"confirmadoEm":{"type":["string","null"]}},"required":["codigo","tipo","estado","lote","quantidade","de","para","certificado","tx","criadoEm","confirmadoEm"]}}},"required":["dados"],"example":{"dados":[{"codigo":"trf_7KX92Q4MPA","tipo":"transferencia","estado":"confirmado","lote":"RCGI-0001-2025-01","quantidade":{"kg":10000,"toneladas":10},"de":{"codigo":"cart_A1B2C3D4E5","nome":"Agro Exemplo S.A."},"para":{"codigo":"cart_F6G7H8J9K2","nome":"Custódia · Lastro"},"certificado":null,"tx":{"hash":"0x9f…","bloco":18420012,"url":"https://registro.exemplo/ledger/tx/0x9f…"},"criadoEm":"2026-10-02T15:00:00.000Z","confirmadoEm":"2026-10-02T15:00:05.000Z"}]}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/eventos/{codigo}":{"get":{"operationId":"obter-evento","tags":["Registro público"],"summary":"Acompanhar um evento","description":"Estado de um evento de custódia (iss_…, trf_…, ret_…). Use para saber quando a transação foi confirmada em bloco.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código do evento"},"required":true,"name":"codigo","in":"path"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"tipo":{"type":"string","enum":["emissao","transferencia","aposentadoria"]},"estado":{"type":"string","enum":["pendente","confirmado"]},"lote":{"type":"string"},"quantidade":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"tx":{"type":["object","null"],"properties":{"hash":{"type":"string"},"bloco":{"type":["number","null"]},"url":{"type":"string"}},"required":["hash","bloco","url"]},"confirmadoEm":{"type":["string","null"]}},"required":["codigo","tipo","estado","lote","quantidade","tx","confirmadoEm"]}},"required":["dados"],"example":{"dados":{"codigo":"trf_7KX92Q4MPA","tipo":"transferencia","estado":"pendente","lote":"RCGI-0001-2025-01","quantidade":{"kg":10000,"toneladas":10},"tx":null,"confirmadoEm":null}}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/mandatos":{"post":{"operationId":"pedir-mandato","tags":["Mandatos e carteiras"],"summary":"Pedir autorização a uma empresa","description":"Cria um pedido de mandato para a organização dona do CNPJ. A empresa recebe um e-mail e autoriza logada no RCGI, pelo link devolvido. Vale 7 dias.\n\nEscopo: `leitura`. Exige o header `Idempotency-Key`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","minLength":8,"maxLength":200,"description":"Chave única por operação; repetir devolve a mesma resposta."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cnpj":{"type":"string"},"escopos":{"type":"array","items":{"type":"string","enum":["leitura","custodia:escrita"]}}},"required":["cnpj"],"example":{"cnpj":"12.345.678/0001-95","escopos":["leitura","custodia:escrita"]}}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"estado":{"type":"string","enum":["pendente"]},"escopos":{"type":"array","items":{"type":"string"}},"expiraEm":{"type":"string"},"linkAutorizacao":{"type":"string"}},"required":["codigo","estado","escopos","expiraEm","linkAutorizacao"]}},"required":["dados"],"example":{"dados":{"codigo":"7KX92Q4MPA3B","estado":"pendente","escopos":["leitura","custodia:escrita"],"expiraEm":"2026-10-09T14:00:00.000Z","linkAutorizacao":"https://registro.exemplo/autorizar/7KX92Q4MPA3B"}}}}}},"400":{"description":"json: O corpo não é JSON válido. · idempotency_key: Escrita sem o header Idempotency-Key (8 a 200 caracteres).","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"422":{"description":"invalido: Campos inválidos — o detalhe vem em `erro.campos`. · idempotency_key: A Idempotency-Key já foi usada com outro corpo ou outra rota.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/mandatos/{codigo}":{"get":{"operationId":"obter-mandato","tags":["Mandatos e carteiras"],"summary":"Estado do mandato","description":"Consulte até virar `ativo`: aí vem o código da carteira que a plataforma passa a operar. Pode virar `recusado`, `revogado` ou `expirado`.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código devolvido ao pedir o mandato"},"required":true,"name":"codigo","in":"path"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"estado":{"type":"string","enum":["pendente","ativo","recusado","revogado","expirado"]},"escopos":{"type":"array","items":{"type":"string"}},"carteira":{"type":["string","null"]},"expiraEm":{"type":"string"},"decididoEm":{"type":["string","null"]}},"required":["codigo","estado","escopos","carteira","expiraEm","decididoEm"]}},"required":["dados"],"example":{"dados":{"codigo":"7KX92Q4MPA3B","estado":"ativo","escopos":["leitura","custodia:escrita"],"carteira":"cart_A1B2C3D4E5","expiraEm":"2026-10-09T14:00:00.000Z","decididoEm":"2026-10-02T14:10:00.000Z"}}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/carteiras":{"post":{"operationId":"abrir-carteira","tags":["Mandatos e carteiras"],"summary":"Abrir carteira custodiada","description":"Carteira de um comprador que não tem conta no RCGI, custodiada pela plataforma. Idempotente por documento: pedir de novo devolve a mesma (200 em vez de 201).\n\nEscopo: `custodia:escrita`. Exige o header `Idempotency-Key`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","minLength":8,"maxLength":200,"description":"Chave única por operação; repetir devolve a mesma resposta."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"titularDocumento":{"type":"string"},"titularNome":{"type":"string"}},"required":["titularDocumento","titularNome"],"example":{"titularDocumento":"98.765.432/0001-10","titularNome":"Comprador Exemplo Ltda."}}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"tipo":{"type":"string","enum":["custodiada"]},"titular":{"type":"string"},"endereco":{"type":"string"}},"required":["codigo","tipo","titular","endereco"]}},"required":["dados"],"example":{"dados":{"codigo":"cart_F6G7H8J9K2","tipo":"custodiada","titular":"Comprador Exemplo Ltda.","endereco":"0x4b1c…"}}}}}},"400":{"description":"json: O corpo não é JSON válido. · idempotency_key: Escrita sem o header Idempotency-Key (8 a 200 caracteres).","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"422":{"description":"invalido: Campos inválidos — o detalhe vem em `erro.campos`. · idempotency_key: A Idempotency-Key já foi usada com outro corpo ou outra rota.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/carteiras/{codigo}/saldos":{"get":{"operationId":"saldos","tags":["Mandatos e carteiras"],"summary":"Saldos de uma carteira","description":"Saldo lote a lote: total, reservado, disponível e a caminho (entrada ainda não confirmada). Só de carteira custodiada pela plataforma ou com mandato ativo.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código da carteira"},"required":true,"name":"codigo","in":"path"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"carteira":{"type":"object","properties":{"codigo":{"type":"string"},"tipo":{"type":"string","enum":["organizacao","custodiada"]},"titular":{"type":"string"}},"required":["codigo","tipo","titular"]},"saldos":{"type":"array","items":{"type":"object","properties":{"lote":{"type":"string"},"vintage":{"type":"integer"},"total":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"reservado":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"disponivel":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"aCaminho":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]}},"required":["lote","vintage","total","reservado","disponivel","aCaminho"]}}},"required":["carteira","saldos"]}},"required":["dados"],"example":{"dados":{"carteira":{"codigo":"cart_A1B2C3D4E5","tipo":"organizacao","titular":"Agro Exemplo S.A."},"saldos":[{"lote":"RCGI-0001-2025-01","vintage":2025,"total":{"kg":120000,"toneladas":120},"reservado":{"kg":10000,"toneladas":10},"disponivel":{"kg":110000,"toneladas":110},"aCaminho":{"kg":0,"toneladas":0}}]}}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/reservas":{"post":{"operationId":"reservar","tags":["Venda e aposentadoria"],"summary":"Reservar créditos","description":"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.\n\nEscopo: `custodia:escrita`. Exige o header `Idempotency-Key`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","minLength":8,"maxLength":200,"description":"Chave única por operação; repetir devolve a mesma resposta."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"carteira":{"type":"string"},"lote":{"type":"string"},"qtdKg":{"type":"integer","exclusiveMinimum":0},"referenciaExterna":{"type":"string"},"validadeHoras":{"type":"integer","minimum":1,"maximum":720}},"required":["carteira","lote","qtdKg"],"example":{"carteira":"cart_A1B2C3D4E5","lote":"RCGI-0001-2025-01","qtdKg":10000,"referenciaExterna":"pedido-1042","validadeHoras":168}}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"estado":{"type":"string","enum":["ativa"]},"carteira":{"type":"string"},"lote":{"type":"string"},"quantidade":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"referenciaExterna":{"type":["string","null"]},"expiraEm":{"type":"string"}},"required":["codigo","estado","carteira","lote","quantidade","referenciaExterna","expiraEm"]}},"required":["dados"],"example":{"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"}}}}}},"400":{"description":"json: O corpo não é JSON válido. · idempotency_key: Escrita sem o header Idempotency-Key (8 a 200 caracteres).","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"409":{"description":"conflito: O estado não permite a operação (ex.: liquidar reserva vencida). · saldo_insuficiente: Disponível menor que o pedido. · em_processamento: Outra chamada com a mesma Idempotency-Key ainda está rodando. Repita em instantes.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"422":{"description":"invalido: Campos inválidos — o detalhe vem em `erro.campos`. · idempotency_key: A Idempotency-Key já foi usada com outro corpo ou outra rota.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/reservas/{codigo}":{"get":{"operationId":"obter-reserva","tags":["Venda e aposentadoria"],"summary":"Estado da reserva","description":"Inclui a transferência, depois de liquidada, com o estado da confirmação na blockchain.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código da reserva"},"required":true,"name":"codigo","in":"path"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"estado":{"type":"string","enum":["ativa","liquidada","cancelada","expirada"]},"quantidade":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"referenciaExterna":{"type":["string","null"]},"expiraEm":{"type":"string"},"transferencia":{"type":["object","null"],"properties":{"codigo":{"type":"string"},"estado":{"type":["string","null"]},"txHash":{"type":["string","null"]}},"required":["codigo","estado","txHash"]}},"required":["codigo","estado","quantidade","referenciaExterna","expiraEm","transferencia"]}},"required":["dados"],"example":{"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…"}}}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/reservas/{codigo}/liquidar":{"post":{"operationId":"liquidar","tags":["Venda e aposentadoria"],"summary":"Liquidar reserva","description":"A venda fechou: transfere os créditos reservados para a carteira do comprador. A transferência nasce pendente e confirma com a blockchain.\n\nEscopo: `custodia:escrita`. Exige o header `Idempotency-Key`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código da reserva"},"required":true,"name":"codigo","in":"path"},{"schema":{"type":"string","minLength":8,"maxLength":200,"description":"Chave única por operação; repetir devolve a mesma resposta."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"carteiraDestino":{"type":"string"}},"required":["carteiraDestino"],"example":{"carteiraDestino":"cart_F6G7H8J9K2"}}}}},"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"estado":{"type":"string","enum":["liquidada"]}},"required":["codigo","estado"]}},"required":["dados"],"example":{"dados":{"codigo":"res_2Q4MPA7KX9","estado":"liquidada"}}}}}},"400":{"description":"json: O corpo não é JSON válido. · idempotency_key: Escrita sem o header Idempotency-Key (8 a 200 caracteres).","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"409":{"description":"conflito: O estado não permite a operação (ex.: liquidar reserva vencida). · saldo_insuficiente: Disponível menor que o pedido. · em_processamento: Outra chamada com a mesma Idempotency-Key ainda está rodando. Repita em instantes.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"422":{"description":"invalido: Campos inválidos — o detalhe vem em `erro.campos`. · idempotency_key: A Idempotency-Key já foi usada com outro corpo ou outra rota.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/reservas/{codigo}/cancelar":{"post":{"operationId":"cancelar","tags":["Venda e aposentadoria"],"summary":"Cancelar reserva","description":"Devolve os créditos ao disponível. Cancelar de novo não é erro.\n\nEscopo: `custodia:escrita`. Exige o header `Idempotency-Key`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código da reserva"},"required":true,"name":"codigo","in":"path"},{"schema":{"type":"string","minLength":8,"maxLength":200,"description":"Chave única por operação; repetir devolve a mesma resposta."},"required":true,"name":"idempotency-key","in":"header"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"codigo":{"type":"string"},"estado":{"type":"string","enum":["cancelada"]}},"required":["codigo","estado"]}},"required":["dados"],"example":{"dados":{"codigo":"res_2Q4MPA7KX9","estado":"cancelada"}}}}}},"400":{"description":"json: O corpo não é JSON válido. · idempotency_key: Escrita sem o header Idempotency-Key (8 a 200 caracteres).","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"409":{"description":"conflito: O estado não permite a operação (ex.: liquidar reserva vencida). · saldo_insuficiente: Disponível menor que o pedido. · em_processamento: Outra chamada com a mesma Idempotency-Key ainda está rodando. Repita em instantes.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"422":{"description":"invalido: Campos inválidos — o detalhe vem em `erro.campos`. · idempotency_key: A Idempotency-Key já foi usada com outro corpo ou outra rota.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/aposentadorias":{"post":{"operationId":"aposentar","tags":["Venda e aposentadoria"],"summary":"Aposentar créditos","description":"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.\n\nEscopo: `custodia:escrita`. Exige o header `Idempotency-Key`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","minLength":8,"maxLength":200,"description":"Chave única por operação; repetir devolve a mesma resposta."},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"carteira":{"type":"string"},"lote":{"type":"string"},"qtdKg":{"type":"integer","exclusiveMinimum":0},"beneficiarioNome":{"type":"string"},"beneficiarioDocumento":{"type":"string"},"motivo":{"type":"string"},"anoCompensado":{"type":"integer"}},"required":["carteira","lote","qtdKg","beneficiarioNome","beneficiarioDocumento","motivo","anoCompensado"],"example":{"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}}}}},"responses":{"201":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"certificado":{"type":"string"},"lote":{"type":"string"},"quantidade":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"beneficiario":{"type":"string"},"anoCompensado":{"type":"integer"},"hashCertificado":{"type":"string"},"evento":{"type":"string"},"estado":{"type":"string","enum":["pendente"]},"urlVerificacao":{"type":"string"}},"required":["certificado","lote","quantidade","beneficiario","anoCompensado","hashCertificado","evento","estado","urlVerificacao"]}},"required":["dados"],"example":{"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"}}}}}},"400":{"description":"json: O corpo não é JSON válido. · idempotency_key: Escrita sem o header Idempotency-Key (8 a 200 caracteres).","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"409":{"description":"conflito: O estado não permite a operação (ex.: liquidar reserva vencida). · saldo_insuficiente: Disponível menor que o pedido. · em_processamento: Outra chamada com a mesma Idempotency-Key ainda está rodando. Repita em instantes.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"422":{"description":"invalido: Campos inválidos — o detalhe vem em `erro.campos`. · idempotency_key: A Idempotency-Key já foi usada com outro corpo ou outra rota.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}},"/api/v1/aposentadorias/{codigo}":{"get":{"operationId":"obter-certificado","tags":["Venda e aposentadoria"],"summary":"Obter certificado","description":"O certificado de aposentadoria, com o estado da confirmação e o hash.\n\nEscopo: `leitura`.","security":[{"chave":[]}],"parameters":[{"schema":{"type":"string","description":"Código RCGI-APO-…"},"required":true,"name":"codigo","in":"path"}],"responses":{"200":{"description":"Sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"dados":{"type":"object","properties":{"certificado":{"type":"string"},"estado":{"type":"string","enum":["pendente","confirmado"]},"lote":{"type":"string"},"projeto":{"type":"object","properties":{"codigo":{"type":["string","null"]},"nome":{"type":"string"}},"required":["codigo","nome"]},"quantidade":{"type":"object","properties":{"kg":{"type":"integer"},"toneladas":{"type":"number"}},"required":["kg","toneladas"]},"beneficiario":{"type":"string"},"motivo":{"type":"string"},"anoCompensado":{"type":"integer"},"hashCertificado":{"type":"string"},"tx":{"type":["object","null"],"properties":{"hash":{"type":"string"},"bloco":{"type":["number","null"]}},"required":["hash","bloco"]},"urlVerificacao":{"type":"string"}},"required":["certificado","estado","lote","projeto","quantidade","beneficiario","motivo","anoCompensado","hashCertificado","tx","urlVerificacao"]}},"required":["dados"],"example":{"dados":{"certificado":"RCGI-APO-7KX9-2Q4M","estado":"confirmado","lote":"RCGI-0001-2025-01","quantidade":{"kg":5000,"toneladas":5}}}}}}},"401":{"description":"nao_autenticado: Sem chave, chave inválida ou revogada.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"404":{"description":"nao_encontrado: Não existe — ou existe e não é da sua plataforma. As duas respostas são iguais de propósito.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}},"429":{"description":"limite: Mais de 120 chamadas por minuto com a mesma chave.","content":{"application/json":{"schema":{"type":"object","properties":{"erro":{"type":"object","properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"campos":{"type":"object","additionalProperties":{"type":"string"}}},"required":["codigo","mensagem"]}},"required":["erro"]}}}}}}}},"webhooks":{}}