تحتوي واجهة برمجة التطبيقات هذه على نقاط نهاية العامة والخاصة. تقوم واجهة برمجة التطبيقات العامة بإرجاع بيانات حول خطوط الطول والعرض وعدد البيض لكل بلدية مشاركة مع مرور الوقت، دون الحاجة إلى المصادقة. يوصى باستخدام واجهة برمجة التطبيقات الخاصة فقط للتطبيقات التي تعمل بالشراكة مع Conta Ovos، لأنها تكشف عن بيانات حساسة وتسمح لك بإدراج السجلات وتغييرها وإزالتها.
المصادقة والمفاتيح
لاستخدام واجهة برمجة التطبيقات الخاصة، ستحتاج إلى مفتاح وصول (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 تفيد:
لماذا تحتاج إلى الوصول إلى واجهة برمجة التطبيقات؟
ما هو مستوى الوصول المطلوب (البلدية أو الإقليمية أو الولاية أو الدولة)؛
ما هي المنطقة الجغرافية التي تنتمي إليها؟
المفتاح مكون من 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).
إرجاع البيانات من EDLs (النقاط الإستراتيجية التي يزورها الوكلاء بشكل دوري) ضمن النطاق الجغرافي للمفتاح. يتم تحديد النطاق تلقائيًا من خلال الخطة المرتبطة بالمفتاح - البلدية أو الإقليمية أو الولاية أو الدولة - وليس من الضروري إبلاغ البلدية أو الولاية أو الدولة في الطلب.
حدود
اسم
يكتب
وصف
key
string
مفتاح API الخاص بك. تحديد النطاق الجغرافي لEDLs المرتجعة.
page
int
صفحة ترقيم الصفحات (الافتراضي 1، والحد الأقصى 100).
تنبيه: حقول الاستجابة من نقطة النهاية الخاصة هذه تستمر بالبادئة edl_visit_*. بدأت نقطة النهاية العامة المكافئة فقط في الاستخدام edl_maintenance_*.
إرجاع بيانات الزيارات التي تمت لEDLs ضمن النطاق الجغرافي للمفتاح، بما في ذلك الملاحظة المسجلة في كل زيارة. يتم تحديد النطاق تلقائيًا من خلال الخطة المرتبطة بالمفتاح - البلدية أو الإقليمية أو الولاية أو الدولة - وليس من الضروري إبلاغ البلدية أو الولاية أو الدولة في الطلب.
حدود
اسم
يكتب
وصف
key
string
مفتاح API الخاص بك. يحدد النطاق الجغرافي للزيارات المرتجعة.
page
int
صفحة ترقيم الصفحات (الافتراضي 1، والحد الأقصى 100).
إرجاع بيانات عن الإجراءات (زيارات العلاج) التي تم تنفيذها في كتل ضمن النطاق الجغرافي للمفتاح. يتم تحديد النطاق تلقائيًا من خلال الخطة المرتبطة بالمفتاح - البلدية أو الإقليمية أو الولاية أو الدولة - وليس من الضروري إبلاغ البلدية أو الولاية أو الدولة في الطلب.
حدود
اسم
يكتب
وصف
key
string
مفتاح API الخاص بك. يحدد النطاق الجغرافي للإجراءات التي تم إرجاعها.
page
int
صفحة ترقيم الصفحات (الافتراضي 1، والحد الأقصى 100).
إرجاع البيانات من مصائد البيض (نقاط مراقبة البيض) ضمن النطاق الجغرافي للمفتاح. يتم تحديد النطاق تلقائيًا من خلال الخطة المرتبطة بالمفتاح - البلدية أو الإقليمية أو الولاية أو الدولة - وليس من الضروري إبلاغ البلدية أو الولاية أو الدولة في الطلب.
حدود
اسم
يكتب
وصف
key
string
مفتاح API الخاص بك. يضبط النطاق الجغرافي لمصائد البيض التي تم إرجاعها.
page
int
صفحة ترقيم الصفحات (الافتراضي 1، والحد الأقصى 100).
يعيد العقارات (النقاط الاستراتيجية والعقارات الخاصة) ضمن النطاق الجغرافي للمفتاح. يُحدَّد النطاق تلقائيًا حسب الخطة المرتبطة بالمفتاح — بلدي أو إقليمي أو على مستوى الولاية أو الدولة — لذا لا حاجة لذكر البلدية أو الولاية أو الدولة في الطلب.
حدود
اسم
يكتب
وصف
key
string
مفتاح API الخاص بك. يحدد النطاق الجغرافي للنقاط التي تم إرجاعها.
page
int
صفحة ترقيم الصفحات (الافتراضي 1، والحد الأقصى 100).
جدول بمعرفات كل نوع من مصيدة البيض (ovitrap_type_id): أرسل 1 إلى ovitrap الحضري و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 \
"/ar-sa/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 \
"/ar-sa/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 \
"/ar-sa/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 \
"/ar-sa/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 \
"/ar-sa/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 \
"/ar-sa/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 \
"/ar-sa/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.