Documentação API VMPay Documentation Release 0.0.1 Verti Tecnologia December 23, 2015
Contents 1 Índice 1 1.1 Introdução................................................ 1 1.2 Visão geral................................................ 2 2 Resources disponíveis 5 2.1 Categorias................................................ 5 2.2 Clientes.................................................. 6 2.3 Fabricantes................................................ 8 2.4 Locais.................................................. 9 2.5 Máquinas................................................. 11 2.6 Fabricantes de máquina......................................... 12 2.7 Modelos de máquina........................................... 12 2.8 Tipos de máquina............................................. 13 2.9 Produtos................................................. 13 i
ii
CHAPTER 1 Índice 1.1 Introdução 1.1.1 Objetivo Estabelecer a forma e conteúdo que serão disponibilizados para integração com outros sistemas denominados ERPs. 1.1.2 Áreas envolvidas Departamento tecnologia Departamento comercial / comercial / representantes Suporte 1.1.3 Metodologia As informações disponibilizadas no sistema VMpay, consulta, cadastro, edição e exclusão serão disponibilizadas por meio de um web service de forma que possam ser capturadas e integradas em outro sistema. O sistema de ERP será o agente ativo, ou seja, cabe a ele proceder a busca e/ou envio das informações requeridas, o sistema de Telemetria será o agente passivo, disponibiliza as informações, não realiza buscas ou envia. As informações poderão ainda ser capturas por meio de planilhas eletrônicas, limitando-se as planilhas disponibilizadas no sistema de Telemetria VMPay. 1.1.4 Elaboração As informações serão disponibilizadas pelo web service padrão REST, dados trocado no formato JSON. 1. Comercial 1. Sempre que houver uma previsão de integração o departamento Comercial deverá informar o cliente sobre o processo e forma de integração. 2. O comercial deve enviar para a área de TI o nome do software ERP, os dados de contato Técnico para que a área de TI possa realizar as tratativas Técnicas; 2. T.I. 1
1. Com base nas tratativas com a empresa desenvolvedora do produto a área de T.I determinará o prazo para disponibilização das informações; 2. Se for necessário, a área de T.I desenvolverá um plano de trabalho antes da integração. 3. Toda tratativa será documentada de forma a minimizar os erros de comunicação. 4. Ilustração do processo 1.1.5 Conferência Após definição do processo de integração, o responsável pela área de T.I deverá fazer uma conferência minuciosa de todos os dados. 1.1.6 Aprovação A aprovação é realizada pela Área de T.I e pela fornecedora/desenvolvedora do sistema ERP. 1.1.7 Envio Toda documentação será enviada por meio eletrônico. 1.2 Visão geral 1.2.1 Endpoints Os endpoints são mapeados como segue: http://vmpay.vertitecnologia.com.br/api/v1/caminho/para/resource 1.2.2 Autenticação Cada operador receberá a sua api key, que deverá ser passada na URL em TODAS as requisições feitas à API. Exemplo: http://vmpay.vertitecnologia.com.br/api/v1/caminho/para/api?access_token=837e068fbb4c1e1f 2 Chapter 1. Índice
1.2.3 Exemplo de requisição válida Essa requisição lista toda as categorias de um determinado operador: GET http://vmpay.vertitecnologia.com.br/api/v1/categories?access_token=213qweasdzxc 1.2.4 Códigos de retorno e seus significados 200: OK 201: Criado com sucesso 204: Excluído com sucesso 400: bad request, algum parâmetro obrigatório faltando 401: unauthorized, tentativa de alterar/excluir uma categoria de outro operador 422: Erro ao criar, nome já está em uso 1.2.5 Código de exemplo Um exemplo de código em linguagem Python para acessar a API do VMPay está disponível no repositório da Verti no github. 1.2. Visão geral 3
4 Chapter 1. Índice
CHAPTER 2 Resources disponíveis 2.1 Categorias 2.1.1 Listar GET /api/v1/categories 2.1.2 Ver GET /api/v1/categories/[id] 2.1.3 Criar POST /api/v1/categories "category": "name": "Refrigerantes" Obrigatórios category name: Nome da categoria. Opcionais: Nenhum. 5
2.1.4 Atualizar PATCH /api/v1/categories/[id] "category": "name": "Refrigerantes" Obrigatórios category name: Nome da categoria. Opcionais: Nenhum. 2.1.5 Excluir DELETE /v1/categories/[id] 2.2 Clientes 2.2.1 Listar GET /api/v1/clients 2.2.2 Ver GET /api/v1/clients/[id] 2.2.3 Criar POST /api/v1/clients 6 Chapter 2. Resources disponíveis
"client": "name": "Cliente fictício", "legal_type": "corporation", "corporate_name": "Razão social Ltda.", "cnpj": "63271298000194", "contact_name": "João Silva", "contact_phone": "41-9999-8888", "contact_email": "joao@example.org", "notes": "observação" Obrigatórios client name: Nome do cliente. legal_type: Indica o tipo de pessoa. Valores permitidos: person (pessoa física) ou corporation (pessoa jurídica). Opcionais: corporate_name: razão social cpf : CPF cnpj: CNPJ contact_name: Nome para contato contact_phone: Telefone para contato contact_email: email para contato notes: Observação main_location_id: id do endereço principal do cliente 2.2.4 Atualizar PATCH /api/v1/clients/[id] "client": "name": "Novo nome" 2.2. Clientes 7
client é obrigatório. Pelo menos um campo deve ser passado. 2.2.5 Excluir DELETE /v1/clients/[id] 2.3 Fabricantes 2.3.1 Listar GET /api/v1/manufacturers 2.3.2 Ver GET /api/v1/manufacturers/[id] 2.3.3 Criar POST /api/v1/manufacturers "manufacturer": "name": "TAURUS" Obrigatórios manufacturer name: Nome do fabricante. Opcionais: Nenhum. 8 Chapter 2. Resources disponíveis
2.3.4 Atualizar PATCH /api/v1/manufacturers/[id] "manufacturer": "name": "ACME" Obrigatórios manufacturer name: Nome do fabricante. Opcionais: Nenhum. 2.3.5 Excluir DELETE /v1/manufacturers/[id] 2.4 Locais 2.4.1 Listar GET /api/v1/locations 2.4.2 Ver GET /api/v1/locations/[id] 2.4.3 Criar POST /api/v1/locations 2.4. Locais 9
"location": "name": "Nome do local", "phone": "41-9999-8888", "street": "Rua das Flores", "number": "123", "complement": "loja 1", "neighborhood": "Centro", "city": "Curitiba", "state": "PR", "zip_code": "80140110" Obrigatórios location name: Nome do local. state: Sigla de uma das UF do Brasil, em letras maiúsculas. Ex.: PR Opcionais: client_id: id do cliente situado neste endereço phone: telefone street: logradouro number: número complement: complemento neighborhood: bairro city: cidade zip_code: CEP 2.4.4 Atualizar PATCH /api/v1/locations/[id] "location": "name": "Matriz" 10 Chapter 2. Resources disponíveis
location é obrigatório. Pelo menos um campo deve ser passado para ser atualizado. 2.4.5 Excluir DELETE /v1/locations/[id] 2.5 Máquinas 2.5.1 Listar GET /api/v1/machines 2.5.2 Ver GET /api/v1/machines/[id] 2.5.3 Criar POST /api/v1/machines "machine": "asset_number": "987654321", "machine_model_id": "69" Obrigatórios machine asset number: número de patrimônio machine_model_id: id do modelo da máquina Opcionais: Nenhum. 2.5. Máquinas 11
2.5.4 Atualizar PATCH /api/v1/machines/[id] "machine": "asset_number": "998877" machine é obrigatório. Pelo menos um campo deve ser passado para ser atualizado. 2.5.5 Excluir DELETE /v1/machines/[id] 2.6 Fabricantes de máquina 2.6.1 Listar GET /api/v1/machine_manufacturers 2.6.2 Ver GET /api/v1/machine_manufacturers/[id] 2.7 Modelos de máquina 2.7.1 Listar GET /api/v1/machine_models 2.7.2 Ver GET /api/v1/machine_models/[id] 12 Chapter 2. Resources disponíveis
2.8 Tipos de máquina 2.8.1 Listar GET /api/v1/machine_types 2.8.2 Ver GET /api/v1/machine_types/[id] 2.9 Produtos 2.9.1 Listar GET /api/v1/vendibles 2.9.2 Ver GET /api/v1/vendibles/[id] 2.9.3 Criar POST /api/v1/vendibles "vendible": "type": "Product", "name": "Vanilla Coke", "manufacturer_id": 56, "category_id": 21, "upc_code": 111 Obrigatórios vendible name: Nome do produto. type: valor deve ser sempre Product. 2.8. Tipos de máquina 13
Opcionais: manufacturer_id: id do fabricante category_id: id da categoria upc_code: código do produto 2.9.4 Atualizar PATCH /api/v1/vendibles/[id] "vendible": "name": "Vanilla Coke", "manufacturer_id": 521, "category_id": 253, "upc_code": 999 Proibidos: type: Este parâmetro não é passado na atualização. Caso esteja presente, a request retornará um erro 400. Obrigatórios vendible Pelo menos um campo deve ser passado. 2.9.5 Excluir DELETE /v1/vendibles/[id] 14 Chapter 2. Resources disponíveis