ROCKY ECOMMERCE API v2.02

Uniom Team
Rua Campos Sales, 520
Erechim, RS - 99700-224
+55 (54) 2106 8563

Descrição dos módulos

A plataforma Rocky E-commerce possibilitará a implementação de módulos JSON para importação/exportação de dados.

Endpoints

API Produção: https://api.plataformarocky.com.br/

Autenticação

Em toda chamada à API Rocky Ecommerce será validada através do Token de Authenticação do cliente junto aos headers da requisição. O Token é gerado e enviado para o cliente após a loja estar no ar.

Tipo de conteúdo

A API Rocky Ecommerce utliza JSON (JavaScript Object Notation) para representação de entidades. O header Accept: application/json é obrigatório em toda requisição.

Com exceção do método GET, é obrigatório também o header Content-Type: application/json, que indicará que o conteúdo no corpo da requisição está codificado em JSON.

Exemplo de requisição com o método GET:

GET /departaments HTTP/1.1
Authorization: Bearer <auth-token>
Accept: application/json

Exemplo de requisição com outros métodos (POST, PUT, PATCH e DELETE):

POST /products/1/variations HTTP/1.1
Authorization: Bearer <auth-token>
Accept: application/json
Content-Type: application/json

{
    "product_variation": {
        "nome": "Produto Teste Verde",
        "configurations": [34]
    }
}

Exceções

Existem endpoints na API que possuem como entrada o tipo de conteúdo multipat/form-data, nestes casos o header Content-Type deve também deve ser informado, porém com este tipo. O header Accept ainda é obrigatório nestes casos, sendo que o corpo da resposta permanacerá sendo em JSON.

Endpoints que possuírem o tipo de conteúdo fora do padrão serão sinalizados nesta documentação, indicando o tipo correto.

Paginação e Ordenação de Resultados

Todo endpoint de listagem de produtos tem suporte a paginação e ordenação dos resultados, veja abaixo:

GET /categories?page=2&order_by=nome,desc HTTP/1.1
Authorization: Bearer <auth-token>
Accept: application/json

{
    "current_page": 1,
    "data": ["..."],
    "first_page_url": "/?page=1",
    "from": 11,
    "next_page_url": "/?page=3",
    "path": "/",
    "per_page": 10,
    "prev_page_url": "/?page=1",
    "to": 20
}

Assim, para acessar uma página especifica dos resultados, basta informar o parametro na query string da URL: page={page-number}.

Para ordenar os resultados, basta informar o parametro order_by:{field-name},{asc-or-'desc} (a virgula pode ser codificado como URL).

1 Categorias

Definição de categoria

{
    "category": {
        "id": 1,
        "nome": "Lençois",
        "posicao": 1,
        "id_categoria_pai": null,
        "seo_page_title": "Lençois na Minha Loja!",
        "seo_description": "...",
        "seo_keywords": ["...", "..."]
    }
}

Descrição

Informações sobre os campos da Categoria

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento de departamentos.

2 Marcas

Definição de marca

{
    "brand": {
        "id": 1,
        "nome": "Adidas",
        "vendido_por_loja" : "Loja B Store", 
        "vendido_por_link": "https://lojab.com",
        "seo_page_title": "Adidas na Minha Loja - Melhores ofertas!",
        "seo_description": "...",
        "seo_keywords": ["...", "..."]
    }
}

Descrição

Informações sobre os campos da marca

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento de marcas.

3 Produtos

Definição de produto

{
    "product": {
        "id": 1,
        "ref": "TEST123",
        "nome": "Produto Teste",
        "marca": 2,
        "preco_base": 230,
        "preco": 230,
        "preco_promocional": 182.99,
        "descricao": "<p>Descrição do Produto - HTML</p>",
        "descricao_en": "<p>Product description in english - HTML</p>",
        "peso": 200,
        "largura": 30,
        "altura": 40,
        "comprimento": 10,
        "tags": [
            "test",
            "test1"
        ],
        "multiplos": 1,
        "destaque": true,
        "novo_ate": "2017-11-20",
        "seo_description": "Melhor oferta do produto - Minha Loja",
        "seo_page_title": "...",
        "seo_keywords": [
            "...",
            "..."
        ]
    }
}

Descrição

Informações sobre os campos do produto

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento de produtos.

POST /products/{id}/images - Request Body (multipart/form-data)

POST /products/999/images?main=1 HTTP/1.1
Authorization: Bearer <auth-token>
Accept: application/json 
Content-Type: multipart/form-data; boundary=12345

--12345
Content-Disposition: form-data; name="images[]" filename="image1.jpg"

*content of image1.jpg ...*
--12345
Content-Disposition: form-data; name="images[]" filename="image2.png"

*content of image2.png ...*
--12345--

As imagens devem ser enviadas em formato array através de uma requisição com Content-Type do tipo multipart/form-data, como exemplificado acima. O nome do campo array deve ser images.

DELETE /products/{id}/images - Request Body

{
    "images": [123, 43, 65, 1111]
}

Remove as imagens do produto em questão a partir da lista de IDs informada.

GET /products/{id}/categories - Response Body

{
    "product": {
        "id": 1,
        "ref": "123",
        "nome": "Produto Teste Aleatório",
        "categories": [
            {
                "id": 2,
                "id_departamento": 1,
                "nome": "Camisetas",
                "home": true,
                "posicao": 2,
                "id_banner": null,
                "seo_description": "...",
                "seo_page_title": "Camisetas para Meninos",
                "seo_keywords": "asdasdasd"
            },
            {"..."},
            {"..."}
        ]
    }
}

POST /products/{id}/categories - Request Body

{
	"categories": [
        //objeto categoria com id válido
        {
            "id": 2 
        },
        // id de um categoria
        3, 
        1,
        // categoria inexistente - será criada no procedimento
        { 
            "id_departamento": 1,
            "nome": "Camisetas",
            "home": 1,
            "posicao": 2,
            "id_banner": null,
            "seo_description": "...",
            "seo_page_title": "Camisetas para Meninos",
            "seo_keywords": "asdasdasd"
        }
    ]
}

DELETE /products/{id}/categories - Request Body

{
    // ids de categorias vinculadas ao produto
    "categories": [1, 2, 3]
}

4 Variações

Definição de variação

{
    "variation": {
        "id": 1,
        "nome": "Tamanho",
        "sigla": "TNUM",
        "tipo": "select",
        "posicao": 1,
        "options_count": 10
    }
}

Definição de opção de variação

{
    "variation_option": {
        "id": 1,
        "id_variacao": 1,
        "item": "14",
        "sigla": "14",
        "cor": "",
        "posicao": 1,
        "variation": {
            "id": 1,
            "nome": "Tamanho"
        }
    }
}

Descrição

Informações sobre os campos da variação

Informações sobre os campos da opção de variação

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento de marcas.

5 Variações do Produto (SKU)

Definição do SKU

{
    "product_variation": {
        "id": 4,
        "id_produto": 1,
        "sku": "123-AZL-G",
        "codigo": null,
        "nome": "Produto Teste Aleatório Azul Grande",
        "preco_base": 230,
        "preco": 230,
        "preco_promocional": 182.99,
        "descricao": "<p>Descrição do Produto - HTML</p>",
        "descricao_en": "<p>Product description in english - HTML</p>",
        "peso": 200,
        "largura": 30,
        "altura": 40,
        "comprimento": 10,
        "quantidade": 100,
        "multiplos": 1,
        "status": 1,
        "brand": {
            "id": 2,
            "nome": "Marca Aleatória"
        },
        "configurations": [
            {
                "id": 17,
                "item": "Azul",
                "sigla": "AZL",
                "variation": {
                    "id": 3,
                    "nome": "Cor"
                }
            },
            {
                "id": 15,
                "item": "Grande",
                "sigla": "G",
                "variation": {
                    "id": 2,
                    "nome": "Tamanho"
                }
            }
        ],
        "product_ref": [
            {
                "ref": "321"
            }
        ]
    }
}

Descrição

Informações sobre os campos da variação de produto

OBS: Campos omitidos da variação são automaticamente preenchidos utilizando os dados do produto.

GET /products/variations/allResults - Request Body

{
    "product_variation": {
        "nome": "Produto Teste Azul Grande",
        "quantidade": 50,
        "descricao": "Descrição do produto azul",
        "status": 1,
        "configurations": [20, 30]
    }
}

POST /products/{id}/variations - Request Body

{
    "product_variation": {
        "nome": "Produto Teste Azul Grande",
        "quantidade": 50,
        "descricao": "Descrição do produto azul",
        "status": 1,
        "configurations": [20, 30]
    }
}

POST /products/{productId}/variations/{id}/images - Request Body (multipart/form-data)

POST /products/999/variations/9999/images?main=1 HTTP/1.1
Authorization: Bearer <auth-token>
Accept: application/json 
Content-Type: multipart/form-data; boundary=12345

--12345
Content-Disposition: form-data; name="images[]" filename="image1.jpg"

*content of image1.jpg ...*
--12345
Content-Disposition: form-data; name="images[]" filename="image2.png"

*content of image2.png ...*
--12345--

As imagens devem ser enviadas em formato array através de uma requisição com Content-Type do tipo multipart/form-data, como exemplificado acima. O nome do campo array deve ser images.

PUT /products/variations/{sku} - Request Body

{
    "product_variation": {
        "quantidade": 10
    }
}

DELETE /products/{productId}/variations/{id}/images - Request Body

{
    "images": [123, 43, 65, 1111]
}

Remove as imagens da variação de produto em questão a partir da lista de IDs informada.

6 Clientes

Pessoa Física

Definição do cliente

{
    "client": {
        "id": 4,
        "nome": "Jão José",
        "email": "[email protected]",
        "token_beasy": "12jfF294HajO9Jab481Njsh",
        "cpf": "12345678989",
        "celular": "5499999999",
        "endereco": "R. Teste",
        "numero": "99",
        "complemento": "apto 101",
        "bairro": "Centro",
        "cep": "99999999",
        "cidade": "São Paulo",
        "estado": "RS",
        "genero": "Masculino",
        "data_nasc": "1996-06-18",
        "cro": "exemplo"
    }
}

Descrição

Informações sobre os campos do Cliente

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento de departamentos.

Pessoa Jurídica

Definição da empresa

{
    "company": {
        "id": 4,
        "razaosocial": "Teste",
        "nomefantasia": "Teste",
        "ie": "987456321456",
        "email": "[email protected]",
        "cnpj": "1234567891234",
        "token_beasy": "ahn1528djsaiHSA6FAJS1Jjsh",
        "categoria": 1,
        "telefone": "54999999999",
        "celular": "54999999999",
        "endereco": "Rua Alemanha",
        "numero": "989",
        "complemento": "Centro",
        "bairro": "Teste",
        "cep": "99700226",
        "cidade": "Erechim",
        "estado": "RS",
        "nome_responsavel": "teste",
        "email_responsavel": "[email protected]",
        "cpf_responsavel": "12345678912",
        "cro": "exemplo",
        "data_cadastro": "2018-02-08"
    }
}

Descrição

Informações sobre os campos do Cliente Pessoa Jurídica

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento de departamentos.

7 Pedidos

Definição do pedido

{
    "order": {
        "id": 88,
        "codigo": 95773010,
        "codigo_erp": null,
        "transacao": "PAY-16S19624NM617440PLKA5QQQ",
        "id_cliente": 4,
        "tipo_cadastro": "b2b",
        "canal": "site",
        "subtotal": 95,
        "juros": 0,
        "cupom_desconto": null,
        "pontos_resgate": null,
        "valor_pontos_resgate": null,
        "frete": 0,
        "total": 95,
        "operacao": 1,
        "qtd_operacoes": 1,
        "desconto_boleto": null,
        "formapagamento": 11,
        "envio": "PAC",
        "clearsale_score": 1,
        "status": 7,
        "observacao": "Cancelado devido a não finalização do pagamento.",
        "rastreamento": "",
        "endereco_entrega": {
            "cep": "99700020",
            "endereco": "Rua Alemanha",
            "numero": "305",
            "complemento": "",
            "bairro": "Centro",
            "cidade": "Erechim",
            "estado": "RS"
        },
        "recebedor": {
            "nome": "João das Neves",
            "cpf": "33739291800",
            "telefone": "11999999999"
        },
        "data": "2018-02-12 15:51:41",
        "atualizado": "2018-02-12 15:51:41",
        "total_itens": 182.99,
        "status_info": {
            "id": 1,
            "nome": "Efetuado"
        },
        "items": [
            {
                "id": 89,
                "id_pedido": 88,
                "id_sku": 10,
                "nome": "Tênis",
                "qtd": 1,
                "valor": 95,
                "valor_desconto": null,
                "observacao": null,
                "sku": "teste"
            }
        ],
        "transaction_integration": {
            "nome": "PagarMe",
            "identificador": "pagarme",
            "tipo": "payment"
        },
        "coupon": null,
        "operation_type": {
            "id": 1,
            "nome": "À vista"
        },
        "payment_method": {
            "id": 1,
            "nome": "Boleto",
            "sigla": "BOLETO"
        }
    }
}

Descrição

Informações sobre os campos do Pedido

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento de pedidos.

OBS: Para filtrar pela data ela precisa estar nesse formato: d-m-Y. Ex: 12-06-2019.

Status de pedido disponíveis

8 Especificações de produtos

Definição da especificação

{
    "specification": {
        "id": 1,
        "id_produto": 1,
        "id_sku_produto": 1,
        "nome": "Especificação teste",
        "valor": "Valor teste",
        "salvo_em": "2019-09-17 15:08:02"
    }
}

Descrição

Informações sobre os campos da espeficação do produto

9 Listas de Presente

Definição da lista de presente

{
    "ListaPresente": {
        "id": 1,
        "id_cliente": 1253,
        "id_image": 1,
        "codigo": "#FESTADAANA",
        "data": "2020-02-22",
        "tipo": "aniversario",
        "nome": "Aniversario da Ana",
        "mensagem": "Festa de aniversário da Ana",
        "qtd_total_prod": 1,
        "criado_em": "2020-02-17 10:52:27",
        "produtos_lista_presente": {
            "id": "1",
            "id_sku": "124",
            "id_lista": "1",
            "qtd_disponivel": "1",
            "nome_comprador": "Amanda",
        }
    }
}

Descrição

Informações sobre os campos da Lista de Presente

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento das listas de presente.

Changelog

v2.00

* Adição do campo CRO no cadastro de clientes (apenas para lojas que possuem essa funcionalidade)

v2.00

* Adição de listas de presentes (apenas para lojas que possuem essa funcionalidade)

v1.03 - 02/12/2019

Adições:

* Pedidos:
    * Adicionado informações de captura no endpoint GET /orders

v1.02 - 11/10/2019

Alterações:

* Produtos:
    * Retorno do endpoint /products/update/{ref} alterado de 'alterações' para 'product'
        * Caso o produto seja atualizado com sucesso, retornará o produto atualizado
        * Caso haja erro, retornará null

Adições:

* Produtos:
    * Adicionado endpoint /products/ref/{ref} 
        * Busca um produto pela referência

* Categorias: 
    * Adicionado endpoint /categories/name/{name} 
        * Busca uma categoria pelo nome
    
* Marcas:
    * Adicionado endpoint /brands/name/{name} 
        * Busca uma marca pelo nome

v0.4 - 04/2019

* Departamentos descontinuados e serão removidos na próxima atualização
* Categorias:
  * Novos *endpoints*:
    * /categories/tree         
    * /categories/{id}/children
    * /categories/{id}/tree    
  * Campo 'id_categoria_pai' adicionado ao recurso '/categories'
  * O campo 'id_departamento' não é mais obrigatório

v0.1 ~ v0.2

* Implementação inicial da API
* Implantação no ambiente Rocky Ecommerce
* Correções de *bugs* diversos

Descontinuado

Departamentos (DESCONTINUADO)

Definição do departamento

{
    "departament": {
        "id": 1,
        "nome": "Cama e banho",
        "posicao": 1,
        "seo_page_title": "Cama e banho na Minha Loja!",
        "seo_description": "...",
        "seo_keywords": ["...", "..."]
    }
}

Descrição

Informações sobre os campos do Departamento

Métodos diponíveis

Endpoints disponíveis na API para gerenciamento de departamentos.

Rocky Ecommerce @ 2019