Padrões das Requisições (Request)

Esta página pretende descrever todos os padrões no que tange response HTTP de APIs utilizado pela Sompo.

Metodos

O protocolo HTTP possui diversos métodos, sendo que cada um possui uma semântica distinta, e devem ser utilizados para indicar o tipo de manipulação a ser realizada em um determinado recurso.

  • GET: Consultar os dados de um recurso.
  • POST: Criar um novo recurso.
  • PUT: Substituir os dados de um determinado recurso.
  • PATCH: Atualizar parcialmente um determinado recurso.
  • DELETE: Excluir um determinado recurso.
  • HEAD: Similar ao GET, mas utilizado apenas para se obter os cabeçalhos de resposta, sem os dados em si.
  • OPTIONS: Obter quais manipulações podem ser realizadas em um determinado recurso.

Observação importante: Para o método GET, que permite a inclusão de parâmetros na url. Não é permitido a utilização de campos sensíveis a LGPD.

Padrões

Segurança A adoção de mecanismos de segurança na implementação das APIs do portal de desenvolvedores Sompo, irá considerar o padrão de autenticação de mercado OAuth2, visando a proteção e a disponibilidade de dados. Todas as APIs que dependam de fornecimento de dados, respeitam a LGPD, sendo o acesso permitido somente aos envolvidos no processo, com prévia autorização.

RESTFul API As integrações disponíveis usaram o conceito de RESTful API, desconsiderando outros modelos disponíveis, como por exemplo SOAP/XML.

ISO 20022 As Informações disponíveis levarão em conta a estrutura de mensagem baseada na ISO 20022

Extensibilidade As APIs serão estendidas para novas situações em futuros releases.

Códigos de Status As APIs usarão na íntegra os códigos preponderantes do protocolo HTTP.

Nomenclatura de Recursos Utiizamos o padrão de recursos no plural (ex. https://api.sompo.com.br/segurados) e utilizamos Camel Case para recursos compostos. (ex. /processosAdministrativos).

Não utilizamos a operação como recurso (ex. https://api.sompo.com.br/produtos/cadastrar)

Não determinamos na nomenclatura de recursos os diversos modelos de resposta (ex. XML, JSON, HTML), a opção deve ser feita via Content Negotiation.

Estrutura da URI A estrutura da URI seguirá o seguinte padrão:

[host] / [api] / [versao] / [recurso]

host: Endereço host da API - (ex. api.sompo.com.br). Conheça os Ambientes Sompo

api: A API que será consumida (ex. /apolices).

versão: A versão atual da API. A versão deve ser precedida pela letra 'v' seguida pelo número, iniciando-se pelo numeral 1(um). (ex. v1, v2).

recurso: O recurso a ser consumido dentro de uma API. (ex. /auto).

Como exemplo, para realizar o consumo do recursoauto, da API de/apolices, na versão1, a URI ficaria com a seguinte estrutura:

https://api.sompo.com.br/apolices/v1/claims

Cabeçalho de requisição (header) HTTP

A API precisa retornar os códigos HTTP corretos para cada request. O cabeçalho (header) da requisição HTTP devem ser utilizados conforme tabela abaixo.

Nome do cabeçalho Descrição Obrigatório
Content-Type Representa o formato do payload de requisição, por padrão/default definido como application/json;charset UTF-8. Obrigatório para chamadas PUT e POST. Os transmissores poderão implementar tratamento para outros padrões, sendo obrigatório apenas o suporte ao padrão. Não
Accept Especifica o tipo de resposta. Se especificado, deve ser definido como application/json, a menos que o endpoint explicitamente suporte outro formato. Se for definido um valor não suportado pelo endpoint, será retornado o código HTTP 406. Se não especificado, o padrão será application/json Não
Accept-Encoding Especifica os tipos de encoding(geralmente algoritmo de compressão) que são suportados pelo cliente, sendo que o padrão é a transmissão dos dados não compactados e esta orientação aplica-se a todos dados. Não
If-Modified-Since Condiciona o resultado da requisição para que o recurso só seja enviado caso tenha sido atualizado após a data fornecida. Utiliza o padrão da RFC 7232, sessão 3.3: If-Modified-Since do protocolo HTTP. Não
Authorization Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado Sim

Undefined