{ "openapi": "3.0.3", "info": { "title": "Destrava Public API V2", "version": "2.0.0", "description": "Contrato público agregado dos domínios serverless da Destrava para o ambiente production." }, "servers": [ { "url": "https://decwk785irlh8.cloudfront.net", "description": "Ambiente production" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Contracts" }, { "name": "Identity Profile" }, { "name": "Notifications" }, { "name": "Permission" }, { "name": "Receivables Financier" }, { "name": "Settlement" } ], "paths": { "/api/v2/accounts": { "get": { "operationId": "settlement_v2_accounts_list", "summary": "list public V2 operational accounts for the authenticated client", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "REQUEST_PENDING", "REQUESTED", "CREATION_PROCESSING", "CREATED", "CREATION_FAILED", "CLOSED" ] } }, { "name": "operationId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "ownerTaxId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "accountNumber", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "lastItem", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Operational account page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accounts", "pagination" ], "properties": { "accounts": { "type": "array", "items": { "type": "object", "required": [ "accountId", "category", "status", "ownerTaxId", "bankAccount", "balance", "operation", "createdAt" ], "properties": { "accountId": { "type": "string" }, "category": { "type": "string", "enum": [ "OPERATIONAL" ] }, "status": { "type": "string" }, "ownerTaxId": { "type": "string" }, "bankAccount": { "type": "object", "properties": { "ispb": { "type": "string" }, "branch": { "type": "string" }, "accountNumber": { "type": "string" }, "accountVerificationDigit": { "type": "string" } } }, "balance": { "type": "number" }, "operation": { "type": "object", "properties": { "operationId": { "type": "string" }, "onboardingId": { "type": "string" }, "contractId": { "type": "string" }, "contractType": { "type": "string" } } }, "createdAt": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "properties": { "currentItem": { "type": "string" }, "limit": { "type": "integer" }, "nextItem": { "type": "string", "nullable": true }, "totalItems": { "type": "integer" } } } } } } } }, "400": { "description": "Invalid filters or pagination parameters. The removed contractId and contractType filters are rejected." }, "401": { "description": "Client identity is required." }, "403": { "description": "Required scope is missing." } }, "tags": [ "Settlement" ] } }, "/api/v2/accounts/{accountId}/balance": { "get": { "operationId": "settlement_v2_account_balance_get", "summary": "get public V2 account balance for the authenticated client", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account balance snapshot.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accountId", "availableBalance", "blockedBalance", "totalBalance", "updatedAt" ], "properties": { "accountId": { "type": "string" }, "availableBalance": { "type": "number" }, "blockedBalance": { "type": "number" }, "totalBalance": { "type": "number" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Client identity is required." }, "403": { "description": "Required scope is missing." }, "404": { "description": "Account was not found for the authenticated client." } }, "tags": [ "Settlement" ] } }, "/api/v2/accounts/{accountId}/transactions": { "get": { "operationId": "settlement_v2_account_transactions_list", "summary": "list public V2 account transactions for the authenticated client", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 0 } }, { "name": "lastItem", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account transaction page with normalized provider context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "currentItem": { "type": "string" }, "limit": { "type": "integer" }, "nextItem": { "type": "string" }, "totalItems": { "type": "integer" } } }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "transactionAmount": { "type": "number" }, "createdAt": { "type": "string" }, "createdAtTimestamp": { "type": "string" }, "acquirerTaxId": { "type": "string" }, "acquirerName": { "type": "string" }, "providerContext": { "type": "object", "description": "Normalized provider context without providerRawPayload on the public V2 route." } } } }, "totals": { "type": "object", "properties": { "transactionsAmount": { "type": "number" } } } } } } } }, "400": { "description": "Invalid pagination parameters." }, "401": { "description": "Client identity is required." }, "403": { "description": "Required scope is missing." }, "404": { "description": "Account was not found for the authenticated client." } }, "tags": [ "Settlement" ] } }, "/api/v2/cash-advances": { "get": { "operationId": "contracts_cash_advances_v2_list", "summary": "list V2 cash-advance contracts", "responses": { "200": { "description": "Expected response." }, "400": { "description": "Invalid query parameter." } }, "tags": [ "Contracts" ] }, "post": { "operationId": "contracts_cash_advances_v2_create", "summary": "create a V2 cash-advance contract", "responses": { "202": { "description": "Expected response." }, "400": { "description": "Invalid JSON or request schema violation." } }, "tags": [ "Contracts" ] } }, "/api/v2/cash-advances/{cashAdvanceId}": { "parameters": [ { "name": "cashAdvanceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_cash_advances_v2_detail", "summary": "read a V2 cash-advance contract", "responses": { "200": { "description": "Expected response." }, "404": { "description": "Contract not found." } }, "tags": [ "Contracts" ] }, "delete": { "operationId": "contracts_cash_advances_v2_delete", "summary": "delete a V2 cash-advance contract", "responses": { "202": { "description": "Expected response." }, "404": { "description": "Contract not found." } }, "tags": [ "Contracts" ] } }, "/api/v2/cash-advances/{cashAdvanceId}/receivables": { "parameters": [ { "name": "cashAdvanceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_cash_advances_v2_receivables", "summary": "list V2 cash-advance receivables", "responses": { "200": { "description": "Expected response." }, "404": { "description": "Contract not found." } }, "tags": [ "Contracts" ] } }, "/api/v2/collateralized-credits/summary": { "get": { "operationId": "contracts_collateralized_credits_v2_summary", "summary": "summarize V2 collateralized-credit contracts", "responses": { "200": { "description": "Expected response." }, "400": { "description": "Invalid query parameter." } }, "tags": [ "Contracts" ] } }, "/api/v2/collateralized-credits/{creditId}/receivables": { "parameters": [ { "name": "creditId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_collateralized_credits_v2_receivables", "summary": "list V2 collateralized-credit receivables", "responses": { "200": { "description": "Expected response." }, "404": { "description": "Contract not found." } }, "tags": [ "Contracts" ] } }, "/api/v2/collections": { "get": { "operationId": "contracts_collection_v2_list", "summary": "list public collection contracts", "responses": { "200": { "description": "Expected response." }, "400": { "description": "Invalid query parameter." }, "401": { "description": "Missing client identity." } }, "tags": [ "Contracts" ] } }, "/api/v2/collections/automatic-refund": { "patch": { "operationId": "contracts_collection_v2_automatic_refund_patch", "summary": "update automatic refund configuration for a collection company", "responses": { "200": { "description": "Automatic refund configuration was updated." }, "400": { "description": "Invalid JSON or request schema violation." }, "401": { "description": "Missing client identity." }, "404": { "description": "Client company projection was not found locally." } }, "tags": [ "Contracts" ] } }, "/api/v2/collections/by-strategy": { "post": { "operationId": "contracts_collection_v2_create_by_strategy", "summary": "create a public collection contract by strategy", "responses": { "202": { "description": "Collection accepted for asynchronous registration." }, "400": { "description": "Invalid JSON, unknown field, invalid field type, or multiple JSON objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsRequestBodyErrorResponse" } } } }, "422": { "description": "Well-formed request body failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsRequestBodyErrorResponse" } } } }, "401": { "description": "Missing client identity." }, "403": { "description": "Client is not authorized for the company." }, "409": { "description": "External collection ID already exists for the same client and company." }, "424": { "description": "Required settlement write-off accounts are not configured for the financier." } }, "tags": [ "Contracts" ] } }, "/api/v2/collections/summary": { "get": { "operationId": "contracts_collection_v2_summary", "summary": "summarize public collection contracts", "responses": { "200": { "description": "Expected response." }, "400": { "description": "Invalid query parameter." }, "401": { "description": "Missing client identity." } }, "tags": [ "Contracts" ] } }, "/api/v2/collections/{collectionId}": { "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_collection_v2_detail", "summary": "read a public collection contract", "responses": { "200": { "description": "Expected response." }, "400": { "description": "Invalid collection ID." }, "401": { "description": "Missing client identity." }, "404": { "description": "Collection was not found for the client." } }, "tags": [ "Contracts" ] } }, "/api/v2/collections/{collectionId}/events": { "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_collection_v2_events", "summary": "list public collection contract events", "responses": { "200": { "description": "Expected response." }, "400": { "description": "Invalid collection ID or query parameter." }, "401": { "description": "Missing client identity." }, "404": { "description": "Collection was not found for the client." } }, "tags": [ "Contracts" ] } }, "/api/v2/collections/{collectionId}/receivables": { "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_collection_v2_receivables", "summary": "list public collection contract receivables", "responses": { "200": { "description": "Expected response." }, "400": { "description": "Invalid collection ID or query parameter." }, "401": { "description": "Missing client identity." }, "404": { "description": "Collection was not found for the client." } }, "tags": [ "Contracts" ] } }, "/api/v2/companies": { "get": { "operationId": "permission_v2_companies_list", "summary": "Listar empresas", "description": "Escopo OAuth necessário: `companies:read`. Lista as empresas vinculadas ao cliente autenticado.", "responses": { "200": { "description": "Página de empresas." } }, "tags": [ "Permission" ] }, "post": { "operationId": "permission_v2_companies_create", "summary": "Criar empresas", "description": "Escopo OAuth necessário: `companies:write`. Cria uma ou mais empresas no contrato público da API V2.", "responses": { "201": { "description": "Empresas criadas." }, "207": { "description": "Resultado multiempresa com o status de cada item." } }, "tags": [ "Permission" ] } }, "/api/v2/companies/{companyId}": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_company_get", "summary": "Detalhar empresa", "description": "Escopo OAuth necessário: `companies:read`. Retorna os dados de uma empresa vinculada ao cliente autenticado.", "responses": { "200": { "description": "Detalhes da empresa." } }, "tags": [ "Permission" ] }, "delete": { "operationId": "permission_v2_company_delete", "summary": "Desativar empresa", "description": "Escopo OAuth necessário: `companies:write`. Desativa uma empresa vinculada ao cliente autenticado.", "responses": { "204": { "description": "Empresa desativada sem corpo de resposta." }, "409": { "description": "Empresa possui opt-in ativo." } }, "tags": [ "Permission" ] } }, "/api/v2/companies/{companyId}/acquirers": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_company_acquirers_get", "summary": "Consultar credenciadoras da empresa", "description": "Escopo OAuth necessário: `read:companies:acquirers`. Retorna as credenciadoras permitidas para uma empresa do cliente autenticado.", "responses": { "200": { "description": "Credenciadoras permitidas da empresa." } }, "tags": [ "Permission" ] }, "put": { "operationId": "permission_v2_company_acquirers_update", "summary": "Atualizar credenciadoras da empresa", "description": "Escopo OAuth necessário: `write:companies:acquirers`. Atualiza as credenciadoras permitidas para uma empresa do cliente autenticado.", "responses": { "200": { "description": "Credenciadoras da empresa atualizadas." } }, "tags": [ "Permission" ] } }, "/api/v2/companies/{companyId}/payment-schemes": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_company_payment_schemes_get", "summary": "Consultar arranjos de pagamento da empresa", "description": "Escopo OAuth necessário: `read:companies:schemes`. Retorna os arranjos de pagamento permitidos para uma empresa do cliente autenticado.", "responses": { "200": { "description": "Arranjos de pagamento permitidos da empresa." } }, "tags": [ "Permission" ] }, "put": { "operationId": "permission_v2_company_payment_schemes_update", "summary": "Atualizar arranjos de pagamento da empresa", "description": "Escopo OAuth necessário: `manage:companies:schemes`. Atualiza os arranjos de pagamento permitidos para uma empresa do cliente autenticado.", "responses": { "200": { "description": "Arranjos de pagamento da empresa atualizados." } }, "tags": [ "Permission" ] } }, "/api/v2/companies/{companyId}/refund-account": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "settlement_v2_refund_account_get", "summary": "get a refund account through the public V2 contract", "responses": { "200": { "description": "Expected response." } }, "tags": [ "Settlement" ] }, "post": { "operationId": "settlement_v2_refund_account_create", "summary": "create a refund account through the public V2 contract", "responses": { "201": { "description": "Expected response." } }, "tags": [ "Settlement" ] }, "put": { "operationId": "settlement_v2_refund_account_update", "summary": "update a refund account through the public V2 contract", "responses": { "200": { "description": "Expected response." } }, "tags": [ "Settlement" ] } }, "/api/v2/company-groups": { "post": { "operationId": "permission_v2_company_group_create", "summary": "Criar grupo de empresas", "description": "Escopo OAuth necessário: `write:companies:groups`. Cria um grupo de empresas para o cliente autenticado.", "responses": { "201": { "description": "Grupo de empresas criado." } }, "tags": [ "Permission" ] } }, "/api/v2/company-groups/{groupId}": { "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_company_group_get", "summary": "Detalhar grupo de empresas", "description": "Escopo OAuth necessário: `read:companies:groups`. Retorna os dados de um grupo de empresas do cliente autenticado.", "responses": { "200": { "description": "Detalhes do grupo de empresas." } }, "tags": [ "Permission" ] } }, "/api/v2/company-groups/{groupId}/members": { "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "permission_v2_company_group_members_add", "summary": "Adicionar empresas ao grupo", "description": "Escopo OAuth necessário: `write:companies:groups`. Adiciona empresas a um grupo do cliente autenticado.", "responses": { "200": { "description": "Empresas adicionadas ao grupo." } }, "tags": [ "Permission" ] }, "delete": { "operationId": "permission_v2_company_group_members_remove", "summary": "Remover empresas do grupo", "description": "Escopo OAuth necessário: `write:companies:groups`. Retira empresas de um grupo do cliente autenticado.", "responses": { "200": { "description": "Empresas removidas do grupo." } }, "tags": [ "Permission" ] } }, "/api/v2/opt-ins": { "get": { "operationId": "permission_v2_opt_ins_list", "summary": "Listar opt-ins", "description": "Escopo OAuth necessário: `companies:read`. Lista os opt-ins das empresas vinculadas ao cliente autenticado.", "responses": { "200": { "description": "Página de opt-ins." } }, "tags": [ "Permission" ] }, "post": { "operationId": "permission_v2_opt_ins_create", "summary": "Criar opt-ins", "description": "Escopo OAuth necessário: `companies:write`. Cria opt-ins para empresas vinculadas ao cliente autenticado.", "responses": { "202": { "description": "Opt-ins aceitos para processamento assíncrono." } }, "tags": [ "Permission" ] }, "patch": { "operationId": "permission_v2_opt_in_recurrence_update", "summary": "Atualizar recorrência de opt-in", "description": "Escopo OAuth necessário: `companies:write`. Atualiza a recorrência de um opt-in vinculado ao cliente autenticado.", "responses": { "200": { "description": "Recorrência de opt-in atualizada." } }, "tags": [ "Permission" ] } }, "/api/v2/opt-ins/{optId}": { "parameters": [ { "name": "optId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_opt_in_get", "summary": "Detalhar opt-in", "description": "Escopo OAuth necessário: `companies:read`. Retorna os dados de um opt-in vinculado ao cliente autenticado.", "responses": { "200": { "description": "Detalhes do opt-in." } }, "tags": [ "Permission" ] } }, "/api/v2/receivables/encumbrances/priority/{companyTaxId}": { "get": { "operationId": "receivables_financier_receivable_encumbrance_priority_v2_empty_window", "summary": "Consultar prioridade de gravames", "description": "Escopo OAuth necessário: `read:receivables`. Consulta a prioridade dos gravames de recebíveis de uma empresa em um intervalo de datas.", "parameters": [ { "name": "companyTaxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "scheduleType", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "PERFORMED", "TO_PERFORM" ] } }, { "name": "relativePriority", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "paymentScheme", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "acquirerTaxId", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "encumbranceType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "FIXED", "PERCENTAGE" ] } } ], "responses": { "200": { "description": "Prioridade dos gravames de recebíveis." }, "400": { "description": "Parâmetros da solicitação inválidos." }, "403": { "description": "Permissões insuficientes para acessar a empresa." }, "422": { "description": "Intervalo de datas não processável." } }, "tags": [ "Receivables Financier" ] } }, "/api/v2/receivables/encumbrances/{companyTaxId}": { "get": { "operationId": "receivables_financier_receivable_encumbrances_v2_empty_window", "summary": "Consultar gravames de recebíveis", "description": "Escopo OAuth necessário: `read:receivables`. Consulta os gravames de recebíveis de uma empresa em um intervalo de datas.", "parameters": [ { "name": "companyTaxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "paymentScheme", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "acquirerTaxId", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "encumbranceType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "FIXED", "PERCENTAGE" ] } }, { "name": "scheduleType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PERFORMED", "TO_PERFORM" ] } } ], "responses": { "200": { "description": "Gravames de recebíveis." }, "400": { "description": "Parâmetros da solicitação inválidos." }, "403": { "description": "Permissões insuficientes para acessar a empresa." }, "422": { "description": "Intervalo de datas não processável." } }, "tags": [ "Receivables Financier" ] } }, "/api/v2/receivables/schedule/{companyTaxId}": { "get": { "operationId": "receivables_financier_receivable_schedule_v2_empty_window", "summary": "Consultar agenda de recebíveis", "description": "Escopo OAuth necessário: `read:receivables:schedule`. Consulta a agenda de recebíveis de uma empresa em um intervalo de datas.", "parameters": [ { "name": "companyTaxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "paymentScheme", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "acquirerTaxId", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "minAmount", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "maxAmount", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "Agenda de recebíveis." }, "400": { "description": "Parâmetros da solicitação inválidos." }, "403": { "description": "Permissões insuficientes para acessar a empresa." }, "422": { "description": "Intervalo de datas não processável." } }, "tags": [ "Receivables Financier" ] } }, "/api/v2/schedule-access-requests": { "post": { "operationId": "permission_v2_schedule_access_request_create", "summary": "Solicitar acesso à agenda", "description": "Escopo OAuth necessário: `companies:write`. Cria uma solicitação de acesso à agenda para empresas do cliente autenticado.", "responses": { "202": { "description": "Solicitação de acesso à agenda aceita para processamento assíncrono." } }, "tags": [ "Permission" ] } }, "/api/v2/webhook-deliveries/summary": { "get": { "operationId": "notifications_webhook_delivery_summary", "summary": "Listar resumo de entregas de webhook", "description": "Escopo OAuth necessário: `read:webhooks`. Retorna contagens agregadas de entregas de webhook para o cliente autenticado.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionIdQuery" }, { "$ref": "#/components/parameters/WebhookDeliveryStatusQuery" }, { "$ref": "#/components/parameters/WebhookEventTypeQuery" }, { "$ref": "#/components/parameters/WebhookStartDateQuery" }, { "$ref": "#/components/parameters/WebhookEndDateQuery" } ], "responses": { "200": { "description": "Resumo de entregas agrupado por inscrição, tipo de evento e status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliverySummaryResponse" } } } }, "401": { "$ref": "#/components/responses/notifications_WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/notifications_WebhookForbidden" }, "422": { "$ref": "#/components/responses/notifications_WebhookValidationError" }, "500": { "$ref": "#/components/responses/notifications_WebhookInternalError" } }, "tags": [ "Notifications" ] } }, "/api/v2/webhook-delivery-replays": { "post": { "operationId": "notifications_webhook_delivery_replay", "summary": "requeue failed webhook deliveries", "description": "Requires OAuth scope `manage:webhooks`. Replay requeues either selected final `FAILED` deliveries or every final `FAILED` delivery for one subscription owned by the authenticated client, preserving the original event ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryReplayRequest" } } } }, "responses": { "200": { "description": "Solicitação de reprocessamento aceita e contabilizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryReplayResponse" } } } }, "400": { "$ref": "#/components/responses/NotificationsRequestBodyBadRequest" }, "401": { "$ref": "#/components/responses/notifications_WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/notifications_WebhookForbidden" }, "422": { "$ref": "#/components/responses/notifications_WebhookValidationError" }, "500": { "$ref": "#/components/responses/notifications_WebhookInternalError" } }, "tags": [ "Notifications" ] } }, "/api/v2/webhook-subscriptions": { "get": { "operationId": "identity_profile_webhook_subscription_list", "summary": "Listar inscrições de webhook", "description": "Escopo OAuth necessário: `read:webhooks`. Lista somente as inscrições de webhook do cliente autenticado, sem expor segredos de assinatura ou autenticação.", "responses": { "200": { "description": "Inscrições de webhook do cliente autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionListResponse" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Identity Profile" ] }, "post": { "operationId": "identity_profile_webhook_subscription_create", "summary": "Criar inscrição de webhook", "description": "Escopo OAuth necessário: `manage:webhooks`. Cria uma inscrição de webhook para o cliente autenticado. A entidade solicitada deve estar permitida no `CLIENT_CONFIG`; os segredos são aceitos apenas na solicitação.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateRequest" } } } }, "responses": { "201": { "description": "Inscrição de webhook criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/IdentityProfileRequestBodyBadRequest" }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Identity Profile" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "identity_profile_webhook_subscription_update", "summary": "Atualizar inscrição de webhook", "description": "Escopo OAuth necessário: `manage:webhooks`. Atualiza uma inscrição de webhook para entregas futuras. A entidade resultante deve estar permitida no `CLIENT_CONFIG`.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Inscrição de webhook atualizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/IdentityProfileRequestBodyBadRequest" }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Identity Profile" ] }, "delete": { "operationId": "identity_profile_webhook_subscription_delete", "summary": "Desativar inscrição de webhook", "description": "Escopo OAuth necessário: `manage:webhooks`. Desativa logicamente a inscrição de webhook, preservando histórico e auditoria.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "204": { "description": "Inscrição de webhook desativada sem corpo de resposta." }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Identity Profile" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/deliveries": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "notifications_webhook_deliveries", "summary": "Listar entregas de webhook", "description": "Escopo OAuth necessário: `read:webhooks`. Lista entregas de webhook e histórico de tentativas com trechos sensíveis redigidos e truncados.", "parameters": [ { "$ref": "#/components/parameters/notifications_WebhookSubscriptionId" }, { "$ref": "#/components/parameters/WebhookDeliveryStatusQuery" }, { "$ref": "#/components/parameters/WebhookEventTypeQuery" }, { "$ref": "#/components/parameters/WebhookStartDateQuery" }, { "$ref": "#/components/parameters/WebhookEndDateQuery" }, { "$ref": "#/components/parameters/WebhookLastItemQuery" }, { "$ref": "#/components/parameters/WebhookLimitQuery" } ], "responses": { "200": { "description": "Histórico de entregas e tentativas de uma inscrição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveriesResponse" } } } }, "401": { "$ref": "#/components/responses/notifications_WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/notifications_WebhookForbidden" }, "422": { "$ref": "#/components/responses/notifications_WebhookValidationError" }, "500": { "$ref": "#/components/responses/notifications_WebhookInternalError" } }, "tags": [ "Notifications" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/pause": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "identity_profile_webhook_subscription_pause", "summary": "Pausar inscrição de webhook", "description": "Escopo OAuth necessário: `manage:webhooks`. Pausa uma inscrição de webhook sem remover a configuração.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "200": { "description": "Inscrição de webhook pausada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Identity Profile" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/reactivate": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "identity_profile_webhook_subscription_reactivate", "summary": "Reativar inscrição de webhook", "description": "Escopo OAuth necessário: `manage:webhooks`. Reativa uma inscrição de webhook pausada e retoma entregas futuras elegíveis.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "200": { "description": "Inscrição de webhook reativada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Identity Profile" ] } }, "/v2/oauth/revoke": { "post": { "operationId": "identity_profile_oauth_revoke", "summary": "revoke an OAuth v2 access token", "description": "Revoke a previously issued OAuth v2 access token for the authenticated OAuth client. Send the request as application/x-www-form-urlencoded.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthRevokeRequest" } } } }, "responses": { "200": { "description": "OAuth token revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthRevokeResponse" } } } }, "400": { "description": "OAuth invalid request or grant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" } } } }, "401": { "description": "OAuth invalid client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" } } } } }, "tags": [ "Identity Profile" ] } }, "/v2/oauth/token": { "post": { "operationId": "identity_profile_oauth_token", "summary": "issue an OAuth v2 client credentials access token", "description": "Exchange an OAuth client ID and client secret for a Bearer access token. Send the request as application/x-www-form-urlencoded. Leave scope blank to use the registered client scopes still allowed by the owner client's current `CLIENT_CONFIG` permissions projection, or provide a space-separated subset to limit the issued token.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } } } }, "responses": { "200": { "description": "OAuth token response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "OAuth invalid request, grant, or scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" } } } }, "401": { "description": "OAuth invalid client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" } } } } }, "tags": [ "Identity Profile" ] } } }, "components": { "schemas": { "ContractsRequestBodyErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "Invalid request body" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ContractsRequestBodyFieldError" } } } }, "ContractsRequestBodyFieldError": { "type": "object", "required": [ "fieldName", "code", "message" ], "properties": { "fieldName": { "type": "string", "description": "JSON field path that failed parsing or validation. Empty for whole-body JSON errors.", "example": "companies[0].companyTaxId" }, "code": { "type": "string", "enum": [ "required", "unknown_field", "invalid_type", "invalid_json", "validation" ], "example": "required" }, "message": { "type": "string", "example": "companyTaxId is required" } } }, "IdentityProfileRequestBodyErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "Invalid request body" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityProfileRequestBodyFieldError" } } } }, "IdentityProfileRequestBodyFieldError": { "type": "object", "required": [ "fieldName", "code", "message" ], "properties": { "fieldName": { "type": "string", "description": "JSON field path that failed parsing or validation. Empty for whole-body JSON errors.", "example": "auth.type" }, "code": { "type": "string", "enum": [ "unknown_field", "invalid_type", "invalid_json" ], "example": "unknown_field" }, "message": { "type": "string", "example": "auth.type has an invalid type" } } }, "NotificationsRequestBodyErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "Invalid request body" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationsRequestBodyFieldError" } } } }, "NotificationsRequestBodyFieldError": { "type": "object", "required": [ "fieldName", "code", "message" ], "properties": { "fieldName": { "type": "string", "description": "JSON field path that failed parsing or validation. Empty for whole-body JSON errors.", "example": "eventIds[0]" }, "code": { "type": "string", "enum": [ "unknown_field", "invalid_type", "invalid_json" ], "example": "invalid_type" }, "message": { "type": "string", "example": "eventIds has an invalid type" } } }, "OAuthErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "OAuth error code.", "example": "invalid_request" }, "error_description": { "type": "string", "description": "OAuth error description.", "example": "OAuth 2.0 Parameter: grant_type" } }, "description": "OAuth 2.0 error response." }, "OAuthRevokeRequest": { "type": "object", "required": [ "client_id", "client_secret", "token" ], "properties": { "client_id": { "type": "string", "description": "Public OAuth client identifier provided by Destrava.", "example": "preencher-com-client-id" }, "client_secret": { "type": "string", "description": "OAuth client secret.", "example": "preencher-com-client-secret" }, "token": { "type": "string", "description": "Access token returned by the OAuth token endpoint.", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type_hint": { "type": "string", "description": "Optional OAuth token type hint. The v2 API supports access_token.", "enum": [ "access_token" ], "example": "access_token" } }, "description": "Credentials and token used to revoke an OAuth 2.0 access token." }, "OAuthRevokeResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Revocation status.", "enum": [ "REVOKED" ], "example": "REVOKED" }, "revokedToken": { "type": "string", "description": "Masked token identifier for the revoked token.", "example": "eyJh...abcd" } }, "description": "OAuth token revocation result." }, "OAuthTokenRequest": { "type": "object", "required": [ "client_id", "client_secret", "grant_type" ], "properties": { "client_id": { "type": "string", "description": "Public OAuth client identifier provided by Destrava.", "example": "preencher-com-client-id" }, "client_secret": { "type": "string", "description": "OAuth client secret. Keep this value out of Git, logs, and shared tools.", "example": "preencher-com-client-secret" }, "grant_type": { "type": "string", "description": "OAuth grant type. Use client_credentials for the v2 API.", "enum": [ "client_credentials" ], "default": "client_credentials", "example": "client_credentials" }, "scope": { "type": "string", "description": "Optional space-separated scope list. Leave blank to use the registered client scopes still allowed by the owner client's current `CLIENT_CONFIG` permissions projection.", "example": "companies:read read:accounts read:accounts:balance" } }, "description": "Credentials used to issue an OAuth 2.0 client credentials access token." }, "OAuthTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Issued Bearer access token.", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type": { "type": "string", "description": "Token type.", "example": "Bearer" }, "expires_in": { "type": "integer", "format": "int32", "description": "Token lifetime in seconds.", "example": 3600 }, "scope": { "type": "string", "description": "Granted scopes separated by spaces.", "example": "read:companies:acquirers" } }, "description": "Bearer token response used to authenticate protected v2 API calls." }, "WebhookAuthRequest": { "type": "object", "required": [ "type", "pwd" ], "properties": { "type": { "$ref": "#/components/schemas/WebhookAuthType" }, "login": { "type": "string", "description": "Username, API-key header name, or other public auth identifier. Required for BASIC and API_KEY.", "example": "X-Webhook-Key" }, "pwd": { "type": "string", "description": "Secret value used for outbound webhook authentication. Stored encrypted and never returned.", "minLength": 1, "writeOnly": true, "example": "client-webhook-api-key" } }, "description": "Optional outbound authentication configuration sent with webhook deliveries." }, "WebhookAuthType": { "type": "string", "enum": [ "BASIC", "BEARER", "API_KEY" ], "example": "API_KEY" }, "WebhookAuthView": { "type": "object", "required": [ "type", "configured" ], "properties": { "type": { "$ref": "#/components/schemas/WebhookAuthType" }, "login": { "type": "string", "description": "Non-secret auth identifier. The secret value is never returned.", "example": "X-Webhook-Key" }, "configured": { "type": "boolean", "description": "True when an outbound auth secret is configured.", "example": true } } }, "WebhookDeliveriesResponse": { "type": "object", "required": [ "deliveries", "limit", "totalItems", "pagination" ], "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "currentItem": { "type": "string" }, "nextItem": { "type": "string" }, "limit": { "type": "integer", "example": 30 }, "totalItems": { "type": "integer", "minimum": 0, "example": 42 }, "pagination": { "$ref": "#/components/schemas/WebhookReplayPagination" } } }, "WebhookDelivery": { "type": "object", "required": [ "eventId", "eventType", "status", "eventStatus", "attempts", "maxAttempts", "eventOccurredAt", "createdAt", "updatedAt", "payload" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Stable delivery/event identifier. Replay preserves this ID.", "example": "99999999-9999-9999-9999-999999999999" }, "eventType": { "$ref": "#/components/schemas/notifications_WebhookEntity" }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "eventStatus": { "type": "string", "description": "Business status associated with the source event when available.", "example": "FAILED" }, "attempts": { "type": "integer", "minimum": 0, "example": 3 }, "maxAttempts": { "type": "integer", "minimum": 1, "example": 5 }, "lastHttpStatus": { "type": "integer", "example": 500 }, "lastError": { "type": "string", "description": "Redacted and truncated last error excerpt.", "example": "upstream returned 500" }, "eventOccurredAt": { "type": "string", "format": "date-time", "example": "2026-06-17T12:00:00Z" }, "nextRetryAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-06-17T12:15:00Z" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-06-17T12:06:00Z" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-06-17T12:00:10Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-06-17T12:05:00Z" }, "payload": { "type": "string", "description": "Redacted and truncated payload excerpt for UI display.", "example": "{\"eventId\":\"99999999-9999-9999-9999-999999999999\",\"payload\":{\"token\":\"[REDACTED]\"}}" }, "response": { "type": "string", "description": "Redacted and truncated final response excerpt.", "example": "{\"message\":\"temporary failure\"}" }, "attemptHistory": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryAttempt" } } } }, "WebhookDeliveryAttempt": { "type": "object", "required": [ "attemptNumber", "webhookUrl", "durationMs", "successful", "attemptedAt" ], "properties": { "attemptNumber": { "type": "integer", "minimum": 1, "example": 2 }, "webhookUrl": { "type": "string", "format": "uri", "example": "https://example.com/destrava/webhooks" }, "payload": { "type": "string", "description": "Redacted and truncated request body excerpt. Sensitive keys are replaced with `[REDACTED]`.", "example": "{\"eventId\":\"99999999-9999-9999-9999-999999999999\",\"secret\":\"[REDACTED]\"}" }, "responseStatus": { "type": "integer", "example": 500 }, "responseBody": { "type": "string", "description": "Redacted and truncated provider response excerpt.", "example": "{\"message\":\"temporary failure\"}" }, "errorMessage": { "type": "string", "description": "Redacted and truncated error excerpt.", "example": "timeout waiting for response" }, "durationMs": { "type": "integer", "format": "int64", "minimum": 0, "example": 842 }, "successful": { "type": "boolean", "example": false }, "attemptedAt": { "type": "string", "format": "date-time", "example": "2026-06-17T12:05:00Z" } } }, "WebhookDeliveryReplayRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "eventIds" ], "properties": { "eventIds": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Delivery/event IDs to replay. Only final FAILED deliveries owned by the client are requeued.", "items": { "type": "string", "format": "uuid" }, "example": [ "99999999-9999-9999-9999-999999999999" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "subscriptionId", "status" ], "properties": { "subscriptionId": { "type": "string", "minLength": 1, "description": "Subscription whose final failed deliveries should all be requeued.", "example": "whsub_01HZX000000000000000000000" }, "status": { "type": "string", "enum": [ "FAILED" ], "description": "Must be `FAILED`; endpoint-wide replay does not requeue pending, delivered, or cancelled deliveries." } } } ] }, "WebhookDeliveryReplayResponse": { "type": "object", "required": [ "requestedEvents", "requeuedEvents", "ignoredEvents" ], "properties": { "requestedEvents": { "type": "integer", "minimum": 0, "example": 3 }, "requeuedEvents": { "type": "integer", "minimum": 0, "description": "Count of final FAILED deliveries requeued.", "example": 1 }, "ignoredEvents": { "type": "integer", "minimum": 0, "description": "Count of missing, non-owned, non-final, or non-FAILED deliveries ignored.", "example": 2 } } }, "WebhookDeliveryStatus": { "type": "string", "enum": [ "PENDING", "IN_PROGRESS", "DELIVERED", "FAILED", "CANCELLED" ], "example": "FAILED" }, "WebhookDeliveryStatusSummary": { "type": "object", "required": [ "status", "deliveries" ], "properties": { "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "deliveries": { "type": "integer", "minimum": 0, "example": 3 } } }, "WebhookDeliverySummaryResponse": { "type": "object", "required": [ "totalDeliveries", "subscriptions" ], "properties": { "totalDeliveries": { "type": "integer", "minimum": 0, "example": 12 }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionDeliverySummary" } } } }, "WebhookEntity": { "type": "string", "enum": [ "OPT_IN_CREATED", "OPT_IN_RECURRENCE_UPDATED", "SCHEDULE_ACCESS_REQUEST", "COLLECTION_CONTRACT_CREATION", "COLLECTION_CONTRACT", "COLLATERALIZED_CREDIT_CONTRACT", "COLLATERALIZED_CREDIT_ESCROW_ACCOUNT" ], "example": "COLLECTION_CONTRACT" }, "WebhookErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "status": { "type": "string", "description": "Optional machine-readable error status.", "example": "forbidden" }, "message": { "type": "string", "example": "missing required OAuth scope" } } }, "WebhookReplayPagination": { "type": "object", "properties": { "currentItem": { "type": "string", "example": "2026-06-17T12:00:00Z#DELIVERY#99999999-9999-9999-9999-999999999999" }, "nextItem": { "type": "string", "example": "2026-06-17T11:50:00Z#DELIVERY#88888888-8888-8888-8888-888888888888" } } }, "WebhookSubscriptionCreateRequest": { "type": "object", "required": [ "entity", "webhookUrl", "signatureSecret" ], "properties": { "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Public HTTPS callback URL. Localhost, private, link-local, metadata and ambiguous IP targets are rejected for SSRF protection.", "example": "https://example.com/destrava/webhooks" }, "signatureSecret": { "type": "string", "minLength": 32, "maxLength": 256, "writeOnly": true, "description": "HMAC signing secret. Stored encrypted and never returned after create/update.", "example": "destrava-webhook-signature-secret-123456" }, "auth": { "$ref": "#/components/schemas/WebhookAuthRequest" } } }, "WebhookSubscriptionDeliverySummary": { "type": "object", "required": [ "subscriptionId", "eventType", "webhookUrl", "totalDeliveries", "statuses" ], "properties": { "subscriptionId": { "type": "string", "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" }, "eventType": { "$ref": "#/components/schemas/notifications_WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "example": "https://example.com/destrava/webhooks" }, "totalDeliveries": { "type": "integer", "minimum": 0, "example": 12 }, "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryStatusSummary" } } } }, "WebhookSubscriptionListResponse": { "type": "object", "required": [ "subscriptions" ], "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "WebhookSubscriptionResponse": { "type": "object", "required": [ "subscriptionId", "entity", "webhookUrl", "active", "status", "signatureSecretConfigured", "createdAt", "updatedAt" ], "properties": { "subscriptionId": { "type": "string", "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" }, "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "example": "https://example.com/destrava/webhooks" }, "active": { "type": "boolean", "description": "Compatibility flag for delivery eligibility. Prefer `status` for UI state.", "example": true }, "status": { "$ref": "#/components/schemas/WebhookSubscriptionStatus" }, "signatureSecretConfigured": { "type": "boolean", "description": "True when an HMAC signing secret is configured; the raw secret is never returned.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-06-17T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-06-17T12:10:00Z" }, "auth": { "$ref": "#/components/schemas/WebhookAuthView" } } }, "WebhookSubscriptionStatus": { "type": "string", "description": "ACTIVE deliveries are eligible, PAUSED keeps the configuration without new deliveries, and DEACTIVATED is logical removal with history preserved.", "enum": [ "ACTIVE", "PAUSED", "DEACTIVATED" ], "example": "ACTIVE" }, "WebhookSubscriptionUpdateRequest": { "type": "object", "minProperties": 1, "properties": { "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Replacement public HTTPS callback URL for future deliveries.", "example": "https://example.com/destrava/webhooks/updated" }, "signatureSecret": { "type": "string", "minLength": 32, "maxLength": 256, "writeOnly": true, "description": "Replacement HMAC signing secret for future deliveries. Never returned by the API.", "example": "destrava-webhook-signature-secret-rotated-123456" }, "auth": { "$ref": "#/components/schemas/WebhookAuthRequest" } } }, "notifications_WebhookEntity": { "type": "string", "enum": [ "OPT_IN_CREATED", "OPT_IN_RECURRENCE_UPDATED", "SCHEDULE_ACCESS_REQUEST", "COLLECTION_CONTRACT_CREATION", "COLLECTION_CONTRACT", "COLLATERALIZED_CREDIT_CONTRACT", "COLLATERALIZED_CREDIT_ESCROW_ACCOUNT" ], "example": "COLLECTION_CONTRACT" }, "notifications_WebhookErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "status": { "type": "string", "description": "Optional machine-readable error status.", "example": "forbidden" }, "message": { "type": "string", "example": "missing required OAuth scope" } } } }, "responses": { "IdentityProfileRequestBodyBadRequest": { "description": "Invalid JSON, unknown field, invalid field type, or multiple JSON objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProfileRequestBodyErrorResponse" } } } }, "NotificationsRequestBodyBadRequest": { "description": "Invalid JSON, unknown field, invalid field type, or multiple JSON objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsRequestBodyErrorResponse" } } } }, "WebhookForbidden": { "description": "Permissões insuficientes para o escopo OAuth ou para a entidade de webhook solicitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookInternalError": { "description": "Erro interno inesperado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookNotFound": { "description": "Inscrição de webhook não encontrada para o cliente ou já desativada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookUnauthorized": { "description": "Token Bearer ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookValidationError": { "description": "URL, entidade, segredo de assinatura, autenticação ou estado da inscrição inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "notifications_WebhookForbidden": { "description": "Authenticated caller lacks the required public OAuth scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } }, "notifications_WebhookInternalError": { "description": "Erro interno inesperado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } }, "notifications_WebhookUnauthorized": { "description": "Token Bearer ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } }, "notifications_WebhookValidationError": { "description": "Consulta, payload, inscrição ou elegibilidade de entrega inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } } }, "parameters": { "WebhookDeliveryStatusQuery": { "name": "status", "in": "query", "required": false, "description": "Optional delivery status filter.", "schema": { "$ref": "#/components/schemas/WebhookDeliveryStatus" } }, "WebhookEndDateQuery": { "name": "endDate", "in": "query", "required": false, "description": "Inclusive UTC date filter in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-17" }, "WebhookEventTypeQuery": { "name": "eventType", "in": "query", "required": false, "description": "Optional canonical webhook event type filter.", "schema": { "$ref": "#/components/schemas/notifications_WebhookEntity" } }, "WebhookLastItemQuery": { "name": "lastItem", "in": "query", "required": false, "description": "Pagination cursor returned as `nextItem` by the previous response.", "schema": { "type": "string" }, "example": "2026-06-17T12:00:00Z#DELIVERY#99999999-9999-9999-9999-999999999999" }, "WebhookLimitQuery": { "name": "limit", "in": "query", "required": false, "description": "Page size for delivery history. Defaults to 30 and must be 100 or less.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "example": 30 }, "WebhookStartDateQuery": { "name": "startDate", "in": "query", "required": false, "description": "Inclusive UTC date filter in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-01" }, "WebhookSubscriptionId": { "name": "subscriptionId", "in": "path", "required": true, "description": "Webhook subscription identifier returned by create/list operations.", "schema": { "type": "string", "minLength": 1 }, "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" }, "WebhookSubscriptionIdQuery": { "name": "subscriptionId", "in": "query", "required": false, "description": "Optional subscription filter.", "schema": { "type": "string", "minLength": 1 }, "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" }, "notifications_WebhookSubscriptionId": { "name": "subscriptionId", "in": "path", "required": true, "description": "Webhook subscription identifier returned by identity-profile subscription APIs.", "schema": { "type": "string", "minLength": 1 }, "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth V2 Bearer access token issued by /v2/oauth/token." } } } }