Documentação B2B

API B2B – consultar informações de pedidos e produtos de forma automatizada

Nossa API REST está disponível para todo cliente com conta de cliente e permite consultar informações de pedidos e produtos de forma automatizada e integrá-las aos seus próprios sistemas.

vpn_key Abrir acesso à API na conta Página de clientes corporativos

Autenticação

Todas as solicitações da API exigem uma API-Key válida, enviada no cabeçalho HTTP. O acesso à API está vinculado à sua conta de cliente e está disponível, em princípio, para contas de cliente.

info Você não precisa de um pedido B2B separado: faça login com a sua conta de cliente, abra a aba da API e gere ali a sua API-Key. Ir para o acesso à API →

Formato do cabeçalho

HTTP Request Header

X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

Exemplo com cURL

cURL

curl -X GET "https://artumos.com/api/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

Base URL

Todos os endpoints são relativos à seguinte Base URL:

Base URL

https://artumos.com/api/v1

Todas as respostas são retornadas como JSON retornado (Content-Type: application/json).

Rate Limits

Plan	Solicitações / minuto	Solicitações / dia
Conta de cliente	60	5.000
Limite estendido	sob consulta	sob consulta

Em caso de excesso é HTTP 429 Too Many Requests retornado. O cabeçalho Retry-After contém o tempo de espera em segundos.

Códigos de erro

HTTP-Code	Significado
`200 OK`	Solicitação bem-sucedida
`400 Bad Request`	Parâmetros inválidos
`401 Unauthorized`	API-Key ausente ou inválida
`403 Forbidden`	Sem permissão para este recurso
`404 Not Found`	Recurso não encontrado
`429 Too Many Requests`	Rate Limit excedido
`500 Internal Server Error`	Erro de servidor – entre em contato com o suporte

Formato da Response de erro

JSON

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Endpoint: Pedidos

GET /api/v1/orders Todos os pedidos da conta

Parameter	Tipo	Descrição
`page`	integer	Página (padrão: 1)
`per_page`	integer	Entradas por página (máx. 100)
`status`	string	`paid` \| `pending` \| `all`

Beispiel-Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ORD-12345",
        "status": "paid",
        "total": 49.99,
        "currency": "EUR",
        "created_at": "2026-01-15T10:30:00Z",
        "items_count": 2
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 42
    }
  }
}

GET /api/v1/orders/{order_id} Consultar um pedido individual

Endpoint: Informações de produto e pedido

GET /api/v1/orders/{order_id}/codes Todas as informações de produto de um pedido

Beispiel-Response

{
  "success": true,
  "data": {
    "order_id": "ORD-12345",
    "codes": [
      {
        "id": "CODE-789",
        "product_name": "Beispielprodukt vom Marktplatz",
        "product_sku": "ART-PRODUCT-001",
        "product_info": "Hinweise laut Verkäuferangaben",
        "delivery_url": "https://...",
        "delivered_at": "2026-01-15T10:31:00Z",
        "status": "active"
      }
    ]
  }
}

GET /api/v1/codes/{code_id} Consultar uma informação de produto individual

warning As informações de produto e pedido só podem ser usadas no âmbito do respectivo pedido e das informações do vendedor. A divulgação abusiva pode violar os termos de uso.

Endpoint: Produtos

GET /api/v1/products Consultar catálogo de produtos

Parameter	Tipo	Descrição
`category`	string	Filtrar por slug de categoria
`in_stock`	boolean	Apenas produtos disponíveis
`page`	integer	Página

Beispiel-Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": 42,
        "sku": "ART-PRODUCT-001",
        "name": "Beispielprodukt vom Marktplatz",
        "price": 49.99,
        "currency": "EUR",
        "in_stock": true,
        "category": "handmade"
      }
    ]
  }
}

Webhooks

Webhooks permitem receber notificações em tempo real quando pedidos ou códigos são disponibilizados. As URLs de Webhook podem ser cadastradas na conta do cliente.

Eventos disponíveis

Event	Descrição
`order.paid`	O pedido foi pago
`codes.delivered`	Os códigos foram disponibilizados
`order.refunded`	O pedido foi reembolsado

Webhook Payload

POST – Seu endpoint de Webhook

{
  "event": "codes.delivered",
  "timestamp": "2026-01-15T10:31:05Z",
  "data": {
    "order_id": "ORD-12345",
    "codes_count": 2
  },
  "signature": "sha256=..."
}

Verifique a assinatura com o seu Webhook-Secret: HMAC-SHA256(payload, webhook_secret)

Perguntas frequentes

Quem pode usar a API B2B?

Todo cliente com conta de cliente pode usar o acesso à API. Faça login na sua conta de cliente e use a API-Key correspondente para solicitações autenticadas.

Qual é o formato das respostas?

Todas as respostas são retornadas como JSON. O objeto raiz sempre contém success: true/false bem como data ou error.

Posso fazer pedidos pela API?

Na primeira versão, a API serve para a consulta de pedidos e de informações de pedido e produto. Endpoints de escrita de pedidos serão liberados separadamente assim que estiverem disponíveis.

Existe um ambiente de sandbox?

Sim. O sandbox pode ser ativado na conta do cliente, na aba „Acesso à API“, e está vinculado diretamente à respectiva API-Key.