Manual de implementação da API SISeCommerce V1.0

Manual de implementação da API SISeCommerce V1.0.0

1/21

Manual de implementação da

API SISeCommerce V1.0.0


2/21

Sumário Manual de implementação da API SISeCommerce V1.0.0 .................................................................... 1

Introdução ............................................................................................................................................. 3

Informações adicionais ......................................................................................................................... 3

1. Limite de requisições ................................................................................................................. 3

2. Padrão de requisições (request) e respostas (response) .......................................................... 3

3. Paginação .................................................................................................................................. 3

4. URL base, Token e Apelido ........................................................................................................ 3

Pré-Requisitos ....................................................................................................................................... 6

Autenticação ......................................................................................................................................... 6

Códigos de erros das requisições .......................................................................................................... 7

Recursos ................................................................................................................................................ 8

Clientes .............................................................................................................................................. 8

Informação .................................................................................................................................... 8

URL ................................................................................................................................................ 8

Tipos de operações aceitas (method) ........................................................................................... 9

Parâmetros aceitos no método ..................................................................................................... 9

Exemplo de uso ............................................................................................................................. 9

Produtos .......................................................................................................................................... 11

Informação .................................................................................................................................. 11

URL .............................................................................................................................................. 11

Tipos de operações aceitas (method) ......................................................................................... 11

Parâmetros aceitos no método GET ........................................................................................... 11

Exemplo de uso ........................................................................................................................... 12

Método PUT ................................................................................................................................ 14

Informação .................................................................................................................................. 14

Exemplo de uso ........................................................................................................................... 15

Pedidos ............................................................................................................................................ 17

Informação .................................................................................................................................. 17

URL .............................................................................................................................................. 17

Tipos de operações aceitas (method) ......................................................................................... 17

Parâmetros aceitos no método ................................................................................................... 17

Exemplo de uso ........................................................................................................................... 18

Observações .................................................................................................................................... 21


3/21

Introdução Esta documentação apresenta a API da plataforma de comércio eletrônico SISeCommerce, esta API permite a interação entre a plataforma e sistemas externos. Serão apresentadas as formas de gerenciar, através de requisições, os recursos disponíveis da plataforma.

Informações adicionais Antes de prosseguir, deve-se atentar a estas informações suplementares que tornarão mais claras as interações com a API.

1. Limite de requisições A API possui um limite de 10 (dez) requisições por minuto;

2. Padrão de requisições (request) e respostas (response) Ao fazer uma operação POST/PUT/DELETE, o Content-Type da requisição deve seguir sempre o formato application/json, e com o conteúdo no formato JSON, caso a requisição não esteja nesse formato um erro será retornado;

3. Paginação No retorno dos registros da API, sempre é informado valores com o status do recurso, o total de registros, total de páginas e a página atual. Isso é feito para facilitar o processo de paginação dos dados. Exemplo de retorno dos registros com os dados para paginação:

4. URL base, Token e Apelido Por padrão, a URL base para trabalhar com a API da plataforma segue as seguintes características:

{ "produtos": [ { "id": 1, (..) } ], "status": "OK", "total_registros": 1, "total_paginas": 1, "pagina_atual": 1 }


4/21

Onde, no lugar de sualojavirtual, substitua para o apelido de sua loja virtual, a qual pode se conseguir acessando o painel administrativo de sua loja virtual e indo em:

1. Configurações;

2. Integrações;

http://sualojavirtual.appsisecommerce.com.br/api/

http://sualojavirtual.appsisecommerce.com.br/api


5/21

3. Webservice.

4. Token de acesso

Ao acessar esta página basta copiar o apelido que se encontra no campo “Token de acesso”.


6/21

Pré-Requisitos Para utilizar a integração com API, e consumir os recursos disponíveis, é necessário ter o Token e o Apelido, para que seja feito a autenticação na plataforma.

Autenticação Para consumir os recursos da API, é necessário utilizar o método Basic Auth do HTTP, onde o username é o apelido de sua loja virtual e o password é o token gerado por você para acesso a API. A seguir, um exemplo em PHP utilizando cURL, consumindo um recurso da API utilizando o método Basic Auth do HTTP:

Em caso de erro na autenticação (Basic Auth), será apresentada a estrutura a seguir.

<?php /** * Consumindo recurso Produtos da API SISeCommerce utilizando Basic Auth * @return JSON */ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "http://sualojavirtual.appsisecommerce.com.br/api/produtos"); curl_setopt($ch, CURLOPT_TIMEOUT, 30); curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($ch, CURLOPT_USERPWD, "sualojavirtual:cdda1df53a0086505d12f47e14ae0235"); $result = curl_exec ($ch); curl_close ($ch);

{ "retorno": { "status": "ERRO", "erros": [ { "codigo": 110, "msg": "Autenticacao invalida." } ] } }


7/21

Códigos de erros das requisições A seguir, confira a tabela com os códigos de erros de todas as requisições efetuadas na API.

Código do erro Descrição do erro

100 Autenticação não informada. Os dados de autenticação a API devem ser informados usando a autenticação OAuth Basic.

110 Autenticação invalida.

111 Apelido não cadastrado na aplicação.

112 Token não informado. Um token deve ser gerado para a comunicação com a API.

113 O Content-Type não foi informado. Somente aceito 'application/json'.

114 O Content-Type informado está errado. Somente aceito 'application/json'.

115 Limite de consultas por minuto a API (N vezes) foi atingido.

116 O conteúdo 'body' não foi enviado na requisição.

117 O conteúdo 'body' enviado não está no formato json ou está com algum erro.

120 Método não disponível.

130 Tipo de request (POST, GET, PUT, DELETE) invalido.

140 Método não encontrado, o método '{valor}' da chamada não existe.

150 Método '{valor}' não disponível para este método.

190 Para a execução deste método e necessário a informação do parâmetro '{valor}'. Consulte a documentação da API.

195 Parâmetro invalido: '{valor}'. Consulte no manual os parâmetros que podem ser usados.

200 Formato de retorno incorreto, o formato deve ser XML ou JSON.

210 O registro ou informação desejada não foi encontrada.

220 Nenhum registro foi encontrado.

300 Sem permissão de acesso a API. Consulte seu plano.

400 O formato da data enviado como parâmetro está errado, o formato deve ser YYYYMMDD.

405 O formato do período enviado como parâmetro está errado, o formato deve ser YYYYMMDD-YYYYMMDD.

410 O valor do parâmetro '{valor}' deve ser enviado com valores separados por virgulas, ex: 1,2,3.

500 O campo '{valor}' com os dados a ser incluídos/atualizados não foi enviado na requisição.

505 O no' principal do array '{valor}' não foi informado.


8/21

Código do erro Descrição do erro

510 O no' dos registros '{valor}' não foi informado.

515 O limite de registros por POST/PUT é de 'N' registros, foram enviados '{valor}'.

520 O envio do campo '{valor}' não e permitido.

525 O campo obrigatório '{valor}' não foi enviado.

530 O campo '{valor}' enviado não é inteiro.

531 O campo '{valor}' enviado não é string.

532 O campo '{valor}' enviado não está no formato correto de data YYYY-MM-DD.

533 O campo '{valor}' enviado não é número.

550 O registro '{valor}' não foi localizado.

555 Registro em duplicidade.

560 Registro não foi atualizado.

600 O campo 'total' para verificação do campo chave não foi informado.

900 API indisponível temporariamente.

910 API desativada na aplicação.

920 IP não liberado para acesso a API.

Recursos A seguir estão todos os recursos disponíveis na API prontos para serem utilizados em integrações

SISeCommerce > ERP > SISeCommerce.

Clientes

Informação Recurso disponível para tratar operações desejadas no cadastro de clientes de sua loja virtual.

URL

http://sualojavirtual.appsisecommerce.com.br/api/clientes/


9/21

Tipos de operações aceitas (method) GET

Parâmetros aceitos no método

Parâmetro Tipo de dados Descrição Observações

id Int Retorna apenas um cliente através do seu ID.

Não obrigatório

data_cadastro String(17) Retorna os clientes com base no intervalo de sua data de cadastro. Formato: YYYYMMDD-YYYYMMDD

Não obrigatório

tipo_pessoa String(1) Retorna os clientes por Tipo de pessoa, se Física ou Jurídica. Valores aceitos: F ou J

Não obrigatório

pagina Int

No caso do retorno ter mais de uma página, pode-se listar uma determinada página. Exemplo: /api/clientes?pagina=2

Não obrigatório

Exemplo de uso

Método GET

Retorna os clientes da plataforma.

<?php /** * Consumindo recurso Clientes da API SISeCommerce utilizando Basic Auth * @return JSON */ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "http://sualojavirtual.appsisecommerce.com.br/api/clientes?id=1"); curl_setopt($ch, CURLOPT_TIMEOUT, 30); curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($ch, CURLOPT_USERPWD, "sualojavirtual:cdda1df53a0086505d12f47e14ae0235"); $result = curl_exec ($ch); curl_close ($ch);


10/21

Resposta (response), em caso de sucesso.

{ "clientes": [ { "id": 1, "ativo": true, "nome": "Fulano de Tal", "tipo_pessoa": "F", "cpf": "06448552316", "rg": "123456", "cnpj": "", "ie": "", "email": "[email protected]", "telefone_1": "01234567890", "telefone_2": "01234567891", "telefone_3": "01234567892", "telefone_3_operadora": "TIM", "aceita_newsletter": false, "qtd_pedidos": 0, "apelido": "fulanodetal", "data_cadastro": "2015-04-28 10:16:22", "pessoa_fisica": { "nascimento": "1980-01-12", "sexo": "M" }, "enderecos": [ { "id": 1, "identificacao": "Rua Victor Meirelles", "destinatario": "Fulano de Tal", "logradouro": "Rua Victor Meirelles", "numero": "600", "complemento": "SC", "bairro": "Campinas", "cidade": "São José", "estado": "SC", "cep": "88101170", "referencia": "" } ] } ], "status": "OK", "total_registros": 1, "total_paginas": 1, "pagina_atual": 1 }


11/21

Resposta (response), em caso de erro. (Simulado parâmetro inválido).

Produtos

Informação Recurso disponível para tratar operações desejadas no cadastro de produtos de sua loja virtual.

URL

Tipos de operações aceitas (method) GET/PUT

Parâmetros aceitos no método GET


id Int Retorna apenas um produto através do seu ID. Exemplo: /api/produtos?id=1

Não obrigatório

id_sku Int Retorna apenas a variação de um produto através do seu ID. Exemplo: /api/produtos?id_sku=25

Não obrigatório

pagina Int

No caso do retorno ter mais de uma página, pode-se listar uma determinada página. Exemplo: /api/produtos?pagina=2

Não obrigatório

{ "retorno": { "status": "ERRO", "erros": [ { "codigo": 220, "msg": "Nenhum registro foi encontrado." } ] } }

http://sualojavirtual.appsisecommerce.com.br/api/produtos/


12/21

Exemplo de uso

Método GET

Retorna os produtos da plataforma.

<?php /** * Consumindo recurso Produtos da API SISeCommerce utilizando Basic Auth * @return JSON */ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "http://sualojavirtual.appsisecommerce.com.br/api/produtos?id=1"); curl_setopt($ch, CURLOPT_TIMEOUT, 30); curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($ch, CURLOPT_USERPWD, "sualojavirtual:cdda1df53a0086505d12f47e14ae0235"); $result = curl_exec ($ch); curl_close ($ch);


13/21


{ "produtos": [ { "id": 1, "ativo": true, "em_destaque": true, "em_lancamento": false, "nome": "Produto de Teste", "marca_id": 1, "marca_nome": "Marca Teste", "unidade": "Un", "tipo": "NORMAL", "possui_variacoes": false, "controla_estoque": true, "saldo_em_estoque_disponivel_total": 0, "saldo_em_estoque_reservado_total": 0, "saldo_em_estoque_total": 0, "categoria_principal_id": 1, "categoria_principal_nome": "Categoria 1", "url": "http://sualojavirtual.appsisecommerce.com.br/produto/produto-de-teste/1", "data_inclusao": "2015-04-27 17:10:59", "data_alteracao": "2015-04-27 17:13:40", "skus": [ { "id_sku": 1, "variacao": "", "preco_de": 1, "preco": 1, "preco_custo": 999.9, "peso": 1, "peso_cubico": 1, "altura": 30, "largura": 30, "profundidade": 30, "saldo_em_estoque_disponivel": 0, "saldo_em_estoque_reservado": 0, "saldo_em_estoque": 0, "sku": "SKU-95988754", "ean": "1234567890123", "ncm": "12345678", "modelo": "Modelo Teste" } ] } ], "status": "OK", "total_registros": 1, "total_paginas": 1, "pagina_atual": 1 }


14/21

Resposta (response), em caso de erro. (Simulado parâmetro inválido).

Método PUT

Informação Este método tem como função atualizar os dados do produto no SISeCommerce. Você pode fazer atualização de preço e de quantidade em estoque.

O conteúdo deve ser enviado no formato JSON, conforme exemplo a seguir.

Formato Descrição Observações

{"produtos":[{"id_sku":1,"qtd":12},{"id_sku":2,"qtd":50,"preco":205.15}]}

JSON com dados dos produtos a serem atualizados na plataforma.

Se o controle de estoque estiver desativado, não será alterado a quantidade do produto ou da sua variação.

Os parâmetros aceitos estão listados na tabela a seguir.


id_sku Int ID do SKU (produto ou sua variação) a ser alterado com os novos valores.

Obrigatório

qtd Int Define o novo valor para atualizar a quantidade em estoque do produto, ou sua variação.

Não obrigatório

preco Float Define o novo valor para atualizar o preço do produto, ou sua variação.

Não obrigatório

{ "retorno": { "status": "ERRO", "erros": [ { "codigo": 195, "msg": "Parametro invalido: 'ida'. Consulte no manual os parametros que podem ser usados." } ] } }


15/21

Exemplo de uso

Método PUT

Atualiza os dados de um produto da plataforma.


<?php /** * Consumindo recurso Produtos da API SISeCommerce utilizando Basic Auth para atualizar dados do produto. * @return JSON */ $data = json_encode(array("produtos" => array(0 => array("id_sku" => 1, "qtd" => 12, "preco":205.15), 1 => array("id_sku" => 2, "qtd" => 50)))); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "http://sualojavirtual.appsisecommerce.com.br/api/produtos"); curl_setopt($ch, CURLOPT_TIMEOUT, 30); curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','Content-Length: ' . strlen($data))); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($ch, CURLOPT_USERPWD, " sualojavirtual:cdda1df53a0086505d12f47e14ae0235"); $result = curl_exec($ch); curl_close($ch);

{ "0": { "id_sku": 1, "qtd": 12, "preco": 205.15, "retorno_api": { "status": "OK" } }, "1": { "id_sku": 2, "qtd": 50, "retorno_api": { "status": "OK" } }, "status": "OK" }


16/21

Resposta (response), em caso de erro. (Simulado valor “id_sku” incorreto para um produto).

Resposta (response), em caso de erro. (Simulado campo indevido para um produto).

{ "0": { "id_sku": "1", "qtd": 12, "preco": 205.15, "retorno_api": { "status": "ERRO", "erros": [ { "codigo": 530, "msg": "O campo 'id_sku' enviado não é inteiro." } ] } }, "status": "OK" }

{ "0": { "id_sku": 1, "qtd": 12, "preco": 205.15, "retorno_api": { "status": "ERRO", "erros": [ { "codigo": 520, "msg": "O envio do campo 'preco' nao e permitido." } ] } }, "status": "OK" }


17/21

Pedidos

Informação Recurso disponível para listar informações sobre os pedidos existentes na plataforma.

URL

Tipos de operações aceitas (method) GET

Parâmetros aceitos no método


id Int Retorna apenas um pedido através do seu ID. Exemplo: /api/pedidos?id=1

Não obrigatório

data_pedido String(17) Retorna os pedidos com base no intervalo de sua data de cadastro. Formato: YYYYMMDD-YYYYMMDD

Não obrigatório

status String

Retorna os pedidos conforme seus status, que podem ser consultados em “Configurações > Pedidos > Status dos pedidos”, na plataforma. Exemplo: /api/pedidos?status=200,205

Não obrigatório

pagina Int

No caso do retorno ter mais de uma página, pode-se listar uma determinada página. Exemplo: /api/pedidos?pagina=2

Não obrigatório

http://sualojavirtual.appsisecommerce.com.br/api/pedidos/


18/21

Exemplo de uso

Método GET

Retorna os pedidos da plataforma.

<?php /** * Consumindo recurso Pedidos da API SISeCommerce utilizando Basic Auth * @return JSON */ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "http://sualojavirtual.appsisecommerce.com.br/api/pedidos?status=205"); curl_setopt($ch, CURLOPT_TIMEOUT, 30); curl_setopt($ch, CURLOPT_RETURNTRANSFER,1); curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($ch, CURLOPT_USERPWD, "sualojavirtual:cdda1df53a0086505d12f47e14ae0235"); $result = curl_exec ($ch); curl_close ($ch);


19/21


{ "pedidos": [ { "id": 1, "data": "2015-04-28 11:54:54", "status_codigo": 205, "status_nome": "Aprovado", "canal_venda_id": 2, "canal_venda_nome": "Televendas", "marketplace_codigo_venda": "", "codigo_cupom": "", "codigo_vale_compra": "", "cliente": { "id": 1, "pessoa": "F", "nome": "Fulano", "sobrenome": "de Tal", "email": "[email protected]", "apelido": "fulanodetal", "cpf": "06448552316", "rg": "123456", "razao_social": "", "cnpj": "", "ie": "" }, "endereco_entrega": { "id": 1, "logradouro": "Rua Victor Meirelles", "numero": "600", "complemento": "SC", "bairro": "Campinas", "cidade": "São José", "estado": "SC", "cep": "88101170" }, "envio": { "forma_de_envio_id": 19, "forma_de_envio_nome": "Grátis", "valor": 0, "gratis": true, "digital": false, "data_envio": "", "codigo_rastreamento": "", "entregue": false, "valor_real": 0 }, (continua a seguir...)


20/21

Resposta (response), em caso de erro. (Simulado um id inexistente).

"pagamento": { "forma_de_pagamento_id": 46, "forma_de_pagamento_nome": "Pagamento na retirada", "valor": 1, "codigo_transacao": "", "data_vencimento": "" }, "totais": { "subtotal": 1, "descontos": 0, "envio": 0, "total": 1 }, "itens": [ { "id": 1, "id_sku": 1, "nome": "Produto de Teste", "variacao": "", "sku": "SKU-95988754", "ean": "1234567890123", "ncm": "12345678", "qtd": 1, "valor_custo": 999.9, "valor_unitario": 1, "valor_total": 1 } ] } ], "status": "OK", "total_registros": 1, "total_paginas": 1, "pagina_atual": 1 } { "retorno": { "status": "ERRO", "erros": [ { "codigo": 220, "msg": "Nenhum registro foi encontrado." } ] } }


21/21

Observações

Caso tenha dúvidas ou necessite de ajuda, entre em contato com a Central de Suporte, clicando aqui, ou pelos telefones da Sede (Florianópolis): (48) 3343-4897, São Paulo: (11) 4096-5344, Rio de Janeiro: (21) 3005-0046, Curitiba: (41) 3321-1330 ou Belo horizonte: (31) 3058-0856.

Manual de implementação da API SISeCommerce V1.0

Documents

Transcript of Manual de implementação da API SISeCommerce V1.0