Manual de implementação da API SISeCommerce V Manual de implementação da API SISeCommerce V /21

Transcrição

1 Manual de implementação da API SISeCommerce V /21

2 Sumário Manual de implementação da API SISeCommerce V Introdução... 3 Informações adicionais Limite de requisições Padrão de requisições (request) e respostas (response) Paginação 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 Informação URL Tipos de operações aceitas (method) Parâmetros aceitos no método GET Exemplo de uso Método PUT Informação Exemplo de uso Pedidos Informação URL Tipos de operações aceitas (method) Parâmetros aceitos no método Exemplo de uso Observações /21

3 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: "produtos": [ "id": 1, (..) ], "status": "OK", "total_registros": 1, "total_paginas": 1, "pagina_atual": 1 4. URL base, Token e Apelido Por padrão, a URL base para trabalhar com a API da plataforma segue as seguintes características: 3/21

4 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; 4/21

5 3. Webservice. 4. Token de acesso Ao acessar esta página basta copiar o apelido que se encontra no campo Token de acesso. 5/21

6 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: <?php /** * Consumindo recurso Produtos da API SISeCommerce utilizando Basic Auth JSON */ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, " 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:cdda1df53a d12f47e14ae0235"); $result = curl_exec ($ch); curl_close ($ch); Em caso de erro na autenticação (Basic Auth), será apresentada a estrutura a seguir. "retorno": "status": "ERRO", "erros": [ "codigo": 110, "msg": "Autenticacao invalida." ] 6/21

7 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 100 Descrição do erro 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 Para a execução deste método e necessário a informação do parâmetro 'valor'. Consulte a documentação da API. 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 O formato da data enviado como parâmetro está errado, o formato deve ser YYYYMMDD. O formato do período enviado como parâmetro está errado, o formato deve ser YYYYMMDD-YYYYMMDD. O valor do parâmetro 'valor' deve ser enviado com valores separados por virgulas, ex: 1,2,3. 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. 7/21

8 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 8/21

9 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. data_cadastro String(17) Retorna os clientes com base no intervalo de sua data de cadastro. Formato: YYYYMMDD-YYYYMMDD tipo_pessoa String(1) Retorna os clientes por Tipo de pessoa, se Física ou Jurídica. Valores aceitos: F ou J pagina Int No caso do retorno ter mais de uma página, pode-se listar uma determinada página. Exemplo: /api/clientes?pagina=2 Exemplo de uso Método GET Retorna os clientes da plataforma. <?php /** * Consumindo recurso Clientes da API SISeCommerce utilizando Basic Auth JSON */ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, " 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:cdda1df53a d12f47e14ae0235"); $result = curl_exec ($ch); curl_close ($ch); 9/21

10 Resposta (response), em caso de sucesso. "clientes": [ "id": 1, "ativo": true, "nome": "Fulano de Tal", "tipo_pessoa": "F", "cpf": " ", "rg": "123456", "cnpj": "", "ie": "", " ": "contato@fulanodetal.com.br", "telefone_1": " ", "telefone_2": " ", "telefone_3": " ", "telefone_3_operadora": "TIM", "aceita_newsletter": false, "qtd_pedidos": 0, "apelido": "fulanodetal", "data_cadastro": " :16:22", "pessoa_fisica": "nascimento": " ", "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": " ", "referencia": "" ] ], "status": "OK", "total_registros": 1, "total_paginas": 1, "pagina_atual": 1 10/21

11 Resposta (response), em caso de erro. (Simulado parâmetro inválido). "retorno": "status": "ERRO", "erros": [ "codigo": 220, "msg": "Nenhum registro foi encontrado." ] 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 Parâmetro Tipo de dados Descrição Observações id Int Retorna apenas um produto através do seu ID. Exemplo: /api/produtos?id=1 id_sku Int Retorna apenas a variação de um produto através do seu ID. Exemplo: /api/produtos?id_sku=25 pagina Int No caso do retorno ter mais de uma página, pode-se listar uma determinada página. Exemplo: /api/produtos?pagina=2 11/21

12 Exemplo de uso Método GET Retorna os produtos da plataforma. <?php /** * Consumindo recurso Produtos da API SISeCommerce utilizando Basic Auth JSON */ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, " 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:cdda1df53a d12f47e14ae0235"); $result = curl_exec ($ch); curl_close ($ch); 12/21

13 Resposta (response), em caso de sucesso. "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": " "data_inclusao": " :10:59", "data_alteracao": " :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 ", "ean": " ", "ncm": " ", "modelo": "Modelo Teste" ] ], "status": "OK", "total_registros": 1, "total_paginas": 1, "pagina_atual": 1 13/21

14 Resposta (response), em caso de erro. (Simulado parâmetro inválido). "retorno": "status": "ERRO", "erros": [ "codigo": 195, "msg": "Parametro invalido: 'ida'. Consulte no manual os parametros que podem ser usados." ] 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] Os parâmetros aceitos estão listados na tabela a seguir. 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. Parâmetro Tipo de dados Descrição Observações 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. preco Float Define o novo valor para atualizar o preço do produto, ou sua variação. 14/21

15 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. 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, " 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:cdda1df53a d12f47e14ae0235"); $result = curl_exec($ch); curl_close($ch); Resposta (response), em caso de sucesso. "0": "id_sku": 1, "qtd": 12, "preco": , "retorno_api": "status": "OK", "1": "id_sku": 2, "qtd": 50, "retorno_api": "status": "OK", "status": "OK" 15/21

16 Resposta (response), em caso de erro. (Simulado valor id_sku incorreto para um produto). "0": "id_sku": "1", "qtd": 12, "preco": , "retorno_api": "status": "ERRO", "erros": [ "codigo": 530, "msg": "O campo 'id_sku' enviado não é inteiro." ], "status": "OK" Resposta (response), em caso de erro. (Simulado campo indevido para um produto). "0": "id_sku": 1, "qtd": 12, "preco": , "retorno_api": "status": "ERRO", "erros": [ "codigo": 520, "msg": "O envio do campo 'preco' nao e permitido." ], "status": "OK" 16/21

17 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 Parâmetro Tipo de dados Descrição Observações id Int Retorna apenas um pedido através do seu ID. Exemplo: /api/pedidos?id=1 data_pedido String(17) Retorna os pedidos com base no intervalo de sua data de cadastro. Formato: YYYYMMDD-YYYYMMDD status pagina String Int 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 No caso do retorno ter mais de uma página, pode-se listar uma determinada página. Exemplo: /api/pedidos?pagina=2 17/21

18 Exemplo de uso Método GET Retorna os pedidos da plataforma. <?php /** * Consumindo recurso Pedidos da API SISeCommerce utilizando Basic Auth JSON */ $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, " 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:cdda1df53a d12f47e14ae0235"); $result = curl_exec ($ch); curl_close ($ch); 18/21

19 Resposta (response), em caso de sucesso. "pedidos": [ "id": 1, "data": " :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", " ": "contato@fulanodetal.com.br", "apelido": "fulanodetal", "cpf": " ", "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": " ", "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...) 19/21

20 "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 ", "ean": " ", "ncm": " ", "qtd": 1, "valor_custo": 999.9, "valor_unitario": 1, "valor_total": 1 ] ], "status": "OK", "total_registros": 1, "total_paginas": 1, "pagina_atual": 1 Resposta (response), em caso de erro. (Simulado um id inexistente). "retorno": "status": "ERRO", "erros": [ "codigo": 220, "msg": "Nenhum registro foi encontrado." ] 20/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) , São Paulo: (11) , Rio de Janeiro: (21) , Curitiba: (41) ou Belo horizonte: (31) /21