1. Visão Geral
Nossa plataforma de e-commerce permite que qualquer sistema ERP consiga fazer integração dos produtos e pedidos, facilitando assim o processo de vendas pela internet. A integração da nossa plataforma com seu sistema ERP é feita de forma simples e rápida. Na integração via API, trabalhamos no padrão REST, e por isso são utilizado os verbos GET, POST, PUT, PATCH e DELETE.
- GET obtém informações sobre um recurso
- POST cria um recurso
- PUT atualiza um recurso
- PATCH serve para atualizar partes de um recurso, e não o recurso todo
- DELETE exclui um recurso
Para iniciar o desenvolvimento leia essa documentação, pois é extremamente importante para o entendimento dos fluxos e regras de negócio da plataforma da Climba. Siga as orientações técnicas aqui, e solicite um ambiente para testes com nossa equipe de integração pelo e-mail: integracao@climba.com.br.
2. Pré requisitos
Em todas as requisições feitas, você deve fazê-las enviando no cabeçalho o parâmetro: x-idcommerce-api-token com a chave fornecida pela nossa equipe de desenvolvimento.
3. Autenticação com a API
Em todos os métodos feitos via API deve ser utilizado a url que nossa equipe disponibilizou + o nome do método, por exemplo, para retornar os detalhes de um pedido na loja demo:
https://www.lojademo.api.climbaapp.com.br/api/v1/orders/954556
https://www.lojademo.api.climbaapp.com.br/api/v1 (url de integração da loja virtual), orders/954556 (nome do método + parâmetro)
4. Por onde começar
A Climba recomenda o desenvolvimento de acordo com os passos abaixo, com o entendimento de que este é o processo mais simplificado de integração:
Com relação aos envios dos cadastros para a loja virtual, indicamos que seja realizada a adição de uma coluna no banco de dados que indique se o item já foi enviado para a Climba.
Exemplo: A Marca código 1 foi enviada para a Climba, então colocar no banco de dados que isso aconteceu para não refazer o envio de uma requisição POST para cadastrá-la, e também não sendo necessário fazer uma requisição GET para saber se essa marca já existe dentro da loja virtual do cliente.
1 – Desenvolvimento do cadastro e atualização de marcas:
Recomendamos que se inicie pelas marcas pois este é um cadastro mais simples, onde é somente necessário informar o ID, nome da marca, e caso exista, uma descrição sobre a marca.
Dessa forma é possível desenvolver uma primeira etapa de cadastro e atualizações de itens com requisições que contenham o body do JSON mais simplificados, e já se cria um entendimento do funcionamento da integração.
2 – Desenvolvimento do cadastro e atualização de atributos:
Qualquer SKU que estiver cadastrado na loja virtual precisará ter uma cor e um tamanho.
Caso os produtos não possuam cor/tamanho, é preciso cadastrar uma cor de nome “Única” e um tamanho de nome “Único” para serem vinculados aos produtos.
Para o cadastro de cores, informar no JSON o “attributeGroup” como 1, e para o cadastro de tamanhos, informar o “attributeGroup” como 2.
3 – Desenvolvimento do cadastro e atualização de categorias:
Os produtos cadastrados também precisam ter uma categoria.
Para cadastrar categorias, é preciso seguir a ordem de cadastro na hierarquia de uma árvore de categorias.
Exemplo:
Há a categoria código 1 – Calçados e a subcategoria 2 – Tênis, que é filha da categoria Calçados. A categoria código 1 precisa ser cadastrada antes, pois no cadastro da categoria Tênis será necessário informar no campo “parentId” o id da categoria pai de tênis.
4 – Desenvolvimento do cadastro e atualização de produtos:
Neste cadastro devem ser informados os dados que o produto possui, contendo as informações de marca, atributos e categorias cadastradas anteriormente.
Além desses dados, é preciso enviar as informações referentes às variações de estoque, assim como peso bruto, altura, largura e comprimento das variações de estoque. Mais detalhes são explicados nesta seção da documentação.
5 – (Opcional) Desenvolvimento do cadastro de fotos do produto:
Caso o ERP possua fotos e considere válido o cadastro, ele pode ser feito com o envio de uma URL com a foto, ou com a imagem convertida em base64.
6 – Desenvolvimento da consulta por pedidos:
A Climba recomenda que a consulta por pedidos seja realizada com dois filtros, que são dateStart (data inicial do pedido, que muda conforme alguma modificação que o pedido tenha passado, como o status, por exemplo) e status. Mais detalhes também podem ser visualizados nesta seção da documentação.
Também recomendamos que essa consulta seja efetuada de 30 em 30 minutos.
Exemplo de requisição GET de pedidos com os dois filtros citados acima:
Caso exista a possibilidade, recomendamos que seja efetuada a consulta por pedidos através de webhooks. O uso de webhooks na integração é indicado nesta seção da documentação.
7 – (Opcional) Desenvolvimento da consulta por formas de pagamento, formas de envio e operadores logísticos:
Caso o ERP deseje realizar o relacionamento dos dados de formas de pagamento, formas de envio e operadores logísticos do site, as consultas dessas informações se encontram disponíveis em nossa API.
8 – Desenvolvimento do envio da requisição PATCH informando que o pedido foi importado pelo ERP:
Após a importação do pedido no ERP, deve ser enviada uma requisição para informar para a Climba que o pedido foi importado. Esse procedimento é detalhado nesta seção da documentação.
9 – Desenvolvimento do processo de faturamento do pedido:
Após o faturamento do pedido no sistema ERP, os dados de faturamento devem ser enviados para a loja virtual para que aconteça a sequência do processo de despacho de forma automatizada. Esse procedimento é detalhado nesta seção da documentação.
Consulte o glossário desse documento para mais informações.
É importante ressaltarmos quanto ao limite de requisições de nossa API. As requisições à nossa API são limitadas a no máximo 10 requisições por segundo e no máximo 1.500 requisições por hora.
Caso seja ultrapassado o limite de requisições a API retornará o status code 429 (too many requests).
5. Diagrama de relacionamento
6. Model e objetos de cada método
Em nossa página de documentação técnica de nossa API (Documentação API), possuímos toda a parte de models, onde é possível visualizar os métodos e os objetos que compõem cada método. Os atributos de conteúdo obrigatórios estão sinalizados com asterisco (*). Reforçando que todos os parâmetros devem ser implementados, caso não seja obrigatório enviar o parâmetro vazio.
Exemplo:
7. Integração de produtos
- Fluxo de cadastro de produtos:
8. API de produtos
- Cadastros acessórios
- Atributos
- Grupos de atributos
- Marcas
- Descrição
- (Para a marca ficar visível, é necessário que ela esteja vinculada ao menos a um produto ativo)
- Categorias
- Cadastro de Produtos
- ID de produto (código interno)
- Se estiver alterando os detalhes de um produto apenas, não é obrigatório enviar os atributos: productVariants e productVariants.prices, apenas deixe um array vazio no lugar.
- Nas variações do produto, você deve sempre cadastrar enviando os 2 atributos: Cor + Tamanho, caso não envie esses atributos, o cadastro não será permitido por falta de dados.
- Alteração de preços:
- É possível altera o preço dos produtos através da função PATCH, alterando diretamente na variação de estoque do produto.
- Outra possibilidade é utilizando a função PUT, sendo necessário o envio de todo o corpo do JSON de produto.
- Alteração de estoque:
- Se estiver alterando o estoque do produto, o atributo productVariants é obrigatório, porém o productVariants.prices não.
- Para alterar apenas o estoque utilizar a função PATCH.
- Fotos dos produtos
- O cadastro de fotos pode ser realizado com o envio do arquivo codificado em base64.
- Outra opção no cadastro de foto é fornecendo um endereço válido de uma foto (URL), para que nosso servidor baixe automaticamente e vincule a um produto.*
- Extensões permitidas: jpg, jpeg, png, gif*
- Tamanho máximo cada foto: 10MB
- Cadastros acessórios
Observações:
- Caso o código do produto possua “/”, é necessário enviar na URL da request em caso de um PUT ou PATCH “__slash__” no lugar da /
- Exemplo: Código do produto – 123/456
Requisição – /products/123__slash__456
- Exemplo: Código do produto – 123/456
- Caso o código do produto possua “#”, é necessário enviar na URL da request em caso de um PUT ou PATCH “__hashtag__” no lugar da #
- Exemplo: Código do produto – 123#456
Requisição – /products/123__hashtag__456
- Exemplo: Código do produto – 123#456
- Caso o código do produto possua “+”, é necessário enviar na URL da request em caso de um PUT ou PATCH “__plus__” no lugar do +
- Exemplo: Código do produto – 123+456
Requisição – /products/123__plus__456
- Exemplo: Código do produto – 123+456
- Ao desabilitar no ERP o envio do produto para a Loja Virtual, deve ser enviada uma requisição PUT para inativar o produto, informando o status código 0.
9. Integração de pedidos
Para a integração de pedidos, recomendamos trabalhar com os pedidos nos status ‘1 – Aguardando Pagamento, 9 – Pagamento Autorizado, 2 – Pagamento Confirmado e 6 – Pedido Cancelado’.
Tabela de status:
Código
Descrição do Status
1
Aguardando Pagamento
2
Pagamento Confirmado
3
Enviado
5
Entregue
6
Cancelado
8
Faturado
9
Pagamento Autorizado
10
Em Separação
Recomendamos o uso de webhooks para a integração de pedidos (mais detalhes na seção Webhooks). Caso for utilizada uma rotina para buscar pedidos via GET, a recomendação da Climba é que seja feita a busca de 30 em 30 minutos.
Os dois filtros que recomendamos a utilização na busca do GET de pedidos são o dateStart (data inicial do pedido, que muda conforme alguma modificação que o pedido tenha passado, como o status, por exemplo) e status.
Exemplo de requisição GET de pedidos com os dois filtros citados acima:
https://staging-testeclimba.api.climbaapp.com.br/api/v1/orders?dateStart=2021-10-15%2008:00:00&status=2
Fluxo de alteração de estoque conforme status dos pedidos:
Para cada Status recebido do pedido, uma ação no estoque dos produtos desse pedido deve ser realizada:
- Ao receber o status do pedido 1 – Aguardando pagamento, o ERP deverá importar o pedido e notificar que o mesmo foi importado (orderExportedToErp: “true”) e reservar o estoque dos produtos que compõem esse pedido.
- Ao receber o status 9 – Pagamento autorizado, o ERP deverá importar o pedido, notificar que o mesmo foi importado (orderExportedToErp: “true”) e reservar o estoque.
- Ao receber o status 2 – Pagamento confirmado, o pedido deverá ser importado e notificado (orderExportedToErp: “true”), efetuando a venda no ERP e baixando o estoque para que seja feito a emissão da nota fiscal.
- Ao receber o status 6 – Cancelado, caso o ERP já tenha importado o pedido, efetuado venda e reservado o estoque, o processo precisará ser desfeito.
Uso da Requisição PATCH do pedido informando que o pedido foi importado
Conforme indicado no fluxo de alteração de estoque conforme status dos pedidos, a partir do momento em que o pedido for importado no sistema ERP, precisamos que seja enviada uma requisição do tipo PATCH informando que o pedido foi importado pelo sistema ERP.
Isso acontece porque a própria plataforma da Climba realiza a reserva de estoque do produto que está no pedido até o momento em que o ERP importar o pedido, e caso o ERP importe o pedido e não nos repasse essa informação, a partir do momento em que o ERP nos enviar uma atualização de estoque do produto, o produto ficará com a quantidade enviada menos a quantidade em reserva.
Exemplo: O pedido 12345 que contém 1 unidade do produto Y foi importado pelo ERP, mas não foi enviado o PATCH informando que o pedido foi importado. Esse produto possuía 2 unidades antes da venda.
Após isso, o ERP enviou a quantidade em estoque de 1 unidade para a Climba. Dessa forma, a quantidade em estoque do produto ficou em 0, porque 1 unidade em estoque menos 1 unidade em reserva se tornou 0 em estoque.
Com o ERP enviando a requisição informando a importação do pedido, a situação não acontecerá, pois a Climba deixa de fazer a reserva do estoque do produto (claro que sem retornar o estoque que o produto tinha antes da realização do pedido).
A requisição utilizada é a seguinte, conforme exemplo:
Exemplo de Requisição PATCH – https://www.lojademo.api.climbaapp.com.br/api/v1/orders/954556
Body:
{
“orderExportedToErp”: true
}
Para mais detalhes, você pode acessar esse link, que irá lhe redirecionar para o swagger da requisição.
Processo de separação do pedido – /inPicking (Opcional)
Após o pedido estar com o status Pago (código 2) na loja virtual e já ter sido importado dentro do Sistema ERP, o processo de separação do pedido deve acontecer.
Caso se entenda que seria importante atualizar o pedido dentro da loja virtual a partir do momento em que o pedido está sendo separado, é possível enviar uma requisição informando a troca de status para “Em Separação”.
A requisição utilizada é a seguinte, conforme exemplo:
Exemplo de Requisição PUT – https://www.lojademo.api.climbaapp.com.br/api/v1/orders/954556/inPicking
Não é necessário enviar nenhuma informação no corpo (body) da requisição.
Para mais detalhes, você pode acessar esse link, que irá lhe redirecionar para o swagger da requisição.
Processo de faturamento do pedido – /billed
Assista o vídeo introdutório abaixo:
O /billed é o procedimento realizado para que o pedido dentro da loja virtual tenha seu status alterado para Faturado na loja virtual e crie um pré-envio dentro da plataforma, de forma que o processo de despacho de pedidos tenha uma maior automação.
Como funciona?
1 – O pedido é importado no sistema ERP.
2 – Dentro do sistema ERP é realizado o procedimento de baixa do estoque e geração da Nota Fiscal.
3 – Após a geração da Nota Fiscal, deve ser executada uma requisição do tipo PUT (veja a requisição) enviando a informação do Operador Logístico (mais detalhes na próxima seção), Número da Nota Fiscal, Chave da Nota Fiscal e XML da Nota Fiscal.
4 – Com o recebimento dessa requisição na loja virtual, é gerado um pré-envio contendo as informações enviadas pela requisição PUT recebida.
5 – No retorno (response) da requisição, a Climba disponibiliza informações do pré-envio cadastrado, contendo o link da etiqueta de envio usada pelo lojista para colar em sua encomenda que será despachada, permitindo com que essa etiqueta seja disponibilizada para impressão diretamente dentro do sistema ERP.
6 – A plataforma fará a alteração do status do pedido para Faturado automaticamente após o recebimento da requisição, realizando o envio de um e-mail ao cliente que efetuou o pedido informando que o pedido foi faturado e está pronto para ser enviado para a transportadora que efetuará a entrega.
Para que o processo se torne o mais completo possível, os passos acima devem ser seguidos. Somente o envio do operador logístico pode ser vazio no JSON caso não seja viável realizá-lo, porém indicamos a leitura da seção que explica o uso dele para entendimento.
Caso a etiqueta de envio não seja disponibilizada dentro do sistema ERP, esse processo se torna parcial, visto que o lojista ainda terá a necessidade de entrar na plataforma da Climba para realizar a impressão da etiqueta de despacho de sua encomenda.
O uso de Método de Envio e Operador Logístico no /billed
Quando um pedido foi realizado na loja virtual, o cliente que efetuou o pedido selecionou por um método de envio disponibilizado na loja virtual. Esse método de envio é o indicado no JSON dentro do GET /orders onde fica o “shipping”. Cada método de envio possui um ID na loja virtual.
Quando o Billed precisa ser efetuado, a requisição PUT solicita o operador logístico, que deve ser enviado no parâmetro “logisticOperatorId”.
O operador logístico é o método de envio ao qual o lojista fará o despacho do pedido, e não necessariamente o operador logístico é igual ao método de envio que o cliente selecionou ao finalizar o pedido, e é por isso que existem essas duas informações. Cada operador logístico possui um ID na loja virtual, e esses IDs não são iguais aos IDs dos métodos de envio.
Exemplo:
O ID do método de Envio “Transportadora do João” é 1;
e o ID do operador logístico “Transportadora do João” é 5.
Nesse caso, no momento em que o lojista realizar o procedimento de faturamento dentro do sistema ERP, ele deve ter a opção de poder definir o operador logístico ao qual será realizado o processo de envio do pedido. De acordo com o operador logístico retornado para a Climba serão definidas de forma automática as informações descritas no e-mail de pedido enviado para o cliente que efetuou o pedido.
Recomendação da Climba – O que recomendamos é que seja realizado um relacionamento do método de envio da Climba com o Transportador que está cadastrado no sistema ERP, e também seja realizado um relacionamento do transportador do sistema ERP com o operador logístico da Climba, conforme exemplo da imagem abaixo:
Da forma acima, esse relacionamento já fica pronto e padronizado, e caso o lojista defina realizar o envio por outro operador logístico, essa opção é disponibilizada pelo ERP antes de faturar o pedido.
OBS.: Caso o operador logístico seja enviado vazio no PUT /billed, automaticamente será considerado o operador logístico relacionado ao método de envio.
Exemplo: O método de envio do pedido é o PAC, e o PUT /billed veio com o “logisticOperatorId” = “”, o operador logístico gerado no pré-envio do pedido será o operador logístico do PAC.
O retorno da etiqueta de despacho no response do /billed
Cada response da requisição /billed, caso retornado com sucesso, informa um link contendo uma etiqueta para despacho que deve ser colada na encomenda que será enviada. Isso permite que a etiqueta para impressão possa ser disponibilizada diretamente dentro do sistema ERP.
O link da etiqueta é disponibilizado no parâmetro “labelUrl”.
10. API de pedidos
11. Webhooks
Webhooks são uma espécie de gatilho em determinada ação, por exemplo, quando um pedido é feito na loja virtual e também a troca de status do pedido, em que a loja virtual notifica o sistema que há um novo pedido na loja virtual, e com isso, o sistema pode recuperar os dados do pedido em questão para que importe para o sistema caso necessário.
No momento não temos desenvolvido uma API para cadastro de Webhooks automaticamente, mas você pode nos enviar por e-mail para: [email protected] para o cadastramento da sua URL para que possa começar a receber notificações da loja virtual. No retorno da Webhook, o sistema deve retornar apenas um cabeçalho código 200, sem corpo no conteúdo.
Exemplo do corpo do Webhook enviado pela loja virtual:
curl -X POST ‘http://url.sistema.erp’ -H ‘accept: application/json’ -H ‘content-type: application/json’ -d ‘{ ‘orderId’: ‘1234567890’}’
No exemplo acima, bastaria em seguida a realização de uma requisição GET para consultar os dados exatamente do pedido em questão:
GET do exemplo acima – https://staging-testeclimba.api.climbaapp.com.br/api/v1/orders/1234567890
12. Homologação
Assim que o ERP finalizar o desenvolvimento de todas as etapas da integração, é necessário efetuar o processo de homologação, que são alguns testes práticos e perguntas conforme checklist de homologação presente neste documento.
Para dar início ao processo de homologação, é preciso ir até a dashboard de seu painel de homologação (staging), selecionar todas as checkbox onde o desenvolvimento foi realizado e então clicar em Agendar Homologação:
Entenda mais sobre o processo de homologação:
13. Checklist de homologação
- Cadastro de atributos:
- Cadastro de cor e tamanho
- Alteração do nome da cor e tamanho
- Cadastro de categorias
- Árvore de categorias
- Alteração dos parâmetros de categoria.
- Envio de descrição da categoria
- Caso a categoria possua categorias filhas, não deve ter produtos amarrados a essa categoria Pai.
- Cadastro de marcas
- Alterar o nome da marca
- Envio de descrição da marca
- Lista de preço
- Cadastro de lista de preços
- Se consegue alterar.
- Cadastro de produtos
- Simples e agrupado (grade)
- Mais de uma categoria
- Fotos
- Descrição
- Enviar com o peso bruto. (recebemos sempre em Gramas)
- Enviar largura X altura X comprimento. (recebemos sempre em CM)
- Adicionar estoque
- Variações de estoque
- Se consegue alterar essa variação.
- Integração de pedido
- Importar pedidos pendentes
- Importar pedidos pagos
- Receber o status Cancelado
- Processo de faturamento (envio do xml)
- Vinculação da transportadora do ERP com os métodos de envio do site
- Requisições
- Cadastro de atributos:
14. Fluxo do checklist de homologação
Para o procedimento de realização de pedidos, é necessário que você esteja logado na plataforma admin (https://erp.climbacommerce.com.br/admin) , conforme usuário e senha passados por nossa equipe, para então acessar a loja virtual e efetuar uma compra como um consumidor final. Você pode acessar a loja virtual através do link conforme imagem abaixo.
Caso você não esteja logado com os dados sua loja virtual aparecerá conforme imagem abaixo:
Acesse a loja virtual, efetuando a compra de um produto. Conforme exemplo abaixo.
Siga o fluxo abaixo para realizar os testes necessários para a homologação, atente-se para informações que deverão ser cadastradas no seu ERP e após isso exportados para o Admin da Climba Commerce (Exemplo: marcas, categorias,produtos).
15. Processo de Implantação no cliente
A implantação da integração no cliente em produção só poderá ser realizada após o término da homologação, ou seja, quando enviarmos um e-mail informando que a integração está homologada e apta a implantar no cliente.
Para realizar a implantação em produção, nosso suporte irá enviar um e-mail para vocês com os dados para efetuar as configurações em nosso cliente em comum.
16. Ferramenta para validação do objeto
Antes de iniciar o desenvolvimento, você poderá utilizar uma ferramenta para validação do objeto, indicamos utilizar a ferramenta Insomnia ela pode ser encontrada em https://insomnia.rest/download/#windows, ela poderá simular todos as requisições que nossa API disponibiliza e os possíveis retornos.
Exemplo: Para inserir um POST de produto, crie uma requisição do tipo POST e preencha as informações de header com os dados de chave e token que recebeu da nossa equipe de desenvolvimento. Conforme imagens abaixo:
https://nomedoerp.api.climbaapp.com.br/api/v1/products
Utilize a opção JSON:
Insira a estrutura do objeto e clique em Send para validar as informações. Na área de Preview, você terá os retornos com as validações necessárias a serem efetuadas, ou mensagem de enviado com sucesso.
17. Glossário
Método | Descrição |
Order | Cabeçalho do pedido |
OrderItem | Itens do pedido |
Category | Categorias do produto |
Brand | Marca do produto |
AttributeGroup | Grupo do atributo |
Attribute | Atributos que estão ligados a um grupo de atributo |
customerDocument | Documentos do cliente do pedido |
customerPhone | Telefone do cliente do pedido |
Customer | Dados do cliente do pedido |
externalMarketplaceOrder | Informações do pedido no Marketplace Externo |
generateOrderNumber | Informações do código de pedido gerado para salvar no banco de dados |
orderDelivery | Informações da entrega do pedido |
orderInvoice | Informações da Nota Fiscal do pedido |
sourceOrder | Informações da origem do pedido |
orderStatus | Informações do Status do Pedido |
orderTracking | Informações do Envio do Pedido |
paymentMethod | Informações da forma de pagamento |
payment | Informações da forma de pagamento escolhida pelo consumidor |
priceList | Informações da lista de preço do produto |
productPicture | Informações das imagens cadastradas em determinado produto |
product | Informações do produto |
productVariantPrice | Informações dos preços das variações do produto |
productVariant | Informações das variações de estoque do produto |
productVideo | Vídeos dos produtos |
receiverAddress | Informações do endereço de entrega do pedido |
shippingAddress | Informações do endereço de cobrança do pedido |
shippingMethod | Informações da forma de envio |
shipping | Informações da forma de envio escolhida pelo consumidor |
generateOrderNumber | Código do Pedido gerado que ainda não está salvo no banco de dados. |