Compatibilitate GMS API

SMSBAT acceptă un strat de compatibilitate cu GMS API. Acest lucru vă permite să migrați integrările existente concepute pentru GMS direct la SMSBAT fără a fi nevoie să modificați schemele de rutare a mesajelor, structurile de încărcare utilă sau ascultătorii de apel invers.

Setări de conexiune

Pentru a direcționa solicitările prin SMSBAT, actualizați adresa URL de bază și acreditările de autentificare în integrarea dvs.:

Adresa URL de bază: https://restapi.smsbat.com
Endpoint: POST /api/GMSMessage/send_message
Format de solicitare: application/json
Autentificare: Autentificare de bază HTTP (folosește acreditările API SMSBAT)

Solicitare parametri

API-ul de compatibilitate GMS acceptă un obiect JSON cu următorii parametri de nivel superior:

Parametru	Tip	Necesar	Descriere
`număr_de_telefon`	șir	Da	Numărul de telefon al destinatarului în format internațional (de ex., „380501234567”).
`etichetă`	șir	Da	Numele expeditorului înregistrat/numele alfa.
`canale`	matrice	Da	Lista canalelor de încercat, în ordinea priorităților. Valori acceptate: `viber`, `sms`, `push`. De exemplu, `["viber", "sms"]`.
`opțiuni_canal`	obiect	Da	Hartă care conține opțiuni pentru fiecare canal activ (vezi mai jos).
`extra_id`	șir	Nu	ID-ul dvs. de mesaj intern la nivelul clientului.
`callback_url`	șir	Nu	Adresa URL a punctului final de pe sistemul dvs. pentru a primi apeluri de starea livrării.
`cod_diviziune`	șir	Nu	Identificator opțional de cod de diviziune (implicit la „principal”).

Setări opțiuni canal

Obiectul channel_options conține configurații specifice canalului.

=== „Mesaj Viber”

Folosit când `viber` este listat în matricea `canale`.

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `text` | șir | **Da** | Textul corpului mesajului. |
| `ttl` | întreg | **Da** | Time-To-Live în secunde. |
| `img` | șir | Nu | Adresa URL publică HTTPS a imaginii de afișat. |
| `legendă` | șir | Nu | Etichetă text pentru buton. |
| `acțiune` | șir | Nu | Adresa URL de destinație când se face clic pe butonul. |
| `survey_options` | matrice | Nu | Matrice de șiruri (2 până la 5 elemente) pentru a fi afișate ca opțiuni de sondaj. |
| `articole_carusel` | matrice | Nu | Matrice de obiecte de diapozitive pentru a fi afișate ca un carusel Viber (vezi structura din filă). |

**Exemplu de solicitare Viber:**
```json
{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}
```

=== „Viber cu SMS de rezervă”

Activează mesageria Viber cu un SMS automat de rezervă dacă livrarea Viber nu reușește în TTL.

**Exemplu de solicitare de rezervă:**
```json
{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}
```

=== „Mesaj SMS”

Folosit când `sms` este listat în matricea `canale`.

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `text` | șir | **Da** | Textul corpului mesajului. |
| `alpha_name` | șir | **Da** | Numele alfa expeditorului. |
| `ttl` | întreg | **Da** | Time-To-Live în secunde. |
| `ctr` | boolean | Nu | Activați urmărirea clicurilor CTR pe linkurile din text (`adevărat`/`fals`). |

**Exemplu de solicitare SMS:**
```json
{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}
```

=== „Sondaj Viber”

Folosit pentru a crea sondaje și sondaje Viber.

!!! avertisment
    Configurația sondajului Viber trebuie să aibă între **2 și 5 opțiuni** în interiorul `survey_options`.

**Exemplu de solicitare de sondaj:**
```json
{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}
```

=== „Carusel Viber”

Folosit pentru a trimite carduri cu diapozitive cu imagini care pot fi glisate. Fiecare diapozitiv acceptă imaginea, titlul și butoanele.

**Exemplu de solicitare carusel:**
```json
{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Choose an offer",
      "ttl": 60,
      "carousel_items": [
        {
          "title": "Offer 1",
          "image_url": "https://www.example.com/offer-1.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-1",
          "secondary_label": "More",
          "secondary_url": "https://www.example.com/offers"
        },
        {
          "title": "Offer 2",
          "image_url": "https://www.example.com/offer-2.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-2"
        }
      ]
    }
  }
}
```

=== „Mesaj push”

Folosit când `push` este listat în matricea `canale`.

| Parametru | Tip | Necesar | Descriere |
| :--- | :--- | :--- | :--- |
| `titlu` | șir | **Da** | Textul titlului notificării push. |
| `text` | șir | **Da** | Textul corpului mesajului. |
| `ttl` | întreg | **Da** | Time-To-Live în secunde. |
| `img` | șir | Nu | Adresa URL publică HTTPS a imaginii de afișat. |
| `legendă` | șir | Nu | Etichetă text pentru buton. |
| `acțiune` | șir | Nu | Adresa URL de destinație când se face clic pe butonul. |
| `ctr` | boolean | Nu | Activați urmărirea clicurilor. |

**Exemplu de solicitare push:**
```json
{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}
```

Format de răspuns

Punctul final returnează răspunsuri în format JSON cu un cod de stare HTTP 200 OK.

Răspuns de succes

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Răspunsuri de eroare

Dacă validarea sau procesarea eșuează, va fi returnat un răspuns de eroare cu un ErrorCode non-null și un ErrorText detaliat.

=== „Canal/Opțiune neacceptată”

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

=== „Număr de opțiuni de sondaj nevalide”

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

=== „Nume alfa neînregistrat”

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

=== „Eroare internă de procesare”

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Format de livrare pentru apel invers

Dacă callback_url a fost specificat în solicitare, SMSBAT trimite actualizări de starea livrării sub formă de încărcare utilă JSON POST către punctul final.

Exemplu de solicitare de apel invers

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Câmpuri de apel invers Descriere

Câmp	Tip	Descriere
`număr`	șir	Numărul de telefon al destinatarului.
`timp`	număr	Timpul evenimentului în milisecunde Unix.
`starea`	număr	Identificator de stare simplificat (vezi tabelul de coduri de stare).
`substatus`	număr	Identificator de stare detaliat (vezi tabelul de coduri de substare).
`hiber_status`	număr	Codul de stare intern SMSBAT detaliat (vezi tabelul de stare Hyber).
`message_id`	șir	ID-ul mesajului SMSBAT (GUID) generat la trimitere.
`extra_id`	șir	ID-ul clientului furnizat în cererea inițială.
`trimit_via`	șir	Canalul care a procesat mesajul: `viber`, `sms` sau `rcs`.
`matching_template_id`	număr	Starea potrivirii șablonului Viber (unde este cazul).

Mapări de stare

1. Stare simplificată (`status`)

Cod	Înțeles
`1`	Mesaj acceptat sau în curs de livrare.
`2`	Mesaj livrat.
`3`	Eroare de procesare sau livrare.

2. Stare detaliată („substatus”)

Cod	Înțeles
`12`	Acceptat pentru procesare.
`23`	Livrat.
`24`	Văzut/citit.
`35`	Nu este livrat în TTL (Expirat).
`36`	Eroare de livrare.

3. Tip de canal (`sent_via`)

Canal	Descriere
`viber`	Stare produsă de canalul Viber.
`sms`	Stare produsă de canalul SMS.
`rcs`	Stare produsă de canalul RCS.

4. Starea SMSBAT detaliată (`hyber_status`)

Cod	Canal	Stare	Substatus	Înțeles
23033	`viber`	`2`	`23`	Mesaj Viber livrat.
24013	`viber`	`2`	`24`	Mesaj Viber citit de destinatar (Văzut).
36013	`viber`	`3`	`36`	Eroare internă Viber.
36023	`viber`	`3`	`36`	ID serviciu Viber nevalid sau indisponibil.
36033	`viber`	`3`	`36`	Date nevalide ale încărcăturii utile Viber.
36037	`viber`	`3`	`36`	Adresa URL a imaginii Viber este prea lungă.
36038	`viber`	`3`	`36`	Adresa URL a imaginii Viber nevalidă.
36039	`viber`	`3`	`36`	Text Viber prea lung.
36044	`viber`	`3`	`36`	Textul Viber gol.
36053	`viber`	`3`	`36`	Tip de mesaj Viber neacceptat.
36063	`viber`	`3`	`36`	Parametri Viber nevalidi.
36073	`viber`	`3`	`36`	Timp de expirare a furnizorului Viber.
36083	`viber`	`3`	`36`	Expeditorul Viber a fost blocat de destinatar.
36093	`viber`	`3`	`36`	Destinatarul nu este înregistrat ca utilizator Viber.
36103	`viber`	`3`	`36`	Nu a fost găsit niciun dispozitiv Android/iOS cu suport Viber.
36113	`viber`	`3`	`36`	Adresă IP neautorizată pentru trimiterea Viber.
36123	`viber`	`3`	`36`	A fost detectat un mesaj Viber duplicat.
36143	`viber`	`3`	`36`	Eroare de facturare Viber.
36153	`viber`	`3`	`36`	Mesaj blocat de lista neagră a platformei.
36163	`viber`	`3`	`36`	Eroare de procesare internă a platformei Viber.
36173	`viber`	`3`	`36`	Etichetă Viber greșită sau lipsă.
36183	`viber`	`3`	`36`	Valoare Viber TTL nevalidă.
12011	`sms` / `rcs`	`1`	`12`	SMS/RCS acceptat.
36011	`sms` / `rcs`	`1`	`12`	SMS/RCS pe ruta.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS livrat.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS a expirat (nu este livrat în TTL).
36021	`sms` / `rcs`	`3`	`36`	Mesajul SMS/RCS a fost șters.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS nu poate fi livrat.
36041	`sms` / `rcs`	`3`	`36`	Starea de livrare SMS/RCS necunoscută.
36051	`sms` / `rcs`	`3`	`36`	Mesajul SMS/RCS a fost respins.