API do CNPSA para órgãos receptores

Sobre esta API

Este manual estabelece o padrão de consulta do Cadastro Nacional de Pagamento por Serviços Ambientais (CNPSA). O órgão firma acordo com o Ministério do Meio Ambiente e Mudança do Clima. Depois do credenciamento, o sistema do órgão consulta os registros do cadastro nacional.

A Lei nº 14.119, de 13 de janeiro de 2021, instituiu o CNPSA. Esta API disponibiliza iniciativas, contratos, previsões de pagamento e a situação registrada no cadastro.

Como ler

Este é o manual da API de consulta do CNPSA. O acordo de cooperação é anterior a este manual e define o recorte autorizado ao órgão.

• Até o roteiro, o texto descreve o que a API disponibiliza e como o órgão se habilita.
• Entradas, saídas e os anexos descrevem cabeçalho, filtro e campo da resposta.
• A especificação de cada operação está em Swagger. O botão Try it out mostra o formato da chamada. O endereço e a credencial são os do credenciamento.

O que a API entrega

A resposta reúne o que o cadastro registra e o que o CNPSA produz na vigência do registro: código nacional, verificação do contrato e situação do benefício.

1. Organização pagadora — CNPJ, razão social, natureza jurídica e endereço público, mais a situação do cadastro (aguardando confirmação de e-mail, ou aprovada).
2. Iniciativa — o programa: onde atua, serviços, orçamento, formas de pagamento e o código nacional.
3. Contrato — o instrumento com o provedor: documento, local, CAR quando for terra privada, valores, serviços e vigência.
4. Previsão de pagamento — ano, período e valor previsto registrados no contrato.
5. Situação — se o provedor conferiu, se manifestou interesse na isenção e se o MMA informou habilitado ou não habilitado, com o motivo quando não habilita.

Banco, agência, conta e chave PIX constam do contrato quando o pagamento é em dinheiro. Esse bloco integra a resposta quando o acordo o autoriza e a chamada envia incluir_dados_recebimento=true. Sem essa autorização, a API recusa a chamada.

O que a API não entrega

• inclusão ou alteração de programa, contrato ou pagamento;
• comprovante de pagamento ou data de liquidação bancária — o bloco de pagamento é a previsão registrada no contrato;
• nome de quem alterou o registro;
• relação de pessoas com acesso à organização;
• polígono ou mapa do imóvel;
• formato diferente do descrito neste manual.

Como o órgão se conecta

O cadastro nacional publica este contrato. O órgão se habilita e passa a consultar.

1. Acordo

MMA e órgão formalizam o entendimento: para que a consulta serve, qual o recorte (UF, tipo de situação, se inclui dado de recebimento) e quem são os pontos focais. Sem acordo vigente, não há token.

2. Credencial

A CGTI libera um ambiente de teste e uma credencial de órgão receptor. Toda chamada leva o token e o CNPJ do órgão no cabeçalho. O token identifica o acordo, não uma pessoa.

3. Homologação

No ambiente de teste, o órgão consulta um conjunto pequeno de registros e confere código nacional, situação, documento do provedor e previsão de pagamento com o descrito neste manual.

4. Rotina

No dia a dia o órgão não baixa o acervo inteiro toda vez. Pede o que mudou desde a última consulta (atualizado_desde) e percorre as páginas. O teto é 200 registros por página.

Regras

• Consulta. As operações desta API leem o cadastro.
• O acordo delimita o recorte. UF, situação ou bloco de recebimento fora do acordo recebe recusa.
• O código nacional é do CNPSA. O órgão guarda esse código para não duplicar o programa do lado dele. Se o registro veio de um Estado, a resposta também traz o código de origem.
• E-mail e telefone do contrato são o contato informado no instrumento.
• O status de benefício é o registrado no CNPSA. Habilitado indica a habilitação informada no cadastro.
• O bloco de pagamento é a previsão do contrato. Ano, período e valor previsto.
• CPF, CAR e valor integram a resposta do órgão credenciado. O tratamento desses dados segue o acordo.

Como saber que a conexão está certa

• Sem token, ou com acordo vencido, a chamada não devolve registro.
• Com credencial de teste, uma iniciativa conhecida volta com id_nacional no formato CNPSA-AAAA-XXXXX.
• O contrato dessa iniciativa volta com situação de verificação e situação de benefício.
• Pedir dado de recebimento sem cláusula no acordo recusa a chamada.
• A segunda consulta com atualizado_desde não repete o que não mudou.
• Página acima de 200 itens é recusada. O órgão pede a página seguinte.

Roteiro de adesão

1. O órgão pede ao MMA a consulta e diz o recorte e se precisa de banco ou PIX.
2. O acordo registra esse recorte.
3. A CGTI entrega host de teste e credencial.
4. A equipe técnica implementa a consulta conforme as entradas, as saídas e o Swagger.
5. Homologação com um recorte pequeno.
6. Rotina: consulta do que mudou, em páginas.

Entradas

Toda chamada informa a credencial e o CNPJ do órgão. Os demais parâmetros recortam a consulta. A comunicação é HTTPS e a resposta é JSON.

Em toda chamada

Para achar o registro

Saídas

Cinco consultas. A lista devolve uma página: pagina, tamanho, total, atualizado_ate e itens. O detalhe de cada item está nos anexos.

Resposta de erro traz codigo e mensagem. Sem credencial, o código é de não autorizado. Fora do acordo, o código é fora_do_acordo.

Anexo A — iniciativa e organização

Serviço, bioma, tipo de provedor, fonte de financiamento e forma de pagamento usam as listas oficiais do cadastro, reproduzidas na especificação Swagger.

Organização pagadora

Iniciativa

A iniciativa não traz pergunta de isenção. Isenção é do provedor, no contrato.

Anexo B — contrato e previsão

Anexo C — o que o CNPSA gera

Campos produzidos pelo CNPSA na vigência do registro.

Especificação Swagger

Cada operação abaixo repete as entradas e as saídas deste manual. O botão Try it out mostra o formato da chamada. O endereço e a credencial são os do credenciamento.

Baixar OpenAPI (.json) Abrir só o Swagger