この API にはエンドポイントがあります 公的なものと私的なもの. パブリック API は、認証を必要とせずに、参加自治体ごとに緯度、経度、卵の数に関するデータを経時的に返します。プライベート API は、機密データを公開し、レコードの挿入、変更、削除を可能にするため、Conta Ovos と連携して動作するアプリケーションにのみ推奨されます。
認証とキー
プライベートAPIを使用するにはアクセスキーが必要です (key). Gestores (municipal para cima) geram a própria chave no botão APIキーをリクエストする, logados na conta do município: a chave sai na hora, com o município e o cargo da conta, e fica visível no perfil. Se a chave vazar, troque-a na mesma tela (ou em “Trocar a chave”, no perfil): a nova vale na hora e a anterior deixa de funcionar. Agentes de endemias pedem ao gestor do município. Para outro nível de acesso, envie um e-mail para contaovosdengue@gmail.com 述べています：
キーの送信先: prefira o cabeçalho Authorization: Bearer SUA_CHAVE. A query string da URL (?key=SUA_CHAVE) continua aceita em todos os endpoints, mas fica gravada em logs de servidor e proxies, e o cabeçalho não. Enviar a chave apenas no corpo do formulário resulta em 404 "Wrong key". 他の POST フィールドは引き続きリクエスト本文に表示されます。
Parâmetro obrigatório ausente, em formato inválido, ou corpo da requisição ilegível.
403
通知されたリソースは、使用されたキーのスコープ (都市/州/地域) に属していません。
404
無効なキー (Wrong key) またはリソースが見つかりません。
409
この識別子、年、週の組み合わせのレコードはすでに存在します。
500
リクエストの処理中に内部エラーが発生しました。
Como enviar o corpo de um POST
Todos os endpoints POST aceitam três formatos, e você escolhe o que for mais fácil no seu sistema:
Formato
Content-Type
Formulário simples
application/x-www-form-urlencoded
Formulário multipart
multipart/form-data
JSON
application/json
Não defina o cabeçalho Content-Type à mão no Postman, no Insomnia ou em bibliotecas de HTTP. Deixe a ferramenta gerá-lo: no multipart ela precisa incluir o boundary, e um Content-Type que não corresponde ao corpo faz todos os campos chegarem vazios.
Quando isso acontece a resposta é 400 com esta mensagem, e ela é sobre o envelope, não sobre os seus campos:
{
"error": "Não consegui ler os campos do corpo da requisição. Envie como form-data, x-www-form-urlencoded ou JSON.",
"dica": "Se usa Postman ou Insomnia, apague o cabeçalho Content-Type e deixe a ferramenta gerá-lo sozinha."
}
各タイプのオビトラップの ID の表 (ovitrap_type_id): 1 つを都市部のオビトラップに、2 つを地方のオビトラップに送信します。 このフィールドはオプションであり、送信されない場合、オビトラップは都市としてインストールされます。
ID
意味
1
都市型オビトラップ (標準)
2
田舎のオビトラップ
具体的な回答:
400 — 必須フィールドのいずれかが送信されない場合: ovitrap_lat, ovitrap_lng, ovitrap_group_id, date
400 — quando a coordenada está fora da faixa geográfica: ovitrap_lat precisa estar entre -90 e 90, e ovitrap_lng entre -180 e 180. O erro mais comum é o ponto decimal se perder na formatação do número — enviar -23374059 no lugar de -23.374059. A resposta traz os valores recebidos em ovitrap_lat e ovitrap_lng.
curl -X POST \
"/ja-jp/api/postdeleteovitrap?key=KEY"
リクエスト本文に必要なデータ (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97
}
POST/api/postactionプライベート
訪問を挿入
Mudança de unidade em 23/09/2026: 畑 action_deposit_<grupo>_larvicid passaram a ser em GRAMA, como pede a diretriz nacional. Antes eram miligrama. Se o seu sistema envia miligrama, divida por 1.000 antes de enviar — caso contrário a quantidade chega 1.000 vezes maior. O campo aceita decimais (0,5 g vai como 0.5).
Desde 30/10/2026: valor de 500 ou mais em action_deposit_<grupo>_larvicid é lido como miligrama e gravado dividido por 1.000 (500 vira 0,5 g), nas inclusões e nas edições. A resposta não muda.
Registra uma visita/ação em um quarteirão. Há duas formas de dizer qual é o quarteirão:
block_id — o número interno do quarteirão no Conta Ovos, sempre inteiro (é o block_id devolvido por /api/getmunicipalityblocks). Se não existir ou for de outro município, a resposta é 403 e nada é cadastrado.
block_group_id — o código do quarteirão usado pelo município, em texto (por exemplo "A1"). Se já existir um quarteirão com esse código no município, a visita é gravada nele; os dados do quarteirão enviados junto são ignorados. Se não existir, o quarteirão é criado com esses dados e recebe a visita. Por isso é seguro reenviar um lote.
Se os dois forem enviados, vale o block_id. Não envie o código do município em block_id: ele é recusado com 400. Este endpoint só aceita quarteirões do município da chave.
パラメータ
名前
タイプ
説明
key
string
API キー。
date
string
Data da visita, AAAA-MM-DD. A semana epidemiológica é calculada a partir dela e não pode ser futura. Obrigatório.
block_id
integer
Número interno do quarteirão no Conta Ovos. Obrigatório se block_group_id não for enviado.
block_group_id
string
Código do quarteirão no município (até 45 caracteres). Obrigatório se block_id não for enviado.
400 — quando a coordenada está fora da faixa geográfica: block_lat precisa estar entre -90 e 90, e block_lng entre -180 e 180. O erro mais comum é o ponto decimal se perder na formatação do número — enviar -23374059 no lugar de -23.374059.
400 — quando a data da visita é anterior a 1900 ou posterior a amanhã, ou quando a coordenada é exatamente zero. A mensagem diz qual valor foi recusado. Até 20/10/2026 esse caso respondia 500.
400 — いつ block_coordinates passa de 2000 caracteres. Antes o desenho era gravado pela metade, em silêncio, e o quarteirão abria sem mapa; agora a requisição é recusada e a resposta traz o tamanho enviado em block_coordinates_length.
400 — いつ block_id não é um número inteiro. O código usado pelo município vai em block_group_id.
403 — いつ block_id informado não existe ou não pertence ao município da chave.
409 — quando já existe uma visita para esse quarteirão nessa mesma data. Visitas ao mesmo quarteirão em dias diferentes, inclusive na mesma semana, são aceitas; o envio não precisa ser semanal.
POST/api/postdeleteactionプライベート
訪問の削除
1 つのブロックから訪問を削除します。
パラメータ
名前
タイプ
説明
key
string
API キー。
リクエスト例
curl -X POST \
"/ja-jp/api/postdeleteaction?key=KEY"
リクエスト本文に必要なデータ (form-data, x-www-form-urlencoded ou JSON):
curl -X POST \
"/ja-jp/api/postdeleteblock?key=KEY"
リクエスト本文に必要なデータ (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97
}
POST/api/postedlプライベート
Inserir EDL
Cadastra um EDL (ponto estratégico de vigilância) no município da sua chave. Reenviar o mesmo edl_group_id devolve o EDL já existente em vez de duplicar, então é seguro repetir um lote.
O município é sempre o da sua chave — não é possível enviá-lo no corpo.
Obrigatórios: edl_group_id, edl_date (AAAA-MM-DD), edl_lat e edl_lng. Os demais campos são opcionais. Devolve o edl_id.
Se você usa Postman ou Insomnia, não defina o cabeçalho Content-Type à mão: a ferramenta precisa gerá-lo sozinha. Um Content-Type que não corresponde ao corpo faz os campos chegarem vazios.
パラメータ
名前
タイプ
説明
key
string
API キー。
リクエスト例
curl -X POST \
"/ja-jp/api/postedl?key=KEY"
リクエスト本文に必要なデータ (form-data, x-www-form-urlencoded ou JSON):
place_type_id é o tipo do imóvel; place_subtype é o subtipo, e precisa pertencer ao tipo enviado — um par que não combina é recusado com 400. Os mesmos códigos saem em place_type_id e place_subtype nas respostas de /api/getmunicipalityplaces e /api/getmunicipalityplacespublic.
place_type_id
place_subtype
説明
1
Ponto Estratégico
1
1
Cemitério
1
2
Borracharia
1
3
Ferro-Velho
1
4
Depósito de Sucata
1
5
Depósito de Material de Construção
1
6
Garagem de ônibus ou outros veículos de grand
1
7
Residência de acumuladores de inservíveis
1
8
Outro
2
Imóvel especial
2
9
Rodoviária
2
10
Aeroporto
2
11
Escola
2
12
Unidade Básica de Saúde (UBS)
2
13
Universidade
2
14
Prédio de Administração Pública
2
15
Outro
POST/api/postdeleteplaceプライベート
Deletar imóvel
Remove um imóvel do município da sua chave.
Este é o único endpoint que pede um id interno: a tabela de imóveis não tem um código definido por você, ao contrário de ovitrampa, quarteirão e EDL. O place_id vem de /api/getmunicipalityplaces.
パラメータ
名前
タイプ
説明
key
string
API キー。
リクエスト例
curl -X POST \
"/ja-jp/api/postdeleteplace?key=KEY"
リクエスト本文に必要なデータ (form-data, x-www-form-urlencoded ou JSON):
{
"place_id": 142
}
Editar registros
Os endpoints /api/postedit* editam ovitrampas, contagens, quarteirões, visitas, EDLs, manutenções e imóveis que já existem. As regras valem para todos:
Escopo: só registros do município da sua chave, como nos demais POST. Registro de outro município responde 404.
Edição parcial: só muda o que você envia. Campo ausente fica como está; campo enviado vazio grava vazio (é assim que se apaga um complemento, por exemplo). Números, datas, coordenadas e códigos não aceitam vazio.
Tudo ou nada: se um dos campos for inválido, nenhum é gravado e a resposta 400 diz qual e por quê.
Mesmos nomes da criação: os campos têm os nomes que você já usa em /api/postcounting, /api/postaction, /api/postedlmaintenance e /api/postplace.
Trocar código ou data:new_ovitrap_group_id, new_block_group_id, new_edl_group_id renomeiam; nas leituras, new_date muda a data e recalcula a semana epidemiológica. Se o novo código ou a nova data já existirem, a resposta é 409 e nada muda.
Resposta:200 com o registro como ficou. Médias, totais e semanas que dependem do registro são recalculados na mesma chamada.
atualizar_desde — data YYYY-MM-DD. Copia o endereço e a coordenada novos para as leituras a partir dessa data. Sem ele, as leituras antigas continuam com o endereço de quando foram feitas.
A resposta traz também countings_updated: quantas leituras receberam o endereço novo.
Imóveis existentes: block_land_residence, block_land_commercial, block_land_empty, block_land_strategy, block_land_another (o total é recalculado)
atualizar_desde — data YYYY-MM-DD. Copia o endereço e a coordenada novos para as visitas a partir dessa data. Sem ele, as visitas antigas continuam com o endereço de quando foram feitas.
400 — algum campo tem valor inválido: nada é alterado, e a resposta lista os campos em invalid_fields e o motivo de cada um em details.
400 — nenhum campo editável foi enviado.
404 — o registro não existe no município da sua chave.
409 — já existe um quarteirão com o new_block_group_id no município.
POST/api/posteditactionプライベート
Editar visita
Edita uma visita a um quarteirão.
Identificação do registro
名前
タイプ
説明
block_group_id
string
Código do quarteirão no município.
date
string
Data da visita a editar (YYYY-MM-DD).
Campos editáveis
new_date
Visitados, como em /api/postaction: block_land_residence, block_land_commercial, block_land_empty, block_land_strategy, block_land_special, block_land_another
action_land_<tipo>_out, _breedings, _treated
action_deposit_<a1|a2|b|c|d1|d2|e>_quantity, _eliminated, _treated, _larvicid (em grama, com decimais, desde 23/09/2026)
action_observation, action_responsable
Os totais da visita (visitados, pendentes, positivos, tratados e larvicida) e a média do quarteirão são recalculados.
atualizar_desde — data YYYY-MM-DD. Copia o endereço e a coordenada novos para as manutenções a partir dessa data. Sem ele, as manutenções antigas continuam com o endereço de quando foram feitas.