Consultez et envoyez les données d'ovitrap, d'îlot et de visite sur le terrain directement depuis votre système. Cette page documente tous les points de terminaison publics et privés disponibles.
Cette API a des points de terminaison public et privé. L'API publique renvoie des données sur la latitude, la longitude et le nombre d'œufs pour chaque commune participante au fil du temps, sans nécessiter d'authentification. L'API privée n'est recommandée que pour les applications qui fonctionnent en partenariat avec Conta Ovos, car elle expose des données sensibles et vous permet d'insérer, de modifier et de supprimer des enregistrements.
Authentification et clés
Pour utiliser l'API privée, vous aurez besoin d'une clé d'accès (key). Pour l'acheter, envoyez un email à contaovosdengue@gmail.com déclarant :
Pourquoi avez-vous besoin d'un accès API ?
Quel niveau d'accès est requis (municipal, régional, étatique ou national) ;
De quelle région géographique faites-vous partie ?
La clé est composée de 45 lettres aléatoires et doit être envoyé en paramètre key de chaque demande privée. Le périmètre géographique et le plan lié à la clé (api_access_municipality_id, state_id, region_id, country_id, plan) définir automatiquement les enregistrements qu'elle peut lire ou modifier — une clé municipale, par exemple, ne peut lire ou modifier que les données de la municipalité elle-même.
Où envoyer la clé : 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". Les autres champs POST continuent d'apparaître dans le corps de la requête.
Pagination: les paramètres page acceptez un maximum de 100 sur les points de terminaison prenant en charge la pagination. Les valeurs invalides ou manquantes prennent la page 1.
Codes de réponse
Tous les points de terminaison suivent le même modèle d'état HTTP :
Code
Signification
200
Demande traitée avec succès.
400
Parâmetro obrigatório ausente, em formato inválido, ou corpo da requisição ilegível.
403
La ressource renseignée n'appartient pas au périmètre (ville/état/région) de la clé utilisée.
404
Clé invalide (Wrong key) ou ressource introuvable.
409
Un enregistrement existe déjà pour cette combinaison identifiant, année et semaine.
500
Erreur interne lors du traitement de la demande.
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.
Points de terminaison publics
GET/api/lastcountingpublicPublique
Derniers décomptes publiés
Renvoie les derniers décomptes publiés par emplacement (ville, état ou pays), avec le nombre d'œufs et les données sur les ovitraps.
Paramètres
Nom
Taper
Description
state
string
Code d'état. Exemple: state=RJ.
municipality
string
Nom de la commune. Exemple: municipality=Ponta Pora
country
string
Nom du pays. Exemple: country=Brasil. En cas d'omission, cela implique "Brésil".
page
int
Page de pagination (par défaut 1, maximum 100).
id
int
Affiche uniquement les occurrences de l'identifiant donné. Exemple: id=7876.
date
date
Affiche les occurrences à partir de la date d'inclusion. Exemple: date=2025-01-01.
date_collect
date
Affiche les occurrences à partir de la date de collecte. Exemple: date_collect=2024-12-12.
date_start
date
Date de début pour filtrer les décomptes. Exemple: date_start=2025-01-01.
date_end
date
Date de fin pour filtrer les décomptes. Exemple: date_end=2025-12-31.
Note: Si aucun paramètre de localisation n'est envoyé, le point de terminaison renvoie les derniers décomptes du Brésil.
Réponses spécifiques :
400 — lorsqu'une des dates envoyées n'est pas au format YYYY-MM-DD. La réponse apporte la liste des champs invalides dans invalid_fields.
Renvoie les îlots enregistrés dans la commune — une ligne par îlot, avec le polygone, le total des propriétés par type et le nombre moyen de parts.
Nouveau point de terminaison. Si vous recherchez des visites effectuées par îlots, utilisez /api/getmunicipalityblocksvisitpublic. Comme il s’agit d’un point de terminaison public, la réponse n’inclut pas l’agent responsable de l'îlot ni les identifiants utilisateur/équipe.
Paramètres
Nom
Taper
Description
state
string
Code d'état. Exemple: state=RJ.
municipality
string
Nom de la commune. Exemple: municipality=Ponta Pora
country
string
Nom du pays. Exemple: country=Brasil. En cas d'omission, cela implique "Brésil".
Renvoie les données sur la maintenance effectuée sur les EDL, y compris l'observation enregistrée lors de chaque maintenance.
Remplace/api/getmunicipalityedlvisitspublic. Les EDL reçoivent de l'entretien, pas des visites - les champs sont passés de edl_visit_* à edl_maintenance_*. L'ancienne URL continue de fonctionner et continue de renvoyer les anciens noms, afin de ne pas interrompre les intégrations en production, mais elle est interrompue.
Paramètres
Nom
Taper
Description
state
string
Code d'état. Exemple: state=RJ.
municipality
string
Nom de la commune. Exemple: municipality=Ponta Pora
country
string
Nom du pays. Exemple: country=Brasil. En cas d'omission, cela implique "Brésil".
Renvoie les données des EDL (points stratégiques visités périodiquement par les agents) dans la portée géographique de la clé. Le périmètre est automatiquement défini par le plan lié à la clé — communale, régionale, étatique ou nationale — et il n'est pas nécessaire d'informer la commune, l'état ou le pays dans la demande.
Paramètres
Nom
Taper
Description
key
string
Votre clé API. Définit la portée géographique des EDL renvoyées.
Attention : les champs de réponse de ce point de terminaison privé continuent avec le préfixe edl_visit_*. Seul le point de terminaison public équivalent a commencé à utiliser edl_maintenance_*.
Renvoie les données sur les visites effectuées aux EDL dans la portée géographique de la clé, y compris l'observation enregistrée lors de chaque visite. Le périmètre est automatiquement défini par le plan lié à la clé — communale, régionale, étatique ou nationale — et il n'est pas nécessaire d'informer la commune, l'état ou le pays dans la demande.
Paramètres
Nom
Taper
Description
key
string
Votre clé API. Définit la portée géographique des visites retournées.
Renvoie des données sur les actions (visites de traitement) réalisées par îlots dans le périmètre géographique de la clé. Le périmètre est automatiquement défini par le plan lié à la clé — communale, régionale, étatique ou nationale — et il n'est pas nécessaire d'informer la commune, l'état ou le pays dans la demande.
Paramètres
Nom
Taper
Description
key
string
Votre clé API. Définit la portée géographique des actions renvoyées.
Renvoie les données des ovitraps (points de surveillance des œufs) dans la portée géographique de la clé. Le périmètre est automatiquement défini par le plan lié à la clé — communale, régionale, étatique ou nationale — et il n'est pas nécessaire d'informer la commune, l'état ou le pays dans la demande.
Paramètres
Nom
Taper
Description
key
string
Votre clé API. Définit la portée géographique des ovitraps renvoyés.
Renvoie les propriétés (points stratégiques et propriétés spéciales) dans le périmètre géographique de la clé. Le périmètre est défini automatiquement par le forfait lié à la clé — communal, régional, étatique ou national — il n'est donc pas nécessaire d'indiquer la commune, l'État ou le pays dans la requête.
Paramètres
Nom
Taper
Description
key
string
Votre clé API. Définit la portée géographique des points renvoyés.
Envoie la lecture d'un ovitrap. Il est possible d'envoyer des données à un ovitrap existant ou d'envoyer les données et d'installer un nouvel ovitrap en même temps.
Paramètres
Nom
Taper
Description
key
string
Votre clé API. Définit la portée de la soumission.
Pour une expédition standard, où il n'est pas nécessaire d'installer un nouvel ovitrap, envoyez les champs suivants (tout est obligatoire) dans le corps de la demande (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
}
Tableau avec les identifiants de chaque type d'observation (counting_observation_id):
ID
Signification
1
Aucune observation
2
Intervalle entre l'installation et la collecte plus long que prévu
3
Ovitrap ou palette manquante
4
Ovitrap ou palette cassée
5
Ovitrap ou palette retirée
6
Ovitrap sec
7
Maison fermée
8
Ovitrap rempli d'eau
9
Ovitrap avec peu d'eau
10
Une autre observation
Pour installer un nouvel ovitrap à côté de l'envoi, obligatoire les champs : ovitrap_lat, ovitrap_lng, ovitrap_group_id
Tableau avec les identifiants de chaque type d'ovitrap (ovitrap_type_id): envoyer 1 à l’ovitrap urbain et 2 à l’ovitrap rural. Le champ est facultatif et, lorsqu'il n'est pas envoyé, l'ovitrap est installé comme urbain :
ID
Signification
1
Ovitrap urbain (standard)
2
Ovitrap rural
Réponses spécifiques :
400 — lorsqu'un des champs obligatoires n'est pas envoyé : 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 — quand le ovitrap_type_id envoyé n’est ni 1 ni 2.
400 — lorsqu'une des dates envoyées n'est pas au format YYYY-MM-DD. La réponse apporte la liste des champs invalides dans invalid_fields.
404 — Il existe déjà un décompte pour cet ovitrap, année et semaine.
POST/api/postdeletecountingPrivé
Supprimer la lecture
Supprime la lecture d'un ovitrap.
Paramètres
Nom
Taper
Description
key
string
Votre clé API. Définit la portée de la suppression.
Exemple de demande
curl -X POST \
"/fr-mc/api/postdeletecounting?key=KEY"
Données requises dans le corps de la demande (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97,
"date": "2025-01-20"
}
Réponses spécifiques :
400 — quand date n'est pas envoyé.
400 — lorsqu'une des dates envoyées n'est pas au format YYYY-MM-DD. La réponse apporte la liste des champs invalides dans invalid_fields.
POST/api/postdeleteovitrapPrivé
Supprimer l'ovitrap
Retirez un ovitrap.
Paramètres
Nom
Taper
Description
key
string
Votre clé API.
Exemple de demande
curl -X POST \
"/fr-mc/api/postdeleteovitrap?key=KEY"
Données requises dans le corps de la demande (form-data, x-www-form-urlencoded ou JSON):
{
"ovitrap_group_id": 97
}
POST/api/postactionPrivé
Insérer une visite
Mudança de unidade em 23/09/2026: les champs 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).
Enregistrez une visite/action dans un îlot. Pour ajouter la visite à un îlot existant, envoyez le champ block_id. S'il n'existe pas, utilisez block_group_id — le système créera automatiquement l'îlot. Ce point de terminaison permet uniquement l'insertion d'îlots situés dans la municipalité du demandeur.
Paramètres
Nom
Taper
Description
key
string
Votre clé API.
Exemple de demande
curl -X POST \
"/fr-mc/api/postaction?key=KEY"
Données envoyées form-data, x-www-form-urlencoded, JSON ou des paramètres de requête, en utilisant block_id:
400 — quand date n’est pas envoyé ou lorsqu’un des champs numériques n’est pas un numéro valide.
400 — lorsqu'une des dates envoyées n'est pas au format YYYY-MM-DD. La réponse apporte la liste des champs invalides dans invalid_fields.
400 — quand block_group_id n'est pas envoyé lors de la création d'un nouvel îlot.
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 — quand 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 — quand le block_id informé n'appartient pas à la commune clé.
409 — lorsqu'il y a déjà une visite pour cet îlot, cette année et cette semaine.
POST/api/postdeleteactionPrivé
Supprimer la visite
Supprime une visite d'un îlot.
Paramètres
Nom
Taper
Description
key
string
Votre clé API.
Exemple de demande
curl -X POST \
"/fr-mc/api/postdeleteaction?key=KEY"
Données requises dans le corps de la demande (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97,
"date": "2025-01-20"
}
Réponses spécifiques :
400 — quand date n'est pas envoyé.
400 — lorsqu'une des dates envoyées n'est pas au format YYYY-MM-DD. La réponse apporte la liste des champs invalides dans invalid_fields.
POST/api/postdeleteblockPrivé
Supprimer l'îlot
Supprime un îlot.
Paramètres
Nom
Taper
Description
key
string
Votre clé API.
Exemple de demande
curl -X POST \
"/fr-mc/api/postdeleteblock?key=KEY"
Données requises dans le corps de la demande (form-data, x-www-form-urlencoded ou JSON):
{
"block_group_id": 97
}
POST/api/postedlPrivé
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.
Paramètres
Nom
Taper
Description
key
string
Votre clé API.
Exemple de demande
curl -X POST \
"/fr-mc/api/postedl?key=KEY"
Données requises dans le corps de la demande (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.
Paramètres
Nom
Taper
Description
key
string
Votre clé API.
Exemple de demande
curl -X POST \
"/fr-mc/api/postdeleteplace?key=KEY"
Données requises dans le corps de la demande (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/posteditactionPrivé
Editar visita
Edita uma visita a um quarteirão.
Identificação do registro
Nom
Taper
Description
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.