Callbacks

As callbacks permitem que sua aplicação seja notificada de forma assíncrona sobre eventos e alterações que ocorrem na plataforma. Sempre que um evento configurado ocorrer, enviaremos para a URL definida os dados relacionados ao evento, permitindo que sua aplicação acompanhe as alterações sem a necessidade de consultar a API continuamente.

Cada callback possui eventos específicos que determinam quando a notificação será enviada e quais informações estarão disponíveis na requisição.

Configuração

A URL de cada callback poderá ser definida por você de acordo com as necessidades da sua integração. Para solicitar o cadastro de uma callback, entre em contato conosco informando a URL que deseja utilizar.

Após o cadastro da URL em nosso sistema, você receberá um e-mail contendo a URL configurada e um token único de autenticação, que deverá ser utilizado para validar as requisições recebidas.

É importante configurar as callbacks de forma segura para reduzir o risco de vulnerabilidades. Para isso, recomendamos:

• utilizar HTTPS nas URLs das callbacks, garantindo a proteção dos dados durante a transmissão;

• implementar, em sua aplicação, uma validação do token de autenticação enviado nas requisições, permitindo verificar se os dados recebidos são provenientes da nossa plataforma.

Headers

Nossa plataforma incluirá na requisição os headers necessários para identificação e autenticação da callback.

O token de autenticação fornecido no momento do cadastro será enviado no header Authorization, utilizando o esquema Bearer, e no header clientID:

"Content-Type": "application/json",
"Origin": "$url_base",
"Authorization": "Bearer $token_de_autenticacao",
"clientID": "$token_de_autenticacao"

Callback de Provedor → POST www.example.customer.com

A callback de provedor é acionada sempre que ocorrer uma ação na plataforma relacionada a um provedor. Nesse caso, enviaremos os dados atuais do provedor e a ação realizada.

Ações que acionam a callback:

• Criação

  → Identificada no JSON pela action create.

  → Ocorre quando um novo provedor é cadastrado.

• Edição

  → Identificada no JSON pela action update.

  → Ocorre quando algum dado do provedor é alterado.

Exemplo de envio:

{
    "customer": {
        "document": "55096452000100",
        "name": "Live Fast Web",
        "email": "livefast.mail@fastweb.net",
        "billing_email": "livefast.billing@fastweb.net",
        "support_email": "livefast.support@fastweb.net",
        "municipal_registration": "34754071",
        "state": "RJ",
        "city": "Itaguaí",
        "zip_code": "23812575",
        "address": "Rua Antônia Barbosa Cunha",
        "district": "Centro",
        "number": "70",
        "complement": "Quadra 18",
        "telephone": "+552198765-1240",
        "telephone2": "+5521981357840",
        "total_subscribers_base": 300000,
        "plan": "COMUNIDADE ISPs",
        "erp": {
            "name": "Grupo Voalle",
            "connection_data": {
                "URL": "URL",
                "Token": "Token"
            }
        },
        "hub": "HUB 12",
        "status": "active",
        "has_unpaid_bills": false,
        "customer_success": {
            "name": "Zemlak II",
            "email": "wiegand.jadon@example.com",
            "telephone": "+5596937366907"
        }
    },
    "response": "success",
    "action": "create",
    "is_integration_active": true,
    "access_token": "9632947623746c029a51d613fcf4a303f57b99db7ec48f645ed7e76685e6bde9823a66f47",
    "token": "c029a51d613fcf4a303f57b99db7ec48f645ed7e76685e6bde9823a66f47",   
    "partner": "celeti"
}

Os dados de conexão do ERP, contidos no campo connection_data, variam de acordo com o ERP utilizado. Dessa forma, a estrutura pode apresentar diferentes campos e índices, que podem variar conforme o ERP em questão.

Callback de Assinante → POST www.example.subscriber.com

A callback de assinante é acionada sempre que ocorrer uma ação na plataforma relacionada a um assinante. Nesse caso, enviaremos os dados atuais do assinante e a ação realizada.

Ações que acionam a callback:

• Criação

  → Identificada no JSON pela action create.

  → Ocorre quando um novo assinante é cadastrado.

• Edição

  → Identificada no JSON pela action update.

  → Ocorre quando algum dado do assinante é alterado.

• Exclusão

  → Identificada no JSON pela action delete.

  → Ocorre quando um assinante é excluído.

• Criação ou alteração de serviço (token)

  → Identificada no JSON pela action update-token.

  → Ocorre quando um novo serviço é ativado para o assinante ou quando o status de um serviço existente é alterado.

A callback também será enviada quando houver uma alteração no status do serviço que não dependa diretamente de uma ação do usuário. Por exemplo, quando um usuário solicita a suspensão de um serviço por meio da API, o serviço passa inicialmente para o status “aguardando suspensão” (status intermediário) e, após a confirmação do processo, para “suspenso” (status final). Nesse momento, a callback será enviada informando o novo status do serviço.

Exemplo de envio:

{
    "subscribers": [
        {
            "id": 1,
            "email": "walker.jeanie@example.net",
            "name": "Walker Jeanie",
            "document": "62458124483",
            "phone": "+5526849068464",
            "internet_speed_id":1,
            "created_at":"2022-06-16T03:00:00.000000Z",
            "customer_plan":"Plano Globoplay 10Mbps"
            "services": [
                {
                    "token_created_at":"2025-06-02T16:55:37.000000Z",
                    "content_supplier_product_id": 1,
                    "content_supplier_product_name": "Globoplay",
                    "content_supplier_product_code": "globoplay",
                    "status_updated_at":"2022-06-16T03:00:00.000000Z",
                    "status_id": 1,
                    "status": "active",
                    "related_content_supplier_product_ids": [25]
                }
            ]
        }
    ],
    "response": "success",
    "customer_document": "55096452000100",
    "action": "create",
    "token": "t029a51d613fcf4a303f57b99db7ec48f645ed7e76685e6bde9823a66f47",
    "partner": "celeti"
}'

Callback de Ativação → POST www.example.activation.com

A callback de ativação é enviada sempre que um serviço for ativado. Ela também é acionada quando o usuário solicitar o reenvio do e-mail de ativação por meio do endpoint correspondente.

Nesses casos, enviaremos para a URL configurada os dados atuais do assinante, incluindo as informações do serviço adquirido e a respectiva URL de ativação.

Exemplo de envio:

{
  "subscribers": [
    {
      "id": 1,
      "email": "corey.taylor@mail.com",
      "name": "Corey Taylor",
      "document": "92780461080",
      "phone": "+5521982217775",
      "internet_speed_id": 1,
      "created_at": "2022-06-16T03:00:00.000000Z",
      "customer_plan": "Plano Globoplay 10Mbps",
      "service": {
        "token_created_at": "2022-06-16T03:00:00.000000Z",
        "content_supplier_product_id": 1,
        "content_supplier_product_name": "Globoplay",
        "content_supplier_product_code": "globoplay",
        "status_updated_at": "2022-06-16T03:00:00.000000Z",
        "activation_link": "url de ativação",
        "related_content_supplier_product_ids": [
          25
        ]
      }
    }
  ],
  "response": "success",
  "customer_document": "42144052000181",
  "action": "activation",
  "token": "c029a51d613fcf4a303f57b99db7ec48f645ed7e76685e6bde9823a66f47",
  "partner": "celeti"
}