Clique Retire - Manual de Integração Básica (1.1.6)

Download OpenAPI specification:Download

Introdução

O objetivo dessa documentação é apresentar de maneira rápida e objetiva como desenvolver uma integração com a Clique Retire. Os serviços disponíveis em nossa API estão exibidos no menu a abaixo e descrição de cada parâmetro assim como exemplos de uso estão disponiveís internamente em cada item, ao abrir o schema correspondente.

Está API utiliza requisições HTTP GET, POST, DELETE e o formato JSON para transferência de dados.

Guia Rápido

Este diagrama mostra os pontos básicos de integração com a nossa API. Com essas integrações prontas, seu sistema já estará pronto para operar com a Clique Retire.

alt text

Autenticação

Header:

Param Value Description
Content-Type application/json
api-id {{api-id}} Credencial obtida através do suporte da Clique Retire.
api-key {{api-key}} Credencial obtida através do suporte da Clique Retire.

Códigos globais de erros

System Level Error Code :

Code Description
200 Success
400 Parameter error
401 userToken expired or Invalid
403 User does not have permission
404 Resource not found
409 Conflict or already exists
500 Server error

Pedidos

Cria pedido de Retirada

Realiza a criação de um pedido a ser armazenado no locker por um operador e retirado pelo cliente final.

header Parameters
Content-Type
required
any
Example: application/json
api-id
required
any
Example: {{api-id}}
api-key
required
any
Example: {{api-key}}
Request Body schema: application/json
required
orderNumber
string

Identificador do pedido do embarcador

boxCode
required
string

Parâmetro orderNo do locker

urlCallback
string

Url para qual o webhook irá disparar eventos relacionados ao pedido

required
object

Dados do destinatário do pedido

required
Array of objects

Dados dos volumes que fazem parte do pedido

Responses

Request samples

Content type
application/json
{
  • "orderNumber": "ID0026",
  • "boxCode": "CB0001",
  • "urlCallback": "https://urlcallback.com.br",
  • "endCustomer": {
    },
  • "volumes": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "ad8012d0-099d-11ec-9607-a5aef51d19fe",
  • "volumes": [
    ]
}

Lista pedidos

É a API utilizada para listagem de pedidos, recebe como paramêtros de consulta api-key e api-id. A resposta é um JSON Array, contendo os pedidos existentes.

query Parameters
maxCount
any
Example: maxCount=10

Quantidade máxima de registros a serem retornados

fromUpdatedAt
any
Example: fromUpdatedAt=2019-10-08T21:00:53.969Z

Data de início da consulta

toUpdatedAt
any
Example: toUpdatedAt=2019-10-08T21:00:53.969Z

Data de fim da consulta

status
any
Example: status=STORED

Status do pedido

boxCode
any
Example: boxCode=CR0001

Código do Locker

lastItem
any
Example: lastItem=8a7ee4856d0299c8016dad2cbf4710b3

Obter pedidos após o último item, utilizado para paginação de resultados

header Parameters
Content-Type
required
any
Example: application/json
api-id
required
any
Example: {{api-id}}
api-key
required
any
Example: {{api-key}}

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Informações do pedido

Esta é a API utilizada para consultar informações de um pedido feito. Ela recebe como pareametros a api-key, api-id e o orderId(Id do pedido que deseja consultar).

path Parameters
orderId
required
any

Id do Pedido

header Parameters
Content-Type
required
any
Example: application/json
api-id
required
any
Example: {{api-id}}
api-key
required
any
Example: {{api-key}}

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Informações do Pedido pelo Código de Barras

Obtem ainformações do Pedido pelo código de barras (expressNumber)

Responses Body Parameters

Field Tpe Description
id string Id do volume
expressNumber string Código de barras do pedido
orderNumber string Número do pedido associado ao pedido
expressType string Tipo de envio
logisticsCompany Object Informações do operador logístico
storeUser Object Usuário que realizou a armazenagem do volume
takeUser Object Usuário que realizou a retirada do volume
box Object Informações relacionadas ao Locker
endCustomer Object Informações do cliente que irá retirar o pedido
acessCode string Pin code para retirada do volume
storeTime Datetime Data/Hora do armnazenamento
takeTime Datetime Data/Hora que o usuário retirou o pedido
overdueTime Datetime Data/Hora expiração do pedido
shortLink Object Informações do QRCode para retirada do pedido
status string Status do pedido (o mesmo que expressStatus)
lastModifiedTime timestamp Data/hora última modificação
createTime timestamp Data/Hora Criação do pedido
importUser Object Usuário que inseriu o pedido o sistema

ExpressType

Code Description
DELIVERY Pedido armazenado pelo operador logístico
SEND Pedido enviado por um usuário
RETURN Pedido rejeitado pelo usuário (retorno)

Tipos de status

Field Description
CREATED Pedido criado no sistema
STORED Pedido armazenado no locker
CUSTOMER_COLLECTED Pedido coletado pelo cliente
COURIER_COLLECTED Pedido coletado pelo operador
CANCELED Pedido cancelado
path Parameters
expressNumber
required
any

expressNumber (código de barras do volume)

header Parameters
Content-Type
required
any
Example: application/json
api-id
required
any
Example: {{api-id}}
api-key
required
any
Example: {{api-key}}

Responses

Response samples

Content type
application/json
{
  • "id": "4e2cfadf-3502-448a-9034-ee382bd251a4",
  • "expressNumber": "100325431",
  • "orderNumber": "321456",
  • "status": "CREATED",
  • "lastModifiedTime": 1611781505138,
  • "expressType": "Delivery",
  • "accessCode": null,
  • "shortLink": "",
  • "storeUser": null,
  • "box": {
    },
  • "endCustomer": {
    },
  • "storeTime": null,
  • "takeTime": null,
  • "overdueTime": null,
  • "createTime": 1611781505000,
  • "logisticsCompany": {
    },
  • "importUser": {
    },
  • "overdueFlag": false,
  • "additionalTrackingNumber": null,
  • "groupName": "54153210-60e3-11eb-b0a2-331cbec28b4f"
}

Cria pedido de Reversa

Realiza a criação de um pedido a ser devolvido no locker pelo cliente e retirado pelo operador para devolvido a loja.

header Parameters
Content-Type
required
any
Example: application/json
api-id
required
any
Example: {{api-id}}
api-key
required
any
Example: {{api-key}}
Request Body schema: application/json
required
orderNumber
string

Identificador do pedido do embarcador

boxCode
required
string

Parâmetro orderNo do locker

urlCallback
string

Url para qual o webhook irá disparar eventos relacionados ao pedido

required
object

Dados do destinatário do pedido

required
Array of objects

Dados dos volumes que fazem parte do pedido

Responses

Request samples

Content type
application/json
{
  • "orderNumber": "ID0026",
  • "boxCode": "CB0001",
  • "urlCallback": "https://urlcallback.com.br",
  • "endCustomer": {
    },
  • "volumes": [
    ]
}

Cria pedido de Home Delivery

Realiza a criação de um pedido a ser enviado ao endereço do cliente.

header Parameters
Content-Type
required
any
Example: application/json
api-id
required
any
Example: {{api-id}}
api-key
required
any
Example: {{api-key}}
Request Body schema: application/json
required
orderNumber
required
string

Identificador do pedido do embarcador

urlCallback
string

Url para qual o webhook irá disparar eventos relacionados ao pedido

required
object

Dados do destinatário do pedido

required
Array of objects

Dados dos volumes que fazem parte do pedido

Responses

Request samples

Content type
application/json
{
  • "orderNumber": "ID9999",
  • "urlCallback": "https://urlcallback.com.br",
  • "endCustomer": {
    },
  • "volumes": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "ad8012d0-099d-11ec-9607-a5aef51d19fe",
  • "volumes": [
    ]
}

Deletar Pedido

API para deletar um pedido

header Parameters
Content-Type
required
any
Example: application/json
api-id
required
any
Example: {{api-id}}
api-key
required
any
Example: {{api-key}}
Request Body schema: application/json
required
Id
string

Id do Pedido

Responses

Request samples

Content type
application/json
{
  • "Id": "string"
}

Lockers

Verificar compatibilidade de volumes com Locker

Essa consulta pode ser utilizada pelo embarcador no momento em que os produtos estão no carrinho de compras para verificação da compatibilidade entre o tamanho dos pacotes e o tamanho suportado pelos compartimentos do Locker para receber o produto. Pode ser utilizada também no momento do Agrupamento por Volumes realizado pelo centro de distribuição do embarcador ou pelo Operador Logístico dependendo do processo. Como resposta, a API envia um JSONArray com as informações do volume e os lockers compatíveis com ele.

Response Body Parameters:

Field Type Description
volumes JSONArray Volumes que foram enviados para consulta

Volumes

Field Type Description
ref_id string Id para Referência do volume no sistema do embarcador
compatible Boolean Volume compativel ou não com o locker
lockers JSONArray Compartimentos disponíveis no locker para receber o volume

Lockers

Field Type Description
type string Tipo do compartimento compativel
width decimal Largura do compartimento do locker em centímetros
heigth decimal Altura do compartimento do locker em centímetros
depth decimal Profundidade do compartimento do locker em centímetros
price decimal Preço da diária do compartimento
enable int Número de compartimentos disponíveis no locker no momento
used int Número de compartimentos usados no locker no momento
header Parameters
Content-Type
required
any
Example: application/json
api-id
required
any
Example: {{api-id}}
api-key
required
any
Example: {{api-key}}
Request Body schema: application/json
required
boxCode
required
string

Código individual do locker

required
Array of objects

Volumes que deseja consultar compatibilidade com o locker

Responses

Request samples

Content type
application/json
{
  • "boxCode": "CR0001",
  • "volumes": [
    ]
}

Response samples

Content type
application/json
{
  • "volumes": [
    ]
}

Listar Pontos / Lockers Disponíveis

Esta é a API pública para consulta dos e-Box disponíveis na rede Clique Retire. Essa consulta retorna um JSON com as informações dos lockers mais próximos ao CEP consultado.

query Parameters
orderNo
any
Example: orderNo=CR0001
cep
any
Example: cep=03169-010
header Parameters
Content-Type
required
any
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "maxCount": 10000,
  • "totalPage": 1,
  • "page": 0,
  • "resultList": [
    ]
}

Exportar CSV

API pública para consulta dos e-Box disponíveis na rede Clique Retire.

query Parameters
orderNo
any
Example: orderNo=CR0001
cep
any
Example: cep=03169-010
header Parameters
Content-Type
required
any
Example: application/json

Responses

Response samples

Content type
application/json
{
  • "maxCount": 100,
  • "page": 0,
  • "resultList": [
    ],
  • "totalCount": 46,
  • "totalPage": 0
}

Webhook

Webhook send

O webhook é o método utilizado para atualizar o status do volume dentro do ciclo logistíco da Clique Retire, disparando eventos que contém o status do volume postado.

# Entrega - eventos Descrição
01 CREATED Pacote criado no sistema
02 FOR_MERCHANT_STORE_IN_BOUND Pacote no centro de distribuição Clique Retire
03 FOR_MERCHANT_STORE_IN_TRANSIT_TO_STORE Pacote em trânsito para o Locker
04 FOR_MERCHANT_STORE_IN_STORE Pacote armazenado no Locker
05 FOR_MERCHANT_STORE_CUSTOMER_TAKEN Pacote coletado pelo usuário
06 FOR_MERCHANT_STORE_IN_STORE_UPCOMING_EXPIRED Pacote próximo da expiração no Locker
07 FOR_MERCHANT_STORE_IN_STORE_EXPIRED Pacote expirado no Locker
08 FOR_MERCHANT_STORE_COURIER_TAKEN Pacote expirado coletado pelo operador
09 FOR_MERCHANT_STORE_EXPIRED_IN_BOUND Pacote expirado no XD Clique Retire
10 FOR_MERCHANT_STORE_RETURNED Pacote expirado devolvido ao embarcador
11 FOR_MERCHANT_STORE_RESEND_CODE QRCode/PINCode reenviado
# Devolução - eventos Descrição
01 CREATED Pacote criado
02 FOR_CUSTOMER_STORE_IN_STORE Pacote inserido pelo usuário no Locker
03 FOR_CUSTOMER_STORE_COURIER_TAKEN Pacote reversa coletado pelo operador
04 FOR_CUSTOMER_STORE_IN_BOUND Pacote no centro de distribuição Clique Retire
05 FOR_CUSTOMER_STORE_RETURNED Pacote reversa devolvido ao embarcador
# Home delivery - eventos Descrição
01 CREATED Pacote criado
02 FOR_SEND_ORDER_INBOUND Pacote no XD Clique Retire
03 FOR_MERCHANT_CUSTOMER_TAKEN Pacote entregue ao destinatário
04 FOR_OTHER_EVENT Outros
05 FOR_MERCHANT_MISSPLACEMENT Extravio
06 FOR_MERCHANT_DAMAGED Avaria
07 FOR_DESTINATION_CLOSED Local fechado
08 FOR_DELIVERY_CANCELED Entrega cancelada
09 FOR_MERCHANT_MISSMATCHING Mercadoria em desacordo
10 FOR_DESTINATION_NOT_FOUND Endereço não encontrado
11 FOR_DELIVERY_REFUSED Cliente recursou a entrega
12 FOR_SEND_ORDER_OUTBOUND Mercadoria expedida da filial
13 FOR_SEND_WAITING_CONSOLIDATION Aguardando consolidação
14 FOR_SEND_NATURAL_CASES Causas naturais
15 FOR_SEND_CONFRONTATION Acareação
16 FOR_MERCHANT_IN_TRANSIT_TO_DESTINATION Saiu para entrega
17 FOR_SEND_ORDER_LAST_INBOUND Chegada na filial de destino
18 FOR_SEND_TAX_ISSUES Problemas fiscais
19 FOR_SEND_INVOICE_RETAINED Nota retida pela fiscalização
20 FOR_SEND_ROAD_CLOSED Estrada interditada
21 FOR_SEND_BROKEN_VEHICLE Quebra do veículo
22 FOR_SEND_ORDER_NOT_SHIPPED Mercadoria não embarcada
23 FOR_SEND_NATIONAL_STRIKE Greve nacional
24 FOR_SEND_CUSTOMER_ABSENT Cliente ausente
25 FOR_SEND_ORDER_STOLED Roubo de carga
26 FOR_SEND_TIME_DELIVERY_FAIL Entrega prejudicada por falta de tempo hábil
27 FOR_SEND_REDELIVERY_REQUESTED Reentrega solicitada
header Parameters
Content-Type
required
any
Example: application/json
Request Body schema: application/json
required
event
string

Evento disparado sobre o status do volume, conforme a tabela de status

expressNumber
string

Código da etiqueta

eventimeTime
timestamp

Horário que o evento é disparado

message
string

Mensagem que descreve o evento, conforme a tabela de status

orderId
string

Id do pedido

accessCode
string

Pin de retirada

shortLink
string

Link para o qrcode de retirada

Responses

Request samples

Content type
application/json
{
  • "event": "{{status}",
  • "expressNumber": "{{expressNumber}}",
  • "eventimeTime": "2021-03-25T17:38:15-03:00",
  • "message": "{{message}}",
  • "orderId": "{{referenceNumber}}",
  • "accessCode": "accessCode",
  • "shortLink": "shortLink"
}