Documentao One Click Buy

Manuais de integrao

Contedo
1

Protocolo bsico ...................................2

1.1

APIs RESTfull .................................................................................................................. 2

1.2

URL Base ......................................................................................................................... 2

1.3

Mensagens JSON ............................................................................................................ 2

1.4

Headers ............................................................................................................................ 2

1.5
1.5.1
1.5.2
1.5.3
1.5.4

Status retornados ............................................................................................................ 2

Retornos de sucesso ......................................................................................................... 3
Retorno em caso de falha.................................................................................................. 3
Exemplo de retorno com falha. HTTP Status Code 400 .................................................... 3
Exemplo de retorno com falha. HTTP Status Code 500 .................................................... 4

APIs de carrinhos ..................................5

2.1

Criao de carrinho ......................................................................................................... 5

2.2

Adio de item a carrinho ............................................................................................... 6

2.3

Dados de um carrinho ..................................................................................................... 6

2.4

Clculo de frete ............................................................................................................... 7

APIs de servios ...................................9

3.1

Verificao de comprador ............................................................................................... 9

3.2

Criao de comprador..................................................................................................... 9

3.3

Criao de pedido ......................................................................................................... 10

3.4

Cancelamento de pedido .............................................................................................. 11

3.5

Dados de pedido............................................................................................................ 11

APIs de listagem de produtos ......................13

4.1

Hierarquia de um produto ............................................................................................. 13

DOCUMENTAO - OCB

Manuais de integrao

1
1.1

PROTOCOLO BSICO
APIs RESTfull

Descrevemos aqui as diretrizes bsicas para comunicao com as APIs RESTfull do Bcash.
Explicamos quais so as informaes necessrias nos headers das chamadas, quais os retornos
esperados e qual o padro para a troca de mensagens.

1.2

URL Base

Para simplificar a descrio das chamadas RESTful nas demais sees do manual de integrao
usaremos a seguinte conveno:
URL_BASE = http[s]://${SEU_DOMINIO}/${SUA_RAIZ}/lojas/${ID_LOJA}
Ex.:
GET ${URL_BASE}/estoque/produtos/23423-234-38

1.3

Mensagens JSON

O formato das mensagens usado nessas APIs o JSON.

1.4

Headers

Para cada chamada de servio deve-se informar os headers de tipo de contedo e autorizao.
"Content-Type": "application/json"
"Authorization": "Basic " + Base64Encode(login + ":" senha)

1.5

Status retornados

Esta seo lista os status de retorno HTTP que sero devolvidos quando o servio for invocado.

DOCUMENTAO - OCB

Manuais de integrao

1.6

Retornos de sucesso

HTTP Code: 200 - Um Get com retorno ok.

HTTP Code: 201 - Retorno de um POST de sucesso onde um recurso foi criado.

HTTP Code: 204 - Um PUT ou DELETE finalizado com sucesso.

1.7

Retorno em caso de falha

HTTP Code: 400 - Requisio mal formada, dados invlidos. Erro de regra de negcio.

HTTP Code: 401 - Erro de autorizao, dados de autorizao invlidos.

HTTP Code: 404 - Recurso no encontrado, erro na descrio do caminho do recurso.

HTTP Code: 500 - Exceo do servidor, erro fatal da aplicao.

1.8

Exemplo de retorno com falha. HTTP

Status Code 400

Tabelle 1 Response: HTTP Code 400

[
{
"codigo": "MSG_00001",
"descricao": "O comprador informado no existe."
},
{
"codigo": "MSG_00002",
"descricao": "Formato de telefone invlido."
}
]

DOCUMENTAO - OCB

Manuais de integrao

1.9

Exemplo de retorno com falha. HTTP

Status Code 500

Tabelle 2 Response: HTTP Code 500

[
{
"codigo": "MSG_10001",
"descricao": "Time out ao salvar recurso."
}
]

DOCUMENTAO - OCB

Manuais de integrao

APIS DE CARRINHOS

Usados para agregar produtos para clculo de frete e reserva de pedidos.

2.1

Criao de carrinho

Cria um novo carrinho com a lista de produtos informados. A lista pode conter um, nenhum ou
vrios produtos com suas respectivas quantidades.
POST ${URL_BASE}/logistica/carrinhos
Tabelle 3 Request:

{
"itens": [
{
"produto": {
"sku": "23423-235-39"
},
"quantidade": 2
}
]
}

Tabelle 4 Response: HTTP Code 201

{
"id": "WQERWE23655",
"itens": [
{
"id": "1"
}
]
}

DOCUMENTAO - OCB

Manuais de integrao

2.2

Adio de item a carrinho

Permite inserir outros itens com produtos a um carrinho existente.

POST ${URL_BASE}/logistica/carrinhos/WQERWE23655/itens
Tabelle 5 Request:

{
"produto": {
"sku": "23423-235-38"
},
"quantidade": 3
}

Tabelle 6 Response: HTTP Code 201

{
"id": "2"
}

2.3

Dados de um carrinho

Retorna o contedo de um carrinho.

GET ${URL_BASE}/logistica/carrinhos/WQERWE23655
Tabelle 7 Response: HTTP Code 200

{
"id": "WQERWE23655",
"itens": [
{
"produto": {
"sku": "23423-235-39"
},
"quantidade": 2
}
]
}

DOCUMENTAO - OCB

Manuais de integrao

2.4

Clculo de frete

Calcula os fretes por tipo de servio para o envio de todos os produtos do carrinho ao cep
informado.
GET ${URL_BASE}/logistica/carrinhos/WQERWE23655/calcula-frete?cepDestino=76582-906
Tabelle 8 Response: HTTP Code 200

[
{
"preco": 23.30,
"servico": {
"codigo": "SEDEX"
},
"prazo": {
"minimo": 2,
"maximo": 4,
"unidade": "DIAS"
}
},
{
"preco": 12.00,
"servico": {
"codigo": "PAC"
},
"prazo": {
"minimo": 5,
"maximo": 12,
"unidade": "DIAS"
}
},
{
"preco": 5.20,
"servico": {
"codigo": "Jamef"
},
"prazo": {
"maximo": 10,
"unidade": "DIAS"
}
},
{
"preco": 15.00,
"servico": {
"codigo": "Motoboy",
"descricao": "Apenas grande So Paulo para pedidos aprovados
antes do meio dia"

DOCUMENTAO - OCB

Manuais de integrao
},
"prazo": {
"maximo": 10,
"unidade": "HORAS"
}
}
]

DOCUMENTAO - OCB

Manuais de integrao

APIS DE SERVIOS

Usados para reservar produtos para um comprador at o pagamento ser efetuado.

3.1

Verificao de comprador

Retorna informaes de um comprador quando existir. O identificador do comprador um texto

que pode ser o seu CPF, CNPJ, email.
GET ${URL_BASE}/logistica/compradores/22092430840
Tabelle 9 Response: HTTP Code 200

{
"identificador": "64221571691",
"tipoIdentificador": "CPF",
"nome": "Antnio da Silva",
"email": "comprador@bcash.com.br",
"telefone": "11-978979689",
"endereco": {
"cep": "03422-002",
"logradouro": "Av. Paulista",
"numero": "2211",
"complemento": "ap 45",
"bairro": "Jardim Paulista",
"cidade": "So Paulo",
"uf": "SP"
}
}

3.2

Criao de comprador

Registra os dados de um comprador para ser usado posteriormente em uma reserva de pedido. Se
o registro do comprador j existe, sobrescreve as informaes.
POST ${URL_BASE}/logistica/compradores

DOCUMENTAO - OCB

Manuais de integrao
Tabelle 10 Request:

{
"identificador": "64221571691",
"tipoIdentificador": "CPF",
"nome": "Antnio da Silva",
"email": "comprador@bcash.com.br",
"telefone": "11-978979689",
"endereco": {
"cep": "03422-002",
"logradouro": "Av. Paulista",
"numero": "2211",
"complemento": "ap 45",
"bairro": "Jardim Paulista",
"cidade": "So Paulo",
"uf": "SP"
}
}

Tabelle 11 Response: HTTP Code 201

{
"identificador": "22092430840"
}

3.3

Criao de pedido

Cria um novo pedido usando um comprador e um carrinho. Este pedido deve reservar os produtos
para o comprador at que o pagamento seja feito. Se o pagamento no for feito o pedido deve ser
cancelado e os produtos do carrinho liberados para o estoque novamente.
POST ${URL_BASE}/logistica/pedidos
Tabelle 12 Request:

{
"comprador": {
"identificador": "22092430840"
},
"carrinho": {
"id": "WQERWE23655"
}

DOCUMENTAO - OCB

10

Manuais de integrao
}

Tabelle 13 Response: HTTP Code 201

{
"id": "76234673SDFG",
"comprador": {
"identificador": "22092430840"
},
"carrinho": {
"id": "WQERWE23655"
},
"status": "CRIADO"
}

3.4

Cancelamento de pedido

Usado quando o pagamento no puder ser realizado para liberar os produtos para o estoque da
loja.
PUT ${URL_BASE}/logistica/pedidos/76234673SDFG/cancela
Tabelle 14 Response: HTTP Code 204

/*vazio*/

3.5

Dados de pedido

Usado para retornar as informaes do pedido.

GET ${URL_BASE}/logistica/pedidos/76234673SDFG
Tabelle 15 Response: HTTP Code 200

{
"id": "76234673SDFG",
"comprador": {
"identificador": "22092430840"

DOCUMENTAO - OCB

11

Manuais de integrao
},
"carrinho": {
"id": "WQERWE23655"
},
"status": "EM_TRANSPORTE"
}

DOCUMENTAO - OCB

12

Manuais de integrao

APIS DE LISTAGEM DE
PRODUTOS

Servios usados para interagir com os produtos da loja.

4.1

Hierarquia de um produto

Dado um SKU de produto retorna a hierarquia de produtos relacionados. O SKU informado pode
ser qualquer um presente na hierarquia retornada. O exemplo abaixo mostra uma hierarquia
complexa de sub-produtos baseados em variaes de cor e tamanho.
GET ${URL_BASE}/estoque/produtos/23423-235-39/hierarquia
Tabelle 16 Response: HTTP Code 200

{
"sku": "23423",
"preco": 540.20,
"descricao": {
"simples": "Tnis Mizuno Wave Creation 15",
"texto": "Desenhado com um olhar crtico para ..."
},
"caracteristica": {
"nome": "cor",
"produtosRelacionados": [
{
"sku": "23423-234",
"descricao": {
"simples": "Branco",
"completa": "Tnis Mizuno Wave Creation 15 branco"
},
"urlsImagem": [
"http://.../mizuno-branco-frente.jpg",
"http://.../mizuno-branco-lado.jpg"
],
"disponivel": true,
"caracteristica": {
"nome": "tamanho",
"produtosRelacionados": [
{
"sku": "23423-234-38",

DOCUMENTAO - OCB

13

Manuais de integrao
"descricao": {
"simples": "38"
},
"disponivel": true
},
{
"sku": "23423-234-39",
"descricao": {
"simples": "39"
},
"disponivel": false
},
{
"sku": "23423-234-40",
"descricao": {
"simples": "40"
},
"disponivel": true
}
]
}
},
{
"sku": "23423-235",
"descricao": {
"simples": "Preto",
"completa": "Tnis Mizuno Wave Creation 15 preto"
},
"urlsImagem": [
"http://.../mizuno-preto-frente.jpg",
"http://.../mizuno-preto-lado.jpg"
],
"disponivel": true,
"caracteristica": {
"nome": "tamanho",
"produtosRelacionados": [
{
"sku": "23423-235-38",
"descricao": {
"simples": "38"
},
"disponivel": true
},
{
"sku": "23423-235-39",
"descricao": {
"simples": "39"
},

DOCUMENTAO - OCB

14

Manuais de integrao
"disponivel": true
},
{
"sku": "23423-235-40",
"descricao": {
"simples": "40"
},
"disponivel": false
}
]
}
}
]
}
}

DOCUMENTAO - OCB

15