Segurança

📘

BTG Id

O Authorization Server do BTG Empresas se chama BTG Id. Usando o BTG Id, um aplicativo parceiro consegue consentimento e autorização para executar operações nas APIs do BTG em nome do cliente. Para saber mais, acesse a documentação do BTG Id

Escopos necessários

O token para consumir a API de Protest de Cobrança deve ser gerado usando o Authorization Code.

É necessário incluir os seguintes escopos:

Operações de escrita (POST, DELETE) exigem o escopo collections. Operações de leitura (GET) aceitam ambos os escopos.

Protest de Cobrança — Visão Geral da API

A API de Protest de Cobrança do BTG Empresas permite que sua empresa inicie um protesto notarial contra um devedor que não quitou um boleto após o vencimento. O protesto é um ato público que registra formalmente a inadimplência e pode impactar o cadastro de crédito do devedor.

O fluxo é organizado em torno de um único conceito central: o protesto (registro vinculado a uma cobrança específica). Antes de agendar um protesto, a cobrança deve estar vencida e em estado elegível.

📘

Restrição de tipo

Protest é suportado exclusivamente para cobranças do tipo BANKSLIP. Pix, QR Code e cartão de crédito não são compatíveis.

Fluxo de Protestos

Agendar Protesto

O agendamento de um protesto é o ponto de entrada do fluxo. Você informa o collectionId da cobrança vencida e a API registra o protesto para envio ao cartório.

Requisição — POST /{companyId}/banking/protest

{
  "collectionId": "0436436c-77a3-45c7-94af-527cb4dc80e2"
}

A cobrança referenciada deve ser do tipo BANKSLIP e estar em um estado que permita protesto. O envio ao cartório ocorre de forma assíncrona após o agendamento.

Resposta — 201 Created

{
  "id": "9b3f1a2e-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "collectionId": "0436436c-77a3-45c7-94af-527cb4dc80e2",
  "status": "SCHEDULED",
  "issueDate": "2026-08-05",
  "collectionDueDate": "2026-07-15",
  "collectionIssueDate": "2026-07-01",
  "origin": "DEVELOPERS",
  "creditor": {
    "name": "Empresa XYZ Ltda",
    "fantasyName": "XYZ Pagamentos",
    "taxId": "37297902000141",
    "personType": "PJ",
    "address": {
      "state": "SP",
      "city": "São Paulo",
      "street": "Av. Brigadeiro Faria Lima",
      "zipCode": "04538-132",
      "number": "3477"
    }
  },
  "debtor": {
    "name": "João da Silva",
    "taxId": "12345678901",
    "personType": "PF",
    "email": "[email protected]",
    "phoneNumber": "5511999999999",
    "address": {
      "state": "SP",
      "city": "São Paulo",
      "street": "Rua Exemplo",
      "zipCode": "01310-100",
      "number": "100"
    }
  },
  "documents": {
    "isCancellationDocumentAvailable": false,
    "isProtestDocumentAvailable": false
  },
  "createdAt": "2026-07-28T10:00:00.000Z",
  "updatedAt": "2026-07-28T10:00:00.000Z"
}

Guarde o campo id retornado — ele é o protestId e será usado em todas as operações subsequentes: consulta, cancelamento e obtenção de documento.

Buscar Protesto

Uma vez agendado, é possível consultar o estado do protesto a qualquer momento usando o protestId.

Resposta — GET /{companyId}/banking/protest/{id}

{
  "id": "9b3f1a2e-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "collectionId": "0436436c-77a3-45c7-94af-527cb4dc80e2",
  "status": "CONFIRMED",
  "issueDate": "2026-08-05",
  "collectionDueDate": "2026-07-15",
  "collectionIssueDate": "2026-07-01",
  "origin": "DEVELOPERS",
  "creditor": { "..." : "..." },
  "debtor": { "..." : "..." },
  "documents": {
    "isCancellationDocumentAvailable": false,
    "isProtestDocumentAvailable": true
  },
  "createdAt": "2026-07-28T10:00:00.000Z",
  "updatedAt": "2026-07-28T12:30:00.000Z"
}

O campo documents.isProtestDocumentAvailable indica quando o documento notarial está pronto para download. O documento de cancelamento (isCancellationDocumentAvailable) só fica disponível após o cartório confirmar o cancelamento.

Obter Documento de Protesto

O documento é gerado pelo cartório e fica disponível somente após o protesto atingir o status CONFIRMED (para o documento de protesto) ou após o cancelamento ser confirmado (para o documento de cancelamento).

Requisição — GET /{companyId}/banking/protest/{id}/document?type=PROTEST

O parâmetro type aceita dois valores:

Resposta — 200 OK

{
  "base64": "JVBERi0xLjQKMSAwIG9iago8PC..."
}

Decodifique o campo base64 para obter o PDF do documento.

📘

Disponibilidade do documento

Consultar o documento antes de ele estar disponível retorna 404. Verifique documents.isProtestDocumentAvailable (ou isCancellationDocumentAvailable) na resposta do GET /{companyId}/banking/protest/{id} antes de tentar o download.

Cancelar Protesto (individual)

Cancela um protesto individualmente de forma síncrona. O protesto deve estar em estado que permita cancelamento (SCHEDULED ou PROCESSING).

Requisição — DELETE /{companyId}/banking/protest/{id}?feesResponsible=PAYEE

O parâmetro de query feesResponsible é opcional:

Resposta — 204 No Content

Sem corpo de resposta. Para verificar o estado atualizado, consulte o protesto via GET /{companyId}/banking/protest/{id}.

Operações em Lote

As operações em lote são processadas de forma assíncrona — a API retorna 202 Accepted imediatamente e processa cada item individualmente. Use o endpoint individual GET /{companyId}/banking/protest/{id} para acompanhar o status de cada protesto.

Agendar Protestos em Lote

Requisição — POST /{companyId}/banking/protest/batch

{
  "collectionIds": [
    "0436436c-77a3-45c7-94af-527cb4dc80e2",
    "1e5d83c8-92b5-4f39-827c-8c3d45a2b9f1"
  ]
}

Resposta — 202 Accepted

Sem corpo de resposta.

Cancelar Protestos em Lote

Requisição — DELETE /{companyId}/banking/protest/batch

{
  "protests": [
    {
      "protestId": "9b3f1a2e-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
      "feesResponsible": "PAYEE"
    }
  ]
}

O campo feesResponsible por item é opcional. Quando omitido, nenhum responsável por custas é definido para aquele protesto.

Resposta — 202 Accepted

Sem corpo de resposta.

Máquina de estados do Protesto

O protesto percorre os seguintes status ao longo do seu ciclo de vida:

stateDiagram-v2
    [*] --> SCHEDULED
    SCHEDULED --> PROCESSING
    SCHEDULED --> CANCELED
    PROCESSING --> SENT
    PROCESSING --> FAILED
    PROCESSING --> CANCELED
    SENT --> CONFIRMED
    CONFIRMED --> PROTESTED
    CONFIRMED --> REMOVED
    PROTESTED --> FORFEITING
    PROTESTED --> PAID
    PROTESTED --> SETTLED
    FORFEITING --> FORFEITED
    FORFEITING --> REMOVING
    REMOVING --> REMOVE_FAILED
    REMOVING --> REMOVED
    CANCELED --> [*]
    FAILED --> [*]
    FORFEITED --> [*]
    REMOVE_FAILED --> [*]
    REMOVED --> [*]
    PAID --> [*]
    SETTLED --> [*]

Referência de IDs

Operações individuais vs. em lote