Referência da API

Visão geral

A API Centurion Agro é organizada em torno de recursos: car, socio e enriquecimento. Todos os endpoints aceitam e respondem JSON. Usamos códigos HTTP convencionais e bearer tokens.

Convenções

Autenticação

Toda chamada requer um bearer token enviado no header Authorization. Tokens são gerados no painel da conta e têm prefixos distintos por ambiente.

curl "https://api.centurion-agro.com/v1/car/MT-5103403-83F2C7A4" \
  -H "Authorization: Bearer ck_live_•••••" \
  -H "Accept: application/json"

Boas práticas: nunca exponha a chave em código client-side. Use rotação trimestral. Tokens revogados continuam aparecendo em logs por 30 dias para auditoria.

Rate limit & consumo

Limites são por chave de API. Cabeçalhos de resposta indicam o estado atual:

Quando o limite por minuto é atingido, retornamos 429 Too Many Requests com Retry-After. Erros 4xx/5xx não consomem cota do plano.

Códigos de erro

Usamos códigos HTTP convencionais. O corpo de erro segue o formato:

{
  "error": {
    "code": "car_not_found",
    "message": "CAR não encontrado na base SiCAR.",
    "request_id": "req_01HXY8K7N3FQ"
  }
}

API CAR — Introdução

A API CAR consulta o Cadastro Ambiental Rural (SiCAR/Serviço Florestal Brasileiro) e cruza com bases auxiliares: embargos do IBAMA, sobreposição com unidades de conservação, terras indígenas e áreas quilombolas.

Você pode consultar por número do CAR ou por geometria (GeoJSON), retornando os imóveis rurais cadastrados que intersectam aquela área.

Recursos disponíveis

Consultar CAR por número

Retorna a ficha completa do imóvel rural a partir do número do CAR.

Parâmetros de caminho

Parâmetros de query

Exemplo de requisição

curl "https://api.centurion-agro.com/v1/car/MT-5103403-83F2C7A4?include=embargos,ucs" \
  -H "Authorization: Bearer ck_live_•••••"

Exemplo de resposta

{
  "car": "MT-5103403-83F2C7A4",
  "situacao": "ativo",
  "tipo": "imovel_rural",
  "area_total_ha": 1842.30,
  "area_consolidada_ha": 1402.10,
  "reserva_legal_ha": 368.46,
  "app_ha": 71.74,
  "municipio": "Sorriso/MT",
  "data_inscricao": "2014-08-22",
  "embargo_ibama": false,
  "sobreposicao_ucs": [],
  "geometria": {
    "type": "Polygon",
    "coordinates": [[
      [-55.7012, -12.5443],
      [-55.6818, -12.5443],
      [-55.6818, -12.5599],
      [-55.7012, -12.5599],
      [-55.7012, -12.5443]
    ]]
  },
  "srid": 4326,
  "centroid": {
    "type": "Point",
    "coordinates": [-55.6915, -12.5521]
  },
  "bbox": [-55.7012, -12.5599, -55.6818, -12.5443],
  "consultado_em": "2026-05-20T14:02:11Z",
  "fonte": "sicar"
}

Campos geométricos

Consultar CAR por CPF ou CNPJ

Retorna todos os imóveis rurais cujo proprietário ou possuidor é a pessoa física ou jurídica informada. Aceita CPF ou CNPJ, com ou sem máscara.

Parâmetros de caminho

Parâmetros de query

Exemplo de requisição

curl "https://api.centurion-agro.com/v1/car/by-document/12345678000190?uf=MT&include=embargos" \
  -H "Authorization: Bearer ck_live_•••••"

Exemplo de resposta

{
  "documento": "12.345.678/0001-90",
  "tipo_documento": "cnpj",
  "titular": "Fazenda Bom Retiro Ltda",
  "results": [
    {
      "car": "MT-5103403-83F2C7A4",
      "situacao": "ativo",
      "municipio": "Sorriso/MT",
      "area_total_ha": 1842.30,
      "data_inscricao": "2014-08-22",
      "embargo_ibama": false,
      "srid": 4326,
      "centroid": { "type": "Point", "coordinates": [-55.6915, -12.5521] },
      "bbox": [-55.7012, -12.5599, -55.6818, -12.5443]
    },
    {
      "car": "MT-5103403-19A1B502",
      "situacao": "ativo",
      "municipio": "Lucas do Rio Verde/MT",
      "area_total_ha": 412.66,
      "data_inscricao": "2018-11-05",
      "embargo_ibama": false,
      "srid": 4326,
      "centroid": { "type": "Point", "coordinates": [-55.9120, -13.0561] },
      "bbox": [-55.9180, -13.0620, -55.9060, -13.0502]
    }
  ],
  "count": 2,
  "area_total_ha": 2254.96,
  "next_cursor": null,
  "consultado_em": "2026-05-20T14:02:11Z"
}

Incluso Consultas por CPF/CNPJ estão inclusas no consumo do seu plano da API CAR — cada documento consultado conta como 1 requisição, independente da quantidade de imóveis retornados.

Consultas por CPF retornam dados pessoais. Recomenda-se declarar a base legal de tratamento no cabeçalho X-LGPD-Base-Legal conforme a finalidade do uso.

Consultar CAR por geometria

Recebe um polígono GeoJSON (EPSG:4326) e retorna a lista de CARs que intersectam aquela área, ordenados por percentual de sobreposição.

Body

{
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-55.7012, -12.5443],
      [-55.6818, -12.5443],
      [-55.6818, -12.5599],
      [-55.7012, -12.5599],
      [-55.7012, -12.5443]
    ]]
  },
  "min_overlap": 0.05
}

Resposta

{
  "results": [
    {
      "car": "MT-5103403-83F2C7A4",
      "overlap_ratio": 0.78,
      "area_ha": 1842.30
    },
    {
      "car": "MT-5103403-19A1B502",
      "overlap_ratio": 0.12,
      "area_ha": 412.66
    }
  ],
  "count": 2
}

Histórico de consultas

Lista as últimas consultas feitas pela sua chave, com paginação por cursor. Útil para auditoria interna e reconciliação.

Planos & preços da API CAR

Cinco faixas de consumo. Cobrança mensal. Acima de 8.400 requisições/ano, plano customizado.

Ver detalhamento & FAQ dos planos →

Sócio API — Introdução

Consulte quadro societário (QSA), capital social, endereços e ligações entre PFs e PJs no ecossistema agro. Útil para KYC, análise de risco e prevenção a fraude.

Recursos

Consultar CNPJ

Retorna a ficha completa de uma pessoa jurídica, incluindo QSA, situação cadastral e CNAEs.

curl "https://api.centurion-agro.com/v1/socio/cnpj/12345678000190" \
  -H "Authorization: Bearer ck_live_•••••"

Resposta

{
  "cnpj": "12.345.678/0001-90",
  "razao_social": "Fazenda Bom Retiro Ltda",
  "nome_fantasia": "Bom Retiro Agro",
  "situacao": "ativa",
  "data_abertura": "2008-03-15",
  "capital_social": 4200000.00,
  "natureza_juridica": "206-2 Sociedade Empresária Limitada",
  "cnae_principal": {
    "codigo": "0115-6/00",
    "descricao": "Cultivo de soja"
  },
  "qsa": [
    {
      "nome": "João Pereira",
      "cpf": "***.456.789-**",
      "qualificacao": "Sócio-Administrador",
      "participacao": 0.60
    },
    {
      "nome": "Marina Costa",
      "cpf": "***.123.456-**",
      "qualificacao": "Sócia",
      "participacao": 0.40
    }
  ],
  "endereco": {
    "municipio": "Sorriso",
    "uf": "MT",
    "cep": "78890-000"
  },
  "consultado_em": "2026-05-20T14:02:11Z"
}

Vínculos por CPF

Lista todas as PJs em que o CPF informado consta no quadro societário. CPFs são parcialmente mascarados conforme LGPD.

{
  "cpf_mascarado": "***.456.789-**",
  "nome": "João Pereira",
  "vinculos": [
    {
      "cnpj": "12.345.678/0001-90",
      "razao_social": "Fazenda Bom Retiro Ltda",
      "qualificacao": "Sócio-Administrador",
      "participacao": 0.60,
      "situacao_pj": "ativa"
    }
  ],
  "total": 1
}

Busca por nome

Busca aproximada por razão social ou nome fantasia. Suporta filtros por UF, situação e CNAE.

Camadas territoriais

Cruzamento de uma geometria com camadas oficiais: terras indígenas (FUNAI), unidades de conservação (ICMBio), áreas quilombolas (INCRA), zoneamento agrícola de risco climático (Mapa) e malha viária do IBGE.

{
  "geometry": { "type": "Polygon", "coordinates": [...] },
  "layers": ["ti", "uc", "quilombo", "zarc"]
}

Webhooks

Receba notificações assíncronas quando o status de um CAR ou CNPJ monitorado mudar. Configure no painel da conta.

Eventos disponíveis

Verificação de assinatura

Todo webhook é assinado com HMAC-SHA256 no header X-Centurion-Signature. Valide com seu webhook secret antes de processar o payload.