NAV
shell javascript php java

Introdução

A API Yever foi cuidadosamente projetada seguindo os princípios e melhores práticas do padrão REST. Esta API permite a integração com diversas aplicações, independentemente da linguagem de programação utilizada, graças à sua abordagem simples e clara na manipulação de requisições e respostas.

As operações disponíveis são realizadas através de requisições aos endpoints correspondentes, utilizando os verbos HTTP apropriados e corpos de mensagem formatados em JSON. As respostas podem ser analisadas com base nos códigos de status HTTP fornecidos.

É importante ressaltar que não dispomos de um ambiente de homologação, uma vez que todos os endpoints utilizam o método GET. A URL base para todas as requisições é: https://api.yever.com.br/api/v1. A partir desta URL base, é possível acessar o endpoint desejado, como no exemplo a seguir: https://api.yever.com.br/api/v1/order/list, que consulta a lista de pedidos.

Esta documentação oferece informações detalhadas sobre como consultar dados via API e realizar integrações através de Webhooks. Ao longo da documentação, você encontrará descrições detalhadas dos endpoints disponíveis, bem como exemplos de requisições e respostas, para auxiliar no desenvolvimento de sua aplicação.

Autenticação

Exemplo para a rota de pedidos

curl 'https://api.yever.com.br/api/v1/order/list' \
  --header 'Authorization: Bearer 999|xxxxxxxxxxxxxx'

const options = {
  method: "GET",
  headers: {
    Accept: "application/json",
    Authorization: "Bearer 999|xxxxxxxxxxxxxx",
  },
};

fetch("https://api.yever.com.br/api/v1/order/list", options)
  .then((response) => response.json())
  .then((response) => console.log(response));

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request(
  'GET',
  'https://api.yever.com.br/api/v1/order/list',
  [
    'headers' => [
      'Accept' => 'application/json',
      'Authorization' => 'Bearer 999|xxxxxxxxxxxxxx',
    ],
  ],
);

$data = $response->getBody()->getContents();

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.yever.com.br/api/v1/order/list")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer 999|xxxxxxxxxxxxxx")
  .build();

Response response = client.newCall(request).execute();

Lembre-se de substituir 999|xxxxxxxxxxxxxx pelo token fornecido na Yever.

Todas as chamadas devem conter o seguinte Header: Authorization: Bearer 999|xxxxxxxxxxxxxx. O token deve ser gerado dentro do sistema Yever, no seguinte caminho: Configuração > API > Novo token. O formato do token será [0-9]+|[a-zA-z0-9]+, ou seja, um número, pipe (|) e uma string aleatória. O token só será exibido no momento da criação, não sendo possível visualizá-lo novamente.

Filtros e paginação

{
  "orders": [
    {},
    {},
    ...
  ],
  "paginate": {
    "current": 1,
    "last": 5,
    "total": 430,
    "per_page": 100
  }
}

Todos os filtros sempre serão via query parameters. Exemplo: https://api.yever.com.br/api/v1/order/list?created_at_inicial=2022-11-01&created_at_final=2022-12-10&payment_method=credit_card&per_page=50&page=5. Os filtros permitidos serão informados em cada endpoint. Se forem enviados outros filtros além dos permitidos na requisição a API apenas irá ignorá-los. Se existir algum filtro com valor incorreto, será retornado o status 422 e a mensagem de erro. Exemplo: payment_method precisa ser pix, billet ou credit_card.

O objeto paginate sempre estará presente em todas as respostas, independente dela ter apenas 1 registro. Ele sempre vem após os dados, no final da resposta.

O parâmetro per_page tem limite de 500, enquanto o page tem limite de 100. Ou seja, é possível obter até 50.000 registros por filtro. Caso necessite de mais registros, utilize os filtros por data e faça a quantidade de consultas necessárias. No exemplo a direita, você precisa fazer 5 consultas para pegar todos os dados (page=1,page=2,page=3,page=4,page=5). Se o parâmetro page não estiver presente, o valor 1 será considerado. Se o parâmetro per_page não estiver presente, o valor 100 será considerado.

Api

Pedidos

GET: https://api.yever.com.br/api/v1/order/list

curl 'https://api.yever.com.br/api/v1/order/list?created_at_inicial=2022-11-01&created_at_final=2023-01-01&per_page=200&page=1' \
  --header 'Authorization: Bearer 999|xxxxxxxxxxxxxx'

const options = {
  method: "GET",
  headers: {
    Accept: "application/json",
    Authorization: "Bearer 999|xxxxxxxxxxxxxx",
  },
};

fetch(
  "https://api.yever.com.br/api/v1/order/list?created_at_inicial=2022-11-01&created_at_final=2023-01-01&per_page=200&page=1",
  options
)
  .then((response) => response.json())
  .then((response) => console.log(response));

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request(
  'GET',
  'https://api.yever.com.br/api/v1/order/list?created_at_inicial=2022-11-01&created_at_final=2023-01-01&per_page=200&page=1',
  [
    'headers' => [
      'Accept' => 'application/json',
      'Authorization' => 'Bearer 999|xxxxxxxxxxxxxx',
    ],
  ],
);

$data = $response->getBody()->getContents();

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.yever.com.br/api/v1/order/list?created_at_inicial=2022-11-01&created_at_final=2023-01-01&per_page=200&page=1")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer 999|xxxxxxxxxxxxxx")
  .build();

Response response = client.newCall(request).execute();

A resposta da requisição acima será um json no seguinte formato

{
  "orders": [
    {
      "reference": "1234567890", // [0-9]{10}
      "customer": {
        "name": "Nome do cliente",
        "email": "email@email.com",
        "phone": "+5511999991111", // sempre 14 dígitos, +55 (código do brasil), 2 números do ddd e 9 do celular
        "type": "F", // F -> Pessoa Física, J -> Pessoa Jurídica
        "document": "92220244008" // \d{11}(\d{3})? - 11 ou 14 números
      },
      "status": "paid", // pending_payment, paid, refunded, charged_back, canceled
      "products": [ // produtos que de fato foram comprados
        {
          "product_id": 5732411797552, // id no ERP
          "product_title": "Exemplo de produto",
          "variant_id": 53012421484761,
          "variant_title": "Variante abc",
          "quantity": 3,
          "price": 33.15,
          "image_url": "https://images.yever.com.br/product/exemplodeimagem-1669936110.jpg",
          "is_order_bump": 0
        }
      ],
      "shipping_address": {
        "name": "Nome de quem vai receber",
        "phone": "+5511999991111", // sempre 14 dígitos, +55 (código do brasil), 2 números do ddd e 9 do celular
        "address1": "logradouro, numero",
        "address2": "Bairro",
        "city": "Cidade",
        "province_code": "MG",
        "country": "Brazil",
        "country_code": "BR",
        "zip": "11111111" // sempre 8 dígitos
      },
      "tracking": {
        "code": "código de rastreio", // qualquer formato, pode ser de alguma transportadora da china, correios, etc. Ex: NL501111803BR
        "courier": "transportadora" // nome da transportadora. Ex: Correios
      },
      "coupon_code": null, // código do cupom se tiver
      "currency": "BRL",
      "price_initial": 178.86, // valor inicial do pedido -> price_subtotal + price_shipment
      "price_subtotal": 168.40, // valor dos produtos
      "price_shipment": 10.46, // valor do frete
      "price_coupon_discount": 5.05, // desconto do cupom
      "price_shipment_discount": 10.46, // desconto do frete
      "price_offer_discount": 0, // desconto da oferta
      "price_payment_discount": 8.17, // desconto por forma de pagamento
      "price_total": 155.18, // valor final do pedido -> price_subtotal + price_shipment - price_coupon_discount - price_shipment_discount - price_offer_discount - price_payment_discount
      "price_client_final": 155.18, // valor da venda com juros de parcelamento - recebimento no fluxo ou só checkout
      "price_coupon": 0.00, // deprecated, do not use
      "price_discount": 0.00,  // deprecated, do not use
      "payment_method": "credit_card", // pix, billet, credit_card
      "billet_code": null, // linha digitável do boleto
      "billet_url": null, // url para acessar o boleto
      "pix_code": null, // pix copia e cola
      "pix_url": null, // url para imagem do pix
      "checkout_url": "https://seguro.client.com.br/checkout/products?product_id[0]=1&quantity[0]=1", // url para refazer a compra se necessário
      "payment_url": "https://seguro.client.com.br/checkout/pix/1234567890", // url para fazer o pagamento -> Apenas pix e boleto e os números são o reference
      "is_upsell": 0,
      "installments": 12, // sempre será 1 para pix e boleto
      "created_at": "2022-12-09 05:46:59",
      "updated_at": "2022-12-09 05:47:01",
      "utms": {
        "source": "face",
        "campaign": "promocao_blackfriday",
        "medium": null,
        "content": null,
        "term": null,
      },
      "price_client": {
        "client":  102.89, // valor recebido pelo cliente
        "yever_base": 6.56, // taxa da yever
        "installment_antecipation": 0, // valor pago por assumir parcelas sem juros
      }
    },
    {
      ...
    },
  ],
  "paginate": {
    "current": 1,
    "last": 3,
    "total": 475,
    "per_page": 200
  }
}

Possíveis filtros:

Parâmetro Valor padrão Obrigatório Exemplo Description
reference Não 1234567890 Código do pedido
customer Não Maria da C, 31999991111, exemploemail@h Nome, e-mail, telefone (apenas números, sem +55), ou cpf (apenas números). O filtro é do tipo like, ou seja, você pode enviar apenas uma parte do que deseja procurar
status Não paid pending_payment, paid, refunded, charged_back, canceled
payment_method Não credit_card billet, credit_card, pix
created_at_inicial Não 2022-10-01 15:00:00.
created_at_final Não 2022-10-01 19:00:00
updated_at_inicial Não 2023-01-01 Se o horário não for fornecido, será considerado 00:00:00
updated_at_final Não 2023-02-01
page 1 Não 1 Objeto de paginação. Se o resultado tiver mais de uma página, você deverá fazer uma requisição para cada página. Máximo 100 páginas
per_page 100 Não 25 Quantidade de itens por página. Máximo de 500 itens

Carrinho

GET: https://api.yever.com.br/api/v1/cart/list

curl 'https://api.yever.com.br/api/v1/cart/list?last_step=payment&order_status=canceled&per_page=10' \
  --header 'Authorization: Bearer 999|xxxxxxxxxxxxxx'

const options = {
  method: "GET",
  headers: {
    Accept: "application/json",
    Authorization: "Bearer 999|xxxxxxxxxxxxxx",
  },
};

fetch(
  "https://api.yever.com.br/api/v1/cart/list?last_step=payment&order_status=canceled&per_page=10",
  options
)
  .then((response) => response.json())
  .then((response) => console.log(response));

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request(
  'GET',
  'https://api.yever.com.br/api/v1/cart/list?last_step=payment&order_status=canceled&per_page=10',
  [
    'headers' => [
      'Accept' => 'application/json',
      'Authorization' => 'Bearer 999|xxxxxxxxxxxxxx',
    ],
  ],
);

$data = $response->getBody()->getContents();

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.yever.com.br/api/v1/cart/list?last_step=payment&order_status=canceled&per_page=10")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer 999|xxxxxxxxxxxxxx")
  .build();

Response response = client.newCall(request).execute();

A resposta da requisição acima será um json no seguinte formato

{
  "carts": [
    {
      "reference": "41413750-c68f-46f0-ae42-a8f3ad9e4859", // 36 char, nesse formato
      "customer": {
        "name": "Nome do cliente",
        "email": "email@email.com",
        "phone": "+5511999991111" // sempre 14 dígitos, +55 (código do brasil), 2 números do ddd e 9 do celular
      },
      "last_step": "payment", // client, delivery, shipment, payment. Até qual step o cliente chegou
      "order_status": "canceled", // null se não tiver sido gerado um pedido, pending_payment, paid, refunded, charged_back, canceled
      "products": [ // produtos iniciais quando o cliente entrou na tela
        {
          "product_title": "Exemplo de produto",
          "variant_title": "Variante abc",
          "quantity": 2,
          "price": 47.91, // preço unitário
          "image_url": "https://images.yever.com.br/product/exemplodeimagem-1669936110.jpg",
        }
      ],
      "currency": "BRL",
      "price_total": 95.82,
      "checkout_url": "https://seguro.yever.com.br/checkout/products?product_id[0]=1&quantity[0]=2",
      "created_at": "2022-12-02 06:59:17",
      "updated_at": "2022-12-02 07:00:27",
      "abandoned_at":"2022-12-02 07:05:00",
      "utms": {
        "source": "face",
        "campaign": "promocao_blackfriday",
        "medium": null,
        "content": null,
        "term": null,
      },
    },
    {
      ...
    }
  ],
  "paginate": {
    "current": 1,
    "last": 4,
    "total": 36,
    "per_page": 10
  }
}

Possíveis filtros:

Parâmetro Valor padrão Obrigatório Exemplo Description
reference Não 41413750-c68f-46f0-ae42-a8f3ad9e4859 uuid do cliente pedido. 36 dígitos
customer Não Maria da C, 31999991111, exemploemail@h Nome, e-mail, telefone (apenas números, sem +55), ou cpf (apenas números). O filtro é do tipo like, ou seja, você pode enviar apenas uma parte do que deseja procurar
last_step Não payment client, delivery, shipment, payment
order_status Não paid pending_payment, paid, refunded, charged_back, canceled
created_at_inicial Não 2022-10-01 15:00:00.
created_at_final Não 2022-10-01 19:00:00
updated_at_inicial Não 2023-01-01 Se o horário não for fornecido, será considerado 00:00:00
updated_at_final Não 2023-02-01
page 1 Não 5 Objeto de paginação. Se o resultado tiver mais de uma página, você deverá fazer uma requisição para cada página. Máximo 100 páginas
per_page 100 Não 500 Quantidade de itens por página. Máximo de 500 itens

Exemplos respostas

Se os filtros não retornarem nenhum item, a resposta será o seguinte json.

{
  "carts": [],
  "paginate": {
    "current": 1,
    "last": 1,
    "total": 0,
    "per_page": 100
  }
}

Exemplo de filtro de data incorreto: https://api.yever.com.br/api/v1/order/list?created_at_inicial=2022-11-02&created_at_final=2022-10-01

{
  "errors": {
    "created_at_final": [
      "O campo created at final deve conter uma data superior ou igual a created at inicial."
    ]
  }
}

Exemplo de filtro de status incorreto: https://api.yever.com.br/api/v1/order/list?status=teste

{
  "errors": {
    "status": ["The selected status is invalid."]
  }
}

Webhook

Toda vez que houver um evento (criação ou atualização de um pedido/carrinho), será disparado um POST para a URL cadastrada. Em todas as requisições será enviado no corpo da requisição o parâmetro token para validar se foi disparado pela Yever. O token é informado na criação do webhook no sistema da Yever. O corpo da requisição será um json e nos Headeres da requisição será informado o Content-Type: application/json.

Pedidos

{
  "token": "xxxxxxxxxxxxx", // [a-zA-Z0-9]{64}
  "reference": "1234567890", // [0-9]{10}
  "customer": {
    "name": "Nome do cliente",
    "email": "email@email.com",
    "phone": "+5511999991111", // sempre 14 dígitos, +55 (código do brasil), 2 números do ddd e 9 do celular
    "type": "F", // F -> Pessoa Física, J -> Pessoa Jurídica
    "document": "92220244008" // \d{11}(\d{3})? - 11 ou 14 números
  },
  "status": "paid", // pending_payment, paid, refunded, charged_back, canceled
  "products": [
    // produtos que de fato foram comprados
    {
      "product_id": 5732411797552, // id no ERP
      "product_title": "Exemplo de produto",
      "variant_id": 53012421484761,
      "variant_title": "Variante abc",
      "quantity": 3,
      "price": 33.15,
      "image_url": "https://images.yever.com.br/product/exemplodeimagem-1669936110.jpg",
      "is_order_bump": 0
    }
  ],
  "shipping_address": {
    "name": "Nome de quem vai receber",
    "phone": "+5511999991111", // sempre 14 dígitos, +55 (código do brasil), 2 números do ddd e 9 do celular
    "address1": "logradouro, numero",
    "address2": "Bairro",
    "city": "Cidade",
    "province_code": "MG",
    "country": "Brazil",
    "country_code": "BR",
    "zip": "11111111" // sempre 8 dígitos
  },
  "tracking": {
    "code": "código de rastreio", // qualquer formato, pode ser de alguma transportadora da china, correios, etc. Ex: NL501111803BR
    "courier": "transportadora" // nome da transportadora. Ex: Correios
  },
  "coupon_code": null, // código do cupom se tiver
  "currency": "BRL",
  "price_initial": 178.86, // valor inicial do pedido -> price_subtotal + price_shipment
  "price_subtotal": 168.4, // valor dos produtos
  "price_shipment": 10.46, // valor do frete
  "price_coupon_discount": 5.05, // desconto do cupom
  "price_shipment_discount": 10.46, // desconto do frete
  "price_offer_discount": 0, // desconto da oferta
  "price_payment_discount": 8.17, // desconto por forma de pagamento
  "price_total": 155.18, // valor final do pedido -> price_subtotal + price_shipment - price_coupon_discount - price_shipment_discount - price_offer_discount - price_payment_discount
  "price_client_final": 155.18, // valor da venda com juros de parcelamento - recebimento no fluxo ou só checkout
  "price_coupon": 0.0, // deprecated, do not use
  "price_discount": 0.0, // deprecated, do not use
  "payment_method": "credit_card", // pix, billet, credit_card
  "billet_code": null, // linha digitável do boleto
  "billet_url": null, // url para acessar o boleto
  "pix_code": null, // pix copia e cola
  "pix_url": null, // url para imagem do pix
  "checkout_url": "https://seguro.client.com.br/checkout/products?product_id[0]=1&quantity[0]=1", // url para refazer a compra se necessário
  "payment_url": "https://seguro.client.com.br/checkout/pix/1234567890", // url para fazer o pagamento -> Apenas pix e boleto e os números são o reference
  "is_upsell": 0,
  "installments": 12, // sempre será 1 para pix e boleto
  "created_at": "2022-12-09 05:46:59",
  "updated_at": "2022-12-09 05:47:01",
  "utms": {
    "source": "face",
    "campaign": "promocao_blackfriday",
    "medium": null,
    "content": null,
    "term": null
  },
  "price_client": {
    "client": 102.89, // valor recebido pelo cliente
    "yever_base": 6.56, // taxa da yever
    "installment_antecipation": 0 // valor pago por assumir parcelas sem juros
  }
}

Carrinho

{
  "reference": "41413750-c68f-46f0-ae42-a8f3ad9e4859", // 36 char, nesse formato
  "customer": {
    "name": "Nome do cliente",
    "email": "email@email.com",
    "phone": "+5511999991111" // sempre 14 dígitos, +55 (código do brasil), 2 números do ddd e 9 do celular
  },
  "last_step": "payment", // client, delivery, shipment, payment. Até qual step o cliente chegou
  "order_status": "canceled", // null se não tiver sido gerado um pedido, pending_payment, paid, refunded, charged_back, canceled
  "products": [
    // produtos iniciais quando o cliente entrou na tela
    {
      "product_title": "Exemplo de produto",
      "variant_title": "Variante abc",
      "quantity": 2,
      "price": 47.91, // preço unitário
      "image_url": "https://images.yever.com.br/product/exemplodeimagem-1669936110.jpg"
    }
  ],
  "currency": "BRL",
  "price_total": 95.82,
  "checkout_url": "https://seguro.yever.com.br/checkout/products?product_id[0]=1&quantity[0]=2",
  "created_at": "2022-12-02 06:59:17",
  "updated_at": "2022-12-02 07:00:27",
  "abandoned_at": "2022-12-02 07:05:00",
  "utms": {
    "source": "face",
    "campaign": "promocao_blackfriday",
    "medium": null,
    "content": null,
    "term": null
  }
}

Errors

A API utiliza os códigos de erro HTTP. Além do erro, a grande maioria vai retornar alguma mensagem para explicar o motivo do erro.

Código Significado
400 Bad request -> Requisição inválida.
401 Unauthorized -> O Bearer Token fornecido no header Authorization é inválido. Confira a seção Autenticação.
403 Forbidden -> O token não possui permissão para executar esta ação.
404 Not found -> Não encontrado.
405 Method not allowed -> Você tentou acessar a rota com o método errado.
422 Unprocessable entity -> Erro de validação em algum parâmetro.
429 Too many requests -> Limit de requisições atingido.
5xx Se qualquer erro 5xx acontecer a Yever será notificada e o time irá realizar as correções necessárias.
shell javascript php java