-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathapiary.apib
1811 lines (1614 loc) · 70.3 KB
/
apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
FORMAT: 1A
HOST: https://api.smsfire.com.br
# SMSFire - REST API
Bem vindo ao manual das APIs da SMSFire. Com nossas APIs você poderá utilizar todos os serviços dos canais disponíveis tal como obter informações da sua conta.
A API suporta nativamente o formato REST que recebe e devolve dados em objetos JSON.
Todos os parâmetros que devem ser enviados como obrigatórios e opcionais assim como parâmetros dos objetos devolvidos serão descritos ao longo da documentação.
Qualquer dúvida sobre nossos serviços e APIs, fique a vontade para contatar nossa equipe de suporte técnico.
# Autenticação
Todas as requisições as APIs da SMSFire devem utilizar cabeçalhos Basic Authorization.
Neste campo deve-se informar seus dados de usuário e senha, estes dados são os mesmos que é utilizado para acessar o <a href="http://portal.smsfire.com.br" target="_blank">***Portal SMSFire***</a>.
Caso haja erro na autenticação, o respectivo código de erro será retornado.
<b>Exemplo:</b><br>
```
Authorization: Basic Y29udGE6c2VuaGE=
```
O valor após a palavra Basic é uma chave (token) em Base64 formados pelos seus dados de usuário e senha.
A formação dessa chave pode ser feita em PHP com a função nativa <a href="http://php.net/manual/pt_BR/function.base64-encode.php" target="_blank"><b><i>base64_encode("usuario:senha")</i></b></a> da linguagem.
<br><br>
O site <a href="https://www.base64encode.org/" target="_blank">base64Encode</a> também faz essa codificação gratuitamente.
# Parâmetros SMS
Veja nesta seção todos os parâmetros obrigatórios e opcionais para a utilização da API SMSFire para envios de SMS.
##to
O parâmetro **`to`** é utilizado para indicar os destinatários da mensagem.
| Nome | Tipo | Formato | Limitação | Utilização |
|------|------|---------|-----------|------------|
| `to`| *array* | DDI+DDD+Numero | 200 indices | **Obrigatório**
A sintaxe do número deve sempre ser em formato internacional.
***Exemplo JSON***
```json
{
"to":["5511944556677","5521966778899"]
}
```
<blockquote>
<p><b>Atenção:</b><br>
Se houverem mais de 200 índices no array, a API irá retornar o respectivo código erro e nenhuma mensagem será processada
</p>
</blockquote>
##from
O parâmetro **`from`** é utilizado para indicar o remetente da mensagem.
| Nome | Tipo | Limitação | Utilização
|------|------|-----------|------------
| `from`| *string* | 11 caracteres | **Obrigatório**
***Exemplo JSON***
```json
{
"from":"SMSFire"
}
```
##text
O parâmetro **`text`** é utilizado para indicar o texto da mensagem.
| Nome | Tipo | Limitação | Utilização |
|------|------|---------|-----------|------------|
| `text`| *string* | 765 caracteres | **Obrigatório**
***Exemplo JSON***
```json
{
"to":"Acesse nosso site www.smsfire.com.br"
}
```
###Codificação do texto
Todas as mensagens recepcionadas serão enviadas em codificação GSM-7 e todo caractere fora desta codificação será substituido pelo seu equivalente simplificado.
<img src="http://www.smsfire.com.br/public/images/table-set.jpg">
###Mensagens concatenadas
O sistema de SMS da SMSFire permite envios de mensagens com até 765 caracteres. Mensagens acima de 160 caracteres, serão divididas em partes iguais de 153 e então cada parte será tarifada individualmente.
Apesar da separação e tarifação individualizada por partes, o destinatário receberá uma mensagem única.
<blockquote>
<p><b>Atenção:</b><br>
Algumas operadoras podem encaminhar a mensagem separada com indicações de paginação.</p>
</blockquote>
##campaignName
O parâmetro **`campaignName`** é utilizado para indicar o nome da campanha do envio.
Todas os envios, sejam unitários ou em lote farão parte de uma campanha que sempre poderá ser visualizada no <a href="http://portal.smsfire.com.br" target="_blank">***Portal SMSFire***</a>
| Nome | Tipo | Valor padrão | Limitação | Utilização |
|------|------|---------|-----------|------------|
| `campaignName`| *string* | UNNAMED REST API CAMPAIGN | 100 caracteres | *Opcional*
***Exemplo JSON***
```json
{
"campaignName":"Campanha dia dos pais"
}
```
Se o parâmetro não for especificado, uma campanha nomeada com o **Valor padrão** será criada e ficará a disposição para visualização no ***Portal SMSFire***
<blockquote>
<p><b>Atenção:</b><br>
Campanhas que tenham as mesmas características serão agrupadas numa única campanha. As características utilizadas de checagem para o agrupamento são nome, custo unitário da mensagem, 2ways, flash, rota, tags e a origem de processamento.</p>
</blockquote>
##tags
O parâmetro **`tags`** é utilizado para criar etiquetas na campanha do envio. Assim você poderá detalhar melhor os dados da sua campanha e criar melhores filtros.
| Nome | Tipo | Valor padrão | Limitação | Utilização |
|------|------|---------|-----------|------------|
| `tags`| *array* | *empty* | Não há | *Opcional*
***Exemplo JSON***
```json
{
"tags":["julho","promocao","pais"]
}
```
##schedule
O parâmetro **`schedule`** é utilizado para indicar o agendamento de envio de uma mensagem. A não indicação deste parâmetro fará com que a mensagem seja enviada imediatamente.
| Nome | Tipo | Formato | Limitação | Utilização |
|------|------|---------|-----------|------------|
| `schedule`| *string* | YYYY-MM-DD HH:II:SS | Não há | *Opcional*
***Exemplo JSON***
```json
{
"schedule":"2018-08-22 15:20:00"
}
```
Ao indicar este modelo de data, a mensagem será agendada para disparo em 22 de Agosto do ano de 2018 às 15:20PM
<blockquote>
<p><b>Atenção:</b><br>
Atualmente nossas APIs não possuem a função de gestão de mensagens agendadas, devido a isto caso seja necessário cancelar um agendamento será necessário entrar em contato com a nossa equipe de suporte através do e-mail <a href="mailto:[email protected]">[email protected]</a> com no mínimo 2h de antecedência para podermos cancelar o envio.
</p>
</blockquote>
Para realizar um agendamento de data compátivel com a sua zona horária, consulte o parâmetro `timezone`
##timezone
O parâmetro **`timezone`** é utilizado para indicar a faixa horária do destinatário quando o parâmetro **`schedule`** é indicado.
| Nome | Tipo | Timezones | Valor padrão | Utilização |
|------|------|---------|-----------|------------|
| `timezone`| *string* | <a href="https://secure.php.net/manual/pt_BR/timezones.php" target="_blank">Lista completa</a> | America/Sao_Paulo | *Opcional*
***Exemplo JSON***
```json
{
"timezone":"Europe/Madrid"
}
```
Ao indicar o parâmetro **`schedule`** para agendar um envio e nenhum timezone for especificado, o sistema irá considerar o mencionado em **Valor padrão**. Se o timezone indicado neste parâmetro for inválido um erro será dado no callback da requisição.
##2ways
O parâmetro **`2ways`** é utilizado para ativar o recebimento de respostas das mensagens enviadas no <a href="http://portal.smsfire.com.br">Portal SMSFire</a>, e-mail ou numa URL. Caso o parâmetro não seja especificado, todas as respostas enviadas pelos destinatários não serão visualizadas.
Este parâmetro é um array composto por índices que permitem a ativação da função assim como o envio das respostas por e-mail ou url.
***Exemplo JSON***
```json
{
"2ways":{
"active":true,
"url":"http://www.meusite.com.br",
"email":"[email protected]"
}
}
````
Sabendo destes parâmetros internos do **`2ways`** temos as definições na tabela a seguir
| Nome | Tipo | Formato | Valor padrão | Utilização |
|------|:----:|---------|-----------|------------|
| `2ways` | *array* | - | null | *Opcional*
| `2ways:active` | *boolean* | true / false | false | ***Obrigatório***
| `2ways:url` | *string* | URL | null | *Opcional*
| `2ways:email` | *string* | E-Mail | null | *Opcional*
###2ways via URL
Com o parâmetro **`url`** as respostas recebidas serão enviadas no formato ***JSON*** via método ***POST*** ao seu endpoint sem nenhum custo adicional.
***Exemplo de JSON***
```json
{
"mo":{
"id": 12345,
"text": "Sim, agendar para as 11am",
"date":"2018-08-20 15:05:00"
},
"mt":{
"id": 54321,
"text": "Podemos agendar sua visita para o proximo sabado?",
"date":"2018-08-20 14:00:00"
},
"campaign":{
"id": 78945,
"name": "Agendamento sabado",
"date":"2018-08-20 13:58:00"
},
"ddi": 55,
"mobile": 5511944556677,
"route": "short"
}
```
Sabendo destes parâmetros enviados ao seu endpoint, temos as definições na tabela a seguir
| Nome | Tipo | Descrição
|------|:-----:| ---------
| `mo:id` | *int* | *ID* da mensagem recebida
| `mo:text` | *string* | Texto da resposta
| `mo:date` | *string* | Data do recebimento da resposta
| `mt:id` | *int* | *ID* da mensagem de origem
| `mt:text` | *string* | Texto da mensagem de origem
| `mt:date` | *string* | Data do envio da mensagem de origem
| `campaign:id` | *int* | *ID* da campanha da mensagem
| `campaign:name` | *string* | Nome da campanha da mensagem
| `campaign:date` | *string* | Data de criação da campanha
| `ddi` | *string* | *DDI* do número que respondeu a mensagem
| `mobile` | *string* | Número do usuário que respondeu a mensagem em formato internacional
| `route` | *string* | Rota utilizada no processamento do envio e do recebimento da resposta
###2ways via E-mail
Com o parâmetro **`email`** as respostas recebidas serão enviadas ao e-mail especificado com um custo adicional.
É importante adicionar o dominio ***@smsfire.com.br*** como domínio confiável para que as mensagens não caiam em Lixo Eletrônico / Spam
<blockquote><p>
<b>Atenção:</b><br> A ativação da função 2ways irá gerar custo adicional a sua campanha por cada resposta recebida. Envios de respostas via e-mail gerará um custo adicional de 15% do valor da sua tarifa além do custo do recebimento da resposta. Para mais detalhes entre em contato com a equipe de Suporte
</p></blockquote>
##notificationUrl
O parâmetro **`notificationUrl`** deve ser indicado para o recebimento do status final da mensagem enviada. Os dados enviados a url mencionada será um objeto ***JSON*** via método ***POST*** de cada mensagem individualmente.
| Nome | Tipo | Formato | Valor padrão | Utilização |
|------|------|---------|-----------|------------|
| `notificationUrl` | *string* | *URL* | *null* | *Opcional*
***Exemplo JSON***
```json
{
"notificationUrl":"http://www.meusite.com/smsDlr"
}
```
###Requisição a Url
Uma vez que nossos servidores recebam os dados do gateway/operadora, imediatamente enviaremos o objeto ***JSON*** a url mencionada neste parâmetro.
***Exemplo JSON***
```json
{
"id": 16232,
"to": 5511944556677,
"from": "SMSFire",
"date": "2018-08-10 17:19:54",
"status": {
"code": 2,
"name": "DELIVERED"
},
"sub_status": {
"code": 1,
"name": "OK"
},
"description": "MESSAGE DELIVERED TO CARRIER"
}
```
Sabendo destes parâmetros enviados ao seu endpoint, temos as definições na tabela a seguir
| Nome | Tipo | Descrição
|------|:-----:| ---------
| `id` | *int* | *ID* da mensagem enviada
| `to` | *int* | Número do destinatário em formato internacional
| `from` | *string* | Remetente utilizado no envio
| `date` | *string* | *ID* Data do status recebido
| `status` | *array* | Detalhe com código e nome do status
| `status:code` | *int* | Código do status da mensagem
| `status:name` | *string* | Nome do código de status da mensagem
| `sub_status` | *array* | Detalhe com código e nome do status complementar
| `sub_status:code` | *int* | Código do status complementar da mensagem
| `sub_status:name` | *string* | Nome do código de status complementar da mensagem
| `description` | *string* | Descrição complementar do status da mensagem
Para consultar os possíveis **`status`**, **`sub_status`** e **`description`** acesse a seção ***Tabela de status***
##routing
O parâmetro **`routing`** é utilizado para indicar por qual rota de envio a campanha deverá ser processada.
| Nome | Tipo | Formato | Valor padrão | Utilização |
|------|:----:|:-------:|:---------:|------------|
| `routing` | *int* | 1 / 0 | 1 | *Opcional*
| Valor | Rota
|------:|-----
| 1 | *shortcode*
| 0 | *longcode*
***Exemplo JSON***
```json
{
"routing":1
}
```
Ao indicar o parâmetro **`routing`** a API irá processar o envio a partir da rota escolhida, caso não seja mencionado o sistema irá considerar o **Valor padrão**. Se o routing indicado neste parâmetro for inválido um erro será dado no callback da requisição.
###Características de rotas
Avalise sempre qual a melhor rota para o seu tipo de utilização. Cada rota possui características que podem afetar diretamente a efetividade da sua campanha.
####Rotas longcode
Rotas de baixo custo que podem utilizar tecnologias alternativas para processamento das mensagens até as operadoras, porém possuem maior tempo de demora para o recebimento da mensagem, efetividade de entrega intermitente e baixo custo.
+ Características longcode
+ Demora para entrega da mensagem (até 4 horas)
+ Remetente variável entre número curto e longo
+ Sem garantias no funcionamento dos MOs (2ways)
+ Baixo custo
+ Efetividade intermitente
+ Status final do tipo SMSC (confirmação de entrega da mensagem até a operadora)
+ Capacidade de processamento diário limitada
<blockquote>
<p><b>Atenção:</b><br>
Algumas rotas longcode que utilizamos não fornecem os dados de status final e nestes casos todas as mensagens receberão automaticamente o status inicial como DELIVERED
</p>
</blockquote>
####Rotas shortcode
Rotas de conexão direta ou via brokers homologados pelas operadoras que possuem excelente qualidade com tempo de demora de entrega reduzido e efetividade de entrega constante.
+ Características shortcode
+ Processamento prioritário para entrega imediata da mensagem
+ Remetente com número de 5 dígitos fixo
+ MOs (2ways)
+ Alta efetividade de entrega
+ Status final do tipo Handset (confirmação de recebimento no dispositivo)
+ Capacidade de processamento diário ilimitada
##flash
O parâmetro **`flash`** é utilizado para indicar a classe da mensagem, ou seja, se a mensagem será entregue como um SMS comum ou um SMS "popup"
| Nome | Tipo | Formato | Valor padrão | Utilização |
|:----:|:----:|:-------:|:---------:|------------|
| `flash` | *boolean* | true / false | false | *Opcional*
***Exemplo JSON***
```json
{
"flash":true
}
```
<blockquote>
<p><b>Atenção:</b><br>
Este parâmetro apenas tem efeito em envios de mensagens pela rota Shortcode.
</p>
</blockquote>
##Tabela de status
As mensagens enviadas a partir da API da SMSFire possuem status inicial e final.
O status inicial é dado como callback da requisição que pode ser única ou múltipla e o status final é dado para cada envio individualmente.
Todos os dados do status inicial e final fazem parte de um objeto ***JSON***. Os dados do status final são enviados via método ***POST*** a uma url que pode ser fornecida no momento da requisição através do parâmetro **`notificationUrl`**.
Quando o envio é processado corretamente a API devolve o código HTTP de acordo com o tipo de requisição
| Http Code | Nome | Descrição
|:---------:|----------------|------------
| 202 | *Accepted* | Retorno dado para envios individuais
| 207 | *Multi-status* | Retorno dado para envios múltiplos
###Status inicial
O status inicial será dado nos detalhes do parâmetro **`status`** que compõe o *array* **`sms`** como callback da requisição como objeto ***JSON***. Este callback somente será fornecido se a requisição ocorrer sem nenhum erro.
Veja abaixo os possíveis retornos que a API pode gerar neste momento.
| Code | Name | Detail | Significado
|:----:|-----------|-------------------------------------|------------
| 1 | ACCEPTED | Data accepted by the carrier | Envio processado corretamente até o gateway/operadora
| 2 | DELIVERED | Data delivered to carrier | Envio entregue a operadora. Este código somente será fornecido neste estágio em rota longcode
| 6 | SCHEDULED | Data scheduled at the carrier | Envio programado corretamente até o gateway/operadora
| 7 | ERROR | Not enough credits | Saldo indisponível. Envio não processado até o gateway/operadora.
| 7 | ERROR | User do not have gateway assigned | Login sem roteamento. Contate o suporte
Deste modo temos os seguintes detalhes de cada parâmetro
| Nome | Tipo
|--------:|:----
| `code` | *int*
| `name` | *string*
| `detail`| *string*
Abaixo temos o seguinte objeto ***JSON*** completo do callback bem sucedido.
***Exemplo JSON***
```json
"sms": [
{
"id": 16237,
"to": 5511944556677,
"from": "SMSFire",
"text": "Envio de sms bem sucedido",
"parts": 1,
"date": "2018-08-13 19:07:56",
"status": {
"code": 1,
"name": "ACCEPTED",
"detail": "DATA ACCEPTED BY THE CARRIER"
}
}
]
```
###Status final
O status final será dado nos detalhes do parâmetro **`status`** e **`sub_status`** como objeto ***JSON*** enviado no método ***POST*** a url indicada no parâmetro **`notificationUrl`**.
Este objeto será encaminhado assim que o gateway/operadora encaminhar aos nossos servidores a resposta final do seu envio.
Este objeto sempre será individual para cada envio, diferentemente do objeto fornecido no status inicial.
Veja abaixo os possíveis códigos e detalhes que a API poderá encaminhar ao seu endpoint neste momento.
####Status
| Code | Name | Significado
|:----:|-------------|------------
| 2 | DELIVERED | Mensagem recebida na operadora/dispositivo
| 3 | UNDELIVERED | Mensagem não entregue. Número inválido ou bloqueado
| 4 | REJECTED | Mensagem não entregue. Envio rejeitado pelo gateway/operadora
####Sub_status
Este parâmetro terá determinados resultados baseado no parâmetro **`status`**
Veja abaixo os possíveis códigos de **`sub_status`** em combinação com o **`status`**
| Status code | Sub_status code | Name
|:-----------:|:---------------:|------
| 2 | 1 | OK
| 3 | 1 | INVALID
| 4 | 1 | BLOCKED
| 7 | 1 | WITHOUT CREDITS
| 7 | 2 | GATEWAY ERROR
| 7 | 3 | WITHOUT ASSIGNED GATEWAY
Deste modo temos os seguintes detalhes de cada parâmetro
| Nome | Tipo
|--------:|:-----
| `code` | *int*
| `name` | *string*
Abaixo temos o seguinte objeto ***JSON*** completo que será enviado ao endpoint.
***Exemplo JSON***
```json
{
"id": 16232,
"to": 5511944556677,
"from": "SMSFire",
"date": "2018-08-10 17:19:54",
"status": {
"code": 2,
"name": "DELIVERED"
},
"sub_status": {
"code": 1,
"name": "OK"
},
"description": "MESSAGE DELIVERED TO CARRIER"
}
```
# Parâmetros WHATSAPP
Veja nesta seção todos os parâmetros obrigatórios e opcionais para a utilização da API SMSFire para envios de mensagens ao Whatsapp.
##token
O parâmetro **`token`** é utilizado em diversos serviços da API para indicar o canal que está recebendo fila de envios, alterações ou sincronização.
| Nome | Tipo | Utilização
|---------|:------:|---------|
| `token` | *string* | **Obrigatória**
O token é formado por um token de 32 caracteres alfanuméricos. Cada canal possuí o seu próprio token.
***Exemplo JSON***
```json
{
"token":"49ba5k13çp8xm?d0a976e1a14ea3af35"
}
```
<blockquote>
<p><b>ATENÇÃO:</b><br>O token somente será disponibilizado aqueles usuários que possuem um ou mais canais configurados em seu acesso.</p>
</blockquote>
##messageType
O parâmetro **`messageType`** é utilizado para indicar o tipo de mensagem a ser enviada ao aplicativo.
| Nome | Tipo | Formato | Utilização
|---------|:------:|---------|---------|
| `messageType` | *string* | *text ou image* | **Obrigatória**
Os formatos de mensagem que são possíveis a serem enviados são
| Valor | Descrição |
|---------|:------|
| *text* | Envio de texto simples ou com formatação nativa do aplicativo |
| *image* | Envio de imagens (JPG e JPEG somente) |
##schedule
O parâmetro **`schedule`** é utilizado para indicar o agendamento de envio de uma mensagem. A não indicação deste parâmetro fará com que a mensagem seja enviada imediatamente.
| Nome | Tipo | Formato | Limitação | Utilização |
|------|------|---------|-----------|------------|
| `schedule`| *string* | YYYY-MM-DD HH:II:SS | Não há | *Opcional*
***Exemplo JSON***
```json
{
"schedule":"2018-08-22 15:20:00"
}
```
Ao indicar este modelo de data, a mensagem será agendada para disparo em 22 de Agosto do ano de 2018 às 15:20PM
<blockquote>
<p><b>Atenção:</b><br>
Atualmente nossas APIs não possuem a função de gestão de mensagens agendadas, devido a isto caso seja necessário cancelar um agendamento será necessário entrar em contato com a nossa equipe de suporte através do e-mail <a href="mailto:[email protected]">[email protected]</a> com no mínimo 2h de antecedência para podermos cancelar o envio.
</p>
</blockquote>
Para realizar um agendamento de data compátivel com a sua zona horária, consulte o parâmetro `timezone`
##timezone
O parâmetro **`timezone`** é utilizado para indicar a faixa horária do destinatário quando o parâmetro **`schedule`** é indicado.
| Nome | Tipo | Timezones | Valor padrão | Utilização |
|------|------|---------|-----------|------------|
| `timezone`| *string* | <a href="https://secure.php.net/manual/pt_BR/timezones.php" target="_blank">Lista completa</a> | America/Sao_Paulo | *Opcional*
***Exemplo JSON***
```json
{
"timezone":"Europe/Madrid"
}
```
##notificationUrl
O parâmetro **`notificationUrl`** deve ser indicado para o recebimento do status final da mensagem enviada. Os dados enviados a url mencionada será um objeto ***JSON*** via método ***POST*** de cada mensagem individualmente.
| Nome | Tipo | Formato | Valor padrão | Utilização |
|------|------|---------|-----------|------------|
| `notificationUrl` | *string* | *URL* | *null* | *Opcional*
***Exemplo JSON***
```json
{
"notificationUrl":"http://www.meusite.com.br/whatsapp_dlr.php"
}
```
###Requisição a Url
Uma vez que nossos servidores façam o processamento das mensagens ao aplicativo do Whatsaap, imediatamente enviaremos o objeto ***JSON*** a url mencionada com os seguintes dados:
***Exemplo JSON***
```json
{
"id": 16432,
"customId": "123456",
"to": 55119445566777,
"date": "2019-03-07 01:00:00",
"pushname": "Roberto Carlos",
"photo": "https://pps.whatsapp.net/v/t61.11540-24/51544550_287898701880958_8819848413307731968_n.jpg?oe=5C848BBC&oh=720dc23dac0416eb9b52f7977b454cea&t=l&[email protected]&i=1549468927",
"status": {
"code": 2,
"name": "DELIVERED"
},
"sub_status": {
"code": 1,
"name": "OK"
},
"description": "MESSAGE DELIVERED TO WHATSAPP"
}
```
Sabendo destes parâmetros enviados ao seu endpoint, temos as definições na tabela a seguir
| Nome | Tipo | Descrição
|------|:-----:| ---------
| `id` | *int* | *ID* da mensagem enviada
| `customId` | *string* | Identificador definido pelo usuário no momento do envio
| `to` | *string* | Número do destinatário em formato internacional
| `date` | *string* | Data do status recebido
| `pushname` | *string* | Nome fornecido pelo o destinatário ou o que está salvo na lista de contatos
| `photo` | *string* | *URL* com a foto do perfil do destinatário caso seja de acesso público.
| `status` | *array* | Detalhe com código e nome do status
| `status:code` | *int* | Código do status da mensagem
| `status:name` | *string* | Nome do código de status da mensagem
| `sub_status` | *array* | Detalhe com código e nome do status complementar
| `sub_status:code` | *int* | Código do status complementar da mensagem
| `sub_status:name` | *string* | Nome do código de status complementar da mensagem
| `description` | *string* | Descrição complementar do status da mensagem
Para consultar os possíveis **`status`**, **`sub_status`** e **`description`** acesse a seção ***Tabela de status***
##destinations
O parâmetro **`destinations`** é o responsável a informar os destinatários e seus respectivos textos, url de imagens a serem enviados ao aplicativo Whatsapp.
Este parâmetro é um array composto por índices. Cada índice é um destinatário a ser impactado.
***Exemplo JSON***
```json
{
"destinations":[
{
"to":"5511944556677",
"text":"Envio do texto 1",
"customId":"123456",
"fileUrl":"https://i.imgur.com/9L6xi78.jpg"
},
{
"to":"5511966778899",
"text":"Envio do texto 2",
"customId":"456789",
"fileUrl":"https://i.imgur.com/9L6xi78.jpg"
},
{
"to":"011969157483",
"text":"Envio do texto 3",
"customId":"012345"
}
]
}
````
Sabendo destes parâmetros internos do **`destinations`** temos as definições na tabela a seguir
| Nome | Tipo | Formato | Limitação | Utilização |
|------|:----:|:-------:|:---------:|------------|
| `destinations` | *array* | --- | 50 índices | ***Obrigatório***
| `destinations:to` | *string* | DDI+DDD+Número | --- | ***Obrigatório***
| `destinations:text` | *string* | --- | 1.000 caracteres | ***Obrigatório***
| `destinations:customId` | *string* | --- | 40 caracteres | *Opcional*
| `destinations:fileUrl` | *string* | --- | Arquivos JPG ou JPEG | *Opcional*
<blockquote>
<p><b>Atenção:</b><br>
Se houverem mais de 50 índices no array, a API irá retornar o respectivo código erro e nenhuma mensagem será processada
</p>
</blockquote>
<blockquote>
<p><b>Importante:</b><br>
O parâmetro <i>fileUrl</i> somente terá utilidade caso o <i>messageType</i> seja para envios de imagens ou arquivos
</p>
</blockquote>
# Parâmetros BIGDATA
Veja nesta seção todos os parâmetros obrigatórios e opcionais para a utilização da API SMSFire para consultas no Bigdata com fontes públicas e privadas de dados.
##doc
O parâmetro **`doc`** é utilizado para indicar o documento CPF ou CNPJ de acordo com o endpoint.
| Nome | Tipo | Utilização
|---------|:------:|---------|
| `doc` | *string* | **Obrigatória**
O valor deste parâmetro deve conter 11 caracteres para consulta por pessoa, ou então conter 14 caracteres para consulta por empresa.
***Exemplo JSON***
```json
{
"doc":"02708702203"
}
```
##renew
O parâmetro **`renew`** é utilizado para indicar se a consulta resultará em dados de uma pessoa/empresa já consultada pelo usuário ou se então irá buscar no Bigdata por novos dados.
| Nome | Tipo | Valor padrão | Utilização
|---------|:------:|:---------:|---------|
| `renew` | *boolean* | *true* | **Opcional** |
***Exemplo JSON***
```json
{
"renew":false
}
```
<blockquote>
<p><b>Importante:</b><br>
A consulta somente será tarifada se o parâmetro permanecer como <i>true</i>.<br><br>
Ao renovar a consulta <u>podem não existir novos dados</u> e ainda assim, a tarifa será cobrada.
</p>
</blockquote>
#Tabela de erros
Todos os códigos de erros são compostos pela matriz **`error`** formatados num objeto ***JSON***.
Na tabela abaixo estão listados todos os códigos, descrições e ações que devem ser realizadas para cada situação.
| Code | Description | Http Response | Ação
|:------:|---------------------------------------------------------|:-------------:|------
| 101 | Username unknown | 401 | Verifique o nome de usuário.
| 102 | Invalid password | 401 | Senha informada é incorreta.
| 103 | Username Blocked | 403 | Usuário bloqueado. Contate o suporte.
| 104 | Invalid endpoint | 404 | Endpoint consumido não existe.
| 105 | Method not allowed | 405 | Método de envio de dados não permitido.
| 106 | Content type not allowed | 406 | Modifique o *Content-type* do cabeçalho para o formato permitido.
| 107 | Parameter TO is required | 400 | O parâmetro `to` é obrigatório e não foi mencionado.
| 108 | Parameter TO invalid | 400 | O parâmetro `to` deve ser um array.
| 109 | Parameter TO do not accept more than 200 items | 400 | O parâmetro `to` não pode conter mais que 200 indices.
| 110 | Parameter FROM is required | 400 | O parâmetro `from` é obrigatório e não foi mencionado.
| 111 | Parameter FROM too long. | 400 | O parâmetro `from` não pode conter mais que 11 caracteres.
| 112 | Parameter TEXT is required | 400 | O parâmetro `text` é obrigatório e não foi mencionado.
| 113 | Parameter TEXT is too long | 400 | O parâmetro `text` não pode conter mais que 765 caracteres.
| 114 | Parameter SCHEDULE invalid | 400 | O parâmetro `schedule` foi fornecido com data passada ou em formato inválido.
| 115 | Parameter TIMEZONE invalid | 400 | O timezone informado não existe. Campo *case-sensitivity*
| 116 | Parameter FLASH invalid | 400 | O parâmetro `flash`não teve seu valor indicado como *boolean*
| 117 | Parameter 2WAYS > Active invalid | 400 | O parâmetro `active` da chave `2ways` não teve seu valor indicado como *boolean*
| 118 | Could not define URL or EMAIL data with ACTIVE as false | 400 | Defina o parâmetro `active` como *true* da chave `2ways` para poder indicar valores nos parâmetros `url` e/ou `email`
| 119 | Parameter 2WAYS > Email invalid | 400 | Informe um e-mail válido no parâmetro `email` da chave `2ways`.
| 120 | Parameter 2WAYS > Url invalid | 400 | Informe uma url válida no parâmetro `url` da chave `2ways`.
| 121 | Parameter CAMPAIGNNAME too long | 400 | O parâmetro `campaignName` não pode conter mais que 100 caracteres.
| 122 | Parameter TAGS invalid | 400 | O parâmetro `tags`deve ser um array.
| 123 | Parameter ROUTING invalid | 400 | O parâmetro `routing` não teve seu valor indicado como *integer*.
| 124 | Parameter NOTIFICATIONURL invalid | 400 | Informe uma url válida no parâmetro `notificationUrl`.
| 125 | You are not allowed to reach the destination | 205 | Sua conta não pode enviar mensagem ao país especificado. Contate o suporte.
| 126 | It is forbidden send multi country campaign | 400 | Crie campanhas distintas para cada país.
| 127 | Parameter ID invalid | 400 | O `id` deve conter apenas números.
| 128 | Parameter NAME is required | 400 | O parâmetro `name` é obrigatório e não foi mencionado.
| 129 | Parameter NAME too long. Maximum 50 characters. | 400 | O parâmetro `name` não pode conter mais que 50 caracteres.
| 131 | Data should be a valid mobile with international sintax.| 400 | O parâmetro `mobile` tem que ser em formato internacional Ex. 5511944556677
| 133 | Parameter TOKEN is required | 400 | O parâmetro `token` é obrigatório e não foi mencionado.
| 134 | Parameter TOKEN invalid. | 400 | O `token` informado é inválido.
| 135 | Parameter TOKEN invalid for the logged user. | 400 | O `token` informado é inválido.
| 136 | Parameter ID incorrect. Data should be a valid id. | 400 | O `id` informado é inválido/inexistente.
| 137 | This channel is deactivated. Contact support | 402 | O canal informado está desativado.
| 139 | Parameter QRCODE invalid | 400 | O token informado está fora do padrão aceito pelo sistema.
| 140 | Parameter QRCODE expired. Get new qrcode token. | 404 | O token do qrcode está expirado. Capture um novo token.
| 141 | Parameter MESSAGETYPE is required. | 400 | O `parâmetro messageType` é obrigatório e não foi mencionado.
| 142 | Parameter MESSATETYPE invalid. Data should be string. | 400 | O parâmetro `messageType` deve ser uma string.
| 143 | Parameter MESSATETYPE invalid. Data should be text or file. | 400 | O parâmetro `messageType` deve ter valores especificos, consulte detalhes na documentação.
| 144 | Parameter DESTINATIONS is required. | 400 | O parâmetro `destinations` é obrigatório e não foi mencionado.
| 145 | Parameter DESTINATIONS invalid. Data should be array. | 400 | O parâmetro `destinations` deve ser um array.
| 146 | Parameter TO invalid. Data sould be a valid number. | 400 | O parâmetro `to` deve ser um número válido em formato internacional.
| 147 | Parameter TEXT too long. Maximum 1000 characters. | 400 | O parâmetro `text` deve ser uma string de até 1.000 caracteres.
| 148 | Parameter CUSTOMID invalid. Data should be string. | 400 | O parâmetro `customId` deve ser uma string de até 40 caracteres.
| 149 | Account not allowed to use links. | 403 | A conta não tem permissão para envio de Link. Contate o suporte.
| 150 | Only JPG/JPEG images are allowed. | --- | Somente as extensões JPG e JPEG são permitidas.
| 151 | File not found or not authorized to catch. | 403 | O conteúdo do parâmetro `fileUrl` não existe ou não tem permissão de captura.
| 401 | Login were canceled | 401 | A validação do usuário e senha foi cancelada.
| 1xxx | Database Error | 500 | Falha no servidor. Contate o suporte com o código retornado.
Sabendo dos possíveis códigos de erro que a API pode retornar, veja abaixo um exemplo do objeto *JSON*
***Exemplo JSON***
```json
{
"error":{
"code":121,
"description":"Parameter CAMPAIGNNAME too long. Maximum 100 characters."
}
}
```
<blockquote>
<p><b>Atenção:</b><br>
Quando a API retorna erro, nenhum envio é processado, ou então dependendo do canal utilizado o envio com erro é ignorado
</p>
</blockquote>
#Group Serviços da API SMS
A partir deste módulo, você será capaz de utilizar todas as funcionalidades dos nossos serviços de SMS via API.
##Envio de SMS [/v1/sms/send]
**Endpoint:** `https://api.smsfire.com.br/v1/sms/send`
###Testar envio de SMS [POST]
Este serviço permite o envio de SMS para um ou mais destinatários de forma imediata ou agendada com base no fuso horário do destinatário.
***Exemplo JSON simplificado***
```json
{
"to":["5511944556677","5511977889900"],
"from":"30125",
"text":"Activation code: 20181907"
}
```
***Exemplo JSON completo***
```json
{
"to":["5511944556677","5511977889900"],
"from":"30125",
"text":"Activation code: 20181907",
"compaignName": "Dia dos pais",
"tags":["promocao","desconto"],
"schedule":"2018-08-12 10:00:00",
"timezone":"America/Sao_Paulo",
"2ways":{
"active":true,
"url":"http://www.meusite.com.br/moDlr",
"email":"[email protected]"
},
"notificationUrl":"http://www.meusite.com.br/mtDlr",
"routing":1
}
```
Logo que a requisição for bem sucedida, sem erros, nós teremos a resposta HTTP *202 - Accepted* para envios individuais ou *207 - Multi-Status* para envios múltiplos com o seguinte objeto ***JSON*** como resposta
***Callback JSON da requisição***
```json
{
"campaign": {
"id": 163,
"name": "Dia dos pais",
"tags": ["promocao","desconto"],
"cost": 0.08,
"volume": 2,
"currency": "BRL",
"routing": "short"
},
"sms": [
{
"id": 16237,
"to": 5511944556677,
"from": "30125",
"text": "Activation code: 20181907",
"parts": 1,
"date": "2018-08-12 10:00:00",
"status": {
"code": 6,
"name": "SCHEDULED",
"detail": "DATA SCHEDULED AT THE CARRIER"
}
},
{
"id": 16238,
"to": 5511977889900,
"from": "30125",
"text": "Activation code: 20181907",
"parts": 1,
"date": "2018-08-12 10:00:00",
"status": {
"code": 7,
"name": "ERROR",
"detail": "NOT ENOUGH CREDITS"
}
}
]
}
```
Sabendo do objeto ***JSON*** recebido no callback, a tabela abaixo detalha os valores de cada um dos parâmetros.
####Indice `campaign`
| Nome | Tipo | Descrição
|----------|:--------:|-----------
|`id` | *int* | *ID* da campanha criada
|`name` | *string* | Nome da campanha criada
|`tags` | *array* | Etiquetas da campanha
|`cost` | *float* | Custo unitário da mensagem
|`volume` | *int* | Total de mensagens vinculadas a campanha
|`currency`| *string* | Sigla da moeda utilizada na tarifação
|`routing` | *string* | Rota utilizada no envio das mensagens
####Indice `sms`
| Nome | Tipo | Descrição
|---------------|:--------:|-----------
|`id` | *int* | *ID* da mensagem enviada
|`to` | *int* | Número do destinatário em formato internacional
|`from` | *string* | Remetente utilizado na mensagem
|`text` | *string* | Texto utilizado na mensagem
|`parts` | *int* | Indicador do total de partes da mensagem
|`date` | *string* | Data do envio da mensagem em formato YYYY-MM-DD HH:II:SS
|`status:code` | *int* | Código de status inicial da mensagem
|`status:name` | *string* | Nome do status inicial da mensagem
|`status:detail`| *int* | Detalhe do status inicial da mensagem
+ Attributes
+ to: 5511944556677,5511977889900 (array, required) - Número do destinatário, formato internacional.
+ from: 30125 (string, required) - Nome do remetente.
+ text: Activation code: 20181907 (string, required) - Texto da mensagem a ser enviada.
+ campaignName: Dia dos pais (string, optional) - Nome da campanha
+ tags: promocao,desconto (array, optional) - Etiquetas da campanha
+ schedule: `2018-08-12 10:00:00` (string, optional) - Data de agendamento
+ timezone: America/Sao_Paulo (string, optional) - Faixa horária do destinatário
+ 2ways/active: true (boolean, optional) - Ativação do recebimento de respostas
+ 2ways/url: http://www.meusite.com.br/moDlr (string, optional) - Url para o direcionamento da resposta
+ 2ways/email: [email protected] (string, optional) - E-mail onde serão direcionados o MO *Custo adicional
+ notificationUrl: http://www.meusite.com.br/mtDlr (string, optional) - Url onde serão direcionados os status finais
+ routing: 1 (number, optional) - Definição da rota de processamento da mensagem
+ request (application/json)
+ Header
Authorization: Basic YWRtaW46YWRtaW4=
+ Body
{
"to":["5511944556677","5511977889900"],
"from":"SMSFIRE",
"text":"Activation code: 20181907",
"compaignName": "Dia dos pais",
"tags":["promocao","desconto"],
"schedule":"2018-08-12 10:00:00",
"timezone":"America/Sao_Paulo",
"2ways":{
"active":true,
"url":"http://www.meusite.com.br/moDlr",
"email":"[email protected]"
},
"notificationUrl":"http://www.meusite.com.br/mtDlr",
"routing":1
}
+ Response 207 (application/json)
{
"campaign": {
"id": 163,
"name": "Dia dos pais",
"tags": ["promocao","desconto"],
"cost": 0.08,
"volume": 2,
"currency": "BRL",
"routing": "short"
},
"sms": [
{
"id": 16237,
"to": 5511944556677,
"from": "SMSFIRE",
"text": "Activation code: 20181907",
"parts": 1,
"date": "2018-08-12 10:00:00",
"status": {
"code": 6,
"name": "SCHEDULED",
"detail": "DATA SCHEDULED AT THE CARRIER"
}
},
{
"id": 16238,
"to": 5511977889900,
"from": "SMSFIRE",
"text": "Activation code: 20181907",
"parts": 1,
"date": "2018-08-13 19:07:56",
"status": {
"code": 7,
"name": "ERROR",
"detail": "NOT ENOUGH CREDITS"
}
}
]
}
##Consultar status [/v1/sms/status/{id}]
**Endpoint:** `https://api.smsfire.com.br/v1/sms/status/{id}`
###Testar consulta de status [GET]
Este serviço permite a consulta do status final de um determinado SMS enviado.
A consulta dá-se pelo parâmetro `id` da mensagem e o resultado será dado num objeto ***JSON***.
Caso o `id` consultado não exista, o objeto retornado terá seus valores como *null*
***Exemplo JSON retornado***
```json
{
"id": 16232,
"to": 5511944556677,
"from": "SMSFire",
"date": "2018-08-10 17:19:54",
"status": {
"code": 2,
"name": "DELIVERED"
},
"sub_status": {
"code": 1,
"name": "OK"
},
"description": "MESSAGE DELIVERED TO CARRIER"
}
```
<blockquote>
<p>Consulte a seção <u><i>Tabela de status</i></u> para identificar o que cada código representa.</p>
</blockquote>
+ parameters
+ id: 16232 (number, required) - Identificado da mensagem fornecido nos envios
+ request
+ Header
Authorization: Basic YWRtaW46YWRtaW4=
+ response 200 (application/json)
{
"id": 16232,
"to": 5511944556677,
"from": "SMSFire",
"date": "2018-08-10 17:19:54",
"status": {
"code": 2,
"name": "DELIVERED"
},
"sub_status": {
"code": 1,
"name": "OK"
},
"description": "MESSAGE DELIVERED TO CARRIER"
}
#Group Serviços da API ACCOUNT
A partir deste módulo, você poderá consultar via API todos os dados da conta como saldo, tarifas, países configurados entre outras informações.
##Consultar saldo [/v1/account/balance]
**Endpoint:** `https://api.smsfire.com.br/v1/account/balance`
###Testar consulta de saldo [GET]
Este serviço permite a consulta do saldo atualizado da sua conta indicando valor, moeda e limite de crédito caso sua conta esteja no regime pós-pago.
A consulta dá-se mediante uma requisição GET a partir da autenticação do seu usuário e os dados são retornados num objeto em formato ***JSON***. Abaixo temos seus detalhes
| Nome | Tipo | Formato |
|------|------|---------|
| `balance`| *float* | 9999.00 |
| `negative_limit`| *float* | -9999.00 |
| `currency`| *string* | BRL,EUR,USD,MXN ou COP |
***Exemplo JSON retornado***
```json
{
"balance": 1125.91,
"negative_limit": 0,
"currency": "BRL"
}
```
<blockquote>
<p>Consulte a seção <u><i>Autenticação</i></u> para ter detalhes de como autenticar a sua requisição</p>
</blockquote>
+ request
+ Header
Authorization: Basic YWRtaW46YWRtaW4=
+ response 200 (application/json)
{
"balance": 1500.00,
"negative_limit": 0,
"currency": "BRL"