API Cyan: Guia de Relatórios de Precipitação por Município

​

Este documento orienta desenvolvedores na utilização da API Cyan para solicitação e obtenção de relatórios de precipitação acumulada por município.

​

Visão Geral do Processo (Workflow)

​

O processo de obtenção de dados climáticos é assíncrono e dividido em trẽs etapas principais:

​

• IDENTIFICAÇÃO: Localizar o ID interno da cidade (insuranceCityId) usando códigos oficiais do IBGE (Geocodes).​

​

• VALIDAÇÃO (/insurance/city/by/ids): Confirmar os nomes das cidades vinculadas aos IDs encontrados.

​

1 - Localizando Municípios (FIltros)

​

Para evitar erros entre cidades com nomes idênticos, a API utiliza o Geocode do IBGE.

​

• O que é o Geocode e onde obter?:

O Geocode é o identificador único de 7 dígitos para cada município brasileiro.

• Consulta Manual: Porta de Cidades do IBGE (O código aparece abaixo do nome da cidade).

• Lista Completa: Tabela de Códigos de Municípios - IBGE.

​

• Endpoint de Busca:

​

        GET /insurance/city/id/by/filters/sort/pagination

​

REGRA CRÍTICA DE FORMATAÇÃO (STRINGFY) 

​

Os campos filters, sort e pagination não aceitam JSON puro. Eles devem ser convertidos em uma única String.

​

Como converter:

​

1. Monte seu JSON.

2. Cole-o no site JSON Stringify Online.

3. Copie o resultado gerado e use-o como valor do parâmetro.

​

Exemplo de Parâmetros (Antes vs. Depois):

​

CAMPO                JSON Original (Legível)                                 Valor a ser enviado (Stringify)

filters                     {"codes": ["3552203"]}                              "{\"codes\":[\"3552203\"]}"

sort                         {"field":"CODE","order":"DESC"}          "{\"field\":\"CODE\",\"order\":\"DESC\"}"

pagination         {"page":1,"size":50}                                         "{\"page\":1,\"size\":50}"

​

Resposta (200 OK): Um array de IDs internos, ex: [542].

​

2 - Solicitando o Relatório

​

Antes de pedir o relatório, use este endpoint para confirmar se os IDs retornados correspondem às cidades corretas (Nome e Estado).

​​

• Endpoint de Detalhes:

​

      GET /insurance/city/by/ids

​

• Input:

​

      JSON{ "insuranceCityIds": [542, 543] }

​

      Validação: Máximo de 50 IDs por requisição.

​

      Resposta (200 OK):

      JSON[ { "id": 542, "code": "3552203", "name": "São José dos Campos", "stateId": 27 } ]

​

3 - Solicitando o Relatório

​

Com o insuranceCityId (ex: 542) obtido no passo anterior, você deve registrar a requisição do relatório.

​

• Endpoint de Solicitação:

​

      POST /insurance/city-report-request

​

• Regras e Validações:

   ​

        Datas: A startDate deve ser anterior à endDate.  

        Período Máximo: A diferença entre as datas não pode ultrapassar 1 ano.

        Limite de Cidades: Mínimo de 1 e máximo de 50 IDs por requisição.

        Permissão: Requer a role API_REQUEST.

​

• Exemplo de Payload:

​

JSON

{

 "companyId": 10,   // ID da companhia

 "endDate": "2025-06-01",

 "insuranceCityIds": [

   542  // Exemplo de ID de cidade obtido pelo endpoint de filtros.

 ],

 "startDate": "2025-01-01",

 "companySectorId": 3  // Setor da companhia

}

​

4 - Recebimento via Callback

​

Após o processamento pelo time de pesquisa da Cyan, o sistema enviará um POST para o seu endpoint de callback cadastrado.

​

• Estrutura do Relatório (Exemplo de Resposta):

​

     Os dados de chuva são agrupados por decêndios (períodos de 10 dias).​​

​

JSON

{

 "insuranceCityReportRequestId": 12345,

 "items": [

   {

     "code": "AVERAGE_ACCUMULATED_RAIN_BY_PERIODS",

     "data": [

       {

         "index": 0,

         "properties": [

           {

             "code": "TEN_DAY_PERIOD",

             "value": 10

           },

           {

             "code": "PRECIPITATION_ACCUMULATED_MM",

             "value": 32.4

           },

           {

             "code": "YEAR",

             "value": 2025

           }

         ]

       }

     ]

   }

 ]

}

​

5 - Resumo de Erros e Troubleshooting (FAQ)

​

CÓDIGO       CAUSA                                                                

400                 Formato inválido ou falha nas datas.                      

403                 Falta de permissão.

500                 Erro interno Cyan.

 

FAQ Rápido

​

• Posso usar o nome da cidade para buscar o ID?  

        Sim, através do campo names no filtro, mas recomendamos usar o codes (Geocode IBGE) para total precisão.

​

•  Como testo se meu sistema recebe os dados corretamente?

        Use o endpoint de exemplo /insurance/city-report/callback/items. Após o teste, envie o JSON gerado para insurance@cyan-agro.com para que possamos validar sua integração.

​

​