Просматривайте и отправляйте данные о ловушках, кварталах и посещениях мест непосредственно из вашей системы. На этой странице описаны все доступные общедоступные и частные конечные точки.
У этого API есть конечные точки общественные и частные. Публичный API возвращает данные о широте, долготе и количестве яиц для каждого участвующего муниципалитета с течением времени без необходимости аутентификации. Частный API рекомендуется использовать только для приложений, работающих в партнерстве с Conta Ovos, поскольку он предоставляет конфиденциальные данные и позволяет вставлять, изменять и удалять записи.
Аутентификация и ключи
Для использования частного API вам понадобится ключ доступа (key). Чтобы приобрести его, отправьте письмо на адрес 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=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.
Возвращает зарегистрированные в муниципалитете кварталы — по одной строке на квартал с указанием полигона, общего количества объектов недвижимости по типам и среднего количества долей.
Новая конечная точка. Если вы ищете посещения, выполненные кварталами, используйте /api/getmunicipalityblocksvisitpublic. Поскольку это общедоступная конечная точка, ответ не включает агента, ответственного за квартал, или идентификаторы пользователя/команды.
Параметры
Имя
Тип
Описание
state
string
Код штата. Пример: state=RJ.
municipality
string
Название муниципалитета. Пример: municipality=Ponta Pora
country
string
Название страны. Пример: country=Brasil. Если опущено, предполагается «Бразилия».
page
int
Страница нумерации страниц (по умолчанию 1, максимум 100).
Возвращает данные о техническом обслуживании, выполненном на EDL, включая наблюдения, записанные во время каждого обслуживания.
Заменяет/api/getmunicipalityedlvisitspublic. EDL получают обслуживание, а не посещения — поля ушли из edl_visit_* к edl_maintenance_*. Старый URL продолжает работать и продолжает возвращать старые имена, чтобы не нарушать интеграцию в продакшене, но он прекращен.
Параметры
Имя
Тип
Описание
state
string
Код штата. Пример: state=RJ.
municipality
string
Название муниципалитета. Пример: municipality=Ponta Pora
country
string
Название страны. Пример: country=Brasil. Если опущено, предполагается «Бразилия».
page
int
Страница нумерации страниц (по умолчанию 1, максимум 100).
Возвращает данные из EDL (стратегических точек, периодически посещаемых агентами) в пределах географической области действия ключа. Объем автоматически определяется планом, связанным с ключом — муниципальным, региональным, штатным или страновым — и нет необходимости информировать муниципалитет, штат или страну в запросе.
Параметры
Имя
Тип
Описание
key
string
Ваш API-ключ. Определяет географический охват возвращаемых EDL.
page
int
Страница нумерации страниц (по умолчанию 1, максимум 100).
Внимание: поля ответа от этой частной конечной точки продолжаются с префиксом edl_visit_*. Только эквивалентная общедоступная конечная точка начала использовать edl_maintenance_*.
Возвращает данные о посещениях EDL в пределах географического охвата ключа, включая наблюдения, записанные при каждом посещении. Объем автоматически определяется планом, связанным с ключом — муниципальным, региональным, штатным или страновым — и нет необходимости информировать муниципалитет, штат или страну в запросе.
Параметры
Имя
Тип
Описание
key
string
Ваш API-ключ. Определяет географический охват повторных посещений.
page
int
Страница нумерации страниц (по умолчанию 1, максимум 100).
Возвращает данные о действиях (лечебных посещениях), выполненных в кварталах в пределах географического охвата ключа. Объем автоматически определяется планом, связанным с ключом — муниципальным, региональным, штатным или страновым — и нет необходимости информировать муниципалитет, штат или страну в запросе.
Параметры
Имя
Тип
Описание
key
string
Ваш API-ключ. Определяет географический охват возвращаемых действий.
page
int
Страница нумерации страниц (по умолчанию 1, максимум 100).
Возвращает данные из яйцеловок (точек мониторинга яиц) в пределах географической области действия ключа. Объем автоматически определяется планом, связанным с ключом — муниципальным, региональным, штатным или страновым — и нет необходимости информировать муниципалитет, штат или страну в запросе.
Возвращает объекты (стратегические точки и особые объекты) в пределах географической области ключа. Область определяется автоматически планом, связанным с ключом — муниципальный, региональный, уровня штата или страны — поэтому указывать муниципалитет, штат или страну в запросе не нужно.
Параметры
Имя
Тип
Описание
key
string
Ваш API-ключ. Определяет географический охват возвращаемых точек.
page
int
Страница нумерации страниц (по умолчанию 1, максимум 100).
Для стандартной доставки, при которой нет необходимости устанавливать новый яйцеловитель, отправьте следующие поля: (все обязательно) в теле запроса (form):
{
"ovitrap_group_id": 97,
"ovitrap_lat": -7.000000,
"ovitrap_lng": -8.000000,
"date": "2025-01-20",
"counting_observation_id": 1,
"counting_observation": "caso o counting_observation_id seja 9",
"counting_eggs": 5
}
Таблица с идентификаторами каждого типа наблюдения (counting_observation_id):
ID
Значение
1
Нет замечаний
2
Интервал между установкой и сбором дольше, чем ожидалось.
3
Яйцеловка или недостающая палитра
4
Яйцеловка или сломанная палитра
5
Яйцеварка или палитра удалены
6
Сухая яйцеловка
7
Закрытый дом
8
Яйцеловушка, наполненная водой
9
Яйцеловушка с небольшим количеством воды
10
Еще одно наблюдение
Чтобы установить новую яйцеловку рядом с грузом, обязательный поля: ovitrap_lat, ovitrap_lng, ovitrap_group_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.
400 — когда ovitrap_type_id отправлено не 1 и не 2.
400 — когда какая-либо из отправленных дат не соответствует формату YYYY-MM-DD. В ответ выводится список недопустимых полей в invalid_fields.
404 — Этой яйцеловке уже есть счет, год и неделя.
POST/api/postdeletecountingЧастный
Удалить чтение
Удаляет чтение из яйцеловки.
Параметры
Имя
Тип
Описание
key
string
Ваш API-ключ. Определяет объем удаления.
Пример запроса
curl -X POST \
"/ru-ru/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 \
"/ru-ru/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 \
"/ru-ru/api/postaction?key=KEY"
Данные отправлены form-data, x-www-form-urlencoded, JSON или параметры запроса, используя block_id:
400 — когда date не отправляется или когда одно из числовых полей не является допустимым числом.
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 \
"/ru-ru/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 \
"/ru-ru/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 \
"/ru-ru/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 \
"/ru-ru/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.