Integre os serviços Force ao seu sistema

Autenticação

A equipe Force cria uma chave vinculada à sua revenda. Envie-a em todas as chamadas:

Authorization: Bearer ft_live_SEU_TOKEN
Accept: application/json
Content-Type: application/json

Escopos

• catalog:read — planos e disponibilidade.
• orders:read — consultar seus pedidos.
• orders:write — criar pedidos.
• wallet:read — saldo e extrato.
• wallet:write — recarregar saldo.
• numbers:activate — ligar o número (subir a linha).
• numbers:read — status da ativação.
• sms:read — ler os SMS recebidos (inclui o código).

Rotas

Escolha do número

GET /virtual-numbers/available/{ddd} devolve uma vitrine curta — até 5 opções, não o estoque inteiro do DDD:

{ "ddd": "11", "numeros": ["935851986", "935851987", "935851988"] }

Os números já vêm normalizados (9 dígitos, sem DDD colado e sem máscara), no mesmo formato que numero_escolhido / numeros_escolhidos aceitam de volta — basta devolver o escolhido no POST. Operadora fora do ar responde 502 com message e sem o campo numeros.

Ativar número e receber o SMS

1. POST /virtual-numbers/orders/{order}/activate liga a linha e devolve { "request_id": "..." } (202).

2. Faça poll em GET /virtual-numbers/orders/{order}/status até ultimo_request.estado == "WAITING_SMS".

3. Só então peça o código no WhatsApp. Pedir antes joga o SMS num chip sem registro e ele fica retido ~10 min na operadora; pedindo depois, chega em 26–100s.

4. Faça poll em GET /virtual-numbers/orders/{order}/sms até vir a mensagem com extracted_code.

Carteira e recarga

A revenda se abastece sozinha. POST /wallet/topups abre uma recarga e devolve o Pix:

{ "valor": 500.00 }

{
  "id": "9f1c...", "valor": 500.0, "status": "pendente",
  "pix_copy_paste": "00020126...5802BR", "qr_code": "data:image/png;base64,...",
  "expira_em": "2026-08-22T11:00:00-03:00", "pago_em": null
}

Valor livre acima de um mínimo (hoje R$ 50; o vigente vem em GET /wallet). Abrir a recarga não credita nada — o saldo só se move quando o pagamento é confirmado na fonte, e aí status vira pago. Acompanhe por GET /wallet/topups/{id}; reenvio de confirmação não credita duas vezes.

Webhook

Em vez de consultar o status da recarga, receba o aviso. A equipe Force cadastra sua URL (https) e entrega um segredo — mostrado uma única vez. GET /webhook diz o que está configurado para você.

X-Force-Event: wallet.topup.paid
X-Force-Event-Id: 1910c654-199c-5c5a-bf4c-477d8f4f2bbe
X-Force-Timestamp: 1787289600
X-Force-Signature: sha256=<hmac>

{
  "event": "wallet.topup.paid",
  "event_id": "1910c654-...",
  "data": { "topup_id": "9f1c...", "valor": 500.0, "pago_em": "...", "saldo": 530.10 }
}

Responda 2xx para confirmar. Qualquer outra coisa (ou timeout de 10s) é retentada 5 vezes, com espera crescente de 1min, 5min, 15min e 1h. Uma entrega pode chegar mais de uma vez: use o X-Force-Event-Id, estável por evento, para ignorar repetição.

Consulta de pedidos

As rotas GET /virtual-numbers/orders, /chips/orders e /rentals/orders são paginadas no formato padrão do Laravel (data, current_page, last_page, total, per_page).

• per_page — padrão 25, mínimo 1, máximo 100. Valores fora da faixa são contidos, não recusados.
• status — filtra por status do pedido.

Exemplo

curl -H "Authorization: Bearer ft_live_SEU_TOKEN" \
  -H "Accept: application/json" \
  https://management.navitelecom.com.br/api/partners/v1/chips/plans

O reseller_id é obtido exclusivamente da chave. Tentativas de atribuir o pedido a outra revenda são ignoradas.

Erros e limites

401 chave inválida ou revogada · 403 revenda/escopo sem acesso · 422 dados inválidos · 429 limite excedido.

Limite inicial: 120 chamadas por minuto.

Toda chamada tem um identificador para rastrear no suporte, e ele aparece em um lugar diferente conforme o desfecho: credencial aceita devolve o header X-Request-Id; credencial recusada (401/403) devolve request_id no corpo — justamente o caso em que você mais vai precisar dele. Guarde os dois.