Descobrindo se uma compra deve receber frete grátis ou não

Descobrindo se uma compra deve receber frete grátis ou não

É possível descobrir se um determinado cliente precisa receber frete grátis ou não para que não abandone o carrinho. É assim que a FREEP ajuda sua empresa a economizar com as políticas de frete grátis.
A FREEP disponibiliza essa consulta através de uma api REST. O endpoint /v1/free retorna true/false informando se essa compra deve receber frete grátis ou não. Especificação da API aqui.

A FREEP entra como um passo adicional em seu carrinho ou PDP

Um processo de integração simplificado possui apenas 2 ou 3 etapas:

• 1 - Efetuar um post no /v1/free para saber se é para oferecer frete grátis ou não
• 2 - Atualizar o id do pedido (x_order_id) quando este for conhecido
• 3 - Atualizar o status final do pedido (em uma janela de até 30 dias)

Autenticação

É necessário uma chave de api para utilizar a freep. A chave de api é informada no header de todas as requisições no campo x-api-key. Entre em contato para efetuar seu cadastro e receber a chave de api.

Passo 1 - POST no /v1/free

Envie o máximo de informações sobre a compra e sobre o histórico do consumidor que tiver.
Mais informações tornam a resposta mais assertiva.

Field	Description	Required	Format
delivery_zip	delivery ZIP code (CEP)	YES (either delivery_zip or document)	String numeric [0-9]
document	Document number (CPF)	YES (either delivery_zip or document)	String numeric [0-9]
birth_date	customer's birth date	NO	YYYY-MM-DD ISO 8601
shipping_price	shipping price of this cart	NO	numeric DDDDDDD.DD (2 decimals) [0-9.]
cart_price	total cart price	NO	numeric DDDDDDD.DD (2 decimals) [0-9.]
count_purchases	Times this customer bought in this store	NO	integer [0-9]
count_free_abandonment	Times this customer abandoned a free shipping cart	NO	integer [0-9]
count_total_abandonment	Times this customer abandoned the cart (total)	NO	integer [0-9]
count_free_cart	Times this customer received a free shipping cart	NO	integer [0-9]
x_session_id	your session id for this purchase	YES	String (255 chars) [0-9-.A-Z]
x_order_id	The order id for this purchase (set when known)	NO	String (255 chars) [0-9-.A-Z]
cart_items	Array of cart items (name: string, sku: string, price:number, shipping_price: number)	NO	JSON Object "cart_items": [ { "name": "string", "sku": "string", "price": 0, "shipping_price": 0 } ]

A resposta da API é sempre um JSON. Nesse caso, contendo o free_shipping (true/false) e o x_session_id informado anteriormente.

Passo 2 - PUT no /v1/free/session

Atualize o número do pedido (x_order_id) quando conhecer ele. É comum que lojas de ecommerce apenas gerem o código do pedido quando o cliente finaliza a compra. O passo 2 é opcional. É possível informar o x_order_id na primeira requisição, se já souber.

Field	Description	Required	Format
x_session_id	your session id for this purchase	YES	String (255 chars) [0-9-.A-Z]
order_success	final state of the purshade (paid/success or not)	YES	true/false
x_order_id	The order id for this purchase	NO	String (255 chars) [0-9-.A-Z]

A resposta da API é sempre um JSON. Nesse caso, contendo apenas um "OK".

Passo 3 - PUT no /v1/free/order

Atualize o status do pedido (se a compra foi aprovada ou não). Perceba que é possível informar o status final (order_success) tanto no passo 2 quanto no passo 3, tornando um deles opcional.

Field	Description	Required	Format
order_success	final state of the purshade (paid/success or not)	YES	true/false
x_order_id	The order id for this purchase	YES	String (255 chars) [0-9-.A-Z]

A resposta da API é sempre um JSON. Nesse caso, contendo apenas um "OK".

Limites padrões da API

• Tamanho das strings: 255 caracteres (se os limites forem ultrapassados, sua string será truncada.)
• Rate: 30 requests per second
• Quota: 50000 requests per day
• Alterações sob consulta em tools@freep.com.br

Todos os tipos de resposta da API

HTTP Status code	Description	Info
200 OK	Success	Expect a JSON data with the message detail (usually just OK)
201 created	Session created	expect a JSON data with the response
403 Forbidden	Autentication Error. The response includes a JSON { "message": "Forbidden" }	Check the access token you received and check if you are sending it in the x_api_key on the header
400 Bad Request	{ "message": "Can't change delivery_zip for this x_session_id" }	In this case, you cannot modify a previous delivery_zip or document using this x_session_id. Create a new session.
400 Bad Request	{ "message": "invalid JSON body" }	The JSON you sent is not valid.
500 Internal Server Error	{ "message": "ERROR LOADING DATA" }	Check if you have valid document (CPF), delivery_zip(CEP). Check the datatype and string size
502 Bad Gateway	Includes a generic error message. { "message": "Internal server error" }	Check the size of your payload and data type. Suspicious characters also may cause this. If persists, contact tools@freep.com.br