Documentação para Configuração do Webhook de Portabilidade

1. Objetivo

Este documento tem como objetivo orientar o time de desenvolvimento do cliente MVNO na criação da URL do webhook de portabilidade, especificando o formato do corpo da requisição, os parâmetros necessários e as boas práticas de segurança e validação.

2. Estrutura da URL do Webhook

A URL do webhook deve ser uma URL pública e segura (HTTPS) para garantir a segurança na transmissão dos dados. Recomenda-se que a URL esteja protegida por mecanismos de autenticação (como tokens de autenticação) e controle de acesso por IP.

Exemplo de URL:
https://seu-dominio.com/api/webhook/portability

3. Método HTTP Utilizado

O método HTTP utilizado para a chamada do webhook será o POST, pois ele permite o envio de dados no corpo da requisição.

4. Cabeçalhos da Requisição (Headers)

Para garantir a segurança e a identificação da requisição, recomenda-se a utilização dos seguintes cabeçalhos:

• Content-Type: application/json
• Authorization: Bearer {token_de_autenticacao}

5. Corpo da Requisição (Payload)

O corpo da requisição será enviado no formato JSON com os seguintes campos obrigatórios:

{
  "PhoneNumber": "19982614648",
  "PortabilityStatus": 2,
  "DateOfChange": "2024-10-25T15:38:56.4330959+00:00"
}

 

Descrição dos Campos

• PhoneNumber (string): O número de telefone associado à portabilidade. Deve estar no formato E.164, ou seja, com o código do país e o DDD.
• PortabilityStatus (integer): O status da portabilidade, podendo ter os seguintes valores:
  • 0: Solicitado
  • 1: Conflito
  • 2: Pendente
  • 3: Cancelamento em Progresso
  • 4: Cancelado
  • 5: Ativo
  • 6: Erro
• DateOfChange (string): A data e a hora da alteração no status da portabilidade, no formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.fffffffZ).

6. Exemplo de Requisição HTTP

Exemplo de uma requisição HTTP utilizando cURL:

curl -X POST \
  https://seu-dominio.com/api/webhook/portability \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token_de_autenticacao}" \
  -d '{
    "PhoneNumber": "19982614648",
    "PortabilityStatus": 2,
    "DateOfChange": "2024-10-25T15:38:56.4330959+00:00"
  }'

7. Validações Recomendadas

• Validação do Formato JSON: Certifique-se de que o JSON seja válido.
• Validação dos Campos: Verifique se os campos obrigatórios estão presentes e no formato correto.
• Controle de IP: Caso possível, limite as chamadas para serem recebidas apenas de IPs conhecidos.

8. Tratamento de Erros

Em caso de falha no processamento do webhook, recomenda-se retornar uma resposta HTTP adequada:

9. Boas Práticas de Segurança

• HTTPS: Sempre utilize HTTPS para proteger os dados em trânsito.
• Autenticação: Utilize tokens de autenticação JWT ou tokens de API seguros.
• Validação de Origem: Verifique se o IP de origem é confiável.
• Rate Limiting: Implemente limites de taxa para evitar ataques de negação de serviço (DDoS).

10. Contato e Suporte

Para dúvidas ou suporte técnico, entre em contato com o time de desenvolvimento ou o suporte técnico do cliente MVNO.