​

Comprar linhas telefônicas

​

Endpoint

​

Cabeçalhos

​

Corpo da requisição

​

Exemplo

curl -X POST "https://pilotstatus.com.br/v1/phone-lines" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_tenant_scoped_key" \
  -H "Idempotency-Key: 6f1c2a0e-7b1d-4c2e-9a5f-3d8e1b2c4a70" \
  -d '{ "numbers": ["551148637200", "551148637201"] }'

{
  "results": [
    {
      "number": "551148637200",
      "ok": true,
      "lineId": "cmg5k2l1n0001pl8example9x"
    },
    {
      "number": "551148637201",
      "ok": false,
      "code": "PAYMENT_FAILED",
      "error": "The payment did not go through. Add balance or check your card. | O pagamento não foi concluído. Adicione saldo ou confira seu cartão."
    }
  ]
}

​

Resposta: 200 com um resultado por número

​

Ordem das operações, por número

1. Reservar o número sob a sua Idempotency-Key (veja abaixo). Já reservado → REQUEST_ALREADY_PROCESSED.
2. Verificar que o número não pertence a nenhuma linha — de nenhum workspace, incluindo o seu — e que não há outra compra dele em andamento → caso contrário, NUMBER_UNAVAILABLE, nada é cobrado.
3. Cobrar o preço mensal cheio: primeiro os créditos da carteira, o restante no cartão salvo. Se a etapa do cartão falhar, os créditos já descontados são devolvidos → PAYMENT_FAILED.
4. Adquirir o número na operadora. Se isso falhar, o preço cheio é estornado para a sua carteira — inclusive qualquer parte paga com cartão — → NUMBER_UNAVAILABLE ou SUPPLIER_UNAVAILABLE.
5. Criar a linha: status: "ACTIVE", currentPeriodEnd um mês à frente, e o evento de webhook phone_line.purchased.

​

Erros da requisição inteira

{
  "error": "Not a number from GET /v1/phone-lines/available: +551148637201, 11948637202. Use E.164 digits without \"+\", e.g. 551148637200. | Não é um número de GET /v1/phone-lines/available: +551148637201, 11948637202. Use os dígitos E.164 sem \"+\", ex.: 551148637200.",
  "code": "INVALID_NUMBERS",
  "details": { "invalidNumbers": ["+551148637201", "11948637202"] }
}

​

Idempotência

• A chave é rastreada por número, durante uma hora. Antes de qualquer coisa, cada número é registrado sob (seu workspace, a chave, o número). Durante a hora seguinte, enviar de novo a mesma chave com esse número não cobra nada e não compra nada: o item responde ok: false, REQUEST_ALREADY_PROCESSED.
• Uma repetição não devolve o resultado original. REQUEST_ALREADY_PROCESSED volta tanto se a primeira tentativa comprou o número quanto se ela falhou. Para saber qual foi o caso, chame GET /v1/phone-lines: um número comprado está na sua lista.
• Um número que falhou fica travado sob essa chave durante a hora. Depois de um PAYMENT_FAILED, você recarrega e tenta de novo — com uma chave nova, senão a nova tentativa responde REQUEST_ALREADY_PROCESSED.
• Depois da hora, a chave é esquecida. Um número que você comprou passa a responder NUMBER_UNAVAILABLE (ele é seu — não há segunda cobrança); um número que tinha falhado é tentado de novo. Para repetir um número que falhou, use sempre uma chave nova.
• Só os números são protegidos, não a requisição. Enviar a mesma chave com um número diferente compra esse número.
• Uma requisição recusada por inteiro não registra nada. Depois de qualquer 400 ou 403 acima, corrija a requisição e reenvie-a com a mesma chave.
• Duplicatas simultâneas. Se dois envios da mesma requisição estiverem em andamento ao mesmo tempo, cada número segue em um deles; o outro recebe REQUEST_ALREADY_PROCESSED para esse número.
• Restrita ao seu workspace. A mesma chave enviada por outro workspace nunca colide com a sua.

​

Padrão recomendado de retentativa

​

Depois da compra

• A linha fica ACTIVE até currentPeriodEnd — um mês após a compra — e depois se renova mês a mês. Veja o ciclo de vida da linha.
• Solicite o código de ativação do WhatsApp com POST /v1/phone-lines/{id}/activations.