Umbrella Technology

API Rural — referência e testes

Documentação pública para integrar dados do CAR (Cadastro Ambiental Rural) em sistemas externos. Cole seu token abaixo e execute qualquer endpoint direto desta página.

Base URL Token (Authorization: Bearer …)

O token fica só na aba do navegador (sessionStorage) e nunca é enviado para a Umbrella fora das chamadas que você disparar. Ainda não tem token? Solicite a liberação no painel.

Sandbox — teste sem gastar crédito

Os valores abaixo são reservados: respondem com dados fixos, não consultam a base e não debitam saldo nem contam nos seus limites. Toda resposta de sandbox traz o campo "sandbox": true. Use-os à vontade em ambiente de desenvolvimento e em CI.

Valor	Onde usar	Resposta
`ZZ-0000000-SANDBOXCARBASICO0000000000000000`	CAR básico, completo e recibo	200 dados de exemplo (recibo devolve um PDF real)
`ZZ-0000000-SANDBOXNAOEXISTE0000000000000000`	CAR básico, completo e recibo	404 `CAR_NAO_ENCONTRADO`
`ZZ-0000000-SANDBOXSEMSALDO00000000000000000`	CAR básico, completo e recibo	402 `SALDO_INSUFICIENTE`
`00000000000`	Proprietário	200 dois CARs, `truncado: false`
`00000000000000`	Proprietário	200 `truncado: true`
`11111111111`	Proprietário	404 `CPF_CNPJ_NAO_ENCONTRADO`

A autenticação continua valendo no sandbox: um token inválido devolve 401 normalmente, para você exercitar esse caminho também.

Visão geral

A API Rural fornece acesso direto aos dados de imóveis rurais por código CAR ou por CPF/CNPJ. A maioria das respostas é em JSON; o endpoint de recibo entrega o PDF do CAR diretamente no corpo da resposta. Projetada para integrações backend, aplicações web e fluxos internos de análise.

Endpoint	Preço vigente (HTTP 200)	Formato
`GET /v1/car/{codigoCar}`	R$ 1,00	JSON
`GET /v1/car/{codigoCar}/completo`	R$ 2,30	JSON
`GET /v1/car/{codigoCar}/recibo`	R$ 11,00	PDF (`application/pdf`)
`GET /v1/proprietario/{cpfCnpj}`	R$ 2,60	JSON
`GET /v1/saldo`	Grátis	JSON
`GET /v1/historico`	Grátis	JSON
`GET /v1/limites` · `PUT /v1/limites`	Grátis	JSON
`GET /v1/uso`	Grátis	JSON
`GET /v1/recarga/faixas`	Grátis	JSON
`POST /v1/recarga`	Grátis	JSON (PIX)
`GET /v1/recarga/{id}`	Grátis	JSON
`GET /v1/recargas`	Grátis	JSON

Base URL: https://api.umbrellatecnologia.com/v1 (ou o domínio informado no seu contrato). Preços da tabela = vigentes (contas novas e após qualquer recarga). Contas antigas ainda sem recarga podem estar em tabela legada (R$ 0,50 / R$ 1,50 / R$ 1,50 / R$ 10,00) até a próxima recarga — o preço efetivo da sua conta vem em GET /v1/saldo → precos.

Autenticação

Solicite a liberação da API com a Umbrella Technology.
Receba seu token exclusivo no dashboard do cliente.
Envie o token no header Authorization em cada chamada.

Authorization: Bearer umb_token_exemplo_xxxxxxxxx

Créditos e cobrança

Esta API segue o modelo pré-pago (pay as you go). A cobrança ocorre apenas em respostas HTTP 200 dos endpoints de consulta (CAR, proprietário e recibo), de acordo com o preço de cada um. Os endpoints de apoio (/v1/saldo, /v1/historico, /v1/limites, /v1/uso, /v1/recarga*) são gratuitos e cobrem o que antes exigia o dashboard da API: consultar saldo, histórico, ajustar limites e adicionar créditos via PIX.

Rate limit: até 10 requisições por segundo por token (inclui endpoints de apoio). Erros (4xx/5xx) não debitam saldo. Recarga mínima: R$ 500,00.

Endpoints

GET /v1/car/{codigoCar} R$ 1,00 Retorna dados básicos do CAR (sem lista de proprietários)

Parâmetros

Nome	Obrigatório	Tipo	Descrição
`codigoCar`	Sim	string	Código CAR no formato UF-CodigoMunicipio-Hash.

Exemplo de resposta

{
  "success": true,
  "cache": true,
  "dados": {
    "codigoCar": "UF-1234567-ABCD.EF12.3456.7890.ABCD.EF12.3456.7890",
    "nomeImovel": "FAZENDA MODELO A",
    "areaTotalHa": "150,0000",
    "dataCadastro": "01/02/2024 00:00:00",
    "matriculaNumero": "12345",
    "matriculaData": "20/01/2024",
    "matriculaCartorio": "Cartório Modelo/UF",
    "tipoImovel": "Imóvel Rural",
    "municipio": "Cidade Exemplo",
    "uf": "ESTADO EXEMPLO",
    "codigoProtocolo": "UF-1234567-PROT.0001.0002.0003.0004.0005.0006.0007",
    "latitude": "10°00'00,00 S",
    "longitude": "40°00'00,00 O",
    "modulosFiscais": "5,0000"
  },
  "dataConsulta": "2026-03-26T19:42:17.7444013Z",
  "dataExpiracao": null
}

codigoCar

GET /v1/car/{codigoCar}/completo R$ 2,30 Retorna dados completos do CAR, incluindo proprietários

Parâmetros

Nome	Obrigatório	Tipo	Descrição
`codigoCar`	Sim	string	Código CAR no formato UF-CodigoMunicipio-Hash.

Exemplo de resposta

{
  "success": true,
  "cache": true,
  "dados": {
    "codigoCar": "UF-1234567-ABCD.EF12.3456.7890.ABCD.EF12.3456.7890",
    "nomeImovel": "FAZENDA MODELO B",
    "areaTotalHa": "320,5000",
    "dataCadastro": "05/03/2023 00:00:00",
    "matriculaNumero": "67890",
    "matriculaData": "10/02/2023",
    "matriculaCartorio": "Cartório Exemplo/UF",
    "tipoImovel": "Imóvel Rural",
    "municipio": "Município Fictício",
    "uf": "ESTADO EXEMPLO",
    "codigoProtocolo": "UF-1234567-PROT.9000.8000.7000.6000.5000.4000.3000",
    "proprietariosNomes": "PROPRIETARIO EXEMPLO LTDA",
    "proprietariosCpfs": "12.345.678/0001-99",
    "latitude": "11°11'11,11 S",
    "longitude": "41°11'11,11 O",
    "modulosFiscais": "10,7000"
  },
  "dataConsulta": "2026-03-26T19:05:05.3974095Z",
  "dataExpiracao": null
}

codigoCar

GET /v1/car/{codigoCar}/recibo R$ 11,00 Download do PDF do recibo CAR

Retorna o arquivo PDF do recibo do imóvel rural correspondente ao código CAR informado. Diferente dos demais endpoints, a resposta de sucesso não é JSON: o corpo da resposta HTTP é o binário do PDF.

Parâmetros

Nome	Obrigatório	Tipo	Descrição
`codigoCar`	Sim	string	Código CAR no formato `UF-CodigoMunicipio-Hash` (hash com 32 caracteres).

Resposta de sucesso (HTTP 200)

Header	Valor
`Content-Type`	`application/pdf`
`Content-Disposition`	`attachment; filename="{codigoCar}.pdf"`

Salve o corpo da resposta como arquivo .pdf. Clientes HTTP que respeitam Content-Disposition (navegadores, Postman) usam automaticamente o nome sugerido com o código CAR.

Resposta de erro

Falhas retornam JSON no mesmo padrão dos outros endpoints: { "success": false, "error": "...", "message": "..." }. Erros não consomem crédito.

Exemplo (curl)

curl -i "https://api.umbrellatecnologia.com/v1/car/BA-2900801-0A466FD693B247B9A397829A0D6AA2E3/recibo" \
  -H "Authorization: Bearer umb_token_exemplo_xxxxxxxxx" \
  -J -o ./

# Ou nome explícito:
curl "https://api.umbrellatecnologia.com/v1/car/BA-2900801-0A466FD693B247B9A397829A0D6AA2E3/recibo" \
  -H "Authorization: Bearer umb_token_exemplo_xxxxxxxxx" \
  -o "BA-2900801-0A466FD693B247B9A397829A0D6AA2E3.pdf"

Exemplo (Python)

import requests

codigo = "BA-2900801-0A466FD693B247B9A397829A0D6AA2E3"
url = f"https://api.umbrellatecnologia.com/v1/car/{codigo}/recibo"
headers = {"Authorization": "Bearer umb_token_exemplo_xxxxxxxxx"}

response = requests.get(url, headers=headers, timeout=60)
if response.status_code == 200:
    with open(f"{codigo}.pdf", "wb") as f:
        f.write(response.content)
    print("PDF salvo:", f"{codigo}.pdf")
else:
    print(response.status_code, response.json())

codigoCar

GET /v1/proprietario/{cpfCnpj} R$ 2,60 Retorna os CARs vinculados ao CPF/CNPJ informado

Parâmetros

Nome	Obrigatório	Tipo	Descrição
`cpfCnpj`	Sim	string	CPF (11 dígitos) ou CNPJ (14 caracteres numéricos ou alfanuméricos; com ou sem máscara).

Exemplo de resposta

Retorna no máximo 200 CARs. Se o documento tiver mais registros, truncado vem true e a lista traz os 200 primeiros ordenados por código CAR.

{
  "success": true,
  "total": 2,
  "limite": 200,
  "truncado": false,
  "itens": [
    {
      "registroCar": "UF-1234567-ABCD.EF12.3456.7890.ABCD.EF12.3456.7890",
      "codigoProtocolo": "UF-1234567-PROT.1111.2222.3333.4444.5555.6666.7777",
      "nomeImovel": "SÍTIO DEMONSTRAÇÃO 01",
      "matriculaNumero": "10101",
      "municipio": "Cidade Exemplo",
      "uf": "Estado Exemplo",
      "areaTotalHa": "45,9000",
      "proprietarioConsultado": "PESSOA FICTÍCIA A"
    },
    {
      "registroCar": "UF-7654321-9999.8888.7777.6666.5555.4444.3333.2222",
      "codigoProtocolo": null,
      "nomeImovel": "FAZENDA DEMONSTRAÇÃO 02",
      "matriculaNumero": "20202",
      "municipio": "Município Modelo",
      "uf": "Estado Modelo",
      "areaTotalHa": "87,3000",
      "proprietarioConsultado": "PESSOA FICTÍCIA B"
    }
  ]
}

cpfCnpj

GET /v1/saldo Grátis Saldo, limites, preços e uso do dia/mês

Retorna o saldo atual da conta autenticada pelo token, limites configurados, preços efetivos dos endpoints de consulta e totais de uso do dia e do mês (fuso de Brasília). Não consome crédito e não aparece no histórico de cobrança.

Exemplo de resposta

{
  "success": true,
  "saldoReais": 1234.56,
  "limiteDiarioRequisicoes": 1000,
  "limiteMensalReais": 5000.00,
  "precos": {
    "carBasico": 1.00,
    "carCompleto": 2.30,
    "proprietario": 2.60,
    "recibo": 11.00
  },
  "usoHoje": {
    "requisicoes": 12,
    "gasto": 15.60,
    "erros": 1
  },
  "usoMes": {
    "requisicoes": 80,
    "gasto": 120.00
  }
}

GET /v1/historico Grátis Histórico paginado de requisições da conta

Lista o consumo da conta com paginação (padrão 20 itens, máximo 100 por página) para não sobrecarregar a integração. Ordenado da requisição mais recente para a mais antiga. Não consome crédito.

Query params

Nome	Obrigatório	Tipo	Descrição
`page`	Não	int	Página (padrão `1`).
`size`	Não	int	Itens por página (padrão `20`, máximo `100`).
`busca`	Não	string	Filtra por trecho em `chaveConsulta` ou `endpoint`.
`endpoint`	Não	string	Filtro exato do endpoint (ex.: `/v1/car/{codigo}`).
`status`	Não	string	`sucesso` (HTTP 200) ou `erro` (demais status).

Exemplo de resposta

{
  "success": true,
  "page": 1,
  "size": 20,
  "total": 1532,
  "totalPaginas": 77,
  "itens": [
    {
      "data": "2026-07-30T16:00:00Z",
      "endpoint": "/v1/car/{codigo}",
      "chaveConsulta": "BA-2900801-0A466FD693B247B9A397829A0D6AA2E3",
      "statusHttp": 200,
      "cobrado": true,
      "valorCobrado": 1.00,
      "saldoAntes": 100.00,
      "saldoDepois": 99.00
    }
  ]
}

Exemplo (curl)

curl "https://api.umbrellatecnologia.com/v1/historico?page=1&size=20&status=sucesso" \
  -H "Authorization: Bearer umb_token_exemplo_xxxxxxxxx"

page size status busca

Conta e gestão (sem cobrança)

Endpoints equivalentes ao dashboard: saldo, histórico, limites, uso e recarga PIX. Todos usam o mesmo Bearer token e não debitam crédito.

GET PUT /v1/limites Grátis Consultar e ajustar limites diário/mensal

GET retorna os limites atuais. PUT atualiza apenas os campos enviados no JSON (omissão preserva o valor atual; 0 ou null remove o limite). Máximos: 100.000 req/dia e R$ 1.000.000/mês.

Body (PUT)

{
  "limiteDiarioRequisicoes": 1000,
  "limiteMensalReais": 5000.00
}

Exemplo de resposta

{
  "success": true,
  "message": "Limites atualizados com sucesso.",
  "limiteDiarioRequisicoes": 1000,
  "limiteMensalReais": 5000.00
}

limiteDiarioRequisicoes limiteMensalReais

Este botão altera os limites reais da sua conta. Campo deixado em branco não entra no JSON e preserva o valor atual.

GET /v1/uso Grátis Uso por endpoint nos últimos 30 dias

{
  "success": true,
  "periodoDias": 30,
  "itens": [
    { "endpoint": "/v1/car/{codigo}", "quantidade": 40, "valorTotal": 40.00 },
    { "endpoint": "/v1/proprietario/{cpf_cnpj}", "quantidade": 12, "valorTotal": 31.20 }
  ]
}

GET /v1/recarga/faixas Grátis Faixas de bônus, valor mínimo e preços após recarga

Query opcional ?valor=1000 devolve preview do bônus. Se confirmarNovosPrecosObrigatorio for true, a conta ainda está em preço legado e o POST /v1/recarga exige confirmarNovosPrecos: true.

valor

POST /v1/recarga Grátis Gerar PIX para adicionar saldo (mín. R$ 500)

Usa CPF/CNPJ e e-mail do usuário Umbrella vinculado à conta API (cadastre o documento no perfil do site se receber DOCUMENTO_AUSENTE).

Proteção contra retentativas: se já existir um PIX pendente de mesmo valor gerado nos últimos 10 minutos, ele é reaproveitado e a resposta traz "reaproveitada": true em vez de criar um novo pagamento.

Body

{
  "valor": 500.00,
  "confirmarNovosPrecos": true
}

Exemplo de resposta

{
  "success": true,
  "recargaId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "paymentId": "1234567890",
  "valor": 500.00,
  "status": "Pendente",
  "qrCode": "00020126...",
  "qrCodeBase64": "iVBORw0KGgo...",
  "previewBonus": {
    "percentualBonus": 5.00,
    "valorBonus": 25.00,
    "totalCreditado": 525.00
  },
  "message": "PIX gerado. Após o pagamento, consulte GET /v1/recarga/{recargaId}."
}

Este é o único endpoint sem botão de teste nesta página: ele gera uma cobrança PIX real no Mercado Pago. Use o painel ou o seu próprio cliente HTTP quando for recarregar de verdade.

GET /v1/recarga/{recargaId} Grátis Status do PIX (somente leitura)

Consulte periodicamente após gerar o PIX, com intervalo de 5 segundos ou mais. O endpoint apenas lê o status registrado — não credita saldo nem altera a recarga.

A confirmação do pagamento, o crédito do valor com bônus e a aplicação dos preços vigentes são feitos pelo webhook do Mercado Pago, com reconciliação automática a cada 2 minutos caso o webhook falhe. Enquanto status for Pendente, a resposta reenvia qrCode e qrCodeBase64.

recargaId

GET /v1/recargas Grátis Histórico paginado de recargas

Query params: page, size (máx. 100) e status opcional (Pendente, Confirmado, Rejeitado).

page size status

Códigos HTTP e erros

Status	Erro	Descrição	Correção sugerida
`200`	-	Sucesso. Cobrança só nos endpoints de consulta; gestão/recarga são grátis. Corpo em JSON ou PDF (`/recibo`).	Nenhuma ação necessária.
`400`	`CODIGO_CAR_INVALIDO`	Código CAR em formato inválido.	Enviar no padrão UF-CodigoMunicipio-Hash.
`400`	`VALOR_MINIMO` / `VALOR_INVALIDO`	Valor de recarga inválido ou abaixo de R$ 500.	Enviar valor ≥ 500.
`400`	`CONFIRMACAO_PRECOS_OBRIGATORIA`	Conta em preço legado sem confirmação.	Consultar `/v1/recarga/faixas` e reenviar com `confirmarNovosPrecos: true`.
`400`	`DOCUMENTO_AUSENTE`	CPF/CNPJ do usuário vinculado ausente.	Atualizar documento no perfil Umbrella.
`400`	`LIMITE_INVALIDO`	Limite fora da faixa permitida.	Ajustar valores ou usar 0/null para remover.
`400`	`CPF_CNPJ_INVALIDO`	CPF/CNPJ com formato inválido.	Enviar documento válido.
`401`	`TOKEN_INVALIDO`	Token ausente ou inválido.	Enviar header `Authorization: Bearer ...` válido.
`402`	`SALDO_INSUFICIENTE`	Saldo insuficiente para executar a consulta.	Adicionar créditos via `POST /v1/recarga` ou no dashboard.
`404`	`RECARGA_NAO_ENCONTRADA`	Recarga inexistente ou de outra conta.	Usar o `recargaId` retornado em `POST /v1/recarga`.
`404`	`CAR_NAO_ENCONTRADO`	Código CAR não encontrado na base.	Validar o código e tentar novamente.
`404`	`CPF_CNPJ_NAO_ENCONTRADO`	Documento sem CARs vinculados na base.	Conferir documento consultado.
`404`	`RECIBO_NAO_ENCONTRADO`	PDF do recibo não disponível para o código CAR informado.	Validar o código CAR ou contatar suporte.
`429`	`LIMITE_EXCEDIDO`	Rate limit ou limites de consumo excedidos.	Aguardar ou ajustar limites no dashboard.
`502`	`RECIBO_INDISPONIVEL`	Falha ao transmitir o PDF após validação (endpoint `/recibo`).	Tentar novamente; acionar suporte se persistir.
`503`	`SERVICO_INDISPONIVEL`	Serviço de recibos temporariamente indisponível.	Tentar novamente mais tarde.
`500`	`ERRO_INTERNO`	Erro interno do servidor.	Tentar novamente e acionar suporte se persistir.

Exemplos de código

JavaScript — consulta JSON

const response = await fetch(
  "https://api.umbrellatecnologia.com/v1/proprietario/12345678901",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer umb_token_exemplo_xxxxxxxxx"
    }
  }
);

const data = await response.json();
console.log(data);

JavaScript — saldo e histórico

const headers = {
  Authorization: "Bearer umb_token_exemplo_xxxxxxxxx"
};

const saldo = await fetch(
  "https://api.umbrellatecnologia.com/v1/saldo",
  { headers }
).then(r => r.json());

const historico = await fetch(
  "https://api.umbrellatecnologia.com/v1/historico?page=1&size=20",
  { headers }
).then(r => r.json());

console.log(saldo.saldoReais, historico.total);

JavaScript — download PDF (recibo)

const codigo = "BA-2900801-0A466FD693B247B9A397829A0D6AA2E3";
const response = await fetch(
  `https://api.umbrellatecnologia.com/v1/car/${codigo}/recibo`,
  {
    headers: { "Authorization": "Bearer umb_token_exemplo_xxxxxxxxx" }
  }
);

if (!response.ok) {
  console.error(await response.json());
  throw new Error("Falha ao baixar recibo");
}

const blob = await response.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = `${codigo}.pdf`;
a.click();
URL.revokeObjectURL(url);

Python — consulta JSON

import requests

url = "https://api.umbrellatecnologia.com/v1/car/BA-2918407-6B9BF14D1B5C4A68B3556361634660D0"
headers = {
    "Authorization": "Bearer umb_token_exemplo_xxxxxxxxx"
}

response = requests.get(url, headers=headers, timeout=30)
print(response.status_code)
print(response.json())

cURL — download PDF (recibo)

curl "https://api.umbrellatecnologia.com/v1/car/BA-2900801-0A466FD693B247B9A397829A0D6AA2E3/recibo" \
  -H "Authorization: Bearer umb_token_exemplo_xxxxxxxxx" \
  -o "BA-2900801-0A466FD693B247B9A397829A0D6AA2E3.pdf"