API públicaReferência por operaçãoComprar números

Criar pagamento de um número

Cria um pedido de exatamente um DID. Pix retorna copia e cola e imagem QR; cartão retorna checkoutUrl para o cliente concluir a assinatura. Exige Idempotency-Key no cabeçalho. Criar o pedido não significa pagamento confirmado ou número ativado. HTTP 409 did_number_unavailable: não foi possível confirmar o telefone selecionado antes de criar o pagamento. Consulte o pedido indicado em error.details.orderId e atualize o catálogo antes de uma nova tentativa; não repita uma cobrança sem conferir o pedido anterior.

Catálogo, cotação, pagamento e acompanhamento de um DID por pedido.

Base: https://novodid.com. Consulte autenticação e limites antes de executar operações.

Criar pagamento de um número

POST /api/v1/orders

Cria um pedido de exatamente um DID. Pix retorna copia e cola e imagem QR; cartão retorna checkoutUrl para o cliente concluir a assinatura. Exige Idempotency-Key no cabeçalho. Criar o pedido não significa pagamento confirmado ou número ativado. HTTP 409 did_number_unavailable: não foi possível confirmar o telefone selecionado antes de criar o pagamento. Consulte o pedido indicado em error.details.orderId e atualize o catálogo antes de uma nova tentativa; não repita uma cobrança sem conferir o pedido anterior.

Permissão: orders:create

Idempotency-Key: 16–128 letras, números, hífen ou sublinhado. Gere uma chave para cada nova intenção de compra e reutilize a mesma chave e o mesmo corpo nas repetições. Outra compra precisa de outra chave.
A reserva pendente vale somente para o DID escolhido e dura no máximo 15 minutos desde a criação do pedido. Outros DIDs podem ser comprados durante esse período, respeitando os limites da conta. A mesma chave com dados diferentes retorna 409 idempotency_conflict. Em timeout, consulte o pedido ou repita a mesma chave; não gere outra cobrança.
409 checkout_initializing indica que outra compra da conta ainda está sendo preparada. Aguarde alguns instantes e repita com a mesma Idempotency-Key e o mesmo corpo. Essa espera ocorre somente na criação, não durante os 15 minutos para pagamento.
409 order_expired indica que a resposta de criação chegou após o prazo do pedido. Nenhum QR Code ou link vencido é entregue. Consulte details.orderId antes de iniciar outra compra e não pague instruções antigas.
Fixos exigem fixedDidSmsAcknowledged=true. Planos móveis sem SMS exigem mobileMonthlySmsAcknowledged=true quando indicado na cotação. Não aceite essas condições automaticamente em nome do cliente.
Em ofertas temporárias de números móveis, os ciclos disponíveis e a inclusão de SMS podem variar. Consulte sempre a cotação: did.smsEnabled informa se o plano inclui SMS, e acknowledgements.mobileMonthlySms.required indica se é necessário enviar mobileMonthlySmsAcknowledged=true após o aceite do cliente. Apesar do nome, esses campos se aplicam a qualquer ciclo móvel sem SMS. A cotação não garante a oferta; as condições são conferidas novamente ao criar o pagamento. Pagamentos emitidos durante a oferta preservam suas condições até a validade do próprio pagamento. Após o encerramento, novas compras seguem as condições vigentes, e contratações concluídas mantêm seu ciclo e a condição de SMS nas renovações enquanto permanecerem vigentes. Isso não representa garantia de preço. Conta apta, verificação, limites, estoque disponível e um número por pedido continuam obrigatórios.
Para comprar, use um token sem restrição a posses de números existentes. O escopo não permite usar cartão salvo nem efetuar pagamento sem ação do cliente.
A reserva pendente expira em até 15 minutos, inclusive se a criação falhar ou o pedido precisar de análise. Isso não confirma cancelamento externo instantâneo nem reembolso. Não pague instruções vencidas; um pagamento confirmado após a expiração será analisado sem substituir outra reserva ou posse. Pagamentos já confirmados e números ativos continuam protegidos. Em review_required, contate o suporte com o ID do pedido.

Corpo da requisição

{
  "didId": 1234,
  "quantity": 1,
  "cycle": "monthly",
  "paymentMethod": "pix",
  "fixedDidSmsAcknowledged": true
}

Resposta de sucesso (201)

{
  "order": {
    "id": "11111111-1111-4111-8111-111111111111",
    "didId": 1234,
    "quantity": 1,
    "status": "awaiting_payment",
    "paymentMethod": "pix",
    "currency": "BRL",
    "amount": 1499,
    "createdAt": "2026-09-23T15:00:00.000Z",
    "expiresAt": "2026-09-23T15:15:00.000Z",
    "checkoutUrl": null,
    "pix": {
      "copyPaste": "PIX_COPY_AND_PASTE_EXAMPLE",
      "qrCodeDataUrl": "data:image/png;base64,EXAMPLE"
    }
  }
}

Exemplo de erro

{
  "error": {
    "code": "checkout_in_progress",
    "message": "Este número já tem um pedido pendente. A reserva dura até 15 minutos. Você pode escolher outro número."
  }
}

curl

curl -X POST \
  -H "Idempotency-Key: order_example_20260923_01" \
  -H "Authorization: Bearer $NOVODID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"didId":1234,"quantity":1,"cycle":"monthly","paymentMethod":"pix","fixedDidSmsAcknowledged":true}' \
  "https://novodid.com/api/v1/orders"

Node

const response = await fetch("https://novodid.com/api/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NOVODID_API_TOKEN}`,
    "Idempotency-Key": "order_example_20260923_01",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "didId": 1234,
  "quantity": 1,
  "cycle": "monthly",
  "paymentMethod": "pix",
  "fixedDidSmsAcknowledged": true
})
});
const payload = await response.json();

if (!response.ok) {
  throw new Error(payload.error?.message || "Erro na API NovoDID");
}

console.log({ status: response.status });

Python

import os
import requests

response = requests.post(
    "https://novodid.com/api/v1/orders",
    headers={"Idempotency-Key": "order_example_20260923_01", "Authorization": f"Bearer {os.environ['NOVODID_API_TOKEN']}"},
    json={
  "didId": 1234,
  "quantity": 1,
  "cycle": "monthly",
  "paymentMethod": "pix",
  "fixedDidSmsAcknowledged": True
},
    timeout=30,
)

payload = response.json()
response.raise_for_status()
print({"status": response.status_code})

Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://novodid.com/api/v1/orders", strings.NewReader(`{"didId":1234,"quantity":1,"cycle":"monthly","paymentMethod":"pix","fixedDidSmsAcknowledged":true}`))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Idempotency-Key", "order_example_20260923_01")
    req.Header.Set("Authorization", "Bearer "+os.Getenv("NOVODID_API_TOKEN"))
    req.Header.Set("Content-Type", "application/json")

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    _, _ = io.Copy(io.Discard, res.Body)
    if res.StatusCode >= 300 {
        panic(fmt.Sprintf("NovoDID API HTTP %d", res.StatusCode))
    }

    fmt.Println(res.StatusCode)
}

Rust

use serde_json::json;
use reqwest::blocking::Client;
use std::env;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let response = client
        .post("https://novodid.com/api/v1/orders")
        .header("Idempotency-Key", "order_example_20260923_01")
        .bearer_auth(env::var("NOVODID_API_TOKEN")?)
        .json(&json!({
  "didId": 1234,
  "quantity": 1,
  "cycle": "monthly",
  "paymentMethod": "pix",
  "fixedDidSmsAcknowledged": true
}))
        .send()?;

    let status = response.status();
    let _payload = response.text()?;
    if !status.is_success() {
        return Err(format!("NovoDID API HTTP {}", status).into());
    }

    println!("HTTP {}", status);
    Ok(())
}

PHP

<?php

$ch = curl_init("https://novodid.com/api/v1/orders");

curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Idempotency-Key: order_example_20260923_01",
    "Authorization: Bearer " . getenv("NOVODID_API_TOKEN"),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => '{"didId":1234,"quantity":1,"cycle":"monthly","paymentMethod":"pix","fixedDidSmsAcknowledged":true}',
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($response === false || $status >= 300) {
  throw new RuntimeException("NovoDID API HTTP " . $status);
}

echo $status . PHP_EOL;

Ruby

require "net/http"

uri = URI("https://novodid.com/api/v1/orders")
request = Net::HTTP::Post.new(uri)
request["Idempotency-Key"] = "order_example_20260923_01"
request["Authorization"] = "Bearer #{ENV.fetch("NOVODID_API_TOKEN")}"
request["Content-Type"] = "application/json"
request.body = %q({"didId":1234,"quantity":1,"cycle":"monthly","paymentMethod":"pix","fixedDidSmsAcknowledged":true})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

raise "NovoDID API HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)

puts response.code

C#

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://novodid.com/api/v1/orders");

request.Headers.Add("Idempotency-Key", "order_example_20260923_01");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer",
    Environment.GetEnvironmentVariable("NOVODID_API_TOKEN")
);

request.Content = new StringContent(
    """
{
  "didId": 1234,
  "quantity": 1,
  "cycle": "monthly",
  "paymentMethod": "pix",
  "fixedDidSmsAcknowledged": true
}
""",
    Encoding.UTF8,
    "application/json"
);

using var response = await client.SendAsync(request);
var payload = await response.Content.ReadAsStringAsync();

response.EnsureSuccessStatusCode();
Console.WriteLine(response.StatusCode);

Cotar a compra de um número

Valida os requisitos da conta e calcula uma assinatura de um DID. Não cria cobrança nem reserva o número. Apresente preço, recorrência e condições de SMS ao cliente antes de criar o pedido.

Consultar um pedido

Consulta apenas pedidos da conta autenticada. Substitua {orderId} pelo UUID retornado na criação. Retorna as instruções de pagamento enquanto o pedido aguarda pagamento. Pedido de outra conta retorna 404.

Nesta página

Criar pagamento de um número Corpo da requisição Resposta de sucesso (201)Exemplo de erro curl Node Python Go Rust PHP Ruby C#