POST /secure/send da API REST com um transporte binário: o mesmo login, os
mesmos campos, a mesma tarifação e cobrança, a mesma aprovação de sender ID e de template, a mesma
verificação de rota, a mesma regra de retry com client_ref e o mesmo limite de taxa por conta.
Uma vez aceita, uma mensagem enviada via gRPC é indistinguível de uma enviada via REST.
Ela acrescenta uma coisa que o REST não tem: um feed de recibos. Peça recibos sem informar um
webhook e eles esperam por você numa fila durável que você lê pela mesma conexão — sem nenhum
endpoint seu para manter.
O gRPC fica desligado a menos que seu provedor o ligue. Um gateway que não foi configurado para
ele responde toda chamada com
UNAVAILABLE e o código de erro GRPC_DISABLED. Se você vir isso, a
API existe mas não está habilitada na plataforma que você está chamando — peça ao seu provedor o
endereço gRPC.Quando escolher
Uma requisição tem algumas dezenas de bytes de protobuf em vez de um corpo JSON, e o
SendStream envia muitas
mensagens num único stream sem esperar cada resposta. Nenhum dos dois muda o que você pode enviar nem
a que velocidade: REST e gRPC compartilham o limite de mensagens por segundo da sua conta, então
mover tráfego de um para o outro não te dá mais limite.
O SMPP continua sendo a terceira via de entrada, e é separado — veja Bind.
Três serviços
Conectando
Seu provedor te dá um host e uma porta. Num gateway sem nada na frente, a porta costuma ser 8090; atrás do proxy TLS de um provedor, muitas vezes é 443.
O gRPC precisa de HTTP/2 o caminho todo. Se as chamadas falham no nível de transporte antes de o
gateway responder, algo entre você e ele está falando HTTP/1.1.
O contrato
O contrato é um arquivo,fireflo.proto, pacote protobuf fireflo.v1. Ele está reproduzido na
íntegra em O arquivo proto.
Ele está congelado desde a 0.15.9, do mesmo jeito que a API REST: números de campo nunca são
reutilizados nem renumerados, nada é removido, e as adições chegam como novos campos opcionais, novas
mensagens e novos métodos. Um cliente gerado a partir do arquivo da 0.15.9 continua funcionando com
todo gateway posterior; ele simplesmente não vê o que foi adicionado depois.
Obtendo o proto
Qualquer uma destas opções te dá o mesmo arquivo:-
Do próprio gateway. A server reflection vem ligada por padrão, então uma ferramenta que a fale
não precisa de arquivo nenhum:
Seu provedor pode ter desligado a reflection; nesse caso, use uma das outras duas.
- Deste site: O arquivo proto, para copiar ou baixar.
-
Do seu provedor, como
fireflo.proto.
protoc com o plugin gRPC,
buf generate, python -m grpc_tools.protoc, ou o plugin protobuf do Gradle ou do Maven. O arquivo
define go_package (fireflo/v1;fireflov1) e csharp_namespace (FireFlo.V1); em Java, as classes
geradas ficam no pacote fireflo.v1. Ele importa apenas google/protobuf/timestamp.proto, que toda
distribuição de protobuf inclui.
Limites que se aplicam a toda chamada
Seu provedor pode alterar cada um desses; os valores acima são os padrões.
Para onde ir em seguida
Autenticação e sessões
Faça login uma vez, carregue o token, faça login de novo em SESSION_EXPIRED.
Enviando mensagens
Send e SendStream, cada campo ao lado do seu nome no REST.
Erros e códigos de status
Status REST, código gRPC, código de erro e o que fazer.
Recibos de entrega via gRPC
Subscribe, Pull e Ack — pelo menos uma vez.
Exemplos
grpcurl, Python, Java e Go.
O arquivo proto
O contrato inteiro.