A API de SMON tem como característica processamento assíncrono. Essa abordagem trás inúmeros benefícios não só para a Plataforma NSTech, mas para consumidores e fornecedores integrados à API. Nesse tutorial iremos detalhar como essa abordagem foi implementada na API de SMON da Plataforma NSTech.
Tipos de Respostas da API de SMON
A API SMON é composta por um conjunto de recursos,
cada um desses recursos define um Tipo de Resposta sendo eles:
- Solicitação de Monitoramento: "include-smon"
- Alterar Veículo: "update-vehicle"
- Alterar Motorista: "update-driver"
- Alterar Itinerário: "update-itinerary"
- Cancelamento de Solicitação de Monitoramento: "cancel-smon"
- Cancelamento de Documentos de Carga: "cancel-document"
Fluxo da API SMON
Em uma API de processamento síncrono, para cada requisição HTTP feita nos recursos da API, espera-se a resposta como retorno definitivo da requisição.
Já em uma API de processamento assíncrono não espera-se resultados no retorno da requisição de soliitação e sim apenas uma resposta que deixe claro que a solicitação foi recebida e está sendo processada. Quando o processamento for concluído, o servidor fará uma requisição para enviar o resultado desse processamento. Para essa abordagem ser viável o soliciante deve disponibilizar uma URL para receber as respostas das solicitações enviadas para API, o que muitos entende por "Callback URL" ou "Endpoint de Resposta".
Endpoint de Resposta para Consumidores
O consumidor deve disponibilizar um endpoint na seguinte estrutura
http://{domínio do consumidor}/smon/response
Esse endpoint será configurado na plataforma pela equipe da Plataforma nstech. Com a configução feita as respostas serão direcionadas ao endpoint de resposta. Nas requisição feita pelo servidor, será enviado no Request Body a seguinte estrutura:
{
"title": "smon-response",
"type": "object",
"properties": {
"request_id": {
"type": "string",
"format": "uuid",
},
"type": {
"type": "string",
"enum": [
"include-smon",
"update-vehicle",
"update-driver",
"update-itineraty",
"cancel-document",
"cancel-smon"
]
},
"status": {
"type": "string",
"enum": [
"SUCCESS",
"FAILURE"
]
},
"provider_response": {
"type": "string",
"format": "json"
}
}
}
Exemplo em caso de Sucesso
{
"request_id": "77dda20c-7118-11ee-b962-0242ac120002",
"type": "include-smon",
"status": "SUCCESS",
"provider_response": {
"id": "exemplo",
"message": "exemplo"
}
}
Exemplo em caso de Falha
{
"request_id": "77dda20c-7118-11ee-b962-0242ac120002",
"type": "include-smon",
"status": "FAILURE",
"provider_response": {
"message": "Falha na solicitação",
"erros": [
{
"path": "root.itinerary.waypoints[0]",
"message": "when sequence = 1, type must be 1 (start)"
}
]
}
}
Também será enaminhado no Header da Requisição o Token gerado pelo consumidor e utilizado na solitação contendo informações do solicitante (requester_token).
Endpoint de Resposta para Fornecedores
Para os fornecedores a perspectiva se inverte, onde a Plataforma nstech é tem um papel de "consumidor". Nessa perspectiva os fornecedores devem encaminhar suas respostas assíncronas para um endpoint gerado pela plataforma:
https://dev.nstech.com.br/platform/api/monitoringrequest/v3/response/{request_id}/{response_type}
Nota-se que existem dois "Path Params" que compõem a URL de Resposta da Plataforma, sendo eles:
- request_id
Se refere a propriedade "id" da inclusão de Solicitação de Monitoramento. - response_type
Se refere ao tipo de resposta listado no tópico Tipos de Respostas