HTTP API v1

Introdução

A API do NoKYCNumber é organizada em torno de REST. Usamos URLs orientadas a recursos previsíveis, aceitamos e retornamos corpos codificados em JSON e usamos códigos de resposta HTTP padrão, autenticação e verbos.

URL base

https://api.nokycnumber.com/v1/

Todas as requisições devem ser feitas via HTTPS. Chamadas via HTTP simples falharão com 301 Moved Permanently. Requisições sem autenticação falharão com 401 Unauthenticated.

Convenção JSON

• Todas as requisições com corpo usam Content-Type: application/json. Corpos codificados como formulário são rejeitados com 415.
• Os timestamps são retornados como strings ISO-8601 UTC (2026-04-26T14:23:00Z) e aceitos no mesmo formato.
• Os números de telefone são retornados em E.164 com um + inicial (+33647189022) e formatados em display quando relevante.
• Os IDs de objeto têm prefixo do recurso: num_, call_, sms_, vm_, whk_, evt_.

Autenticação

Autentique com uma chave bearer emitida pelo seu painel em Configurações → Chaves de API. Existem dois tipos de chave:

• sk_live_… — segredo do servidor. Leitura/escrita completa. Nunca exponha no código do cliente.
• pk_live_… — chave pública. Reservada por enquanto; ainda não usada por nenhum endpoint.

Formato do header

Authorization: Bearer sk_live_5f3a8b2c4d1e9f6a7b8c2d1e9f6a7b8c
Content-Type: application/json
NoKYC-Version: 2026-04-01

Use o header NoKYC-Version para fixar uma versão específica da superfície da API (veja Versionamento). Quando omitido, o padrão fixado da sua conta é usado.

Escopos

As chaves são emitidas com um dos três escopos:

As chaves podem ser rotacionadas a qualquer momento. Chaves antigas permanecem válidas por 5 minutos após a rotação para permitir deploy sem interrupção.

Erros

A API usa códigos de status HTTP convencionais. 2xx significa sucesso, 4xx significa um problema com sua requisição, 5xx significa que cometemos um erro e gostaríamos de saber.

Envelope de erro

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Required parameter `country` is missing.",
    "param": "country",
    "request_id": "req_8a4c2f1e9b3d4a7c"
  }
}

Códigos de status

Tipos de erro

• invalid_request_error — entrada malformada, campos ausentes, formato inválido.
• authentication_error — problema com a chave.
• authorization_error — problema de escopo.
• rate_limit_error — diminua o ritmo.
• api_error — erro nosso. Pode tentar novamente.
• resource_error — o estado do recurso impede a operação (ex.: tentar fazer uma chamada de um número pausado).
• upstream_error — operadora ou parceiro não respondeu a tempo.

Toda resposta de erro inclui um request_id. Sempre registre-o — é a única forma de nosso suporte correlacionar sua chamada com o rastreamento interno.

Paginação

Os endpoints de listagem usam paginação por cursor unidirecional. Retornam até limit objetos (padrão 25, máx. 100) e um boolean has_more. Para buscar a próxima página, passe o id do último objeto como starting_after.

curl https://api.nokycnumber.com/v1/numbers?limit=10 \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "url": "/v1/numbers",
  "data": [
    { "id": "num_8a4c2f1e9b3d", "object": "number", "number": "+33647189022", … },
    { "id": "num_2k7m9p3w8x4t", "object": "number", "number": "+12025550143", … }
  ],
  "has_more": true,
  "next_cursor": "num_2k7m9p3w8x4t"
}

As listas são ordenadas com os objetos criados mais recentemente primeiro. Paginação reversa via ending_before não é suportada — use o cursor para paginar.

Idempotência

Requisições POST que alteram estado aceitam um header Idempotency-Key. Deduplicamos na chave por 24 horas, retornando a resposta em cache para novas tentativas. Use um UUID por operação lógica.

POST /v1/sms HTTP/1.1
Authorization: Bearer sk_live_…
Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e
Content-Type: application/json

{ "from": "num_8a4c2f1e9b3d", "to": "+33612345678", "body": "Hello" }

Repetir a mesma chave com conteúdo de corpo diferente retorna 409 Conflict com idempotency_key_mismatch.

Chaves de idempotência não são obrigatórias, mas são fortemente recomendadas para qualquer operação que custe dinheiro (chamadas, SMS, compra de números). Sem uma, uma nova tentativa de rede pode cobrar em dobro.

Limites de taxa

Por padrão, cada chave de API está limitada a 100 requisições por minuto. Clientes de alto volume podem solicitar aumento ao suporte. Os limites são aplicados por chave, não por IP.

Headers de resposta

X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 73
X-Rate-Limit-Reset: 1745672460
Retry-After: 8

Quando você excede o limite, recebe 429 Too Many Requests com um header Retry-After em segundos. Backoff linear de até 4 tentativas é recomendado; se persistir, solicite um limite maior.

Tolerância a picos

O limitador é um token bucket — picos curtos acima de 100 rpm são tolerados desde que a média móvel de 60 segundos permaneça abaixo do limite.

Versionamento

As versões da API têm datas (2026-04-01). Mudanças incompatíveis são lançadas como nova versão datada; adições compatíveis vão para a versão atual. Fixe uma versão com o header NoKYC-Version.

Compatibilidade

• Oferecemos suporte a cada versão por pelo menos 24 meses após o próximo lançamento.
• Avisos de depreciação são enviados por e-mail aos titulares de conta com 90 dias de antecedência.
• Um header de resposta NoKYC-Deprecation avisa quando você está usando uma versão desatualizada.

Versão atual: 2026-04-01.

Números

Um número representa uma linha telefônica virtual que você controla. Os números estão vinculados a um país e a um tipo (mobile ou landline) e têm um período de cobrança.

curl https://api.nokycnumber.com/v1/numbers?country=fr&type=mobile \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "data": [
    {
      "id": "num_8a4c2f1e9b3d",
      "object": "number",
      "number": "+33647189022",
      "display": "+33 6 47 18 90 22",
      "country": "fr",
      "type": "mobile",
      "tier": "standard",
      "status": "active",
      "billing_period": "yearly",
      "renews_at": "2027-04-26T11:23:00Z",
      "ai_enabled": true,
      "created_at": "2026-04-26T11:23:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl "https://api.nokycnumber.com/v1/numbers/available?country=fr&type=mobile&tier=premium&limit=5" \
  -H "Authorization: Bearer sk_live_…"

{
  "object": "list",
  "data": [
    { "id": "navail_2k7m9p3w8x4t", "number": "+33611112222", "display": "+33 6 11 11 22 22", "tier": "premium", "pattern": "double-repeat", "price_usd_per_month": 11.98 },
    { "id": "navail_4n2v8j1q6h7y", "number": "+33612345678", "display": "+33 6 12 34 56 78", "tier": "premium", "pattern": "sequential",    "price_usd_per_month": 11.98 }
  ],
  "expires_at": "2026-04-26T11:33:00Z"
}

curl https://api.nokycnumber.com/v1/numbers \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e" \
  -d '{
    "available_id":   "navail_2k7m9p3w8x4t",
    "billing_period": "yearly",
    "addons":         ["ai-pickup"]
  }'

{
  "id": "num_8a4c2f1e9b3d",
  "object": "number",
  "number": "+33611112222",
  "display": "+33 6 11 11 22 22",
  "country": "fr",
  "type": "mobile",
  "tier": "premium",
  "status": "active",
  "billing_period": "yearly",
  "renews_at": "2027-04-26T11:23:00Z",
  "ai_enabled": true,
  "created_at": "2026-04-26T11:23:00Z"
}

curl https://api.nokycnumber.com/v1/numbers/num_8a4c2f1e9b3d \
  -H "Authorization: Bearer sk_live_…"

curl -X DELETE https://api.nokycnumber.com/v1/numbers/num_8a4c2f1e9b3d \
  -H "Authorization: Bearer sk_live_…"

Chamadas

Uma chamada é uma sessão de voz originada em um dos seus números. Chamadas de saída são feitas via POST /v1/calls; chamadas de entrada são espelhadas no seu webhook e também podem ser consultadas via API.

curl https://api.nokycnumber.com/v1/calls \
  -H "Authorization: Bearer sk_live_…" \
  -d '{
    "from": "num_8a4c2f1e9b3d",
    "to":   "+33612345678",
    "callerid_mask": "rotate"
  }'

{
  "id": "call_2k7m9p3w8x4t",
  "object": "call",
  "from": "num_8a4c2f1e9b3d",
  "from_e164": "+33647189022",
  "to": "+33612345678",
  "status": "ringing",
  "direction": "outbound",
  "started_at": "2026-04-26T11:24:01Z",
  "answered_at": null,
  "ended_at": null,
  "duration_sec": 0,
  "recording_url": null,
  "cost_usd": null
}

Mensagens SMS

Enviar e recuperar SMS. Mensagens longas são auto-segmentadas conforme as regras GSM-03.38 / UCS-2; a resposta mostra a contagem real de segmentos para cobrança.

curl https://api.nokycnumber.com/v1/sms \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 9b3d4a7c-8a4c-2f1e-9b3d-4a7c8a4c2f1e" \
  -d '{
    "from": "num_8a4c2f1e9b3d",
    "to":   "+33612345678",
    "body": "Bonjour. Your code is 482917."
  }'

{
  "id": "sms_4n2v8j1q6h7y",
  "object": "sms",
  "from_e164": "+33647189022",
  "to": "+33612345678",
  "body": "Bonjour. Your code is 482917.",
  "direction": "outbound",
  "segments": 1,
  "status": "queued",
  "created_at": "2026-04-26T11:24:50Z",
  "delivered_at": null,
  "cost_usd": 0.012
}

Caixas postais

As caixas postais são armazenadas, transcritas e traduzidas automaticamente. As URLs de áudio são pré-assinadas e expiram 1 hora após a emissão.

{
  "id": "vm_5p3w8x4t9k2m",
  "object": "voicemail",
  "number_id": "num_8a4c2f1e9b3d",
  "from_e164": "+33612345678",
  "received_at": "2026-04-26T11:25:42Z",
  "duration_sec": 27,
  "audio_url": "https://files.nokycnumber.com/vm/5p3w8x4t9k2m.mp3?expires=1745676342&sig=…",
  "transcript": {
    "text": "Bonjour, c'est Marc. Rappelez-moi quand vous pouvez.",
    "language": "fr",
    "translation_en": "Hello, this is Marc. Call me back when you can.",
    "summary": "Marc asks for a callback.",
    "sentiment": "neutral"
  }
}

Configuração de IA

Cada número pode executar um agente de IA que atende chamadas quando você não atende, triagem de chamadas desconhecidas, resumo de caixas postais ou tradução de conversas ao vivo. Configure por número via o sub-recurso de IA.

{
  "object": "ai_config",
  "number_id": "num_8a4c2f1e9b3d",
  "addons": ["ai-pickup", "ai-summary"],
  "auto_pickup": {
    "enabled": true,
    "after_rings": 4,
    "script": "I'm unavailable right now. Leave your name, the reason for the call, and a callback number.",
    "language": "auto",
    "voice": "neutral_fr"
  },
  "screening": { "enabled": false },
  "translator": { "enabled": false, "target_language": "en" },
  "voicemail_summary": { "enabled": true, "include_sentiment": true }
}

Vozes

Vozes disponíveis: neutral_en, neutral_fr, neutral_es, neutral_de, neutral_jp, warm_en, warm_fr. Vozes clonadas personalizadas para empresas sob consulta.

Conta

Ler dados da conta: saldo, estatísticas de uso, webhooks configurados.

{
  "object": "account",
  "email_hash": "9b3d4a7c8a4c2f1e",
  "balance_usd": 47.32,
  "default_country": "fr",
  "active_numbers": 3,
  "monthly_call_minutes": 412,
  "monthly_sms_segments": 1820,
  "created_at": "2026-04-12T09:15:00Z"
}

Webhooks

Assine eventos da sua conta ou de números específicos. Fazemos POST de um evento JSON no seu endpoint e tentamos novamente até 5 vezes com backoff exponencial em 24 horas.

Envelope de evento

{
  "id": "evt_3d4a7c8a4c2f",
  "object": "event",
  "type": "sms.received",
  "created": "2026-04-26T11:25:42Z",
  "livemode": true,
  "data": { "object": { "id": "sms_…", … } },
  "request_id": "req_8a4c2f1e9b3d4a7c"
}

Verificação de assinatura

Cada requisição carrega um header X-NoKYC-Signature no formato t=<ts>,v1=<hex>. A assinatura é HMAC-SHA256 de <ts>.<raw_body> usando o segredo de assinatura do endpoint. Rejeite qualquer requisição com mais de 5 minutos.

# Pseudocode
ts, v1 = parse(header)
if abs(now - ts) > 300: reject
expected = hmac_sha256(secret, f"{ts}.{body}")
if not constant_time_eq(expected, v1): reject

Endpoints

Tipos de evento

Schemas de objeto

number

{
  "id":             "string · num_…",
  "object":         "string · constant \"number\"",
  "number":         "string · E.164",
  "display":        "string · pretty-printed",
  "country":        "string · ISO-2",
  "type":           "enum · mobile | landline",
  "tier":           "enum · standard | premium",
  "tier_pattern":   "string | null · double-repeat | sequential | mirror | round | …",
  "status":         "enum · active | paused | released",
  "billing_period": "enum · monthly | quarterly | yearly",
  "renews_at":      "string · ISO-8601 UTC",
  "auto_renew":     "boolean",
  "addons":         "array · ai-pickup | ai-screen | ai-summary | ai-trans",
  "ai_enabled":     "boolean",
  "metadata":       "object | null",
  "created_at":     "string · ISO-8601 UTC"
}

call

{
  "id":             "string · call_…",
  "object":         "string · constant \"call\"",
  "from":           "string · num_…",
  "from_e164":      "string · E.164",
  "to":             "string · E.164",
  "direction":      "enum · inbound | outbound",
  "status":         "enum · queued | ringing | in_progress | completed | failed | no_answer | busy",
  "started_at":     "string · ISO-8601 UTC",
  "answered_at":    "string | null",
  "ended_at":       "string | null",
  "duration_sec":   "integer",
  "recording_url":  "string | null · pre-signed, expires in 1h",
  "cost_usd":       "number | null"
}

sms

{
  "id":             "string · sms_…",
  "object":         "string · constant \"sms\"",
  "from":           "string · num_…",
  "from_e164":      "string · E.164",
  "to":             "string · E.164",
  "body":           "string",
  "media_urls":     "array · up to 5",
  "direction":      "enum · inbound | outbound",
  "segments":       "integer · 1–10",
  "status":         "enum · queued | sent | delivered | failed | undelivered",
  "failure_code":   "string | null",
  "created_at":     "string · ISO-8601 UTC",
  "delivered_at":   "string | null",
  "cost_usd":       "number | null"
}

SDKs oficiais

A HTTP API é a fonte de verdade, mas esses SDKs fornecem bindings tipados, novas tentativas, idempotência e verificação de webhook prontos para uso.

• node npm install @nokycnumber/sdk
• python pip install nokycnumber
• go go get github.com/nokycnumber/sdk-go
• php composer require nokycnumber/sdk
• ruby gem install nokycnumber