Visão Geral

API da Concil

Os recursos desta API são baseados em REST(Representational State Transfer) e possuem somente retornos JSON.

Os recursos: lançamentos, conciliações, retornos, clientes e filiais são focados em conciliação de cartão.

Nota importante:

Para que os dados desta API tenham consistência é obrigatório em todas as mensagens passar o parâmetro de id do cliente salvo o recurso de incluir cliente.

Sendo que:

HOSTNAME

Endereço principal dos serviços

VERSÃO DA API

Versão do serviço que está sendo consumido

RECURSO RAIZ

Nome do serviço

REST

REST é um paradigma arquitetural criado para facilitar a comunicação entre componentes através de uma interface uniforme aplicando o princípio de generalização. É visto também como uma abstração da Web por ter o conceito de navegar entre recursos através de hyperlinks.

De acordo com a uniform interface podemos consumir os recursos da seguinte forma:

Recurso

GET

POST

PUT

DELETE

/lançamentos/vendas

Lista os lançamentos de vendas

Cria um lançamento de venda

*

*

/clientes/1

Detalhes do

cliente 1***

**

Atualiza o cliente

1

Exclui o cliente

1

/clientes/1/filiais/

Lista as filiais do cliente 1

Cria uma filial nova para o cliente 1

*

*

/clientes/1/filiais/1

Detalhes da filial 1 do cliente 1

**

Atualiza a filial 1 do cliente 1

Exclui a filial 1 do cliente 1

HTTP 1.1

O protocolo padrão para comunicação com as APIs é o HTTP versão 1.1. Para maiores informações sobre esse protocolo, consulte:http://www.w3.org/Protocols/rfc2616/rfc2616.html http://www.ietf.org/rfc/rfc2616.txt

UTF-8

O Charset padrão para chamadas às APIs é o UTF-8. Para maiores informações sobre essa codificação, consulte:https://tools.ietf.org/html/rfc3629   

JSON

JSON (JavaScript Object Notation) é um padrão para descrição de dados para intercâmbio entre sistemas e é mais simples e mais leve que o XML. Por padrão toda a API trafega JSON, tanto para receber informações quanto no retorno.

exemplo de response do recurso /clientes:



    {

      "clienteId": "int",

      "tipo": "string",

      "logradouro": "string",

      "numero": "string",

      "complemento": "string",

      "bairro": "string",

      "cidade": "string",

      "uf": "string",

      "pais": "string",

      "cep": "string",

      "documento": "string",

     "inscricaoEstadual": "string",

      "inscricaoMunicipal": "string",

      "telefone": "string",

      "fax": "string",

      "site": "string",

      "email": "string"


    }

Paginação

Durante a exibição do resultado de alguns métodos da API é necessário o uso de parâmetros de paginação. Para paginar resultados é necessário utilizar dois parâmetros na própria Query String _offset e _limit, conforme exemplos abaixo:

https://api.concil.com/conciliabrasil/v1/lancamentos/vendas?_offset=0&_limit=100

Como resultado deverá retornar uma lista contendo 100 objetos a partir do primeiro objeto da lista.

_offset: Indica a posição inicial da consulta. Ou seja, 100, indica o primeiro registro trazido deve estar na posição 100.

_limit: Indica a quantidade de registros que a consulta irá retornar.

Observação:

O índice das listagems inicia em 0 (zero). Ou seja para uma consulta com os 10 primeiros itens de uma lista (_offset=0 e _limit=10), os índices serão de zero (0) a nove (9).

Alguns recursos estão com paginação default, sendo assim,  um GET sem nenhum parametro de filtro não retornará muitos registros resultando em uma baixa performance.