Desenvolvedorv1

CargaCell API

O mesmo backend da aplicação web está disponível via HTTP. Crie uma chave de API no seu perfil e autentique pedidos servidor a servidor com o cabeçalho x-api-key.

URL basehttps://www.cargacell.com/api/v1

Obter chave de API →

Início rápido

Autenticação por chave de API

Envie a sua chave no cabeçalho x-api-key em cada pedido. As sessões JWT do browser continuam a funcionar em paralelo para clientes web.

curl -X GET \
  https://www.cargacell.com/api/v1/auth/me \
  -H "x-api-key: cc_live_your_key"

Comportamento da lista branca de IP

0Qualquer IP é permitido — predefinição para novas chaves.
≥1Apenas esses endereços exatos são aceites.
RevogarA chave deixa de funcionar imediatamente; crie uma nova.

Referência de endpoints

Todos os caminhos são relativos ao URL base acima.

Os endpoints marcados como Apenas web requerem um token de sessão do browser e rejeitam a autenticação x-api-key.

Autenticação

Valide a chave e leia ou atualize o perfil da conta atual.

Método	Caminho	Descrição
POST	/auth/login	Login com e-mail e palavra-passe
GET	/auth/me	Obter utilizador autenticado atual
PATCH	/auth/me	Atualizar perfil e dados de faturação

Catálogo e carrinho

Pesquise operadores e produtos, depois crie encomendas antes do pagamento.

Método	Caminho	Descrição
GET	/catalog/countries	Listar países disponíveis
GET	/catalog/operators	Listar operadores disponíveis
GET	/catalog/recharge-products	Catálogo de recargas com filtros
GET	/cart	Obter carrinho atual
POST	/cart/items	Adicionar item ao carrinho
DELETE	/cart/items/:itemId	Remover item do carrinho

Pagamentos e carteira

Calcule preços e envie recargas com saldo da carteira. O checkout externo é apenas para sessões web.

Método	Caminho	Descrição	Tags
POST	/payments/quote	Obter cotação de preço
POST	/payments/prepare	Validar entradas do checkout web	Apenas web
POST	/payments/checkout	Concluir checkout web externo	Apenas web
GET	/payments/history	Histórico de pagamentos
GET	/wallet/balance	Saldo atual da carteira
POST	/wallet/checkout	Enviar recargas financiadas pela carteira
POST	/api-access/b2b/recharges	Recarga B2B dedicada por carteira	B2B

Administração

As contas de administrador podem usar o mesmo mecanismo de chave de API para todos os endpoints de back-office.

Método	Caminho	Descrição	Tags
GET	/admin/summary	Resumo do painel	Admin
GET	/admin/users	Gestão de utilizadores	Admin
GET	/admin/recharges	Operações de recarga	Admin
GET	/admin/payments	Operações de pagamento	Admin
GET	/admin/products	Operações de catálogo	Admin

Exemplos de código

Exemplos ao vivo que refletem o comportamento atual do backend. Alterne entre Pedido e Resposta em cada cartão.

Verificar a sua chave

Envie um pedido GET para confirmar que a autenticação funciona e inspecionar a conta associada à chave.

curl -X GET \
  https://www.cargacell.com/api/v1/auth/me \
  -H "x-api-key: cc_live_your_generated_key" \
  -H "Accept-Language: en"

Listar produtos com detalhes de promoção

Obtenha o catálogo de recargas. Os produtos com promoções ativas ou agendadas incluem detalhes completos da promo (nome, descrição, termos opcionais).

curl -X GET \
  "https://www.cargacell.com/api/v1/catalog/recharge-products?country=ES&limit=5" \
  -H "x-api-key: cc_live_your_generated_key" \
  -H "Accept-Language: en"

Adicionar item ao carrinho

Adicione uma linha de destinatário ao carrinho. Primeiro obtenha o catálogo de produtos para resolver um productId válido.

curl -X POST \
  https://www.cargacell.com/api/v1/cart/items \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "sessionId": "agent-session-001",
    "productId": "12345",
    "recipientNumber": "+5355512345",
    "quantity": 2
  }'

Recarga B2B por carteira

Endpoint B2B dedicado — ignora o MONEI completamente e envia imediatamente a partir do saldo aprovado da carteira.

curl -X POST \
  https://www.cargacell.com/api/v1/api-access/b2b/recharges \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "items": [
      {
        "productId": "12345",
        "recipientNumber": "+5355512345",
        "quantity": 2
      }
    ],
    "baseCurrency": "EUR"
  }'

Checkout genérico por carteira

Checkout padrão financiado pela carteira — funciona com chaves de API e sessões web.

curl -X POST \
  https://www.cargacell.com/api/v1/wallet/checkout \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "items": [
      {
        "productId": "12345",
        "recipientNumber": "+5355512345",
        "quantity": 1
      }
    ],
    "baseCurrency": "EUR"
  }'

Listar recargas (admin)

As chaves de API de admin podem chamar endpoints de back-office com o mesmo cabeçalho x-api-key.

curl -X GET \
  "https://www.cargacell.com/api/v1/admin/recharges?page=1&limit=20" \
  -H "x-api-key: cc_live_admin_key"

Fluxos de recarga

Existem três caminhos de envio. Escolha o que se adequa à sua integração.

Checkout com pagamento externo

Apenas web

O browser inicia um pagamento MONEI via POST /payments/prepare, depois confirma após autorização via POST /payments/checkout. Requer sessão JWT web. Chaves de API são rejeitadas.

Checkout por carteira

Chame POST /wallet/checkout com os seus itens. O backend calcula o saldo disponível a partir de top-ups aprovados menos pagamentos de carteira capturados e rejeita se insuficiente. Funciona com chaves de API e sessões web.

Recarga B2B por carteira

B2B

Chame POST /api-access/b2b/recharges. Usa o mesmo motor de carteira do caminho 2, mas foi criado para clientes de API que nunca devem interagir com o fluxo MONEI. Envia imediatamente quando o saldo é suficiente.

Em todos os caminhos financiados pela carteira, um pagamento bem-sucedido cria linhas de recarga em fila. Estas são processadas pelo processador de recarga, ou marcadas como em lista de espera quando se aplica uma janela de promoção DT One.

Gestão de chaves

Todas as operações com chaves estão disponíveis em Painel → Perfil.

Criar

Crie uma chave nomeada para cada integração ou ambiente. O valor em texto simples é mostrado apenas uma vez no momento da criação — copie-o imediatamente.

Restringir

Adicione entradas à lista branca de IP para bloquear uma chave a infraestrutura fixa — gateways de escritório, servidores worker ou IPs de saída de funções cloud.

Revogar

Revogue imediatamente chaves comprometidas ou não utilizadas. A revogação tem efeito instantâneo. Nunca reutilize chaves antigas — gere uma nova.