Jamef API

Olá. Essa gem é um Ruby wrapper da API SOAP da Jamef.com.br. Use-a em qualquer projeto Ruby/Rails.

Você poderá facilmente

  • Consultar frete e prazo de entrega
  • ~~Rastrear encomendas despachadas~~ (#TO DO)

1. Consulta de Frete e Prazo (Rating)

Após a instalação da gem, realizar uma consulta de frete é bastante simples. São apenas 4 passos, veja um resumo do processo:

  1. Defina o remetente com Jamef::Sender
  2. Defina o destinatário com Jamef::Receiver
  3. Defina a mercadoria que vai ser enviada com Jamef::Package
  4. Realize a consulta com Jamef.rate ou Jamef.complete_rate

1.1 - Remetente

Inicialize um objeto Jamef::Sender com as informações da sua empresa.

my_company = Jamef::Sender.new({
  document: 'xxx',          # cnpj/cpf
  city: 'Jundiaí',          # sua cidade
  state: 'SP',              # seu estado
  jamef_branch: :campinas   # sua filial da jamef
})

Importante:

  • jamef_branch é sempre o nome da cidade da filial da Jamef associada à sua conta. Veja a tabela no final do documento.

1.2 - Destinatário

Crie um destinatário com o Jamef::Receiver.

receiver = Jamef::Receiver.new({
  zip: 'CEP AQUI',         # obrigatório: CEP
  document: 'CNPJ AQUI',   # opcional: cpf/cnpj do destinatário
  contrib: true            # opcional: Dest. é contribuinte?
})

1.3 - Mercadoria

Faça um pacote informando o volume final cubado (m³) e também seu peso (kg) com o Jamef::Package.

package = Jamef::Package.new({
  weight: 5,            # kg - peso da encomenda
  package_price: 1000,  # R$ - valor da encomenda
  volume: 2,            # m³ - vol. total cubado
  type: :nf             # opcional (leia abaixo)
})

Este último parâmetro type está relacionado com o tipo de produto que será transportado.

Você pode omitir type: :nf que é o valor padrão. O tipo :nf diz à Jamef para inferir o tipo de produto a partir da nota fiscal. Veja a tabela no final do documento para preencher o campo type adequadamente.

1.4 - Consulta

Há dois métodos que você pode usar para fazer a consulta: Jamef.complete_rate e Jamef.rate. Escolha a maneira mais adequada.

1.4.1 Consulta com retorno simplificado

Você pode realizar uma consulta simples com o Jamef::rate

Em shipping_in, informe a data/horário (datetime) de coleta da encomenda.

Jamef.rate({
  sender: my_company, 
  receiver: receiver, 
  package: package, 

  # Tipo de transporte: Aéreo (:air) ou rodoviário (:road)
  service_type: :road,

  # data/hora de coleta (Datetime obj.)
  shipping_in: 3.days.from_now.midday

})

O retorno é uma hash como esta abaixo:

  {
    freight: 50.00,               # total do frete
    min_delivery_date: min_date,  # data mínima de entrega
    max_delivery_date: max_date   # data máxima de entrega
  }

1.4.2 Consulta com retorno completo

É possível também pode realizar uma consulta completa com o método Jamef.complete_rate.

Os parâmetros são idênticos aos da versão simplificada acima, o que muda é o retorno que agora é uma hash originada diretamente da resposta da Jamef.

Exemplo de retorno:

{:freight=>
  {:msgerro=>"Ok - Calculo executado na filial [ CPQ ] cFilAnt : [03] Cliente Destinatario [  ] ",
   :valfre=>
    {:avalfre=>
      [{:componente=>"[01]-Pedagio             ", :imposto=>"0.58634409", :total=>"8.37634409", :valor=>"7.79000000"},
       {:componente=>"[03]-GRIS                ", :imposto=>"0.17583323", :total=>"2.51190323", :valor=>"2.33607000"},
       {:componente=>"[04]-TAS                 ", :imposto=>"0.49000000", :total=>"7.00000000", :valor=>"6.51000000"},
       {:componente=>"[05]-Taxa (ate 100kg)    ", :imposto=>"0.00000000", :total=>"0.00000000", :valor=>"0.00000000"},
       {:componente=>"[06]-Frete Peso (FM)     ", :imposto=>"13.81830288", :total=>"197.40432688", :valor=>"183.58602400"},
       {:componente=>"[07]-Frete Valor         ", :imposto=>"0.55680522", :total=>"7.95436022", :valor=>"7.39755500"},
       {:componente=>"[10]-TRT                 ", :imposto=>"0.00000000", :total=>"0.00000000", :valor=>"0.00000000"},
       {:componente=>"[23]-Frete Peso (FP)     ", :imposto=>"0.00000000", :total=>"0.00000000", :valor=>"0.00000000"},
       {:componente=>"[24]-Taxa (acima 100kg)  ", :imposto=>"0.00000000", :total=>"0.00000000", :valor=>"0.00000000"},
       {:componente=>"TF-TOTAL DO FRETE", :imposto=>"15.63000000", :total=>"223.25000000", :valor=>"207.62000000"}]}},
 :delivery=>{:cdtmax=>"03/05/18", :cdtmin=>"02/05/18", :msgerro=>"OK"}}

2. Rastreio (Tracking)

Ainda não está pronto.

3. Instalação

Se você estiver usando o Bundler, adiciona esta linha no seu Gemfile

gem 'jamef-api', require: 'jamef'

E execute

$ bundle

Ou instale diretamente no Ruby com

$ gem install jamef-api

Neste caso, quando for utilizar, não esqueça de dar um

require 'jamef'

em cima do documento antes utilizar a Gem.

4. Informações Complementares - Jamef

4.1 Tipo de Produto a ser enviado

Você pode especificar o tipo de produto transportado num pacote a partir da tabela abaixo.

4.1.1 Para frete rodoviário​
Ruby symbol Tipo de produto
:nf CONFORME NOTA FISCAL
:livros LIVROS
4.1.2 Para frete aéreo
Ruby symbol Tipo de produto
:nf CONFORME NOTA FISCAL
:livros LIVROS
:alimentos ALIMENTOS INDUSTRIALIZADOS
:confeccoes CONFECCOES
:comesticos COSMETICOS
:cirugicos MATERIAL CIRURGICO
:jornais JORNAIS / REVISTAS
material_escolar MATERIAL ESCOLAR

4.2 Filiais da Jamef

Encontre a sua filial e veja o valor do jamef_branch que você deve utilizar. Basicamente é o nome da cidade, mas por via das dúvidas:

Filial Map:

Ruby symbol Filial
:aracaju AJU - Aracaju - SE
:barueri BAR - Barueri - SP
:bauru BAU - Bauru - SP
:belo_horizonte BHZ - Belo Horizonte - MG
:blumenau BNU - Blumenau - SC
:brasilia BSB - Brasília - DF
:criciuma CCM - Criciúma - SC
:campinas CPQ - Campinas - SP
:caxias_do_sul CXJ - Caxias do Sul - RS
:curitiba CWB - Curitiba - PR
:divinopolis DIV - Divinópolis - MG
:feira_de_santana FES - Feira de Santana - BA
:florianopolis FLN - Florianópolis - SC
:fortaleza FOR - Fortaleza - CE
:goiania GYN - Goiânia - GO
:joao_pessoa JPA - João Pessoa - PB
:juiz_de_fora JDF - Juiz de Fora - MG
:joinville JOI - Joinville - SC
:londrina LDB - Londrina - PR
:manaus MAO - Manaus - AM
:maceio MCZ - Maceió - AL
:maringa MGF - Maringá - PR
:porto_alegre POA - Porto Alegre - RS
:pouso_alegre PSA - Pouso Alegre - MG
:ribeirao_preto RAO - Ribeirão Preto - SP
:recife REC - Recife - PE
:rio_de_janeiro RIO - Rio de Janeiro - RJ
:sao_paulo SAO - São Paulo - SP
:sao_jose_dos_campos SJK - São José dos Campos - SP
:sao_jose_do_rio_preto SJP - São José do Rio Preto - SP
:salvador SSA - Salvador - BA
:uberlandia UDI - Uberlândia - MG
:vitoria_da_conquista VDC - Vitória da Conquista - BA
:vitoria VIX - Vitória - ES

5. Contribuições

Se vir um bug, manda aí.

Pull requests são super bem-vindos e serão aceitos desde que:

  • Não sejam mirabolantes,
  • Incluam testes,
  • Façam sentido.

Tamo junto. :)

6. License

MIT License.