Esta página é destinada a parceiros do Eitri que precisam disparar push notifications para os dispositivos de uma loja Eitri Shopping usando a infraestrutura do Eitri.

O fluxo é padrão OAuth 2.0 client credentials:

1. O time interno do Eitri gera um par client_id / client_secret para a sua integração, vinculado a uma loja específica.
2. Você troca essas credenciais por um access token em POST /v1/oauth/token.
3. Você usa esse token para chamar um dos endpoints de envio:
   • POST /v1/partner/push — push livre, com título, corpo e dispositivos definidos por você.
   • POST /v1/partner/push/order-status — push de alteração de status de pedido, em que você envia apenas o pedido e o Eitri monta e dispara a notificação.

URL base (produção): https://api.eitri.tech/push-notification-eitri-shop-api

1. Solicitando as credenciais¶

As credenciais não são autoatendimento. Não existe cadastro público: elas são geradas pelo time do Eitri mediante solicitação.

Abra uma solicitação com o time interno do Eitri (seu contato comercial ou o canal de suporte) informando:

Após a criação, o time do Eitri fornece a você o client_id e o client_secret — é esse par que você usará para se autenticar em POST /v1/oauth/token e obter o access token do push.

Ciclo de vida da credencial¶

Todas as operações abaixo são feitas pelo time do Eitri, mediante solicitação:

• Criação — gera o client_id e o client_secret para uma loja.
• Rotação — gera um novo segredo para o mesmo client_id (invalida o anterior).
• Atualização de escopos — altera o conjunto de escopos da credencial.
• Revogação — desativa a credencial. Tokens já emitidos deixam de funcionar imediatamente.

Uma credencial é sempre vinculada a uma única loja. Se você atende várias lojas, solicite uma credencial por loja.

2. Obtendo o access token¶

POST /v1/oauth/token

Endpoint público (não requer autenticação prévia além das próprias credenciais). O grant_type suportado é client_credentials.

As credenciais podem ser enviadas de duas formas:

a) No corpo da requisição

curl --request POST \
  --url https://api.eitri.tech/push-notification-eitri-shop-api/v1/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "pk_live_2f1c...",
    "client_secret": "s3cr3t..."
  }'

b) Via HTTP Basic (Authorization: Basic base64(client_id:client_secret))

curl --request POST \
  --url https://api.eitri.tech/push-notification-eitri-shop-api/v1/oauth/token \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic cGtfbGl2ZV8yZjFjLi4uOnMzY3IzdC4uLg==' \
  --data '{ "grant_type": "client_credentials" }'

Resposta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "push:send"
}

O token tem validade padrão de 900 segundos (15 minutos) — sempre use o valor retornado em expires_in em vez de fixar o tempo no código. Ele já identifica a loja vinculada à credencial; você não precisa informar a loja nas chamadas seguintes.

Reaproveite o token até ele expirar em vez de pedir um novo a cada push.

Erros¶

3. Enviando um push livre¶

POST /v1/partner/push

Requer o header Authorization: Bearer <access_token> e o escopo push:send.

curl --request POST \
  --url https://api.eitri.tech/push-notification-eitri-shop-api/v1/partner/push \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --data '{
    "deviceIds": ["fcm-token-do-dispositivo-1", "fcm-token-do-dispositivo-2"],
    "notification": {
      "title": "Seu pedido saiu para entrega",
      "body": "Acompanhe pelo app",
      "image": "https://cdn.exemplo.com/banner.png"
    },
    "data": {
      "deeplink": "eitrishopping://orders/123"
    }
  }'

Corpo da requisição¶

Resposta — 202 Accepted¶

{
  "accepted": true,
  "requestId": "9c2a5f4e-...",
  "enqueued": 2
}

O envio é assíncrono: o 202 significa que a solicitação foi aceita, não que a notificação já chegou ao dispositivo. Guarde o requestId — é ele que você informa ao suporte do Eitri para rastrear um envio.

Dispositivos desconhecidos ou que não pertencem à loja da sua credencial são ignorados no processamento. Portanto enqueued reflete o que foi aceito, não o total efetivamente entregue.

Erros¶

4. Push de alteração de status de pedido¶

POST /v1/partner/push/order-status

Alternativa ao endpoint anterior para o caso mais comum: avisar o cliente de que o status do pedido mudou. Aqui o parceiro não monta a notificação nem escolhe os dispositivos — envia apenas a identificação do pedido e o novo status, e o Eitri faz o resto:

1. Recebe o orderId e o orderStatus.
2. Busca o pedido na plataforma de e-commerce da loja (VTEX, Wake ou Shopify) para descobrir o cliente e os dados do pedido.
3. Resolve os dispositivos daquele cliente registrados para a loja.
4. Monta a notificação a partir da mensagem configurada para aquele parceiro e aquele status e dispara o push.

Isso significa que os textos das notificações são definidos na configuração da integração junto ao Eitri, e não a cada requisição — para alterá-los, fale com o time do Eitri.

Requer o header Authorization: Bearer <access_token>, exatamente como o endpoint de push livre.

curl --request POST \
  --url https://api.eitri.tech/push-notification-eitri-shop-api/v1/partner/push/order-status \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --data '{
    "orderId": "123",
    "orderStatus": "CHANGE"
  }'

Corpo da requisição¶

A loja é sempre a do token — não há campo de loja no corpo e não é possível consultar pedidos de outra loja com a mesma credencial.

Resposta — 202 Accepted¶

Assim como no push livre, o processamento é assíncrono: o 202 confirma que a solicitação foi aceita, não que a notificação foi entregue. A resposta traz um requestId para rastreamento.

O push pode não ser enviado — sem erro para o parceiro — quando o pedido não é encontrado na plataforma, o cliente não possui dispositivos registrados, ou não há mensagem configurada para aquele status. Nesses casos, informe o requestId ao suporte do Eitri para verificação.

Erros¶

Boas práticas¶

• Guarde o segredo em cofre, nunca no código-fonte, em repositório ou no front-end. A integração deve ser feita a partir do seu backend.
• Cacheie o access token durante sua validade e renove-o apenas quando expirar (ou ao receber 401).
• Trate o 202 como aceite, não como entrega. Se precisar de confirmação de entrega, alinhe com o time do Eitri.
• Envie os deviceIds em lotes em vez de uma requisição por dispositivo.
• Peça rotação imediata ao suspeitar de vazamento do segredo.

Deeplinks¶

Para direcionar o usuário a uma tela específica ao tocar na notificação, use o campo data com o deeplink correspondente. Veja nossa documentação de deeplinks para saber como estruturá-los.