API EuMonitoro

Os mesmos dados que você vê na plataforma, disponíveis para o seu BI, ERP ou portal.

Baixar a especificação OpenAPI 3.1 — para gerar SDK ou importar no Postman.

Início rápido

Do zero ao primeiro dado em três passos.

1. Crie um token

No painel, abra Integrações e API e clique em Novo Token. O segredo aparece uma única vez — copie na hora.

2. Faça a primeira chamada

curl -H "Authorization: Bearer SEU_TOKEN" \
     https://eumonitoro.eco.br/api/v1/projetos

3. Puxe as coletas de um projeto

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/projetos/12/coletas?limite=50"

Autenticação

Envie o token no cabeçalho Authorization. Ele pertence à organização, não a uma pessoa — continua funcionando quando alguém sai da empresa.

Authorization: Bearer 12|aBcDeF...

Permissões

Cada token carrega apenas as permissões que você marcar:

Como o dado nasce

Entender o caminho evita integrar errado. Uma coleta é um formulário preenchido em campo por um técnico:

1. O coletor preenche o formulário no celular, offline se preciso.
2. Ao sincronizar, a coleta chega ao EuMonitoro como JSON bruto.
3. Um processador específico da normativa (SMA 32, INEA, CONAMA 392…) extrai cobertura, espécies e medições.
4. As espécies passam por enriquecimento taxonômico: nome científico, família, grupo funcional e síndrome de dispersão.
5. A coleta fica processado e passa a alimentar os indicadores.

Vocabulário

Envelope estável

Cada normativa produz campos diferentes. Para você não escrever um if por normativa, a resposta tem sempre as mesmas chaves e os mesmos tipos:

• especies e observacoes são sempre listas, mesmo vazias.
• indicadores traz sempre as mesmas chaves, com null onde não se aplica.
• parcela e gps são normalizados a partir de qualquer formulário.
• O que é específico da normativa fica em dados_normativa.

Dado pessoal

Um único campo do envelope contém dado pessoal: coletor.rotulo, o nome do técnico que fez a coleta. Ele permanece porque é conteúdo obrigatório do relatório entregue ao órgão ambiental — omiti-lo inviabilizaria o uso principal da API.

Ao levar esse dado para o seu sistema, você passa a tratá-lo: aplique a mesma proteção que aplicaria a qualquer cadastro de pessoa. Nenhum outro identificador pessoal é exposto — em particular, o identificador interno do coletor no ODK Central não sai na API, justamente para não permitir correlacionar a mesma pessoa entre sistemas.

Paginação

Usamos cursor, não offset: sob escrita concorrente, offset repete e pula registros.

{
  "data": [ ... ],
  "proxima_pagina": "eyJpZCI6MTMzNH0",
  "tem_mais": true
}

Enquanto tem_mais for true, repita passando ?cursor=:

import requests

url = "https://eumonitoro.eco.br/api/v1/projetos/12/coletas"
headers = {"Authorization": "Bearer SEU_TOKEN"}
cursor, todas = None, []

while True:
    params = {"limite": 100}
    if cursor:
        params["cursor"] = cursor
    r = requests.get(url, headers=headers, params=params).json()
    todas += r["data"]
    if not r["tem_mais"]:
        break
    cursor = r["proxima_pagina"]

Referência

Projetos

Projetos de monitoramento e suas cotas de coleta.

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/projetos"

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/projetos/12"

Coletas

Coletas de campo já processadas e normalizadas.

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/projetos/12/coletas"

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/coletas/1234"

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/projetos/12/cobertura"

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/projetos/12/especies"

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/projetos/12/observacoes"

Indicadores

Números consolidados — os mesmos do relatório entregue ao órgão.

curl -H "Authorization: Bearer SEU_TOKEN" \
     "https://eumonitoro.eco.br/api/v1/projetos/12/indicadores"

Escrita

Alterações de dado. Exigem nível Automação e ficam registradas na trilha de auditoria.

curl -X PATCH "https://eumonitoro.eco.br/api/v1/projetos/12/coletas" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ativa":true}'

curl -X PATCH "https://eumonitoro.eco.br/api/v1/coletas/1234" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ativa":false}'

curl -X POST "https://eumonitoro.eco.br/api/v1/coletas/1234/reprocessar" \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X POST "https://eumonitoro.eco.br/api/v1/projetos/12/sincronizar" \
  -H "Authorization: Bearer SEU_TOKEN"

Webhooks

Em vez de consultar a API de tempos em tempos esperando dado novo, receba um POST assim que algo acontecer. Cadastre os endpoints em Integrações e API → Webhooks.

O que você recebe

POST https://seu-sistema.com.br/webhooks/eumonitoro
Content-Type: application/json
X-EuMonitoro-Event: coleta.processada
X-EuMonitoro-Delivery: 4821
X-EuMonitoro-Signature: t=1755624000,v1=5f2b...

{
  "id": "9f8e7d6c-...",
  "evento": "coleta.processada",
  "ocorrido_em": "2026-08-19T14:30:00-03:00",
  "dados": { ... a coleta completa, no mesmo formato de GET /coletas/{id} ... }
}

O evento coleta.processada já traz a coleta inteira — você não precisa de uma segunda chamada para saber o que mudou.

Reentrega

Falhou? Tentamos de novo em 1 min, 5 min, 30 min, 2 h e 6 h. Depois de 5 tentativas desistimos daquela entrega — mas você pode reenviá-la manualmente pelo painel, que mostra a resposta exata do seu servidor em cada tentativa.

Após 10 entregas seguidas sem sucesso, o endpoint é pausado automaticamente. Conserte e clique em Reativar.

Validar a assinatura

Toda entrega vem assinada com HMAC-SHA256 usando o segredo mostrado na criação do endpoint. Sempre valide antes de confiar no payload — qualquer um pode enviar um POST para a sua URL.

import hmac, hashlib, time

def valida(corpo_bruto: bytes, cabecalho: str, segredo: str) -> bool:
    partes = dict(p.split("=", 1) for p in cabecalho.split(","))
    timestamp, assinatura = partes["t"], partes["v1"]

    # Rejeita entrega antiga: sem isso, um payload capturado pode ser
    # reenviado contra você indefinidamente.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    esperada = hmac.new(
        segredo.encode(),
        f"{timestamp}.".encode() + corpo_bruto,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(esperada, assinatura)

Use o corpo bruto da requisição, não o JSON reserializado: qualquer diferença de espaçamento ou ordem de chaves invalida a assinatura.

Eventos disponíveis

Antes de ir para produção, use o botão Testar no painel: ele envia uma entrega de exemplo para você validar assinatura e parsing sem depender de uma coleta real chegar do campo.

Catálogo de erros

Todo erro segue o RFC 7807. Trate a falha pelo campo type, que é estável — nunca pelo title, cuja redação pode mudar.

{
  "type": "https://eumonitoro.com/errors/limite-excedido",
  "title": "Limite de requisições excedido",
  "status": 429,
  "detail": "Too Many Attempts.",
  "request_id": "3ddc3a09-f13d-4658-a7c3-1db59e41b497"
}

O request_id também vem no cabeçalho X-Request-Id de toda resposta. Guarde-o no seu log: com ele, o suporte localiza exatamente a sua requisição.

Limites e planos

O limite é aplicado por organização, não por token — criar credenciais novas não aumenta a cota.

Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Ao estourar, respeite o Retry-After do 429.

Versionamento

• A versão vai no caminho: /api/v1.
• Campo novo é adição compatível e pode chegar sem aviso — ignore chaves que não conhece em vez de falhar.
• Remover campo ou mudar tipo exige uma /v2, com no mínimo 6 meses de aviso e cabeçalho Sunset nas respostas da versão antiga.
• dados_normativa não é coberto por essa garantia.