Documentação da API
A API (Interface de Programação de Aplicativos) do Mercado Máquinas é um conjunto de funções e padrões estabelecidos para criação de aplicativos customizados, em que há necessidade de uso da base de dados de anúncios e serviços oferecidos pelo Portal Mercado Máquinas.
Como funciona?
Para utilizar a API do Mercado Máquinas é necessário:
- Cadastro no Portal Mercado Máquinas
- Plano de acesso à API Mercado Máquinas. Planos disponíveis
- Solicitar a liberação dos IPs (de origem) que serão utilizados nas requisições.
Todos os serviços utilizam a tecnologia REST no tratamento de requisições, através de XML ou JSON sobre HTTP, usando todos principais verbos HTTP (GET, POST, PUT, DELETE). Cada recurso possui sua própria URL e pode ser manipulado de maneira isolada, para ser executada em seu navegador, linha de comando ou código.
Ambientes
Foram disponibilizados 2 tipos de ambientes para os clientes: Desenvolvimento e Produção.
O ambiente de desenvolvimento é um ambiente onde os desenvolvedores, clientes e usuários poderão testar as funcionalidades da API. Toda a manipulação de dados feita neste ambiente não modifica os dados de produção e poderão ser descartadas a qualquer momento.
O ambiente de produção é utilizado para manipular os dados utilizados no Portal Mercado Máquinas e somente deve ser utilizado após todos os testes no ambiente de desenvolvimento forem realizados com sucesso. Para utilizar este ambiente é necessário solicitar a autorização de uso no Portal Mercado Máquinas. Todas as requisições realizadas neste ambiente serão monitoradas.
Ambiente de desenvolvimento: http://apidev.mercadomaquinas.com.br
Ambiente de produção: http://api.mercadomaquinas.com.br
Autenticação e autorização
Todo acesso à API é feito através de um usuário autorizado no Portal Mercado Máquinas. Assim sendo, toda requisição deverá ser autenticada.
Para realizar a autorização, é necessário enviar as credenciais de autenticação usando o cabeçalho de autorização HTTP Basic.
O cabeçalho de autorização é construído como se segue:
- O nome de usuário e a senha são combinadas em uma string "usuário:senha"
- A seqüência resultante literal é então codificado em Base64
- O método de autorização seguido da palavra "Basic" é, então, colocado antes da seqüência codificada.
Por exemplo, se o usuário é 'Aladdin' e a senha é "abra-de-sésamo" então o cabeçalho deve ser:
Authorization: Basic QWxhZGRpbjphYnJhLWRlLXPDqXNhbW8=Em caso de falha na autorização será retornado um erro do tipo HTTP/1.1 401 Unauthorized
Formato de requisição
A tecnologia REST é a única utilizada em todos os serviços da API do Mercado Máquinas no tratamento de requisições.
curl -X GET -H "Accept: application/json" -H "Content-type: application/json; charset=utf-8" -H "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" http://api.mercadomaquinas.com.br/v1/ads/1
Formatos de retorno
Pode-se usar XML e/ou JSON como formatos de retorno da API do Mercado Máquinas.
Ads
Api para publicação de anúncios no Portal Mercado Máquinas.
Passo-a-passo de recomendações para publicar um Anúncio.
- Consultar o contrato vigente do anunciante (GETv1/contracts)
- Verificar se o modelo (Categoria/Fabricante/Modelo) informado existe (GETv1/ad-models/{category}/{make}/{model})
- Criar um novo anúncio (POSTv1/ads)
- Retorna as Especificações de um anúncio através do código informado (GETv1/ads/{adid}/specs)
- Atualizar/Modificar as Especificações de um anúncio já existente (PUTv1/ads/specs)
Contracts
Api para gerenciamento dos contros dos anunciantes.
