Exibir origem

O objetivo desta api é oferecer uma forma simples e padronizada para acesso aos recursos que o nosso ERP tem a oferecer. Explicaremos aqui todos os passos para que seu produto possa se integrar com ela.

Autenticação

Antes de ter acessos aos recursos do ERP, é necessário estabelecer uma identificação segura para manter esta comunicação. Para isso, utilizamos o procolo oAuth 1.0a.

Para detalhes de como estabelecer a autenticação com nosso Sistema, consulte esta página.

Formato das requisições

Implementamos em nosso ERP uma API RESTFUL, e o formato de nossas requisições são baseadas neste padrão.

Resumidamente, o RESTFUL usa-se do próprio protocolo http, o mesmo utilizado para exibição de páginas web para um internauta, só que voltado para atender requisições de serviço. Assim, a característica principal de toda e qualquer requisição é que ela é feita para uma url em particular.

Formato da URL

Há três partes nesta url que é importante destacar:

URL base: é uma url única da sua instalação. Qualquer requisição feita para esta instalação deve começar com ela
Identificador do serviço: Todos os serviços oferecidos por nossa começam com /first/api/v1/ e depois possuem mais especificações.

Há dois formatos para identificador de serviço que atendemos, em diferentes situações:

Identificador de entidade: /first/api/v1/{entidade}

Requisições feitas para este tipo de url são para listagem de registro da entidade em questão, ou para incluir um novo registro para aquela entidade. No caso, no lugar de {entidade} informa-se o nome da entidade que se deseja manipular. Exemplo: /first/api/v1/product, /first/api/v1/warehouse, etc...

Identificador de registro: /first/api/v1/{entidade}/{pk}

Requisições feitas para este tipo de url são para obtenção de um registro em particular da entidade em questão, para alteração de um registro, ou para exclusão do mesmo. No caso, no lugar de {entidade}, informa-se o nome da entidade que se deseja manipular e no lugar de {pk}, a sua chave primária sua identificação única.

Exemplo: /first/api/v1/product/000001, /first/api/v1/ncmnbs/01011,2,000, etc...

Tipos de requisição

Quanto às requisições, há quatro tipos de requisição que podem ser feitas, cada uma com um intuito em especial:

GET: Servem para fazer consultas em nossa base de dados. Elas suportam urls com os dois tipos de identificador:
- Identificador de entidade: requisições assim servem para listar registros da entidade em questão. Elas suportam também parâmetros (querystring) para filtragem de registros, ordenação e paginação;
- Identificador de registro: requisições assim servem para retornar os dados de um registro em particular apenas;

POST: Servem para efetuar uma inclusão na entidade em questão. Requisições POST suportam apenas urls com identificador de entidade;

PUT: Servem para efetuar alteração em um registro em questão. Requisições PUT suportam apenas urls com identificador de registro;

DELETE: Servem para efetuar a deleção de um registro em questão. Requisições DELETE suportam apenas urls com identificador de registro;

É muito importante respeitar o formato da url para cada tipo de requisição que estiver sendo feita. Caso o formato da url esteja errado, o API responderá com um erro do tipo 404, o mesmo ocorre caso um nome de entidade inválida seja informada, ou se um identificador de registro não corresponda com nenhum em nossa base de dados.

Esta entidade exibe informações sobre as filiais da empresa e suporta as seguintes operações: GET, POST e PUT.

Tipos de retorno

Para cada requisição efetuada, além do conteúdo de retorno, também há um tipo para o mesmo. Os tipos de restorno de uma API RESTFUL são baseados nos próprios códigos de status já usuais do protocolo HTTP. Os status que nossa api pode retornar são os seguintes:

200: Este status será retornado toda vez que a operação solicitada for bem sucedida;

400: Caso exista algum problema de sintaxe ou de validação de dados com a requisição que a api receber, o status 400 será retornado com a descrição do erro que ocorreu;

401: Este status será retornado caso a requisição não tenha uma autenticação válida. Para mais detalhes sobre autenticação, consulta esta página;

404: Este status será retornado nas seguintes situações:
- Uma entidade inválida for especificada na url;
- Um identificador de registro inexistente for especificado na url;
- A url não corresponder com nenhum serviço provido por nossa API;
- O formato da url utilizado for incorreto para o tipo de requisição informado;

500: Este status será retornado se ocorrer alguma coisa errada do lado da API ou exista algum problema não previsto nos dados recebidos da requisição. Caso isso ocorra, é preciso contatar o suporte técnico para mais orientações.

Cabeçalho da requisição

Toda requisição HTTP possui um cabeçalho. Os atributos de cabeçalho esperados por nossa api são os seguintes:

Content-type: sempre forneça application/json. JSON é o único formato de dados com o qual nossa api trabalha;

Authorization: É necessário fornecer os dados da autenticação oauth neste atributo. Para mais detalhes, consulte esta página;

TenantId: Aqui deve-se informar a identificação da empresa/filial para a qual a requisição está sendo feita. Exemplo: 01,01;

Conteúdo da requisição

Como foi explicado mais acima, nossa api só trabalha com dados no formato JSON. Isso se refere especificamente ao conteúdo da requisição. Os únicos tipos de método que suportam conteúdo em nossa API é POST e PUT. Mais detalhes sobre o formato do conteúdo esperado podem ser encontrados na documentação específica de cada entidade.

Resposta

Há dois tipos de resposta que nossa API poderá fornecer: respostas de erro e respostas de sucesso.

Respostas de erro serão retornadas toda vez que o status do retorno for diferente de 200 e terão o seguinte formato:

{

"errorCode": CÓDIGO DO ERRO (DESCRITO ACIMA),

"errorMessage": "DESCRIÇÃO DO ERRO"

}

Respostas de sucesso serão retornadas toda vez que o status do retorno for 200 e o formato varia de acordo com a requisição. Os possíveis formatos são:

GET de lista (quando a url contém apenas o identificador de entidade):

{

"total": 11441,

"hasNext": true,

"syncing": false,

"lines": [

{ ..json da entidade registro 1... },

{ ..json da entidade registro 2... },

...

{ ..json da entidade registro N... },

]

}

Os campos que compõem este json são:

total: O total de registros que a consulta encontrou. Veja que nem todos os registros poderão estar presentes no resultado por questões de paginação. A paginação padrão das nossas requisições é 10. Para obter os registros seguintes, portanto, é preciso efetuar uma nova requisição solicitando a próxima seguinte;
hasNext: Informa se há mais páginas no retorno;
syncing: Este campo indica se há alguma sincronização ocorrendo no momento. Sincronizações podem ocorrer com outras integrações que nosso Sistema suporta, caso elas estejam contratadas na instalação em questão;
lines: Contém um array com o resultado da requisição. Cada posição deste array contém um json de um registro da entidade em questão. Para saber o formato do json de cada entidade, é preciso consultar a documentação da mesma;
GET de registro único (quando a url contém o identificador de registro):

{ ..json da entidade do registro consultado... }

Para saber os campos que compõem o json de cada entidade, consulte a documentação da entidade em questão;

POST, PUT e DELETE

{

"url": "URL de acesso ao registro que sofreu manutenção",

"nome do primeiro campo da chave": "Valor do primeiro campo que compõe a chave primária do registro",

"nome do segundo campo da chave": "Valor do segundo campo que compõe a chave primária do registro",

...

"nome do enésimo campo da chave": "Valor do enésimo campo que compõe a chave primária do registro",

}

Vejam que o JSON retornado aqui sempre possuirá a propriedade url, as outras propriedade variam de acordo com a entidade manipulada. Vejam um exemplo válido de retorno para a entidade ncmnbs:

{

"url": "/cnpj2/first/api/v1/ncmnbs/01011,2,000",

"id": "01011",

"type": "2",

"exceptionTIPI": "000"

}

Parâmetros de Querystring

Esta característica só é suportada para requisições do tipo GET em nossa api com urls que contenham apenas o identificador de entidade. Elas são, na verdade, tudo o que é informado depois do ponto de interrogação em uma url.

Exemplo:

/first/api/v1/product?description=TESTE

Possuímos alguns parâmetros padrão que todas as nossas apis suportam. São eles:

max: Informa a quantidade máxima de registros a retornar. O padrão é 10. Veja que este parâmetro afeta diretamente como se comporta a paginação em nossa API;

page: Informa o número da página que se deseja receber. Veja que o número de páginas possível varia de acordo com o total de registro encontrados e o valor do parâmetro max;

order: Neste parâmetro deve-se informar, separado por vírgula, todos os campos pelo qual se deseja ordenar a requisição. Geralmente todos os campos retornados na consulta de cada entidade podem ser usados aqui, caso algum campo não seja permitido em uma api em particular, o mesmo será informado na própria documentação. Por padrão, o resultado sempre vem ordenado pelos campos que compõem a chave primária da entidade;

Em nossa api, todos os campos retornados por uma requisição podem ser utilizados para filtrá-la. A maneira que o filtro vai se comportar varia de acordo com o tipo do campo e é permitido informar múltiplos valores para cada parâmetro, separando-os por vírgula. Vejam abaixo como funciona o filtro por cada tipo de dado:

Campos caractere: filtros efetuados por este tipo de campo retornarão qualquer registro que contiver o valor informado.

Por exemplo:

GET /first/api/v1/product?description=CANETA,LAPIS.

Esta requisição retornará todos os produtos que possuírem as palavras CANETA ou LAPIS na descrição.

Campos numéricos: Filtros por campos numéricos buscarão o valor exato fornecido;

Campos data: Filtros por campos data podem ser usados de três maneiras:

Filtro por ano

Exemplo:

/first/api/v1/order?created=2015

Todos os pedidos criados em 2015 serão retornados;

Filtro por ano e mês

Exemplo:

/first/api/v1/order?created=201501

Todos os pedidos criados em Janeiro de 2015 serão retornados;

Filtro por ano, mês e dia

Exemplo:

/first/api/v1/order?created=20150110

Todos os pedidos criados no dia 10 de Janeiro de 2015 serão retornados

Algumas entidades podem oferecer também o que chamamos de filtros especiais. Filtros especiais implementam pesquisas diferenciadas que não são atendidas pelos parâmetros de campo.

Exemplos:

*/first/api/v1/order?initialCreated=20150110*

Todos os pedidos que foram criados com data igual ou superior a 10/01/2015 serão retornados

*/first/api/v1/order?finalCreated=20150310*

Todos os pedidos que foram criados com data igual ou inferior a 10/03/2015 serão retornados

Finalmente, nossa api também permite a combinação de filtros, bastando seprar cada um pelo caracter especial & na querystring.

Exemplo:

*/first/api/v1/order?initialCreated=20150110&finalCreated=20150310*

Todos os pedidos que foram criados com data igual ou superior a 10/01/2015 E igual ou inferior a 10/03/2015 serão retornados

Agora, vamos supor que um campo caracter sendo pesquisado possua uma vírgula em seu valor e seja de interesse do usuário final filtrar por uma expressão que contenha essa vírgula. Para que uma operação assim possa ser feita, podemos colocar aspas no valor informado no campo:

Exemplo:

*/first/api/v1/product?description=”teste, produto”*

Serão retornados todos os produtos que possuem teste, produto em sua descrição.

*/first/api/v1/product?description=”teste, produto”,mercadoria*

Serão retornados todos os produtos que possuem teste, produto ou mercadoria em sua descrição.

Por fim, digamos que o usuário final cadastrou um produto que possua uma aspa em sua descrição. Para poder resgatar o valor deste campo, neste caso, é preciso colocar o valor do parâmetro entre aspas e substituir as aspas do deste valor por duas aspas.

Exemplo:

*/first/api/v1/product?description=”cano de 5”” verde”*

Serão retornados todos os produtos que possuem cano de 5” verde em sua descrição.

Campo pk dos JSON de entidade e identificador de registro

À medida que você utilizar nossa API, você irá perceber que todas as nossas entidade retornam um campo chamado pk. Este campo não é editável via POST ou PUT e não será descrito na documentação específica de nenhuma api. O seu valor serve, exatamente, para definir como é o identificador do registro em questão.

Por exemplo:

*GET /FIRST/API/V1/product?max=1*

RETORNO:

{

"total": 483,

"hasNext": true,

"syncing": false,

"lines": [

{

"pk": "009500",

"id": "009500",

...

}

]

}

Veja que o retorno possui o campo pk. Se eu quiser fazer uma requisição que envolva apenas este registro em particular, basta adicionar o valor de pk à minha url:

*GET /FIRST/API/V1/product/009500*

RETORNO:

{

"pk": "009500",

"id": "009500",

"description": "PRODUTO TESTE",

...

}

Este é o mesmo procedimento para saber qual url deve ser usada para operações de PUT e DELETE.

Veja que para algumas entidades pk é composto por vários campos. No entanto, o consumidor da api não deve se preocupar com isso na hora de informar a url. O valor retornado em pk é exatamente o valor que deve ser usado como identificador de registro. Caso a chave primária, por qualquer motivo, possua algum caracter especial, o mesmo já estará tratado no valor informado em pk.