Fluxo de Integração

Autenticação

A autenticação das APIs é realizada com a informação de um par de tokens no cabeçalho (header) das requisições. O seguinte par de tokens é esperado em cada requisição:

client_id: Identificação de acesso do cliente. Sua geração ocorre no momento da criação de uma APP pelo painel do desenvolvedor. Seu valor é único por aplicação e poderá ser utilizado tanto em Sandbox quanto em Produção.

access_token: Identificação do token de acesso, que armazena as regras de acesso permitidas ao Client ID. Sua geração ocorre com a operação de criação de Access Token e está vinculado ao Client ID.

Obtenção do Access Token

A geração desse access_token ocorre de forma processual, seguindo um fluxo de autenticação OAuth2 (Saiba mais sobre o fluxo OAuth2) para geração do access_token.

Protocolo de Transporte

Todas as informações trafegadas pelas APIs são realizadas através do protocolo HTTPS, que garante um canal é seguro e dispensa a criptografia dos tokens de forma manual. Saiba mais detalhes sobre a utilização do protocolo HTTPS.

Tecnologias e Padrões

REST

Arquitetura para a disponibilização de recursos através de sistemas distribuídos, popularmente utilizado sobre o protocolo HTTP. Mais detalhes em: https://www.w3.org/2001/sw/wiki/REST.

JSON

Padrão para descrição de dados utilizado para intercâmbio de informações entre sistemas, é mais simples e leve do que algumas alternativas de mercado, como XML. Mais detalhes em: https://www.w3.org/TR/html-json-forms/#introduction.

HTTP 1.1

Protocolo de transporte padrão, amplamente utilizado. Mais detalhes em: http://www.w3.org/Protocols/rfc2616/rfc2616.html ou http://www.ietf.org/rfc/rfc2616.txt.

UTF-8

Conjunto de caracteres padrão para comunicação entre sistemas distribuidos. Mais detalhes em: https://www.w3.org/International/questions/qa-choosing-encodings.

ISO-8601

Padrão de formato específico para dados do tipo date e hora.

  Padrão: YYYY-MM-DDThh:mm:ss.sTZD
  Exemplo: 2013-06-28T08:54:00.000-03:00

Endpoints

Há apenas dois endpoints para acessar os serviços da API, um de Produção e outro de Sandbox. Enquanto sua aplicação estiver sendo desenvolvida, utilize sempre o endpoint de Sandbox e só altere para o de Produção quando sua aplicação for homologada e se token de produção for liberado. Abaixo são apresentados os dois endpoints utilizados para acessar a API:

URL de Produção URL de Sandbox
https://api.zurich.com.br https://api-qa.zurich.com.br

Observação importante: Não se esqueça de incluir a versão da API antes do recurso, por exemplo: /v1, para a versão 1 da API.

Consultas

Paginação

A estratégia de paginação a ser utilizada na Zurich é o uso de parâmetros na “Query String” para o request e no “Header” para o response, onde:

Request:

_offset: Indica o registro inicial a ser retornado.

_limit: Indica a quantidade de registros a ser retornado.

Response:

contentRange: Total de registros existentes.

acceptRange: Quantidade máxima de registros que podem ser solicitado por requisição.

Request:

  Method:
  GET
  
  URI:
  https://api.zurich.com.br/providers/v1/fieldServices?_offset=40&_limit=2
  
  Headers:
  Content-Type → application/json

Response:

  HTTP Status:
  200
  
  Headers:
  contentRange → 8.532
  acceptRange → 100
  
  Body:
  “fieldServices”: [
  {
    “id”: 40,
    “description”: “Field Service 40”
  },
  {
    “id”: 41,
    “description”: “Field Service 41”
  }
  ]

Observação: Neste exemplo, se o consumidor da API tivesse solicitado no parâmetro _limit um valor maior do que o especificado em acceptRange, que nesse exemplo é 100, o consumidor da API receberia um erro com HTTP Status Code 412 (Precondition Failed).

Códigos de Retorno

Status Code 2xx

Código Descrição Método HTTP Response Body
200 (Ok) Requisição bem sucedida. GET De acordo com a necessidade.
201 (Created) Requisição concluída e resultou em um novo recurso. POST De acordo com a necessidade.
204 (No Content) Requisição concluída, mas não é necessário retornar informações adicionais. PUT, DELETE e PATCH. De acordo com a necessidade.

Status Code 4xx

Código Descrição Método HTTP Response Body
400 (Ok)
(Bad Request)		 A solicitação não pôde ser entendida pelo servidor devido à sintaxe malformada (utilizado quando o consumidor da API fez uma requisição passando uma mensagem com formato diferente do especificado pela documentação da API). GET, POST, PUT, DELETE e PATCH. String.
401 (Unauthorized) Requisição requer autenticação do usuário (utilizado quando o consumidor da API não passou uma credencial de acesso válida). GET, POST, PUT, DELETE e PATCH. String.
403 (Forbidden) Servidor entendeu o pedido, mas se recusa a aceitá-la (utilizado quando o consumidor da API passou sua credencial de acesso válida mas não tem permissão para acessar um recurso em específico). GET, POST, PUT, DELETE e PATCH. String.
404 (Not Found) Servidor não encontrou nada na URI (utilizado quando o consumidor da API tentou acessar uma API, recurso ou elemento que não existe). GET, POST, PUT, DELETE e PATCH. String.
405 (Method not Allowed) Método especificado não é permitido para o recurso (utilizado quando o método HTTP não é compatível com o recurso/elemento. Por exemplo: POST: /fornecedores/123, nesse caso, não é possível criar um fornecedor em um elemento). GET, POST, PUT, DELETE e PATCH. String.
412 (Precondition Failed) Condição prévia dada em um ou mais dos campos avaliada como falsa quando foi testado no servidor (utilizando, por exemplo, quando o consumidor da API fez uma requisição com um parâmetro obrigatório vazio, etc…). GET, POST, PUT, DELETE e PATCH. ---
413 (Request Entity Too large) A solicitação é maior do que o servidor está disposto ou capaz de processar (utilizado quando a mensagem passada pelo consumidor da API é maior do que a API está configurada para aceitar). GET, POST, PUT, DELETE e PATCH. ---
415 (Unsupported Media Type) Servidor está se recusando a atender o pedido porque a entidade do pedido está em um formato não suportado pelo recurso solicitado (utilizado quando o consumidor está passando ou tentando consumir um media type não suportado pela API). GET, POST, PUT, DELETE e PATCH. ---
422 (Unprocessable Entity) O pedido foi bem formado, mas não pôde ser seguido devido a erros semânticos (utilizado para o caso de algum erro de negócio, por exemplo, tentativa de excluir um recurso de campo que está atendendo um chamado). GET, POST, PUT, DELETE e PATCH. ---
429 (Too many requests) Usuário enviou muitas solicitações em um determinado período de tempo (utilizado quando o consumidor da API fez mais requisições do que é permitido para ele ou para a API). GET, POST, PUT, DELETE e PATCH. ---

Status Code 5xx

Código Descrição Método HTTP Response Body
500 (Internal Server Error) Servidor encontrou uma condição inesperada que impediu de cumprir o pedido (utilizado em caso de erros inesperados na implementação da API). GET, POST, PUT, DELETE e PATCH. String.
502 (Bad Gateway) Servidor, enquanto age como um gateway ou proxy, recebeu uma resposta inválida (utilizado em casos de erros inesperados no Gateway de APIs). GET, POST, PUT, DELETE e PATCH. String.
504 (Gateway Timeout) O servidor, enquanto age como um gateway ou proxy, não recebeu uma resposta do servidor no tempo especificado (utilizado quando a implementação da API demorou mais tempo do que era esperado para responder). GET, POST, PUT, DELETE e PATCH. String.

Erros de Autenticação

Alguns erros serão tratados durante a autenticação dos Tokens. Abaixo a lista dos erros:

Tipo de erro Descrição
Ausência de um dos Tokens Os dois Tokens devem ser passados em todas as requisições. Caso um deles esteja ausente, será retornado o erro 401 Unauthorized
Token inexistente/errado Se qualquer um dos Tokens passados não existir ou estiver com algum erro (caso tenha sido alterado), será retornado o erro 401 Unauthorized
Tokens revogados (inválidos) Se qualquer um dos Tokens tiver sido revogado ele será considerado inválido e será retornado o erro 403 Forbidden

Para os erros de ausência de um dos tokens e/ou token inexistente/errado, medidas podem ser tomadas do lado do desenvolvedor para validar se as informações que estão sendo passadas estão válidas. Para o erro de tokens revogados (inválidos) a única ação cabível será solicitar um novo token.

Português, Brasil