Perguntas
Frequentes
Encontre respostas para suas dúvidas
Autenticação dos Callbacks
SUMÁRIO
1- Visão Geral
A integração com a Cyan exige que a empresa parceira implemente:
-
Uma API de autenticação compatível com o padrão JWT.
-
Endpoints de callback para receber os dados de relatórios (validações, itens, uso do solo, análise de risco).
-
Envio da documentação completa dessas APIs à equipe da Cyan.
Os dados de relatório são processados de forma assíncrona e particionada por talhão, por isso a estrutura de callbacks é obrigatória.
2 - API Autenticação
Requisitos para a API de autenticação:
-
A autenticação deve ser feita via POST com username e password no corpo da requisição, seguindo o modelo abaixo:
Body esperado (JSON):
{
"username": "MyUserName",
"password": "cyfrinair123"
}
Regras obrigatórias:
-
Os campos username e password são obrigatórios.
-
Os nomes dos atributos devem ser exatamente esses: username, password.
Resposta esperada:
A resposta da API pode ter dois formatos válidos:
1. Apenas o token como string:
eyJraWQiOiJLR2p6Z1ZKUXRidGVx…
2. Objeto JSON com tokens:
{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"idToken": "eyJhbGciOiJIUzI1NiIsIn...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
Regras obrigatórias:
-
accessToken é obrigatório.
-
idToken é opcional (necessário apenas se os callbacks exigirem esse valor).
-
refreshToken é opcional, mas se for utilizado, deve ter validade mínima de 30 dias.
-
Os tokens devem seguir a especificação JWT.
-
O accessToken e o idToken devem ter o mesmo tempo de expiração.
-
Não é necessário retornar os atributos mfaRequired e session, pois não são utilizados na integração com os callbacks.
3 - API de Refresh Token (opcional)
Se desejar oferecer renovação automática de tokens, implemente também um endpoint de refresh:
Body esperado (JSON):
{
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
Resposta esperada:
{
"accessToken": "NOVO_ACCESS_TOKEN",
"idToken": "NOVO_ID_TOKEN (opcional)"
}
Regras obrigatórias:
-
O accessToken deve ser retornado obrigatoriamente.
-
O idToken só deve ser retornado se os callbacks exigirem esse token.
-
O tempo de expiração do idToken deve ser igual ao do accessToken.
4 - APIs de Callback
A empresa parceira deve disponibilizar os seguintes endpoints para receber dados assíncronos dos relatórios de seguro:
Callback de Validações
-
Recebe os resultados de validações (ex: socioambientais).
-
Os dados são enviados de forma particionada e assíncrona, por talhão.
-
A especificação da estrutura dos payloads será fornecida via Swagger.
Callback de Itens
-
Recebe os dados de itens analisados no relatório.
-
Envio particionado e assíncrono, conforme as análises são concluídas.
-
Detalhes no Swagger de referência.
Callback de Uso do Solo (landUse)
-
Recebe a parte do relatório referente aos produtos (uso do solo) de cada talhão.
-
Os dados são enviados todos de uma vez, não de forma particionada.
Callback de Análise de Risco
-
Recebe a análise de risco do relatório.
-
Envio único e estruturado conforme especificação da Cyan.
5 - Autenticação nos Callbacks
Header de autorização
As requisições feitas pela Cyan aos endpoints de callback incluirão o accessToken no header. A API de callback deve aceitar um dos seguintes formatos:
-
Formato 1 (token direto):
Authorization: eyJraWQiOiJLR2p6Z1ZKUX...
-
Formato 2 (prefixo Bearer):
Authorization: Bearer eyJraWQiOiJLR2p6Z1ZKUX...
Caso sua API aceite apenas um dos formatos, informe previamente à equipe da Cyan.
6 - Entrega da Documentação
A documentação das APIs de autenticação e de callback deve ser compartilhada com a equipe da Cyan. Essa documentação deve conter:
-
Endpoints com métodos (ex: POST /callback/validation)
-
Exemplo de payloads de entrada e saída
-
Regras de autenticação e tempos de expiração
-
Definição do formato do header de autorização esperado
