Carga Fácil Brasil - API
API Endpoint
https://prod.balcaobalcao.com.brO 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 ¶
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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 fretesGET/shipping/find{?from,to,value,additional_time,tax,nf,products}
Método para retornar os fretes disponíveis.
Exemplos
Observações de envio
-
O token da api deve ser enviado no header X-BB-ApiToken
-
O parâmetro products é um
arraymultidimensional 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 Fiscal1- 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ão2- Somente com entrega3- Converter destinos com entrega4- 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 |
- from
string(obrigatório) Exemplo: 95012-320CEP de origem
- to
string(obrigatório) Exemplo: 01023-001CEP de destino
- value
number(obrigatório) Exemplo: 1250.95Valor Declarado
- additional_time
integer(opcional) Padrão: 0 Exemplo: 1Tempo adicional de entrega em dias
- tax
integer(opcional) Padrão: 1 Exemplo: 1Adicionar tarifa de serviço sobre o frete
Opções:
01- nf
integer(opcional) Padrão: 1 Exemplo: 1Informa se possui nota fiscal do valor declarado
Opções:
01- products
array(obrigatório) Exemplo: []Informações dos Produtos
- delivery
integer(opcional) Padrão: 1 Exemplo: 1Define o tipo do retorno com entrega
Opções:
1234
Buscar fretes Marketplace ¶
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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 MarketplacePOST/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
Observações
-
O token da api deve ser enviado no header X-BB-ApiToken.
-
O parâmetro quote é um
arraymultidimensional e cada posição recebe os valores no formato do Buscar Fretes. -
Máximo de 20 cotações.
Pedidos ¶
Adicionar Pedido ¶
Headers
Content-Type: application/x-www-form-urlencoded
X-BB-ApiToken: $2$aAgt334s...
Accept: application/jsonHeaders
Content-Type: application/jsonBody
{
"status": 1,
"message": "Pedido criado com sucesso.",
"tracking_code": "RSJSI2TSRS"
}Headers
Content-Type: application/jsonBody
{
"status": 2,
"message": "Etiqueta aguardando pagamento.",
"tracking_code": "RSTJ4F8RS"
}Headers
Content-Type: application/jsonBody
{
"message": "Não foi possível gerar a etiqueta.",
"status_code": 400
}Headers
Content-Type: application/jsonBody
{
"message": "422 Unprocessable Entity",
"errors": {
"customer.document": [
"O campo customer.document é obrigatório."
]
},
"status_code": 422
}Adicionar PedidoPOST/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
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
- phone
- address
- address_number
- address_complement
-
O parâmetro customer é um array contendo as seguintes posições:
- name
- document
- 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
arraymultidimensional, 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.
- return_url
string(opcional) Exemplo: https://www.meudominio.com.br/bbURL 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 ¶
Headers
X-BB-ApiToken: $2$aAgt334s...
Accept: application/jsonHeaders
Content-Type: application/jsonBody
{
"status": 1,
"data": {
"code": 1,
"name": "Pedido no E-commerce."
}
}Headers
Content-Type: application/jsonBody
{
"message": "422 Unprocessable Entity",
"errors": {
"token": [
"O campo token é obrigatório."
]
},
"status_code": 422
}Verificar StatusGET/order/status/{tracking_code}
Método para verificar o status de um pedido.
Exemplos
Observações
-
O token da api deve ser enviado no header X-BB-ApiToken
-
Os possíveis retornos são:
1- Pedido Efetuado2- Pedido Cancelado3- Pedido Recebido4- Pedido Encaminhado ao Destino5- Pedido Recebido no Destino6- Pedido Retirado pelo Cliente7- Pedido Recebido para Redespacho
- tracking_code
string(obrigatório) Exemplo: RSBLWDRS...Código de rastreio
Atualizar Status ¶
Headers
Content-Type: application/x-www-form-urlencoded
X-BB-ApiToken: $2$aAgt334s...
Accept: application/jsonHeaders
Content-Type: application/jsonBody
{
"status": 1,
"message": "Status atualizado com sucesso."
}Headers
Content-Type: application/jsonBody
{
"message": "Este pedido não pode ser cancelado pois já está em trânsito",
"status_code": 409
}Headers
Content-Type: application/jsonBody
{
"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 StatusPATCH/order/status/{tracking_code}
Método para atualizar o status de um pedido.
Exemplos
Observações
- O parâmetro status possui apenas as seguintes opções:
1- Pedido Efetuado2- Pedido Cancelado
- tracking_code
string(obrigatório) Exemplo: RSBLWDRS...Código de rastreio
- status
integer(obrigatório) Exemplo: 1Código do status
Opções:
12
Imprimir etiqueta ¶
Headers
X-BB-ApiToken: $2$aAgt334s...
Accept: text/html, application/jsonHeaders
Content-Type: text/html; charset=UTF-8Body
<html>...</html>Headers
Content-Type: application/jsonBody
{
"message": "422 Unprocessable Entity",
"errors": {
"tracking_code": [
"O campo tracking code é obrigatório."
],
"token": [
"O campo token é obrigatório."
]
},
"status_code": 422
}Imprimir etiquetaGET/order/print/{tracking_code}
Método para gerar a etiqueta de um pedido.
Exemplos
Observações
- O token da api deve ser enviado no header X-BB-ApiToken
- tracking_code
string(obrigatório) Exemplo: RSBLWDRS...Código de rastreio