Documentação API VMPay Documentation

Transcrição

1 Documentação API VMPay Documentation Release Verti Tecnologia December 23, 2015

2

3 Contents 1 Índice Introdução Visão geral Resources disponíveis Categorias Clientes Fabricantes Locais Máquinas Fabricantes de máquina Modelos de máquina Tipos de máquina Produtos i

4 ii

5 CHAPTER 1 Índice 1.1 Introdução Objetivo Estabelecer a forma e conteúdo que serão disponibilizados para integração com outros sistemas denominados ERPs Áreas envolvidas Departamento tecnologia Departamento comercial / comercial / representantes Suporte 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 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

6 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 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 Aprovação A aprovação é realizada pela Área de T.I e pela fornecedora/desenvolvedora do sistema ERP Envio Toda documentação será enviada por meio eletrônico. 1.2 Visão geral Endpoints Os endpoints são mapeados como segue: Autenticação Cada operador receberá a sua api key, que deverá ser passada na URL em TODAS as requisições feitas à API. Exemplo: 2 Chapter 1. Índice

7 1.2.3 Exemplo de requisição válida Essa requisição lista toda as categorias de um determinado operador: GET 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 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 Visão geral 3

8 4 Chapter 1. Índice

9 CHAPTER 2 Resources disponíveis 2.1 Categorias Listar GET /api/v1/categories Ver GET /api/v1/categories/[id] Criar POST /api/v1/categories "category": "name": "Refrigerantes" Obrigatórios category name: Nome da categoria. Opcionais: Nenhum. 5

10 2.1.4 Atualizar PATCH /api/v1/categories/[id] "category": "name": "Refrigerantes" Obrigatórios category name: Nome da categoria. Opcionais: Nenhum Excluir DELETE /v1/categories/[id] 2.2 Clientes Listar GET /api/v1/clients Ver GET /api/v1/clients/[id] Criar POST /api/v1/clients 6 Chapter 2. Resources disponíveis

11 "client": "name": "Cliente fictício", "legal_type": "corporation", "corporate_name": "Razão social Ltda.", "cnpj": " ", "contact_name": "João Silva", "contact_phone": " ", "contact_ ": "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_ para contato notes: Observação main_location_id: id do endereço principal do cliente Atualizar PATCH /api/v1/clients/[id] "client": "name": "Novo nome" 2.2. Clientes 7

12 client é obrigatório. Pelo menos um campo deve ser passado Excluir DELETE /v1/clients/[id] 2.3 Fabricantes Listar GET /api/v1/manufacturers Ver GET /api/v1/manufacturers/[id] Criar POST /api/v1/manufacturers "manufacturer": "name": "TAURUS" Obrigatórios manufacturer name: Nome do fabricante. Opcionais: Nenhum. 8 Chapter 2. Resources disponíveis

13 2.3.4 Atualizar PATCH /api/v1/manufacturers/[id] "manufacturer": "name": "ACME" Obrigatórios manufacturer name: Nome do fabricante. Opcionais: Nenhum Excluir DELETE /v1/manufacturers/[id] 2.4 Locais Listar GET /api/v1/locations Ver GET /api/v1/locations/[id] Criar POST /api/v1/locations 2.4. Locais 9

14 "location": "name": "Nome do local", "phone": " ", "street": "Rua das Flores", "number": "123", "complement": "loja 1", "neighborhood": "Centro", "city": "Curitiba", "state": "PR", "zip_code": " " 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 Atualizar PATCH /api/v1/locations/[id] "location": "name": "Matriz" 10 Chapter 2. Resources disponíveis

15 location é obrigatório. Pelo menos um campo deve ser passado para ser atualizado Excluir DELETE /v1/locations/[id] 2.5 Máquinas Listar GET /api/v1/machines Ver GET /api/v1/machines/[id] Criar POST /api/v1/machines "machine": "asset_number": " ", "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 Máquinas 11

16 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 Excluir DELETE /v1/machines/[id] 2.6 Fabricantes de máquina Listar GET /api/v1/machine_manufacturers Ver GET /api/v1/machine_manufacturers/[id] 2.7 Modelos de máquina Listar GET /api/v1/machine_models Ver GET /api/v1/machine_models/[id] 12 Chapter 2. Resources disponíveis

17 2.8 Tipos de máquina Listar GET /api/v1/machine_types Ver GET /api/v1/machine_types/[id] 2.9 Produtos Listar GET /api/v1/vendibles Ver GET /api/v1/vendibles/[id] 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 Tipos de máquina 13

18 Opcionais: manufacturer_id: id do fabricante category_id: id da categoria upc_code: código do produto 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 Excluir DELETE /v1/vendibles/[id] 14 Chapter 2. Resources disponíveis