이 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 말하다:
API 액세스가 필요한 이유는 무엇입니까?
필요한 액세스 수준(자치단체, 지역, 주 또는 국가)
귀하가 속한 지역은 어디입니까?
열쇠는 다음과 같이 구성됩니다. 무작위 문자 45개 매개변수로 전송되어야 합니다. key 각 개인 요청의 키와 연결된 지리적 범위 및 계획 (api_access_municipality_id, state_id, region_id, country_id, plan) 읽거나 변경할 수 있는 레코드를 자동으로 정의합니다. 예를 들어 자치체 키는 자치단체 자체의 데이터만 읽거나 수정할 수 있습니다.
키를 보낼 곳: 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."
}
A chave (key) vai sempre na URL, nunca no corpo.
공개 엔드포인트
GET/api/lastcountingpublic공공의
최근 출시된 수
알 수 및 난관 데이터와 함께 위치(도시, 주 또는 국가)별로 발표된 최신 개수를 반환합니다.
매개변수
이름
유형
설명
state
string
주 코드. 예: state=RJ.
municipality
string
지방자치단체의 이름입니다. 예: municipality=Ponta Pora
country
string
국가 이름. 예: country=Brasil. 생략하면 "브라질"로 간주됩니다.
page
int
페이지 매김 페이지(기본값 1, 최대 100)
id
int
지정된 ID의 항목만 표시합니다. 예: id=7876.
date
date
포함된 날짜부터 발생 횟수를 표시합니다. 예: date=2025-01-01.
date_collect
date
수집일 이후의 발생을 표시합니다. 예: date_collect=2024-12-12.
date_start
date
개수를 필터링할 시작 날짜입니다. 예: date_start=2025-01-01.
date_end
date
집계를 필터링할 종료 날짜입니다. 예: date_end=2025-12-31.
메모: 위치 매개변수가 전송되지 않으면 엔드포인트는 브라질의 최신 개수를 반환합니다.
구체적인 답변:
400 — 보낸 날짜 중 형식이 아닌 날짜가 있는 경우 YYYY-MM-DD. 응답은 잘못된 필드 목록을 가져옵니다. invalid_fields.
각 유지 관리 중에 기록된 관찰 내용을 포함하여 EDL에서 수행된 유지 관리에 대한 데이터를 반환합니다.
대체/api/getmunicipalityedlvisitspublic. EDL은 방문이 아닌 유지 관리를 받습니다. 필드는 edl_visit_* 에게 edl_maintenance_*. 이전 URL은 계속 작동하고 이전 이름을 계속 반환하므로 프로덕션 통합이 중단되지 않지만 중단됩니다.
각 유형의 난포집 ID가 포함된 표 (ovitrap_type_id): 1개는 도시 난소트랩으로 보내고 2개는 시골 난소트랩으로 보냅니다. 이 필드는 선택 사항이며 전송되지 않은 경우 ovitrap은 도시형으로 설치됩니다.
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.
400 — 언제 ovitrap_type_id 전송된 값은 1도 2도 아닙니다.
400 — 보낸 날짜 중 형식이 아닌 날짜가 있는 경우 YYYY-MM-DD. 응답은 잘못된 필드 목록을 가져옵니다. invalid_fields.
404 — 이 난관, 연도 및 주에 대한 카운트가 이미 있습니다.
POST/api/postdeletecounting사적인
읽은 내용 삭제
난관에서 판독을 제거합니다.
매개변수
이름
유형
설명
key
string
귀하의 API 키. 제거 범위를 정의합니다.
요청 예시
curl -X POST \
"/ko-kr/api/postdeletecounting?key=KEY"
요청 본문에 필요한 데이터 (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97,
"date": "2025-01-20"
}
구체적인 답변:
400 — 언제 date 전송되지 않습니다.
400 — 보낸 날짜 중 형식이 아닌 날짜가 있는 경우 YYYY-MM-DD. 응답은 잘못된 필드 목록을 가져옵니다. invalid_fields.
POST/api/postdeleteovitrap사적인
난관 삭제
난소 트랩을 제거합니다.
매개변수
이름
유형
설명
key
string
귀하의 API 키.
요청 예시
curl -X POST \
"/ko-kr/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.
요청 예시
curl -X POST \
"/ko-kr/api/postaction?key=KEY"
전송된 데이터 form-data, x-www-form-urlencoded, JSON 또는 쿼리 매개변수를 사용하여 block_id:
400 — 보낸 날짜 중 형식이 아닌 날짜가 있는 경우 YYYY-MM-DD. 응답은 잘못된 필드 목록을 가져옵니다. invalid_fields.
400 — 언제 block_group_id 새 블록을 생성할 때 전송되지 않습니다.
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 \
"/ko-kr/api/postdeleteaction?key=KEY"
요청 본문에 필요한 데이터 (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97,
"date": "2025-01-20"
}
구체적인 답변:
400 — 언제 date 전송되지 않습니다.
400 — 보낸 날짜 중 형식이 아닌 날짜가 있는 경우 YYYY-MM-DD. 응답은 잘못된 필드 목록을 가져옵니다. invalid_fields.
POST/api/postdeleteblock사적인
블록 삭제
블록을 제거합니다.
매개변수
이름
유형
설명
key
string
귀하의 API 키.
요청 예시
curl -X POST \
"/ko-kr/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 \
"/ko-kr/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 \
"/ko-kr/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.