API Reference

Documentação completa de todos os endpoints da API Vpay. Use os exemplos abaixo para integrar sua aplicação.

🔧 Variáveis da API

Configure estas variáveis para usar nos exemplos abaixo

Variável	Valor	Descrição
`base_url`	https://api.vpay.co.mz	URL base da API
`client_id`	—	Client ID obtido no dashboard
`client_secret`	—	Client Secret obtido no dashboard
`access_token`	—	Token gerado após autenticação
`refresh_token`	—	Token para renovar acesso
`product_id`	—	ID do produto (preencher após criar)
`customer_id`	—	ID do cliente (preencher após criar)
`plan_id`	—	ID do plano (preencher após criar)
`subscription_id`	—	ID da assinatura (preencher após criar)
`order_id`	—	ID do pedido (preencher após criar)

⚠️ O access_token é preenchido automaticamente após autenticação. O refresh_token é obtido na resposta da autenticação.

1. Authentication

Endpoints para autenticação e gerenciamento de tokens

POST/v1/auth/token

Gerar token de acesso usando Client ID e Secret

Exemplo de payload

{
  "client_id": "seu_client_id",
  "client_secret": "seu_client_secret"
}

POST/v1/auth/token/refresh

Renovar token de acesso usando refresh token

Exemplo de payload

{
  "refresh_token": "seu_refresh_token"
}

POST/v1/auth/token/revoke

Revogar token de acesso

Exemplo de payload

{
  "token": "token_a_revogar"
}

GET/v1/auth/token/list

Listar todos os tokens ativos do cliente

2. Products

Gerenciamento de produtos e catálogo

POST/v1/products/create

Criar um novo produto

Exemplo de payload

{
  "name": "Smartphone XYZ",
  "description": "Latest generation smartphone with 128GB",
  "price": 2499.99,
  "imageUrl": "https://example.com/images/smartphone.jpg",
  "originProductId": "ERP-2026-002",
  "metadata": {
    "brand": "TechBrand",
    "model": "XYZ-2024",
    "color": "Black"
  }
}

GET/v1/products

Listar todos os produtos

GET/v1/products/{{product_id}}

Buscar produto por ID

POST/v1/products/sync

Sincronizar um único produto (cria ou atualiza)

Exemplo de payload

{
  "originProductId": "ERP-2026-002",
  "name": "Smartphone XYZ Pro",
  "description": "Smartphone de última geração",
  "price": 2999.9,
  "imageUrl": "https://images.example.com/smartphone.jpg",
  "metadata": {
    "brand": "XYZ Tech",
    "category": "eletrônicos"
  }
}

POST/v1/products/sync/batch

Sincronizar múltiplos produtos em lote

Exemplo de payload

{
  "products": [
    {
      "originProductId": "ERP-2026-001",
      "name": "Smartphone XYZ Pro",
      "price": 2999.9
    },
    {
      "originProductId": "ERP-2026-002",
      "name": "Notebook Ultra Slim",
      "price": 5499.9
    }
  ]
}

3. Customers

Gerenciamento de clientes

POST/v1/customers

Criar um novo cliente

Exemplo de payload

{
  "name": "João Silva",
  "email": "joao.silva@email.com",
  "phone": "+258 82 123 4567",
  "addressLine": "Rua 1234, Nº 45",
  "city": "Maputo",
  "postalCode": "1100",
  "taxId": "123456789",
  "merchantCustomerId": "CLIENTE-001",
  "metadata": {
    "segment": "premium",
    "birthDate": "1990-05-15"
  }
}

GET/v1/customers

Listar todos os clientes

GET/v1/customers/{{customer_id}}

Buscar cliente por ID

POST/v1/customers/sync

Sincronizar um único cliente (cria ou atualiza)

Exemplo de payload

{
  "merchantCustomerId": "CLIENTE-001",
  "name": "João Silva",
  "email": "joao.silva@email.com",
  "phone": "+258 82 123 4567",
  "addressLine": "Rua 1234, Nº 45",
  "city": "Maputo",
  "postalCode": "1100",
  "taxId": "123456789"
}

POST/v1/customers/sync/batch

Sincronizar múltiplos clientes em lote

Exemplo de payload

{
  "customers": [
    {
      "merchantCustomerId": "ERP-CUSTOMER-001",
      "name": "João Silva",
      "email": "joao.silva@email.com"
    },
    {
      "merchantCustomerId": "ERP-CUSTOMER-002",
      "name": "Maria Santos",
      "email": "maria.santos@email.com"
    }
  ]
}

4. Plans

Gerenciamento de planos de assinatura

POST/v1/plans

Criar um novo plano

Exemplo de payload

{
  "name": "Plano Basic",
  "description": "Plano com recursos essenciais",
  "price": 49.9,
  "interval": "monthly",
  "intervalCount": 1,
  "metadata": {
    "features": [
      "5 produtos",
      "1 usuário"
    ],
    "level": "basic"
  }
}

GET/v1/plans

Listar todos os planos

GET/v1/plans/{{plan_id}}

Buscar plano por ID

POST/v1/plans/sync

Sincronizar um único plano

Exemplo de payload

{
  "originPlanId": "ERP-PLAN-001",
  "name": "Plano Basic",
  "price": 49.9,
  "interval": "monthly"
}

POST/v1/plans/sync/batch

Sincronizar múltiplos planos

Exemplo de payload

{
  "plans": [
    {
      "originPlanId": "ERP-PLAN-001",
      "name": "Plano Basic",
      "price": 49.9,
      "interval": "monthly"
    },
    {
      "originPlanId": "ERP-PLAN-002",
      "name": "Plano Premium",
      "price": 149.9,
      "interval": "monthly"
    }
  ]
}

5. Subscriptions

Gerenciamento de assinaturas

POST/v1/subscriptions

Criar assinatura (com dados novos)

Exemplo de payload

{
  "plan": {
    "originPlanId": "ERP-PLAN-001",
    "name": "Plano Basic",
    "price": 49.9,
    "interval": "monthly"
  },
  "customer": {
    "merchantCustomerId": "CLIENTE-001",
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "name": "Assinatura João Silva",
  "description": "Assinatura do plano basic",
  "maxAttempts": 3,
  "originSubscriptionId": "ERP-SUB-001"
}

POST/v1/subscriptions

Criar assinatura (com dados existentes)

Exemplo de payload

{
  "plan": {
    "planId": "plan_abc123"
  },
  "customer": {
    "customerId": "cus_abc123"
  },
  "name": "Assinatura João Silva",
  "maxAttempts": 3
}

POST/v1/subscriptions/sync

Sincronizar assinatura (cria ou obtém)

Exemplo de payload

{
  "originSubscriptionId": "ERP-SUB-001",
  "plan": {
    "originPlanId": "ERP-PLAN-001",
    "name": "Plano Basic",
    "price": 49.9,
    "interval": "monthly"
  },
  "customer": {
    "merchantCustomerId": "CLIENTE-001",
    "name": "João Silva",
    "email": "joao@email.com"
  }
}

GET/v1/subscriptions

Listar todas as assinaturas

GET/v1/subscriptions/{{subscription_id}}

Buscar assinatura por ID

6. Orders

Criação e gerenciamento de pedidos

POST/v1/orders

Criar pedido (com dados novos)

Exemplo de payload

{
  "source": {
    "source": "api"
  },
  "customer": {
    "merchantCustomerId": "CUS-123",
    "name": "Maria Santos",
    "email": "maria@email.com"
  },
  "items": [
    {
      "originProductId": "ERP-SMARTPRO-001",
      "name": "Smartphone Pro Max",
      "quantity": 2,
      "price": 3999.9
    }
  ]
}

POST/v1/orders

Criar pedido (com dados existentes)

Exemplo de payload

{
  "source": {
    "source": "api"
  },
  "customer": {
    "customerId": "8a90c950-4ca1-42a1-89b3-543038d15633"
  },
  "items": [
    {
      "productId": "9982ba76-8e8a-4161-9722-f456cadad719",
      "quantity": 1
    }
  ]
}

POST/v1/orders

Criar pedido com shipping address

Exemplo de payload

{
  "source": {
    "source": "api"
  },
  "customer": {
    "name": "Ana Pereira",
    "email": "ana@email.com",
    "phone": "+258 84 987 6543"
  },
  "shippingAddress": {
    "street": "Avenida 24 de Julho",
    "number": "100",
    "city": "Maputo",
    "zipCode": "1100",
    "country": "MZ"
  },
  "items": [
    {
      "originProductId": "prod_notebook_001",
      "name": "Notebook Ultra Slim",
      "quantity": 1,
      "price": 5499.9
    }
  ]
}

POST/v1/orders

Criar pedido com shipping e delivery desabilitados

Exemplo de payload

{
  "source": {
    "source": "api"
  },
  "customer": {
    "name": "Rui Mendes",
    "email": "rui@email.com"
  },
  "shippingAddressDisabled": true,
  "deliveryInfoDisabled": true,
  "items": [
    {
      "originProductId": "ERP-CONSULTING-001",
      "name": "Serviço de Consultoria",
      "quantity": 5,
      "price": 300
    }
  ]
}

POST/v1/orders

Criar pedido com shipping cost

Exemplo de payload

{
  "source": {
    "source": "api"
  },
  "customer": {
    "name": "Joana Costa",
    "email": "joana@email.com",
    "phone": "+258 82 888 7777"
  },
  "shippingAddress": {
    "street": "Rua dos Combatentes",
    "number": "25",
    "city": "Beira",
    "zipCode": "2100",
    "country": "MZ"
  },
  "shippingCost": 250,
  "items": [
    {
      "productId": "c325e9d6-fc1b-4583-9da1-9648a02ac0fd",
      "quantity": 1
    }
  ]
}

GET/v1/orders

Listar todos os pedidos com paginação

GET/v1/orders/{{order_id}}

Buscar pedido completo por ID

GET/v1/orders/{{order_id}}/status

Consultar status do pedido (para polling)

Teste rápido

Siga os passos abaixo para validar sua configuração

Configure as variáveis base_url, client_id e client_secret
Execute a requisição POST /v1/auth/token
O token será armazenado automaticamente na variável access_token
Teste qualquer endpoint protegido, como GET /v1/products

v2.0.0

Comunidade Suporte

Variável

Valor

Descrição

base_url

https://api.vpay.co.mz

URL base da API

client_id

—

Client ID obtido no dashboard

client_secret

—

Client Secret obtido no dashboard

access_token

—

Token gerado após autenticação

refresh_token

—

Token para renovar acesso

product_id

—

ID do produto (preencher após criar)

customer_id

—

ID do cliente (preencher após criar)

plan_id

—

ID do plano (preencher após criar)

subscription_id

—

ID da assinatura (preencher após criar)

order_id

—

ID do pedido (preencher após criar)

{ "name": "Smartphone XYZ", "description": "Latest generation smartphone with 128GB", "price": 2499.99, "imageUrl": "https://example.com/images/smartphone.jpg", "originProductId": "ERP-2026-002", "metadata": { "brand": "TechBrand", "model": "XYZ-2024", "color": "Black" } }

{ "originProductId": "ERP-2026-002", "name": "Smartphone XYZ Pro", "description": "Smartphone de última geração", "price": 2999.9, "imageUrl": "https://images.example.com/smartphone.jpg", "metadata": { "brand": "XYZ Tech", "category": "eletrônicos" } }

{ "products": [ { "originProductId": "ERP-2026-001", "name": "Smartphone XYZ Pro", "price": 2999.9 }, { "originProductId": "ERP-2026-002", "name": "Notebook Ultra Slim", "price": 5499.9 } ] }

{ "name": "João Silva", "email": "joao.silva@email.com", "phone": "+258 82 123 4567", "addressLine": "Rua 1234, Nº 45", "city": "Maputo", "postalCode": "1100", "taxId": "123456789", "merchantCustomerId": "CLIENTE-001", "metadata": { "segment": "premium", "birthDate": "1990-05-15" } }

{ "merchantCustomerId": "CLIENTE-001", "name": "João Silva", "email": "joao.silva@email.com", "phone": "+258 82 123 4567", "addressLine": "Rua 1234, Nº 45", "city": "Maputo", "postalCode": "1100", "taxId": "123456789" }

{ "customers": [ { "merchantCustomerId": "ERP-CUSTOMER-001", "name": "João Silva", "email": "joao.silva@email.com" }, { "merchantCustomerId": "ERP-CUSTOMER-002", "name": "Maria Santos", "email": "maria.santos@email.com" } ] }

{ "name": "Plano Basic", "description": "Plano com recursos essenciais", "price": 49.9, "interval": "monthly", "intervalCount": 1, "metadata": { "features": [ "5 produtos", "1 usuário" ], "level": "basic" } }

{ "plans": [ { "originPlanId": "ERP-PLAN-001", "name": "Plano Basic", "price": 49.9, "interval": "monthly" }, { "originPlanId": "ERP-PLAN-002", "name": "Plano Premium", "price": 149.9, "interval": "monthly" } ] }

{ "plan": { "originPlanId": "ERP-PLAN-001", "name": "Plano Basic", "price": 49.9, "interval": "monthly" }, "customer": { "merchantCustomerId": "CLIENTE-001", "name": "João Silva", "email": "joao@email.com" }, "name": "Assinatura João Silva", "description": "Assinatura do plano basic", "maxAttempts": 3, "originSubscriptionId": "ERP-SUB-001" }

{ "originSubscriptionId": "ERP-SUB-001", "plan": { "originPlanId": "ERP-PLAN-001", "name": "Plano Basic", "price": 49.9, "interval": "monthly" }, "customer": { "merchantCustomerId": "CLIENTE-001", "name": "João Silva", "email": "joao@email.com" } }

{ "source": { "source": "api" }, "customer": { "merchantCustomerId": "CUS-123", "name": "Maria Santos", "email": "maria@email.com" }, "items": [ { "originProductId": "ERP-SMARTPRO-001", "name": "Smartphone Pro Max", "quantity": 2, "price": 3999.9 } ] }

{ "source": { "source": "api" }, "customer": { "customerId": "8a90c950-4ca1-42a1-89b3-543038d15633" }, "items": [ { "productId": "9982ba76-8e8a-4161-9722-f456cadad719", "quantity": 1 } ] }

{ "source": { "source": "api" }, "customer": { "name": "Ana Pereira", "email": "ana@email.com", "phone": "+258 84 987 6543" }, "shippingAddress": { "street": "Avenida 24 de Julho", "number": "100", "city": "Maputo", "zipCode": "1100", "country": "MZ" }, "items": [ { "originProductId": "prod_notebook_001", "name": "Notebook Ultra Slim", "quantity": 1, "price": 5499.9 } ] }

{ "source": { "source": "api" }, "customer": { "name": "Rui Mendes", "email": "rui@email.com" }, "shippingAddressDisabled": true, "deliveryInfoDisabled": true, "items": [ { "originProductId": "ERP-CONSULTING-001", "name": "Serviço de Consultoria", "quantity": 5, "price": 300 } ] }

{ "source": { "source": "api" }, "customer": { "name": "Joana Costa", "email": "joana@email.com", "phone": "+258 82 888 7777" }, "shippingAddress": { "street": "Rua dos Combatentes", "number": "25", "city": "Beira", "zipCode": "2100", "country": "MZ" }, "shippingCost": 250, "items": [ { "productId": "c325e9d6-fc1b-4583-9da1-9648a02ac0fd", "quantity": 1 } ] }