Carga Fácil Brasil - API

O objetivo desta documentação é orientar o desenvolvedor sobre como integrar
com a API da Carga Fácil Brasil.

Visão Geral

Autenticação

Todas as operações nesta api devem ser executadas com a utilização da sua chave de autenticação (token) em cada endpoint.

Esta api está liberada apenas para Lojas Virtuais e você deve estar cadastrado em nosso sistema para obter seu token.

Nome Exemplo
token $2y$10$EINEEdZo3C5.NF8XC4…
AMBIENTE ENDPOINT
TESTES https://dev.balcaobalcao.com.br/api/
PRODUÇÃO https://prod.balcaobalcao.com.br/api/
MÉTODO DESCRIÇÃO
GET O método GET é utilizado para consultas de informações já existentes. Por exemplo, buscar fretes.
POST O método POST é utilizado na criação ou no envio de informações que serão processadas pelo nosso sistema. Por exemplo, adicionar um pedido.
PATCH método PATCH é utilizado para atualização de informações já existentes. Por exemplo, atualizar o status de um pedido.

Fretes

Buscar fretes

GET https://prod.balcaobalcao.com.br/shipping/find?from=95012-320&to=01023-001&value=1250.95&additional_time=1&tax=1&nf=1&products=[]
Responses200422
Headers
Content-Type: application/json
Body
{
  "status": true,
  "data": [
    {
      "name": "Retirada na Agência - Porto Alegre",
      "address": "Rua Frederico Mentz, 1419 - Navegantes - Porto Alegre - RS",
      "price": 22.33,
      "deadline": "Disponível para retirada em até 1 dia útil.",
      "token": "eyJpdiI6Il...",
      "origin": {
        "name": "Agência - Caxias do Sul",
        "address": "Rua Ernesto Alves",
        "number": "1341",
        "complement": "Rodoviária - Setor 6",
        "postcode": "95020360",
        "city": "Caxias do Sul",
        "state": "RS",
        "phone": "5432183030",
        "same_origin": true,
        "latitude": -29.1632971,
        "longitude": -51.1726916,
        "pickup": false,
        "delivery": false,
        "hours": [
          {
            "weekday": 3,
            "day": "Quarta-feira",
            "am_from": "08:00",
            "am_to": "12:00",
            "pm_from": "13:30",
            "pm_to": "18:00"
          }
        ]
      },
      "destiny": {
        "name": "Agência - Porto Alegre",
        "address": "Rua Frederico Mentz",
        "number": "1419",
        "complement": null,
        "postcode": "90240110",
        "city": "Porto Alegre",
        "state": "RS",
        "phone": "5133758900",
        "same_destiny": true,
        "latitude": -29.994653350291,
        "longitude": -51.201846382001,
        "pickup": false,
        "delivery": false,
        "hours": [
          {
            "weekday": 3,
            "day": "Quarta-feira",
            "am_from": "08:00",
            "am_to": "12:00",
            "pm_from": "13:30",
            "pm_to": "19:00"
          }
        ]
      }
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "message": "422 Unprocessable Entity",
  "errors": {
    "from": [
      "O campo from é obrigatório."
    ],
    "to": [
      "O campo to é obrigatório."
    ],
    "value": [
      "O campo value é obrigatório."
    ],
    "token": [
      "O campo token é obrigatório."
    ]
  },
  "status_code": 422
}

Buscar fretes
GET/shipping/find{?from,to,value,additional_time,tax,nf,products}

Método para retornar os fretes disponíveis.

Exemplos

PHP

Observações de envio

  • O token da api deve ser enviado no header X-BB-ApiToken

  • O parâmetro products é um array multidimensional importante para aplicarmos os cálculos de peso e dimensões dos produtos, contém uma ou mais posições compostas pela seguinte configuração:

    • quantity
    • weight
    • length
    • width
    • height
  • O peso (weight) deve ser encaminhado sempre em kg

  • As dimensões length (comprimento), width (largura), height (altura), devem ser enviadas sempre em metros

  • O parâmetro tax possui apenas as seguintes opções:

    • 0 - Sem Taxa, retorna o valor do frete sem a adição da tarifa de serviço, o contratante assume a tarifa ao comprar a etiqueta.
    • 1 - Com Taxa, embute o valor da tarifa de serviço sobre o valor do frete.
  • O parâmetro nf possui apenas as seguintes opções:

    • 0 - Sem Nota Fiscal
    • 1 - Com Nota Fiscal
    • Obs: Usuários PJ (Pessoa Jurídica) somente enviam encomendas com apresentação da nota fiscal.
    • Obs2: Usuários PF (Pessoa Física) somente enviam sem nota fiscal e devem apresentar a declaração de conteúdo preenchida.
  • O parâmetro delivery controla o padrão do retorno da api, possuindo as seguintes opções: Se não informado, assume o valor definido nas configurações da loja.

    • 1 - Padrão
    • 2 - Somente com entrega
    • 3 - Converter destinos com entrega
    • 4 - Priorizar com entrega mas com fallback para o padrão

Observações do Retorno

Parâmetro Tipo Observação
service string Nome do serviço
name string Nome do agente da cidade de destino
address string Endereço do agente da cidade de destino
price float Valor da cotação
deadline string Descrição do prazo de retirada
deadline_from string Prazo mínimo de retirada
deadline_to string Prazo máximo de retirada
token string Token da cotação
origin array Dados do agente de origem
origin.name string Nome do agente
origin.address string Endereço do agente
origin.number string Número do endereço do agente
origin.complement string Complemento do endereço do agente
origin.postcode string Cep do agente
origin.city string Cidade do agente
origin.state string Estado do agente
origin.phone string Telefone do agente
origin.same_origin boolean Indica se o agente é da mesma cidade do cep de origem
origin.latitude float Latitude
origin.longitude float Longitude
origin.pickup boolean Indica se o agente faz serviço de coleta
origin.delivery boolean Indica se o agente faz serviço de entrega
origin.hours array Horários de atendimento do agente
origin.hours.*.weekday integer Dia da semana (0=Domingo, 6=Sábado)
origin.hours.*.day string Nome do dia
origin.hours.*.am_from hour Horário de abertura manhã no formato “HH:MM”
origin.hours.*.am_to hour Horário de encerramento manhã no formato “HH:MM”
origin.hours.*.pm_from hour Horário de abertura tarde no formato “HH:MM”
origin.hours.*.pm_to hour Horário de encerramento tarde no formato “HH:MM”
destiny array Dados do agente de destino
destiny.name string Nome do agente
destiny.address string Endereço do agente
destiny.number string Número do endereço do agente
destiny.complement string Complemento do endereço do agente
destiny.postcode string Cep do agente
destiny.city string Cidade do agente
destiny.state string Estado do agente
destiny.phone string Telefone do agente
destiny.same_destiny boolean Indica se o agente é da mesma cidade do cep de destino
destiny.latitude float Latitude
destiny.longitude float Longitude
destiny.pickup boolean Indica se o agente faz serviço de coleta
destiny.delivery boolean|array Indica se o agente faz serviço de entrega
destiny.delivery.code string Token da cotação
destiny.delivery.price float Valor de entrega
destiny.delivery.mileage float Km calculada
destiny.delivery.latitude float Latitude utilizada
destiny.delivery.longitude float Longitude utilizada
destiny.delivery.simulation boolean Indica se o valor é apenas simulação
destiny.delivery.deadline array Informa o tempo de entrega
destiny.delivery.deadline.text string Descrição do prazo de entrega
destiny.delivery.deadline.from integer Prazo mínimo de entrega
destiny.delivery.deadline.to integer Prazo máximo de entrega
destiny.hours array Horários de atendimento do agente
destiny.hours.*.weekday integer Dia da semana (0=Domingo, 6=Sábado)
destiny.hours.*.day string Nome do dia
destiny.hours.*.am_from hour Horário de abertura manhã
destiny.hours.*.am_to hour Horário de encerramento manhã
destiny.hours.*.pm_from hour Horário de abertura tarde
destiny.hours.*.pm_to hour Horário de encerramento tarde
Parâmetros
OcultarExibir
from
string (obrigatório) Exemplo: 95012-320

CEP de origem

to
string (obrigatório) Exemplo: 01023-001

CEP de destino

value
number (obrigatório) Exemplo: 1250.95

Valor Declarado

additional_time
integer (opcional) Padrão: 0 Exemplo: 1

Tempo adicional de entrega em dias

tax
integer (opcional) Padrão: 1 Exemplo: 1

Adicionar tarifa de serviço sobre o frete

Opções: 0 1

nf
integer (opcional) Padrão: 1 Exemplo: 1

Informa se possui nota fiscal do valor declarado

Opções: 0 1

products
array (obrigatório) Exemplo: []

Informações dos Produtos

delivery
integer (opcional) Padrão: 1 Exemplo: 1

Define o tipo do retorno com entrega

Opções: 1 2 3 4


Buscar fretes Marketplace

POST https://prod.balcaobalcao.com.br/shipping/marketplace-find
Responses200422
Headers
Content-Type: application/json
Body
{
  "status": true,
  "quote": [
    [
      {
        "name": "Retirada na Agência - Caxias do Sul",
        "address": "Rua Ernesto Alves, 1341 - Rodoviária - Setor 6 - Centro - Caxias do Sul - RS",
        "price": 22.14,
        "deadline": "Disponível para retirada de 1 a 2 dias úteis.",
        "token": "eyJpdiI6Ino2NXJsR2Z...",
        "origin": {
          "name": "Agência - São Paulo",
          "address": "Avenida Cruzeiro do Sul",
          "number": "1800",
          "complement": "Terminal Rodoviário Tietê, Piso Térreo, box 1",
          "postcode": "02030000",
          "city": "São Paulo",
          "state": "SP",
          "phone": "4131569910",
          "same_origin": true,
          "latitude": -23.5316875,
          "longitude": -46.6257805,
          "pickup": false,
          "delivery": false,
          "hours": [
            {
              "weekday": 3,
              "day": "Quarta-feira",
              "am_from": "08:30",
              "am_to": "12:00",
              "pm_from": "12:00",
              "pm_to": "18:30"
            }
          ]
        },
        "destiny": {
          "name": "Agência - Caxias do Sul",
          "address": "Rua Ernesto Alves",
          "number": "1341",
          "complement": "Rodoviária - Setor 6",
          "postcode": "95020360",
          "city": "Caxias do Sul",
          "state": "RS",
          "phone": "5432183030",
          "same_destiny": true,
          "latitude": -29.1632971,
          "longitude": -51.1726916,
          "pickup": false,
          "delivery": false,
          "hours": [
            {
              "weekday": 3,
              "day": "Quarta-feira",
              "am_from": "08:00",
              "am_to": "12:00",
              "pm_from": "13:30",
              "pm_to": "18:00"
            }
          ]
        }
      }
    ],
    [
      {
        "name": "Retirada na Agência - Caxias do Sul",
        "address": "Rua Ernesto Alves, 1341 - Rodoviária - Setor 6 - Centro - Caxias do Sul - RS",
        "price": 21.49,
        "deadline": "Disponível para retirada de 2 a 3 dias úteis.",
        "token": "eyJpdiI6IlZmZ3dk...",
        "origin": {
          "name": "Agência - São Paulo",
          "address": "Avenida Cruzeiro do Sul",
          "number": "1800",
          "complement": "Terminal Rodoviário Tietê, Piso Térreo, box 1",
          "postcode": "02030000",
          "city": "São Paulo",
          "state": "SP",
          "phone": "4131569910",
          "same_origin": true,
          "latitude": -23.5316875,
          "longitude": -46.6257805,
          "pickup": false,
          "delivery": false,
          "hours": [
            {
              "weekday": 3,
              "day": "Quarta-feira",
              "am_from": "08:30",
              "am_to": "12:00",
              "pm_from": "12:00",
              "pm_to": "18:30"
            }
          ]
        },
        "destiny": {
          "name": "Agência - Caxias do Sul",
          "address": "Rua Ernesto Alves",
          "number": "1341",
          "complement": "Rodoviária - Setor 6",
          "postcode": "95020360",
          "city": "Caxias do Sul",
          "state": "RS",
          "phone": "5432183030",
          "same_destiny": true,
          "latitude": -29.1632971,
          "longitude": -51.1726916,
          "pickup": false,
          "delivery": false,
          "hours": [
            {
              "weekday": 3,
              "day": "Quarta-feira",
              "am_from": "08:00",
              "am_to": "12:00",
              "pm_from": "13:30",
              "pm_to": "18:00"
            }
          ]
        }
      }
    ]
  ]
}
Headers
Content-Type: application/json
Body
{
  "message": "Quote 1: O valor declarado não está entre os valores permitidos. O limite estabelecido pode variar de 100,00 a 1.000,00.",
  "status_code": 422
}

Buscar fretes Marketplace
POST/shipping/marketplace-find

Aceita o envio de multiplas cotações em um único request.

Atenção

Este método está disponível apenas para lojas marketplace.

Exemplos

PHP

Observações

  • O token da api deve ser enviado no header X-BB-ApiToken.

  • O parâmetro quote é um array multidimensional e cada posição recebe os valores no formato do Buscar Fretes.

  • Máximo de 20 cotações.


Pedidos

Adicionar Pedido

POST https://prod.balcaobalcao.com.br/order/store
RequestsExemplo
Headers
Content-Type: application/x-www-form-urlencoded
X-BB-ApiToken: $2$aAgt334s...
Accept: application/json
Responses200200400422
Headers
Content-Type: application/json
Body
{
  "status": 1,
  "message": "Pedido criado com sucesso.",
  "tracking_code": "RSJSI2TSRS"
}
Headers
Content-Type: application/json
Body
{
  "status": 2,
  "message": "Etiqueta aguardando pagamento.",
  "tracking_code": "RSTJ4F8RS"
}
Headers
Content-Type: application/json
Body
{
  "message": "Não foi possível gerar a etiqueta.",
  "status_code": 400
}
Headers
Content-Type: application/json
Body
{
  "message": "422 Unprocessable Entity",
  "errors": {
    "customer.document": [
      "O campo customer.document é obrigatório."
    ]
  },
  "status_code": 422
}

Adicionar Pedido
POST/order/store

Método para enviar um pedido. Este retorna o código de rastreio do pedido.

Atenção

Esse método pode tentar efetuar o pagamento automaticamente se o lojista possuir cartão de crédito cadastrado e o mesmo estiver habilitado para pagamento via API.

Exemplos

PHP

Observações de envio

  • O token da api deve ser enviado no header X-BB-ApiToken

  • O parâmetro sender é um array contendo as seguintes posições e é obrigatório apenas para lojas marketplace:

    • name
    • document
    • email
    • phone
    • address
    • address_number
    • address_complement
  • O parâmetro customer é um array contendo as seguintes posições:

    • name
    • document
    • email
    • phone
    • address
    • address_number
    • address_complement
  • O parâmetro order é um array multidimensional,

    • id
    • value
    • date
    • token
    • products
      • name
      • price
      • quantity
      • weight
      • length
      • width
      • height
  • O parâmetro products é um array multidimensional, contém uma ou mais posições compostas pela seguinte configuração:

    • name
    • price
    • quantity
    • weight
    • length
    • width
    • height
  • O peso (weight) deve ser enviado sempre em kg

  • As dimensões length (comprimento), width (largura), height (altura), devem ser enviadas sempre em metros

Parâmetro Tipo Observação
return_url string Url para recebimento das notificações
sender array Dados do remetente, é obrigatório apenas para lojas marketplace
sender.name string Nome do remetente
sender.document string Documento do remetente (cpf ou cnpj)
sender.email email E-mail do remetente
sender.phone string Telefone do remetente
sender.address string Endereço do remetente
sender.address_number string Número do endereço do remetente
sender.address_complement string Complemento do endereço do remetente
customer array Dados do cliente
customer.name string Nome do cliente
customer.document string Documento do cliente (cpf ou cnpj)
customer.email email E-mail do cliente
customer.phone string Telefone do cliente
customer.address string Endereço do cliente
customer.address_number string Número do endereço do cliente
customer.address_complement string Complemento do endereço do cliente
order array Contém as informações do pedido da sua loja
order.id integer Código do pedido
order.value float Valor total do pedido
order.date date Data do pedido no formato “YYYY-MM-DD”
order.token text Token do frete escolhido pelo cliente
order.products array Contém informações dos produtos
order.products.*.name string Nome do produto
order.products.*.price float Preço do produto
order.products.*.quantity integer Quantidade do produto
order.products.*.weight float Peso do produto em kg
order.products.*.length float Comprimento do produto em Metros
order.products.*.width float Largura do produto em Metros
order.products.*.height float Altura do produto em Metros

Notificações

Quando informado o parâmetro return_url, nossa API irá enviar um callback sempre que ocorrer alguma troca de status em nosso sistema. O callback é um método POST com os seguintes parâmetros:

Nome Tipo Observação
order_id integer id do pedido informado no cadastro.
status_id integer status atual do pedido em nosso sistema.
tracking_code string código de rastreio

Obs: Este callback é executado apenas uma vez na troca do status, para verificar manualmente, utilize o método Verificar Status.

Parâmetros
OcultarExibir
return_url
string (opcional) Exemplo: https://www.meudominio.com.br/bb

URL de retorno para a troca de status

sender
array (opcional) Exemplo: []

Array com os dados do remetente

customer
array (obrigatório) Exemplo: []

Array com os dados do cliente

order
array (obrigatório) Exemplo: []

Array com os dados do pedido e frete escolhido


Verificar Status

GET https://prod.balcaobalcao.com.br/order/status/RSBLWDRS...
RequestsExemplo
Headers
X-BB-ApiToken: $2$aAgt334s...
Accept: application/json
Responses200422
Headers
Content-Type: application/json
Body
{
  "status": 1,
  "data": {
    "code": 1,
    "name": "Pedido no E-commerce."
  }
}
Headers
Content-Type: application/json
Body
{
  "message": "422 Unprocessable Entity",
  "errors": {
    "token": [
      "O campo token é obrigatório."
    ]
  },
  "status_code": 422
}

Verificar Status
GET/order/status/{tracking_code}

Método para verificar o status de um pedido.

Exemplos

PHP

Observações

  • O token da api deve ser enviado no header X-BB-ApiToken

  • Os possíveis retornos são:

    • 1- Pedido Efetuado
    • 2- Pedido Cancelado
    • 3- Pedido Recebido
    • 4- Pedido Encaminhado ao Destino
    • 5- Pedido Recebido no Destino
    • 6- Pedido Retirado pelo Cliente
    • 7- Pedido Recebido para Redespacho
Parâmetros
OcultarExibir
tracking_code
string (obrigatório) Exemplo: RSBLWDRS...

Código de rastreio


Atualizar Status

PATCH https://prod.balcaobalcao.com.br/order/status/RSBLWDRS...
RequestsExemplo
Headers
Content-Type: application/x-www-form-urlencoded
X-BB-ApiToken: $2$aAgt334s...
Accept: application/json
Responses200409422
Headers
Content-Type: application/json
Body
{
  "status": 1,
  "message": "Status atualizado com sucesso."
}
Headers
Content-Type: application/json
Body
{
  "message": "Este pedido não pode ser cancelado pois já está em trânsito",
  "status_code": 409
}
Headers
Content-Type: application/json
Body
{
  "message": "422 Unprocessable Entity",
  "errors": {
    "order_id": [
      "O campo tracking code é obrigatório."
    ],
    "status": [
      "O campo status é obrigatório."
    ],
    "token": [
      "O campo token é obrigatório."
    ]
  },
  "status_code": 422
}

Atualizar Status
PATCH/order/status/{tracking_code}

Método para atualizar o status de um pedido.

Exemplos

PHP

Observações

  • O parâmetro status possui apenas as seguintes opções:
    • 1 - Pedido Efetuado
    • 2 - Pedido Cancelado
Parâmetros
OcultarExibir
tracking_code
string (obrigatório) Exemplo: RSBLWDRS...

Código de rastreio

status
integer (obrigatório) Exemplo: 1

Código do status

Opções: 1 2


Imprimir etiqueta

GET https://prod.balcaobalcao.com.br/order/print/RSBLWDRS...
RequestsExemplo
Headers
X-BB-ApiToken: $2$aAgt334s...
Accept: text/html, application/json
Responses200422
Headers
Content-Type: text/html; charset=UTF-8
Body
<html>...</html>
Headers
Content-Type: application/json
Body
{
  "message": "422 Unprocessable Entity",
  "errors": {
    "tracking_code": [
      "O campo tracking code é obrigatório."
    ],
    "token": [
      "O campo token é obrigatório."
    ]
  },
  "status_code": 422
}

Imprimir etiqueta
GET/order/print/{tracking_code}

Método para gerar a etiqueta de um pedido.

Exemplos

PHP

Observações

  • O token da api deve ser enviado no header X-BB-ApiToken
Parâmetros
OcultarExibir
tracking_code
string (obrigatório) Exemplo: RSBLWDRS...

Código de rastreio