Geliştiriciler için API

API, kendi web siteniz veya uygulamanız üzerinden geçici SMS numaralarını yeniden satmanızı sağlar. Müşterilerinizin Ativa SMS'yi ziyaret etmesi gerekmez.

Hesap oluşturun ve kontrol paneli profil menüsündeki Numara satın seçeneğinden erişim isteyin. Bayilik şartlarının kabul edilmesi zorunludur; Kullanım şartları da geçerlidir. Onaylandıktan sonra Kontrol paneli → API bölümünde anahtar oluşturun.

Temel URL: https://www.ativasms.store/api/v1. İstek gövdeleri için Content-Type: application/json ile UTF-8 JSON gönderin. Yanıtlar JSON'dur ve Cache-Control: no-store içerir.

Tutarlar tam sayı sentlerdir: moeda hesabınıza göre BRL veya USD olur; 83 BRL senti R$ 0.83 anlamına gelir. Test modu her zaman BRL kullanır. Tarihler ISO 8601 UTC'dir. Telefon numaraları uluslararası +ülke-kodu formatındadır veya rezervasyon sürerken null olur.

Örnekler açıklama amaçlıdır ve gerçek yanıt formatlarını izler; satın alma örnekleri kurgusal test verileri kullanır. API'nin döndürdüğü hizmet kodlarını ve seçenekleri kullanın; live fiyatlar değişir. curl örnekleri ATIVA_API_KEY değerini sunucunuzdaki bir ortam değişkeninden okur.

Araçlar ve yapay zeka ajanları için OpenAPI 3.1 belirtimi: /openapi.json.

Her uç noktada Authorization: Bearer <key> gönderin. Anahtarlar üretim için ativa_live_, test için ativa_test_ ile başlar. Anahtarlar sorgu dizelerinde veya gövdelerde kabul edilmez.

Anahtar, oluşturulduğunda bir kez gösterilir. Sunucunuzda saklayın, asla müşterinin tarayıcısında veya uygulamasında saklamayın. Bir hesapta live ve test anahtarları birlikte sayılarak en fazla 5 etkin anahtar bulunabilir. Kaybolan veya açığa çıkan anahtarları kontrol panelinde iptal edin ve değiştirin. IP kısıtlaması yapılandırılmışsa istekler buna da uymalıdır.

Kimlik doğrulama hataları, nedeni açıklamadan aynı HTTP 401 yanıtını döndürür:

{
  "erro": "nao_autorizado",
  "mensagem": "Chave de API ausente, inválida ou revogada."
}

Varsayılan sınırlar her bayi için ayarlanabilir. Hesabınızın güncel sınırlarını kontrol panelinde inceleyin:

Sınır	Varsayılan
Dakika başına istek	120
Dakika başına satın alma/değiştirme	20
Aynı anda SMS bekleyen numaralar	20
24 h içinde hesap başına kodsuz denemeler	100
24 h içinde cliente_ref başına kodsuz denemeler	15

İstek ve satın alma hızları, aynı mod içindeki tüm hesap anahtarlarını birlikte sayar. Test ve live sayımları ayrıdır ve aynı yapılandırılmış sınırları kullanır. SMS olmadan iptaller, değiştirmeler ve süre dolmaları deneme tüketir; kod alan her numara, sınıra kadar 5 deneme geri kazandırır. Teslimat hataları sayılmaz. Açık numaralar ve denemeler için live hesap sınırları, web sitesinden yapılan satın almaları da kapsar.

İstek veya satın alma hızını aşmak HTTP 429 muitas_requisicoes ve Retry-After: 60 (saniye) döndürür. Diğer sınırlar kendi kodlarıyla ve Retry-After olmadan 429 döndürür: duruma göre açık numaraların veya denemelerin serbest kalmasını bekleyin.

Satın alma ve değiştirmeler için Idempotency-Key zorunludur: 1–64 harf, rakam veya . _ : -. Amaçlanan her işlem için yeni anahtar, yeniden denemeler için aynı anahtar kullanın. Anahtarların kapsamı hesap ve moddur; satın alma ve değiştirmeler bu kapsamı paylaşır. Farklı müşteri veya sipariş için anahtarı yeniden kullanmayın.

Kaydedilmiş anahtarın tekrarı, gövde değişmiş olsa bile aynı numara ve güncel durumuyla HTTP 200 döndürür; yeni satın alma 201 döndürür. Live sorguları 24 h sonra durmaz: kayıt var olduğu sürece anahtar o numaraya işaret eder. Test geçmişi 30 gün saklanır. Test bakiyesini sıfırlamak geçmişi ve idempotency'yi korur.

preco_maximo_centavos, hesap para biriminizde kabul ettiğiniz en yüksek tutardır. Güncel fiyat bunu aşarsa API, satın almadan preco_centavos ve opcoes ile preco_acima_do_maximo döndürür. preco_centavos bakiyenizden düşülür; preco_site_centavos web sitesinin referans fiyatıdır. Fiyat satın alma anında tekrar kontrol edilir.

GET /saldo

Parametre yoktur. Bakiyeyi hesap para biriminde (BRL veya USD) döndürür. Test modu her zaman BRL ve kurgusal fonlar kullanır.

curl "https://www.ativasms.store/api/v1/saldo" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "saldo_centavos": 10000,
  "moeda": "BRL"
}

GET /servicos

Parametre yoktur. Yinelenen veya engellenmiş hizmetler olmadan tüm kullanılabilir hizmetleri döndürür. Örnek bir kayıt gösterir; test modu teste_falha (Teste sem código) hizmetini de içerir. API alan adları ve hizmet etiketleri, belgelerin dilinden bağımsız olarak Portekizce kalır.

curl "https://www.ativasms.store/api/v1/servicos" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

[
  {
    "codigo": "wa",
    "nome": "WhatsApp"
  }
]

GET /paises

Parametre yoktur. Tüm ülkeleri döndürür. Sorgularda ve satın almalarda codigo kullanın; iso büyük harflidir, ddi ise telefon arama kodudur. Örnek bir kayıt gösterir.

curl "https://www.ativasms.store/api/v1/paises" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

[
  {
    "codigo": 73,
    "iso": "BR",
    "nome": "Brasil",
    "ddi": "+55"
  }
]

GET /opcoes

Zorunlu sorgu parametreleri: servico (hizmet listesindeki bir kod) ve pais (sayısal ülke kodu). Artan preco_centavos sırasıyla en fazla 6 seçenek döndürür; sonuç [] olabilir. opcao opak bir tanımlayıcıdır: op_ ve ardından 12 onaltılık karakter. Döndürülen değeri yorumlamadan geri gönderin. preco_centavos bayiden alınan tutardır; preco_site_centavos web sitesinin referans fiyatıdır ve ikisi de belirtilen para birimindedir. prazo_min süredir; taxa_sucesso null olabilir; estoque kullanılabilirliği belirtir ve recomendada önerilen seçeneği işaretler. Bu örnek kurgusal test seçeneğini kullanır.

curl "https://www.ativasms.store/api/v1/opcoes?servico=wa&pais=73" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

[
  {
    "opcao": "op_000000000001",
    "preco_centavos": 83,
    "preco_site_centavos": 120,
    "moeda": "BRL",
    "prazo_min": 20,
    "taxa_sucesso": null,
    "estoque": 100,
    "recomendada": false
  }
]

POST /numeros

Zorunlu JSON alanları: servico (1–20 küçük harf, rakam veya _; izin verilen bir hizmet), pais (geçerli tam sayı ülke kodu), preco_maximo_centavos (pozitif tam sayı) ve cliente_ref (1–64 harf, rakam veya . _ : - içeren anonim tanımlayıcı; asla e-posta adresi veya kişisel tanımlayıcı kullanmayın). opcao isteğe bağlıdır ve null olabilir; belirtilmezse en ucuz seçenek seçilir. Idempotency-Key gönderin. Yeni satın alma 201 döndürür; tekrar, ek ücret almadan aynı id ve güncel durumla 200 döndürür. Bu bir test satın alma örneğidir.

curl -X POST "https://www.ativasms.store/api/v1/numeros" \
  -H "Authorization: Bearer $ATIVA_API_KEY" \
  -H "Idempotency-Key: compra_abc123" \
  -H "Content-Type: application/json" \
  -d '{"servico":"wa","pais":73,"opcao":"op_000000000001","preco_maximo_centavos":83,"cliente_ref":"cliente_abc123"}'

HTTP 201

{
  "id": "5f0c0000-0000-4000-8000-000000000001",
  "servico": "wa",
  "servico_nome": "WhatsApp",
  "pais": 73,
  "telefone": "+12025550123",
  "status": "aguardando_sms",
  "motivo": null,
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "cancelavel_em": "2026-10-08T12:02:00.000Z",
  "expira_em": "2026-10-08T12:20:00.000Z",
  "encerrado_em": null,
  "substitui_id": null,
  "cliente_ref": "cliente_abc123",
  "sms": []
}

GET /numeros/{id}

Yol: /numeros/{id}; id numaranın UUID'sidir. Yalnızca bu hesaba ve moda ait API satın almaları görünür; başka sahibin numarası, web sitesi satın alması veya geçersiz UUID, nao_encontrado döndürür. Açık numaralar yanıt öncesinde live anahtar başına dakikada en fazla 60 kez güncellenir; sonraki istekler son kullanılabilir durumu döndürür (200, ek bir senkronizasyon 429'u olmadan). Bu örnek alınmış bir test kodunu gösterir.

curl "https://www.ativasms.store/api/v1/numeros/5f0c0000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "id": "5f0c0000-0000-4000-8000-000000000001",
  "servico": "wa",
  "servico_nome": "WhatsApp",
  "pais": 73,
  "telefone": "+12025550123",
  "status": "recebido",
  "motivo": null,
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "cancelavel_em": "2026-10-08T12:02:00.000Z",
  "expira_em": "2026-10-08T12:20:00.000Z",
  "encerrado_em": null,
  "substitui_id": null,
  "cliente_ref": "cliente_abc123",
  "sms": [
    {
      "codigo": "123456",
      "texto": "Seu código de teste: 123456",
      "recebido_em": "2026-10-08T12:00:20.000Z"
    }
  ]
}

GET /numeros

İsteğe bağlı sorgu parametreleri: status (belgelenmiş numara durumu), cliente_ref (satın almadaki formatla aynı), pagina (1–1000, varsayılan 1). Bu hesap ve mod için sayfa başına en fazla 50 API satın almasını, en yeniler önce olacak şekilde döndürür. tem_mais başka bir sayfa olduğunu belirtir. live numaraları listelemek güncellemeyi zorlamaz; güncellemek için tek bir numarayı sorgulayın.

curl "https://www.ativasms.store/api/v1/numeros?status=aguardando_sms&cliente_ref=cliente_abc123&pagina=1" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "numeros": [
    {
      "id": "5f0c0000-0000-4000-8000-000000000001",
      "servico": "wa",
      "servico_nome": "WhatsApp",
      "pais": 73,
      "telefone": "+12025550123",
      "status": "aguardando_sms",
      "motivo": null,
      "preco_centavos": 83,
      "preco_site_centavos": 120,
      "moeda": "BRL",
      "criado_em": "2026-10-08T12:00:00.000Z",
      "cancelavel_em": "2026-10-08T12:02:00.000Z",
      "expira_em": "2026-10-08T12:20:00.000Z",
      "encerrado_em": null,
      "substitui_id": null,
      "cliente_ref": "cliente_abc123",
      "sms": []
    }
  ],
  "pagina": 1,
  "tem_mais": false
}

POST /numeros/{id}/cancelar

Yol: /numeros/{id}/cancelar. İsteğe bağlı gövde alanı: motivo (desistiu, banido, ja_tem_dono, pede_outra_coisa veya outro; varsayılan outro). Kod yoksa ve cancelavel_em geçmişse numarayı kapatır ve bakiyeyi iade eder. Bu zamandan önce: segundos ile 409 cedo. Zaten kod almış numara nao_cancelavel döndürür; iptal sırasında kod gelirse codigo_recebido oluşabilir. Kapatılmış numarayla 200 döndürür. Bu örnek iki dakika sonra teste_falha kullanır.

curl -X POST "https://www.ativasms.store/api/v1/numeros/5f0c0000-0000-4000-8000-000000000001/cancelar" \
  -H "Authorization: Bearer $ATIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"motivo":"desistiu"}'

HTTP 200

{
  "id": "5f0c0000-0000-4000-8000-000000000001",
  "servico": "teste_falha",
  "servico_nome": "Teste sem código",
  "pais": 73,
  "telefone": "+12025550123",
  "status": "cancelado",
  "motivo": "desistiu",
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "cancelavel_em": "2026-10-08T12:02:00.000Z",
  "expira_em": "2026-10-08T12:20:00.000Z",
  "encerrado_em": "2026-10-08T12:02:01.000Z",
  "substitui_id": null,
  "cliente_ref": "cliente_abc123",
  "sms": []
}

POST /numeros/{id}/trocar

Yol: /numeros/{id}/trocar. Zorunlu gövde alanı: preco_maximo_centavos (pozitif tam sayı); opcao ve motivo yukarıdaki formatlarda isteğe bağlıdır. Hizmet, ülke ve cliente_ref asıl numaradan devralınır. Idempotency-Key ve telefonu olan, kodu olmayan, iptal bekleme süresi dolmuş bir aguardando_sms numarası gerektirir. Eski numara kapatılmadan önce fiyat kontrol edilir. Eski numara trocado olur ve iade edilir; yeni satın alma 201 döndürür (tekrar 200 döndürür). Yeni satın alma iadeden sonra başarısız olursa eski numara trocado kalır: sorgulayın ve hatayı ele alın. Bu örnek iki dakika sonra bir teste_falha numarasını değiştirir.

curl -X POST "https://www.ativasms.store/api/v1/numeros/5f0c0000-0000-4000-8000-000000000001/trocar" \
  -H "Authorization: Bearer $ATIVA_API_KEY" \
  -H "Idempotency-Key: troca_abc123" \
  -H "Content-Type: application/json" \
  -d '{"preco_maximo_centavos":83,"motivo":"banido"}'

HTTP 201

{
  "id": "5f0c0000-0000-4000-8000-000000000002",
  "servico": "teste_falha",
  "servico_nome": "Teste sem código",
  "pais": 73,
  "telefone": "+12025550124",
  "status": "aguardando_sms",
  "motivo": null,
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:02:01.000Z",
  "cancelavel_em": "2026-10-08T12:04:01.000Z",
  "expira_em": "2026-10-08T12:22:01.000Z",
  "encerrado_em": null,
  "substitui_id": "5f0c0000-0000-4000-8000-000000000001",
  "cliente_ref": "cliente_abc123",
  "sms": []
}

POST /numeros/{id}/concluir

Yol: /numeros/{id}/concluir. Gövde yoktur. Kodun kullanıldığını onaylar ve recebido numarasını iadesiz kapatır. concluido numarasıyla 200 döndürür; tamamlamayı tekrarlamak veya kod olmadan tamamlamak 409 nao_concluivel döndürür.

curl -X POST "https://www.ativasms.store/api/v1/numeros/5f0c0000-0000-4000-8000-000000000001/concluir" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "id": "5f0c0000-0000-4000-8000-000000000001",
  "servico": "wa",
  "servico_nome": "WhatsApp",
  "pais": 73,
  "telefone": "+12025550123",
  "status": "concluido",
  "motivo": null,
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "cancelavel_em": "2026-10-08T12:02:00.000Z",
  "expira_em": "2026-10-08T12:20:00.000Z",
  "encerrado_em": "2026-10-08T12:01:00.000Z",
  "substitui_id": null,
  "cliente_ref": "cliente_abc123",
  "sms": [
    {
      "codigo": "123456",
      "texto": "Seu código de teste: 123456",
      "recebido_em": "2026-10-08T12:00:20.000Z"
    }
  ]
}

GET /extrato

İsteğe bağlı sorgu parametresi: pagina (1–1000, varsayılan 1). live modda web sitesi işlemleri dahil en fazla 50 hesap hareketini en yeniler önce olacak şekilde döndürür (satın alma, iade, yükleme, düzeltme). valor_centavos işaretlidir: borçlar için negatif, alacaklar için pozitif; saldo_apos_centavos işlem sonrası bakiyedir. İşlem bir numarayla ilişkili değilse numero_id null olur; descricao null olabilir. Döküm moeda içermez: GET /saldo'daki para birimini kullanın. Test dökümleri ayrıdır ve her zaman BRL kullanır.

curl "https://www.ativasms.store/api/v1/extrato?pagina=1" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "movimentacoes": [
    {
      "id": 42,
      "tipo": "compra",
      "valor_centavos": -83,
      "saldo_apos_centavos": 9917,
      "descricao": "Número WhatsApp",
      "numero_id": "5f0c0000-0000-4000-8000-000000000001",
      "criado_em": "2026-10-08T12:00:00.000Z"
    }
  ],
  "pagina": 1,
  "tem_mais": false
}

Satın aldıktan sonra telefon numarasını müşterinize gösterin ve kodu hedef uygulamada istemesini söyleyin. Numara satın almak otomatik olarak SMS istemez. Test modu teslimatı simüle eder.

Status	Anlamı
aguardando_sms	Bekliyor; null telefon, rezervasyonun sürdüğü anlamına gelebilir.
recebido	En az bir SMS geldi; iptal ve değiştirme kullanılamaz.
concluido	Kod aldıktan sonra manuel olarak veya süre sonunda kapatıldı.
cancelado	Kodsuz iptal edildi ve iade edildi.
trocado	Önceki numara değiştirme sırasında kapatıldı ve iade edildi.
expirado	Süre kod olmadan doldu; otomatik iade.
falhou	Satın alma/teslimat başarısız; fonlar iade edildi.

Numara nesneleri servico_nome, motivo, moeda, preco_site_centavos (null olabilir), encerrado_em, substitui_id (değiştirmede önceki numaranın id'si) ve sms içerir. İptal, süre dolma ve kapanış tarihleri null olabilir. Her SMS, codigo ve texto (her biri null olabilir) ile recebido_em içerir.

cancelavel_em değerine uyun: bazı seçenekler hemen iptale izin verir; diğerleri 2 dakika gerektirir. cedo hatası kalan beklemeyi belirtir:

{
  "erro": "cedo",
  "mensagem": "Este número ainda não pode ser cancelado. Tente de novo após `segundos`.",
  "segundos": 45
}

Süre içinde SMS gelmezse fonlar otomatik olarak bakiyeye döner. Live numaralarda, kapanıştan önce geç SMS'ler için 5 dakikalık ek süre olabilir. expira_em değerini ve döndürülen durumu izleyin. Kod geldikten sonra numarayı tamamlamak iadesiz kapatır; kod almış numaralar iptal edilemez veya değiştirilemez. Değiştirme sırasında yeni numarayı satın alma hatası, eskisini trocado ve iade edilmiş durumda bırakabilir.

Hatalar erro ve mensagem (Portekizce) içerir. Mesajı eşleştirmek yerine kodu işleyin. Ek alanlar campos, segundos, preco_centavos ve opcoes içerebilir.

Kod	HTTP	Ne zaman oluşur
nao_autorizado	401	Eksik, geçersiz veya iptal edilmiş anahtar, izin verilmeyen IP veya askıya alınmış erişim; aynı genel yanıt nedeni gizler.
parametro_invalido	400	Geçersiz alan, sorgu veya gövde; düzeltilecek alanları listeleyen campos içerebilir.
servico_bloqueado	400	Engellenmiş bir hizmet istendi.
idempotencia_obrigatoria	400	Satın alma veya değiştirmede eksik veya hatalı Idempotency-Key.
saldo_insuficiente	402	Satın alma için yetersiz fon.
cliente_bloqueado	403	cliente_ref bu hesap için engellenmiş.
nao_encontrado	404	Geçersiz UUID veya bu hesap ve mod için kullanılamayan numara.
sem_numeros	409	Bu hizmet ve ülke için numara yok; ücret alınmaz.
opcao_indisponivel	409	Seçilen seçenek artık kullanılamıyor; güncel opcoes içerir.
preco_acima_do_maximo	409	Güncel fiyat maksimumu aşıyor; ücret alınmadan preco_centavos ve opcoes içerir.
preco_subiu	409	Satın alma sırasında fiyat değişti; tutar iade edildi.
cedo	409	İptal veya değiştirme için çok erken; beklemeyi segundos içinde belirtir.
codigo_recebido	409	Alınan kod değiştirmeyi engelliyor veya kod iptal sırasında geldi.
nao_cancelavel	409	Durum, zaten recebido olan numara dahil iptale izin vermiyor.
nao_trocavel	409	Telefon yok, numara kapalı veya durum değiştirmeyle uyumsuz.
nao_concluivel	409	İkinci tamamlama talebi dahil numara recebido durumunda değil.
muitas_requisicoes	429	İstek veya satın alma hızı aşıldı; Retry-After: 60.
limite_abertas	429	SMS bekleyen çok fazla numara; Retry-After yok.
limite_tentativas	429	Hesabın 24 h içindeki kodsuz denemeleri tükendi; Retry-After yok.
limite_tentativas_cliente	429	Bu cliente_ref için 24 h içindeki kodsuz denemeler tükendi; Retry-After yok.
erro_fornecedor	502	Numara teslimi başarısız oldu; tutar iade edildi.
sem_confirmacao	502	Satın alma onaylanmadı; aynı Idempotency-Key ile yeniden deneyin. 10 dakika içinde numara teslim edilmezse tutar iade edilir.
erro_interno	500	Beklenmeyen hata; satın almaları ve değiştirmeleri aynı idempotency anahtarıyla yeniden deneyin.

Kontrol paneli → API bölümünde herkese açık bir HTTPS URL yapılandırın. Dahili adresler, URL kimlik bilgileri ve fragment'ler reddedilir; yönlendirmeler izlenmez. Sır, oluşturulduğunda veya yenilendiğinde bir kez gösterilir: sunucunuzda saklayın. Yalnızca URL'yi değiştirmek sırrı korur; webhook'u kaldırmak yapılandırmasını siler. Her teslimat denemesi güncel URL ve sırrı kullanır.

Olaylar JSON POST istekleri olarak gönderilir:

• numero.codigo_recebido: her yeni SMS için bir bildirim; dados.sms, SMS dizisi yerine codigo, texto ve recebido_em içeren bir nesnedir. Bir numara, kapanış sonrası geç SMS'ler dahil birden çok bildirim alabilir.
• numero.encerrado: concluido, cancelado, trocado, expirado veya falhou; belirtilen para biriminde motivo (null olabilir), encerrado_em ve estornado_centavos (iade yoksa sıfır) içerir.
• teste.ping: kontrol panelinden istenen, numara veya ücret içermeyen teslimat testi.

Zarf id (dados.id'den farklı olan bildirimin UUID'si), evento, criado_em ve dados içerir. Numara olayları dados içinde id, cliente_ref, servico, pais, telefone (veya null), status ve moeda içerir. Test numaralarının olayları zarfa modo: "test" ekler; live olaylar ve kontrol paneli ping'i bu alanı içermez. Örnekler:

{
  "id": "a7100000-0000-4000-8000-000000000001",
  "evento": "numero.codigo_recebido",
  "criado_em": "2026-10-08T12:00:20.000Z",
  "modo": "test",
  "dados": {
    "id": "5f0c0000-0000-4000-8000-000000000001",
    "cliente_ref": "cliente_abc123",
    "servico": "wa",
    "pais": 73,
    "telefone": "+12025550123",
    "status": "recebido",
    "moeda": "BRL",
    "sms": {
      "codigo": "123456",
      "texto": "Seu código de teste: 123456",
      "recebido_em": "2026-10-08T12:00:20.000Z"
    }
  }
}

{
  "id": "a7100000-0000-4000-8000-000000000002",
  "evento": "numero.encerrado",
  "criado_em": "2026-10-08T12:20:00.000Z",
  "modo": "test",
  "dados": {
    "id": "5f0c0000-0000-4000-8000-000000000001",
    "cliente_ref": "cliente_abc123",
    "servico": "teste_falha",
    "pais": 73,
    "telefone": "+12025550123",
    "status": "expirado",
    "moeda": "BRL",
    "motivo": "prazo",
    "encerrado_em": "2026-10-08T12:20:00.000Z",
    "estornado_centavos": 83
  }
}

{
  "id": "a7100000-0000-4000-8000-000000000003",
  "evento": "teste.ping",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "dados": {
    "mensagem": "Teste de webhook do Ativa SMS"
  }
}

Başlıklar:

• X-Ativa-Evento: olay adı.
• X-Ativa-Timestamp: her denemede yenilenen, saniye cinsinden Unix zaman damgası.
• X-Ativa-Assinatura: sırrı onaltılıktan çözmeden metin olarak kullanarak timestamp + "." + body ifadesinin UTF-8 baytları üzerinden hesaplanan küçük harfli onaltılık HMAC-SHA256.

JSON'u ayrıştırmadan önce ham gövdeyi doğrulayın; yeniden serileştirme imzayı değiştirebilir. Güncel saatten her iki yönde 5 dakikadan fazla farklı zaman damgalarını reddedin. Uzunlukları kontrol ettikten sonra crypto.timingSafeEqual ile karşılaştırın. Bu Node.js örneği Request/Headers ve asıl gövdeyi içeren Buffer kullanır:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verificarWebhook(headers, corpoBruto, segredo) {
  const timestamp = headers.get("x-ativa-timestamp") ?? "";
  const assinatura = headers.get("x-ativa-assinatura") ?? "";
  if (!/^\d{1,12}$/.test(timestamp)) return false;
  const agora = Math.floor(Date.now() / 1000);
  if (Math.abs(agora - Number(timestamp)) > 300) return false;
  if (!/^[0-9a-f]{64}$/.test(assinatura)) return false;
  const esperada = createHmac("sha256", segredo)
    .update(timestamp + ".", "utf8")
    .update(corpoBruto)
    .digest();
  const recebida = Buffer.from(assinatura, "hex");
  return recebida.length === esperada.length
    && timingSafeEqual(recebida, esperada);
}

export async function lerAviso(request, segredo) {
  const corpoBruto = Buffer.from(await request.arrayBuffer());
  if (!verificarWebhook(request.headers, corpoBruto, segredo)) {
    throw new Error("assinatura_invalida");
  }
  return JSON.parse(corpoBruto.toString("utf8"));
}

Doğrulamadan sonra kalıcı depolamada bildirim id değerine göre yinelenenleri ayıklayın ve asenkron işlemden önce alındığını kaydedin. Daha önce kabul edilen tekrarlar dahil hızla 2xx döndürün. Teslimat zaman aşımı 5 s'dir. Tam olarak bir kez teslim garanti edilmez: kaybolan yanıt tekrara neden olabilir.

Toplam en fazla 8 deneme. 1–7. hatalardan sonra beklemeler, denemenin tamamlanmasından itibaren 1, 2, 4, 8, 16, 32 ve 64 dakika olur; teslimatlar her dakika kontrol edilir. Yalnızca HTTP 2xx teslimatı onaylar; 3xx, diğer hatalar ve zaman aşımları yeniden denemeyi tetikler. Sekizinci hatadan sonra otomatik yeniden gönderim yoktur. id ve gövde denemeler arasında aynı kalır; zaman damgası ve imza yenilenir. Bildirim eksikse GET /numeros/{id} sorgulayın.

Kontrol panelinde ativa_test_ anahtarı oluşturun ve aynı uç noktaları ve temel URL'yi kullanın. Gerçek fon alınmaz. Başlangıç kurgusal bakiyesi, gerçek hesap para biriminden bağımsız olarak R$ 100.00 (10000 BRL senti) tutarındadır. Seçenek op_000000000001: kurgusal fiyat R$ 0.83, web sitesi referansı R$ 1.20, 20 dakika ömür ve 2 dakika sonra iptal.

Telefonlar, +1 202 555-01xx aralığında, +12025550123 gibi boşluksuz döndürülen kurgusal numaralardır; seçtiğiniz ülke pais içinde kalır. 123456 kodu 20 s sonra kullanılabilir olur; bundan sonra numarayı sorgulamak durumunu günceller, webhook ise sonraki dakikada gelebilir.

Kod almamak ve kurgusal iadeyle iptal, değiştirme (2 dakika sonra) veya süre dolmasını (20 dakika sonra) test etmek için servico=teste_falha kullanın. Diğer hizmetler iptal beklemesi bitmeden kodu alır. Kodlu test numaraları süre dolunca concluido olur.

Kontrol panelinde bakiyeyi R$ 100.00'e sıfırlayın: kodsuz açık numaralar iptal edilir; kodlular tamamlanır. Sıfırlama geçmişi, denemeleri, idempotency'yi ve anahtarları korur; dakika başına sınırları sıfırlamaz. Sonraki satın almanız için yeni Idempotency-Key kullanın. Test geçmişi 30 gün sonra temizlenir.

Live ve test anahtarları karışmaz: numaralar, bakiyeler, dökümler, kullanım sayımları ve idempotency ayrıdır. Yapılandırılan sınırlar ve cliente_ref engelleri her iki modda da geçerlidir. Kontrol paneli ping'i yalnızca teslimatı test eder; modo: "test" işleyişini denemek için test anahtarıyla numara satın alın.

• Ağ hatalarından sonra Idempotency-Key'i yeniden kullanın; yeni anahtar seçmeden önce sonucu kontrol edin.
• Webhook eksikse GET /numeros/{id} sorgulayın ve kullanım sınırlarına uyun.
• preco_acima_do_maximo durumunu işleyin: güncel fiyatı gösterin ve başka satın almadan önce müşterinizin kararını alın.
• Alış fiyatınızı (preco_centavos) gizli tutun; anahtarlarınızı ve webhook sırrını da koruyun.
• Yalnızca anonim cliente_ref gönderin; müşteri bağlantısını kendi sisteminizde tutun.

Bayilik şartlarını okuyun. İletişim: contato@ativasms.store.