该API有端点 公共和私人. 公共 API 会随着时间的推移返回每个参与城市的纬度、经度和鸡蛋数量数据，而无需进行身份验证。仅建议与 Conta Ovos 合作的应用程序使用私有 API，因为它会公开敏感数据并允许您插入、更改和删除记录。
身份验证和密钥
要使用私有 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 字段继续出现在请求正文中。
分页： 参数 page 在支持分页的端点上最多接受 100 个。无效或缺失值占据第 1 页。
响应代码
所有端点都遵循相同的 HTTP 状态模式：
代码
意义
200
请求处理成功。
400
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 \
"/zh-hk/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私人的
删除访问
从一个块中删除一次访问。
参数
姓名
类型
描述
key
string
您的 API 密钥。
请求示例
curl -X POST \
"/zh-hk/api/postdeleteaction?key=KEY"
请求正文中所需的数据 (form-data, x-www-form-urlencoded ou JSON):
curl -X POST \
"/zh-hk/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 \
"/zh-hk/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 \
"/zh-hk/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.