이 API에는 엔드포인트가 있습니다. 공개 및 비공개. 공개 API는 인증 없이 시간 경과에 따라 각 참여 지방자치단체의 위도, 경도, 알 수에 대한 데이터를 반환합니다. 비공개 API는 중요한 데이터를 노출하고 기록을 삽입, 변경 및 제거할 수 있도록 허용하므로 Conta Ovos와 협력하여 작동하는 애플리케이션에만 권장됩니다.
열쇠는 다음과 같이 구성됩니다. 무작위 문자 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).
블록에 방문/행동을 등록합니다. 기존 블록에 방문을 추가하려면 필드를 보내십시오. block_id. 존재하지 않는 경우 사용하십시오. block_group_id — 시스템이 자동으로 블록을 생성합니다. 이 엔드포인트는 신청자의 지방자치단체 내에 있는 블록의 삽입만 허용합니다.
매개변수
이름
유형
설명
key
string
귀하의 API 키.
요청 예시
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 — 언제 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.
403 — 언제 block_id 정보는 주요 자치단체에 속하지 않습니다.
409 — 해당 블록, 연도, 주에 대한 방문이 이미 있는 경우.
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):
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.