Introdução
O portal de desenvolvedores da Sompo é a disponibilização direta das informações de nossos Produtos e Serviços ao mercado de Seguros.
O portal de desenvolvedores permitirá conexão direta às informações do dia a dia, boletos, recibos de comissão, apólices e tudo mais.
Para entregar esses benefícios ao consumidor, a Sompo operacionaliza e padroniza o compartilhamento das informações com privacidade e segurança.
Getting Started
Para acessar as informações disponíveis é necessário cadastramento prévio no Portal e apenas informações básicas serão coletadas.
Após o cadastramento, o ingresso no portal, passará por avaliação interna e prontamente informada ao solicitante.
O portal possui uma serie de informações, desde as mais básicas, como outras mais completas. Ao cadastrar-se será possível conhecer todas as APIs disponíveis e havendo interesse, basta incluir no seu perfil.
Todas as APIs exigem autenticação, sendo que ao optar por alguma API, a solicitação será encaminhada e aprovada internamente.
O acesso inicial é liberado em ambiente de testes (sandbox) para todas as Apis. Os dados são fictícios e servem apenas para entendimento das informações.
Ambientes Sompo
A utilização de ambientes isolados garantem que as práticas de gerenciamento de APIs sejam aplicadas às diferentes fases, com controle de qualidade, garantindo segurança e eficiência.
| Ambiente | URL |
|---|---|
| Desenvolvimento | https://api.sompo.com.br/dev |
| Homologação | https://api.sompo.com.br/qa |
| SandBox | https://api.sompo.com.br/sandbox |
| Produção | https://api.sompo.com.br |
| Token | https://api.sompo.com.br/oauth/access-token |
Nossas API´s
APIs disponiveis para consumo pelos parceiros da Sompo, não encontrou o que precisa, faça uma busca pelas APIs expostas no Portal Developers Sompo
| API | Resumo | Versão Atual |
|---|---|---|
| Apólices | Obtenção de informações de Apólice | v1 - Rev 12 |
| Corretores | Obtenção de informações de Corretores | v1 - Rev 6 |
| Financeiro | Informações sobre dados financeiros (posição de débitos, boletos, etc) | v1 - Rev 6 |
| Segurados | Informações sobre dados cadastrais e bancários (vincular contas, atualizar cadastro) | v1 - Rev 10 |
| Sinistros | Serviços para abertura e acompanhamento de sinistros | v1 - Rev 19 |
| Cotação | Cotação/Propostas de seguros de diversos ramos | v1 - Rev 42 |
| Open Insurance | AP´s para integração de congeneres e segurados | v1 |
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/auto
Cabeçalhos HTTP
Cabeçalho de requisição
| 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 |
Cabeçalho de Resposta
| Nome do cabeçalho | Descrição | Obrigatório |
|---|---|---|
| Content-Encoding | Cabeçalho que indica o tipo de encoding (geralmente algoritmo de compressão) que foi utilizado para envio da resposta. | Não |
| Content-Type | Representa o formato do payload de resposta. Deverá ser application/json a menos que o endpoint requisitado suporte outro formato e este formato tenha sido solicitado através do cabeçalho Accept no momento da requisição. | Sim |
| 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 |
Códigos de resposta HTTP Os códigos de resposta HTTP devem ser utilizados conforme tabela mais abaixo.:
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: Obter 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 parametros na url. Não é permitido a utilização de campos sensiveis a LGPD.
| Situação | Código HTTP | POST | GET | DELETE |
|---|---|---|---|---|
| Consulta realizada com sucesso. | 200 OK. | Sim | Sim | Não |
| Execução normal. A solicitação foi bem sucedida. | 201 Created. | Sim | Não | Não |
| Operação de exclusão concluída com sucesso. | 204 No Content. | Não | Não | Sim |
| A resposta não foi modificada desde a última chamada | 304 Not Modified. | Não | Sim | Não |
| A requisição foi malformada. | 400 Bad Request. | Sim | Sim | Sim |
| Cabeçalho de autenticação ausente/inválido ou token inválido. | 401 Unauthorized. | Sim | Sim | Sim |
| O token tem escopo incorreto ou uma política de segurança foi violada. | 403 Forbidden. | Sim | Sim | Sim |
NOTA: Nos casos das APIs que retornarem qualquer código de erro, favor enviar e-mail para arquiteturadeti@sompo.com.br com um print do erro para que possamos avaliar e informar as devidas orientações ou, se for o caso, aplicar as correções necessárias.
Integração
A integração das APIs consiste em trafego sobre o protocolo HTTPS, com obtenção de token de acesso e posterior consumo da API desejada.
Todas as APis são configuradas com timeout e em caso de ocorrência, devem ser previamente verificadas, antes de submeter outra chamada.
Os tokens tem tempo período de validade curto, havendo necessidade, deve-se solicitar um novo a partir do serviço de obtenção de token.
Para um diagrama de sequencia e mais detalhes, acesse a página Autenticação
Segurança
As APIs disponiveis no Portal de Desenvolvedores, exigem no transporte de informações o protocolo HTTP - TLS 1.2+, que fornece segurança na comunicação sobre a rede física.
Toda a estrutura do Portal de Desenvolvedores possui segurança física a partir de soluções de Firewall.
Todos os acessos são gerenciados no Manager da solução, com perfis de acessos distintos e com controles de throlling, quotas e outros.
Para mais informações, acesse o link Autenticação
Versionamento
As APIs usam o padrão de versionamento baseado em 'Versão' e 'Revisão'.
Sendo que cada uma delas, pode estar em diferentes versões ou revisões. (Ex API A pode estar em homologação na sua revisão 5, mas em produção a revisão 4 está ativa)
A evolução das versões, podem ser verificadas individualmente e o padrão para registro de novas implementações é o incremento numeral (Ex. v1, v2, v3).
A evolução das revisões, pode ser verificadas no swagger (contrato).
A seção de Release Notes, pode auxiliar no acompanhamento das mudanças de cada API.
Ferramentas do Desenvolvedor
Acesse a página de ferramentasonde você encontrará as APIs que você tem acesso, e a um ambiente de Sandbox para fazer chamadas as APIs.
