{ "openapi": "3.0.3", "info": { "title": "API Pública V2 da Destrava", "version": "2.0.0", "description": "Contrato público agregado dos domínios da Destrava para o ambiente de produção." }, "servers": [ { "url": "https://api-v2.destrava.ai", "description": "Ambiente de produção" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Autenticação" }, { "name": "Empresas" }, { "name": "Opt-In" }, { "name": "Recebíveis" }, { "name": "Antecipação" }, { "name": "Cobrança" }, { "name": "Crédito com Garantia" }, { "name": "Contas" }, { "name": "Webhooks" }, { "name": "Contratos" } ], "paths": { "/v2/oauth/token": { "post": { "operationId": "identity_profile_oauth_token", "summary": "Criar token de acesso", "description": "Use esta chamada para trocar o `client_id` e o `client_secret` por um token Bearer. Envie os campos em `application/x-www-form-urlencoded` e use o `access_token` retornado no header `Authorization: Bearer ` das próximas requisições. O campo `scope` pode ficar vazio em testes ou integrações que devem usar todos os escopos cadastrados no cliente; preencha apenas quando quiser limitar o token a um subconjunto de permissões. Esta chamada não exige token prévio.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } } } }, "responses": { "200": { "description": "Resposta com token OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" }, "example": { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "scope": "read:companies:acquirers" } } } }, "400": { "description": "Solicitação, concessão ou escopo OAuth inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" }, "example": { "error": "invalid_request", "error_description": "OAuth 2.0 Parameter: grant_type" } } } }, "401": { "description": "Cliente OAuth inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" }, "example": { "error": "invalid_request", "error_description": "OAuth 2.0 Parameter: grant_type" } } } } }, "tags": [ "Autenticação" ] } }, "/v2/oauth/revoke": { "post": { "operationId": "identity_profile_oauth_revoke", "summary": "Revogar token de acesso", "description": "Use esta chamada quando precisar invalidar um token antes da expiração natural. Ela é útil ao encerrar uma sessão de teste, trocar credenciais ou interromper o uso de um token que não deve continuar ativo. A revogação autentica o mesmo cliente que emitiu o token e não exige Bearer no header.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthRevokeRequest" } } } }, "responses": { "200": { "description": "Token OAuth revogado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthRevokeResponse" }, "example": { "status": "REVOKED", "revokedToken": "eyJh...abcd" } } } }, "400": { "description": "Solicitação ou concessão OAuth inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" }, "example": { "error": "invalid_request", "error_description": "OAuth 2.0 Parameter: grant_type" } } } }, "401": { "description": "Cliente OAuth inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorResponse" }, "example": { "error": "invalid_request", "error_description": "OAuth 2.0 Parameter: grant_type" } } } } }, "tags": [ "Autenticação" ] } }, "/api/v2/companies": { "get": { "operationId": "permission_v2_companies_list", "summary": "Listar empresas", "description": "Lista as empresas vinculadas ao cliente autenticado. Use os filtros para encontrar empresas por data de criação, atualização ou situação da agenda, e use a paginação por cursor quando houver muitos resultados. O token precisa incluir `companies:read`.", "responses": { "200": { "description": "Página de empresas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyV2" } }, "pagination": { "type": "object" } } }, "example": { "companies": [ { "companyId": "string", "companyTaxId": "string", "companyName": "string", "nickname": "string", "status": "string", "scheduleStatus": "INACTIVE", "scheduleStatusReasonCode": "string", "lastScheduleQueryAt": "2036-04-23T18:45:00Z", "lastScheduleResultAt": "2036-04-23T18:45:00Z", "queriedUnits": { "acquirers": 0, "paymentSchemes": 0, "packageVersion": "string" }, "createdAt": "2036-04-23T18:45:00Z", "updatedAt": "2036-04-23T18:45:00Z" } ], "pagination": {} } } } } }, "tags": [ "Empresas" ] }, "post": { "operationId": "permission_v2_companies_create", "summary": "Cadastrar uma ou mais empresas", "description": "Cadastra uma ou mais empresas para o cliente autenticado. Para uma única empresa, a resposta de sucesso é direta; para lotes, a API pode retornar `207 Multi-Status` para indicar o resultado individual de cada item. Use um token com `companies:write`.", "responses": { "201": { "description": "Empresas criadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CreateCompaniesResponse" }, "example": { "companyGroupId": "90c6c8a2-3a14-4600-a295-9cda95640fba", "companies": [ { "companyId": "64091b0a-529d-48fc-9802-7b1600a07c8b", "companyTaxId": "12345678000195", "status": "CREATED", "error": "Empresa já cadastrada" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "207": { "description": "Resultado multiempresa com o status de cada item. Um cliente sem pacote de agenda recebe cada item como FAILED com o erro AGENDA_CONFIGURATION_REQUIRED (ENG-1184).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CreateCompaniesResponse" }, "example": { "companyGroupId": "90c6c8a2-3a14-4600-a295-9cda95640fba", "companies": [ { "companyId": "64091b0a-529d-48fc-9802-7b1600a07c8b", "companyTaxId": "12345678000195", "status": "CREATED", "error": "Empresa já cadastrada" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ] } }, "/api/v2/companies/{companyId}": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_company_get", "summary": "Consultar dados de uma empresa", "description": "Consulta os dados cadastrais de uma empresa específica. Use esta chamada depois de descobrir o `companyId` na listagem ou após criar a empresa. O token precisa incluir `companies:read`.", "responses": { "200": { "description": "Detalhes da empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CompanyV2Response" }, "example": { "companyId": "64091b0a-529d-48fc-9802-7b1600a07c8b", "companyTaxId": "12345678000195", "companyName": "Empresa Teste v2", "status": "ACTIVE", "scheduleStatus": "PENDING", "createdAt": "2026-04-17T12:30:00Z", "updatedAt": "2026-04-17T13:45:00Z", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ] }, "delete": { "operationId": "permission_v2_company_delete", "summary": "Inativar uma empresa", "description": "Inativa uma empresa quando ela não possui dependências ativas que impeçam a exclusão lógica. Use esta operação para encerrar o uso da empresa sem remover o histórico associado. O token precisa incluir `companies:write`.", "responses": { "204": { "description": "Empresa desativada sem corpo de resposta. As consultas de agenda da empresa são canceladas e a recorrência é desligada. Com `RegistrarConsentRevocationEnabled` ligado (ENG-1545), os opt-ins da empresa na Núclea que nenhum outro cliente usa têm a revogação pedida à registradora; a resposta não espera esse pedido. Um opt-in que continua mudando enquanto a revogação é planejada (três tentativas) devolve 500 com conflito, sem nada enviado, e a exclusão pode ser pedida de novo." }, "409": { "description": "Com `RegistrarConsentRevocationEnabled` ligado (ENG-1545), outra exclusão está planejando a revogação dos mesmos opt-ins (mesmo CNPJ e mesmo dono de credencial). Código `COMPANY_EXCLUSION_IN_PROGRESS`. Esta exclusão parou sem concluir o pedido de revogação e a empresa continua ativa; a exclusão deve ser pedida de novo." } }, "tags": [ "Empresas" ] } }, "/api/v2/company-groups": { "post": { "operationId": "permission_v2_company_group_create", "summary": "Criar grupo econômico", "description": "Cria um grupo econômico para organizar empresas relacionadas dentro do mesmo cliente. Use grupos para facilitar manutenção, consulta e vínculo de empresas que devem ser tratadas em conjunto. O token precisa incluir `write:companies:groups`.", "responses": { "201": { "description": "Grupo de empresas criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CompanyGroupResponse" }, "example": { "groupId": "90c6c8a2-3a14-4600-a295-9cda95640fba", "groupName": "grupo-econômico-001", "externalGroupId": "group-id-001", "createdAt": "2025-07-01T17:45:00Z", "associatedCompanies": [ { "companyId": "90c6c8a2-3a14-4600-a295-9cda95640fba" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ] } }, "/api/v2/company-groups/{groupId}": { "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_company_group_get", "summary": "Consultar grupo econômico", "description": "Consulta os dados de um grupo econômico e as empresas associadas a ele. Use esta chamada para conferir a composição do grupo antes ou depois de adicionar e remover membros. O token precisa incluir `read:companies:groups`.", "responses": { "200": { "description": "Detalhes do grupo de empresas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CompanyGroupResponse" }, "example": { "groupId": "90c6c8a2-3a14-4600-a295-9cda95640fba", "groupName": "grupo-econômico-001", "externalGroupId": "group-id-001", "createdAt": "2025-07-01T17:45:00Z", "associatedCompanies": [ { "companyId": "90c6c8a2-3a14-4600-a295-9cda95640fba" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ] } }, "/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": "Adiciona empresas a um grupo econômico existente. Envie apenas as empresas que devem ser incluídas no grupo; o vínculo passa a valer para consultas futuras. O token precisa incluir `write:companies:groups`.", "responses": { "200": { "description": "Empresas adicionadas ao grupo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_GroupMembersResponse" }, "example": { "groupId": "90c6c8a2-3a14-4600-a295-9cda95640fba", "companies": [ { "companyId": "90c6c8a2-3a14-4600-a295-9cda95640fba" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ] }, "delete": { "operationId": "permission_v2_company_group_members_remove", "summary": "Remover empresas do grupo", "description": "Remove empresas de um grupo econômico sem excluir as empresas em si. Use para corrigir vínculos ou desfazer uma associação que deixou de fazer sentido. O token precisa incluir `write:companies:groups`.", "responses": { "200": { "description": "Empresas removidas do grupo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_GroupMembersResponse" }, "example": { "groupId": "90c6c8a2-3a14-4600-a295-9cda95640fba", "companies": [ { "companyId": "90c6c8a2-3a14-4600-a295-9cda95640fba" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ] } }, "/api/v2/companies/{companyId}/acquirers": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_company_acquirers_get", "summary": "Consultar adquirentes adicionais", "description": "Mostra os adquirentes adicionais configurados para a empresa. Os adquirentes do pacote padrão continuam ativos por regra de produto e, por isso, não aparecem nesta resposta: `58160789000128`, `01027058000191`, `10440482000154`, `01027058000191`, `18727053000174`, `16501555000157`, `08561701014323`, `08561701000101`, `14380200000121`, `10573521000515`, `10573521000191`, `18189547000142` e `22177858000169`. O token precisa incluir `read:companies:acquirers`.", "responses": { "200": { "description": "Credenciadoras permitidas da empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_AcquirersResponse" }, "example": { "companyId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "updatedAt": "2025-06-26T12:34:56.000Z", "acquirers": [ { "taxId": "43151964000143", "name": "ADQUIRENTE TESTE S.A.", "nickname": "Adquirente Teste" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ] }, "put": { "operationId": "permission_v2_company_acquirers_update", "summary": "Substituir adquirentes adicionais", "description": "Substitui a lista completa de adquirentes adicionais da empresa. O corpo da requisição representa o estado final desejado: adquirentes omitidos são removidos e adquirentes enviados passam a ficar configurados, desde que estejam homologados, não sejam duplicados e não façam parte do pacote padrão. O pacote padrão permanece sempre ativo. O token precisa incluir `write:companies:acquirers`.", "responses": { "200": { "description": "Credenciadoras da empresa atualizadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_AcquirersResponse" }, "example": { "companyId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "updatedAt": "2025-06-26T12:34:56.000Z", "acquirers": [ { "taxId": "43151964000143", "name": "ADQUIRENTE TESTE S.A.", "nickname": "Adquirente Teste" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "409": { "description": "The client has no agenda package; the back office assigns one (`code` = AGENDA_CONFIGURATION_REQUIRED, ENG-1184)." } }, "tags": [ "Empresas" ] } }, "/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", "description": "Lista os arranjos de pagamento habilitados para a empresa. Use esta consulta para entender quais bandeiras/arranjos podem participar dos fluxos de agenda, antecipação, cobrança e recebíveis. O token precisa incluir `read:companies:schemes`.", "responses": { "200": { "description": "Arranjos de pagamento permitidos da empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_PaymentSchemesResponse" }, "example": { "companyId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "updatedAt": "2025-06-26T12:34:56.000Z", "paymentSchemes": [ { "code": "MCC", "name": "Mastercard Cartão de Crédito", "type": "CREDIT" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ] }, "put": { "operationId": "permission_v2_company_payment_schemes_update", "summary": "Substituir arranjos de pagamento", "description": "Substitui o conjunto de arranjos de pagamento da empresa. Envie a lista completa que deve permanecer ativa; valores omitidos deixam de fazer parte da configuração. O token precisa incluir `manage:companies:schemes`.", "responses": { "200": { "description": "Arranjos de pagamento da empresa atualizados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_PaymentSchemesResponse" }, "example": { "companyId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "updatedAt": "2025-06-26T12:34:56.000Z", "paymentSchemes": [ { "code": "MCC", "name": "Mastercard Cartão de Crédito", "type": "CREDIT" } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "409": { "description": "The client has no agenda package; the back office assigns one (`code` = AGENDA_CONFIGURATION_REQUIRED, ENG-1184)." } }, "tags": [ "Empresas" ] } }, "/api/v2/companies/{companyId}/refund-account": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "settlement_v2_refund_account_get", "summary": "Consultar conta de devolução", "description": "Consulta a conta bancária usada em devoluções automáticas da empresa. Essa conta é usada quando uma operação precisa devolver valores ao cliente. O token precisa incluir `read:companies:accounts`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PublicRefundCompanyId" } ], "responses": { "200": { "description": "Existing canonical account, or a masked legacy account represented as version 0. Full holderTaxId and account are never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRefundAccount" }, "example": { "companyId": "company-123", "version": 1, "createdAt": "2026-09-11T12:00:00Z", "updatedAt": "2026-09-11T12:00:00Z", "account": { "holderTaxIdMasked": "**********0143", "holderName": "Empresa Exemplo", "bankName": "Banco Exemplo", "ispb": "12345678", "branch": "0001", "accountMasked": "*****67", "accountDigit": "8" } } } } }, "401": { "description": "Missing trusted OAuth Client identity." }, "403": { "description": "Missing scope, Company ownership mismatch or tenant mismatch." }, "404": { "description": "Owned Company has no registered refund account." }, "503": { "description": "Client tenant binding or Company authority projection is unavailable or not configured." } }, "tags": [ "Empresas" ] }, "post": { "operationId": "settlement_v2_refund_account_create", "summary": "Cadastrar conta de devolução", "description": "Cadastra a conta bancária que será usada para devoluções automáticas da empresa. Use quando ainda não houver conta configurada para esse fim. O token precisa incluir `manage:companies:accounts`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PublicRefundCompanyId" }, { "$ref": "#/components/parameters/PublicRefundIdempotencyKey" }, { "$ref": "#/components/parameters/PublicRefundCorrelationId" }, { "name": "If-Match", "in": "header", "required": true, "description": "Must contain the decimal destination version 0, quoted or unquoted.", "schema": { "type": "string", "pattern": "^\"?0\"?$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRefundAccountReplace" } } } }, "responses": { "201": { "description": "Created account, or the original result of an exact idempotent replay. Only holderTaxIdMasked and accountMasked are returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRefundAccount" }, "example": { "companyId": "company-123", "version": 1, "createdAt": "2026-09-11T12:00:00Z", "updatedAt": "2026-09-11T12:00:00Z", "account": { "holderTaxIdMasked": "**********0143", "holderName": "Empresa Exemplo", "bankName": "Banco Exemplo", "ispb": "12345678", "branch": "0001", "accountMasked": "*****67", "accountDigit": "8" } } } } }, "400": { "description": "Invalid complete body", "unknown field": null, "header or non-zero If-Match.": null, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_ValidationErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "message": "Dados inválidos", "errors": [ { "fieldName": "companies[0].companyTaxId", "message": "CPF ou CNPJ da empresa deve ser válido" } ] } } } }, "401": { "description": "Missing trusted OAuth Client or credential identity." }, "403": { "description": "Missing scope", "Company ownership mismatch or tenant mismatch.": null }, "409": { "description": "Account already exists", "stale version or idempotency key reused with changed intent.": null }, "422": { "description": "Holder document mismatch or BANK_UNAVAILABLE when a new bank account uses an unknown/inactive institution." }, "503": { "description": "Client tenant binding", "Company authority projection or persistence is temporarily unavailable.": null } }, "tags": [ "Empresas" ] }, "put": { "operationId": "settlement_v2_refund_account_update", "summary": "Atualizar conta de devolução", "description": "Atualiza a conta bancária usada nas devoluções automáticas da empresa. Use para corrigir dados bancários ou trocar a conta operacional. O token precisa incluir `manage:companies:accounts`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PublicRefundCompanyId" }, { "$ref": "#/components/parameters/PublicRefundIdempotencyKey" }, { "$ref": "#/components/parameters/PublicRefundCorrelationId" }, { "name": "If-Match", "in": "header", "required": true, "description": "Decimal version returned by GET or the preceding command, quoted or unquoted.", "schema": { "type": "string", "pattern": "^\"?[0-9]+\"?$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRefundAccountReplace" } } } }, "responses": { "200": { "description": "Replaced account, migrated legacy account or original result of an exact replay. Full holderTaxId and account are never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRefundAccount" }, "example": { "companyId": "company-123", "version": 1, "createdAt": "2026-09-11T12:00:00Z", "updatedAt": "2026-09-11T12:00:00Z", "account": { "holderTaxIdMasked": "**********0143", "holderName": "Empresa Exemplo", "bankName": "Banco Exemplo", "ispb": "12345678", "branch": "0001", "accountMasked": "*****67", "accountDigit": "8" } } } } }, "400": { "description": "Invalid or partial body", "unknown field": null, "masked input or invalid command header.": null, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_ValidationErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "message": "Dados inválidos", "errors": [ { "fieldName": "companies[0].companyTaxId", "message": "CPF ou CNPJ da empresa deve ser válido" } ] } } } }, "401": { "description": "Missing trusted OAuth Client or credential identity." }, "403": { "description": "Missing scope", "Company ownership mismatch or tenant mismatch.": null }, "404": { "description": "Owned Company has no registered refund account." }, "409": { "description": "Stale version or idempotency key reused with changed intent." }, "422": { "description": "Holder document mismatch or BANK_UNAVAILABLE when a new bank account uses an unknown/inactive institution." }, "503": { "description": "Client tenant binding", "Company authority projection or persistence is temporarily unavailable.": null } }, "tags": [ "Empresas" ] } }, "/api/v2/schedule-access-requests": { "post": { "operationId": "permission_v2_schedule_access_request_create", "summary": "Solicitar acesso à agenda de recebíveis", "description": "Solicita acesso à agenda de recebíveis das empresas informadas. A solicitação é assíncrona: a API aceita o pedido e o processamento continua em segundo plano. Use um token com `companies:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Identidade estável de repetição. Reutilizá-la com a mesma solicitação retorna a operação original sem criar novo uso faturável; reutilizá-la com conteúdo diferente retorna 409.", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "202": { "description": "Solicitação de acesso à agenda aceita para processamento assíncrono.", "content": { "application/json": { "schema": { "type": "object", "required": [ "operationId", "receivedAt", "status" ], "properties": { "operationId": { "type": "string" }, "receivedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "PENDING", "SCHEDULED" ], "description": "PENDING quando a consulta começa agora; SCHEDULED quando espera a próxima abertura da janela (ENG-1188)." }, "scheduledFor": { "type": "string", "format": "date-time", "description": "Abertura da janela em que a solicitação SCHEDULED começa." } } }, "example": { "operationId": "string", "receivedAt": "2036-04-23T18:45:00Z", "status": "PENDING", "scheduledFor": "2036-04-23T18:45:00Z" } } } }, "409": { "description": "Idempotency-Key was already used for different request content. Also 409 AGENDA_CONFIGURATION_REQUIRED when the client has no agenda package (ENG-1184)." }, "422": { "description": "Invalid request, or AGENDA_QUERY_PRODUCT_INACTIVE / AGENDA_QUERY_PRICING_NOT_CONFIGURED / AGENDA_QUERY_PRICING_INVALID. No new operation is accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleQueryPricingError" }, "example": { "code": "string", "message": "string" } } } }, "503": { "description": "AGENDA_QUERY_PRICING_UNAVAILABLE (pricing check) or REGISTER_CALENDAR_UNAVAILABLE (calendar). No new operation is admitted. Retry with the same idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleQueryPricingError" }, "example": { "code": "string", "message": "string" } } } } }, "tags": [ "Opt-In" ] } }, "/api/v2/receivables/encumbrances/{companyTaxId}": { "get": { "operationId": "receivables_financier_receivable_encumbrances_v2_empty_window", "summary": "Consultar onerações de recebíveis da empresa", "description": "Consulta as onerações existentes sobre os recebíveis de uma empresa pelo CNPJ. Use para entender quais recebíveis já estão comprometidos e com quem. O token precisa incluir `read:receivables`.", "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": "encumbranceCategories", "in": "query", "description": "Filtro OR opcional para a origem de negócio de uma oneração.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "CASH_ADVANCE", "COLLATERALIZED_CREDIT", "JUDICIAL_BLOCK" ] } }, "style": "form", "explode": true }, { "name": "scheduleType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PERFORMED", "TO_PERFORM" ] } } ], "responses": { "200": { "description": "Gravames de recebíveis.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableEncumbrancesResponse" }, "example": { "companyTaxId": "string", "encumbrances": [ {} ], "pagination": {}, "agendaVersion": { "queryId": "string", "sequence": 1, "openedAt": "2036-04-23T18:45:00Z", "asOf": "2036-04-23T18:45:00Z", "closedBy": "ALL_TERMINAL", "totals": { "registeredAmount": "string", "performedAmount": "string", "cededAmount": "string", "encumberedAmount": "string", "notAllocatedAmount": "string", "unitCount": 0, "encumbranceBreakdownStatus": "AVAILABLE", "encumberedByClientAmount": "string", "encumberedByOthersAmount": "string", "encumberedUnitCount": 0, "clientEncumberedUnitCount": 0, "clientFirstUnitCount": 0 }, "acquirers": [ { "acquirerTaxId": "string", "performed": true, "unitCount": 0, "registered": "string", "performedAmount": "string", "cededAmount": "string", "free": "string", "encumbered": "string", "notAllocated": "string", "encumbranceBreakdownStatus": "AVAILABLE", "encumberedByClient": "string", "encumberedByOthers": "string", "encumberedUnitCount": 0, "clientEncumberedUnitCount": 0, "clientFirstUnitCount": 0 } ], "pairs": [ { "acquirerTaxId": "string", "paymentScheme": "string", "result": "DATA", "reason": "string", "performed": true, "unitCount": 0, "registered": "string", "performedAmount": "string", "cededAmount": "string", "free": "string", "encumbered": "string", "notAllocated": "string", "sources": [ "PACKAGE" ], "encumbranceBreakdownStatus": "AVAILABLE", "encumberedByClient": "string", "encumberedByOthers": "string", "encumberedUnitCount": 0, "clientEncumberedUnitCount": 0, "clientFirstUnitCount": 0 } ], "unavailablePairs": [ { "acquirerTaxId": "string", "paymentScheme": "string", "result": "FAILED", "reason": "string" } ] } } } } }, "400": { "description": "Parâmetros da solicitação inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "403": { "description": "Permissões insuficientes para acessar a empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "422": { "description": "Intervalo de datas não processável." } }, "tags": [ "Recebíveis" ] } }, "/api/v2/receivables/encumbrances/priority/{companyTaxId}": { "get": { "operationId": "receivables_financier_receivable_encumbrance_priority_v2_empty_window", "summary": "Consultar prioridade de oneração da empresa", "description": "Mostra a prioridade de oneração por financiador e adquirente para uma empresa. Use esta visão para entender a ordem de preferência entre credores antes de analisar ou criar operações. O token precisa incluir `read:receivables`.", "parameters": [ { "name": "companyTaxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "description": "Primeira data de liquidação inclusiva no intervalo consultado.", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "description": "Última data de liquidação inclusiva no intervalo consultado.", "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" ] } }, { "name": "encumbranceCategories", "in": "query", "description": "Filtro OR opcional para a origem de negócio de uma oneração.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "CASH_ADVANCE", "COLLATERALIZED_CREDIT", "JUDICIAL_BLOCK" ] } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Receivable encumbrance priorities.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_PriorityMetricsResponse" }, "example": { "acquirers": [ { "taxId": "01027058000191", "name": "Adquirente Exemplo", "totalAmount": 10000, "priorities": [ { "financierTaxId": "12345678000190", "financierName": "Financiador Exemplo", "priority": "1", "amount": 1500, "encumbranceType": "FIXED" } ] } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "400": { "description": "Parâmetros da solicitação inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "403": { "description": "Insufficient permission to access the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "422": { "description": "O intervalo de datas solicitado não pode ser processado." } }, "tags": [ "Recebíveis" ] } }, "/api/v2/receivables/schedule/{companyTaxId}": { "get": { "operationId": "receivables_financier_receivable_schedule_v2_empty_window", "summary": "Consultar agenda de recebíveis da empresa", "description": "Lista os recebíveis da última agenda consolidada da empresa. Enquanto nenhuma consulta de agenda tiver sido concluída, a lista vem vazia. Use esta consulta para enxergar os recebíveis que podem compor operações como antecipação ou cobrança. O token precisa incluir `read:receivables:schedule`.", "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableScheduleResponse" }, "example": { "receivables": [ { "source": "ONLINE", "provider": "TAG", "asOf": "2036-04-23T18:45:00Z", "registeredAmount": "string", "receivableKey": "string", "situation": "AVAILABLE", "encumbranceBreakdownStatus": "AVAILABLE", "encumberedTotal": "string", "encumberedByClient": "string", "encumberedByOthers": "string", "paymentSchemeCode": "string", "encumberedAmountByClient": "string", "encumberedAmountByOthers": "string", "riskStatus": "AVAILABLE", "riskEvaluatedAt": "2036-04-23T18:45:00Z", "riskBrokenRules": "string" } ], "pagination": {}, "totals": {}, "scheduleMetadata": { "status": "CURRENT", "lastSuccessfulAt": "2036-04-23T18:45:00Z", "lastAttemptAt": "2036-04-23T18:45:00Z", "scopes": [ { "acquirerTaxId": "string", "paymentScheme": "string", "snapshotId": "string", "resultStatus": "DATA", "asOf": "2036-04-23T18:45:00Z", "stale": true } ] }, "agendaVersion": { "queryId": "string", "sequence": 1, "openedAt": "2036-04-23T18:45:00Z", "asOf": "2036-04-23T18:45:00Z", "closedBy": "ALL_TERMINAL", "totals": { "registeredAmount": "string", "performedAmount": "string", "cededAmount": "string", "encumberedAmount": "string", "notAllocatedAmount": "string", "unitCount": 0, "encumbranceBreakdownStatus": "AVAILABLE", "encumberedByClientAmount": "string", "encumberedByOthersAmount": "string", "encumberedUnitCount": 0, "clientEncumberedUnitCount": 0, "clientFirstUnitCount": 0 }, "acquirers": [ { "acquirerTaxId": "string", "performed": true, "unitCount": 0, "registered": "string", "performedAmount": "string", "cededAmount": "string", "free": "string", "encumbered": "string", "notAllocated": "string", "encumbranceBreakdownStatus": "AVAILABLE", "encumberedByClient": "string", "encumberedByOthers": "string", "encumberedUnitCount": 0, "clientEncumberedUnitCount": 0, "clientFirstUnitCount": 0 } ], "pairs": [ { "acquirerTaxId": "string", "paymentScheme": "string", "result": "DATA", "reason": "string", "performed": true, "unitCount": 0, "registered": "string", "performedAmount": "string", "cededAmount": "string", "free": "string", "encumbered": "string", "notAllocated": "string", "sources": [ "PACKAGE" ], "encumbranceBreakdownStatus": "AVAILABLE", "encumberedByClient": "string", "encumberedByOthers": "string", "encumberedUnitCount": 0, "clientEncumberedUnitCount": 0, "clientFirstUnitCount": 0 } ], "unavailablePairs": [ { "acquirerTaxId": "string", "paymentScheme": "string", "result": "FAILED", "reason": "string" } ] } } } } }, "400": { "description": "Parâmetros da solicitação inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "403": { "description": "Permissões insuficientes para acessar a empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "422": { "description": "Intervalo de datas não processável.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Recebíveis" ] } }, "/api/v2/cash-advances": { "post": { "operationId": "contracts_cash_advances_v2_create", "summary": "Criar antecipação por seleção de recebíveis", "description": "Cria uma antecipação a partir de uma seleção explícita de recebíveis do estabelecimento comercial. Use quando a operação deve nascer de recebíveis escolhidos no payload, com valores e referências controlados pela integração. O token precisa incluir `create:contracts:cash-advances`.", "responses": { "202": { "description": "Solicitação de antecipação aceita para processamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CreateCashAdvanceResponse" }, "example": { "cashAdvanceId": "11111111-1111-4111-8111-111111111111", "externalContractId": "contract-123", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "400": { "description": "JSON inválido ou solicitação incompatível com o esquema." }, "401": { "description": "Invalid or inconsistent trusted technical identity, including missing OAuth credential, owner client, or client_credentials grant." }, "403": { "description": "Required OAuth scope is absent or the owner client has no distinct canonical tenant." } }, "tags": [ "Antecipação" ] }, "get": { "operationId": "contracts_cash_advances_v2_list", "summary": "Listar contratos de antecipação", "responses": { "200": { "description": "Lista de contratos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CashAdvanceListResponse" }, "example": { "cashAdvances": [ { "cashAdvanceId": "11111111-1111-4111-8111-111111111111", "externalContractId": "contract-123", "status": "CREATED", "companyTaxId": "43151964000143", "companyName": "Empresa Teste", "financierTaxId": "12345678000190", "amounts": { "requestedAmount": 1500.0, "effectivelyEncumberedAmount": 1450.0 }, "firstSettlementDate": "2036-04-01", "lastSettlementDate": "2036-04-30", "createdAt": "2036-04-23T18:45:00Z", "updatedAt": "2036-04-23T19:45:00Z" } ], "pagination": { "currentItem": "string", "limit": 30, "nextItem": "string", "totalItems": 150 }, "totals": { "requestedAmount": 15000.0, "effectivelyEncumberedAmount": 14500.0 }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "400": { "description": "Parâmetro de consulta inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Antecipação" ], "description": "Lista contratos de antecipação com paginação e filtros. Use para acompanhar operações criadas, localizar contratos por status ou período e recuperar o identificador usado nas consultas de detalhe. O token precisa incluir `read:contracts:cash-advances`." } }, "/api/v2/cash-advances/{cashAdvanceId}": { "parameters": [ { "name": "cashAdvanceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_cash_advances_v2_detail", "summary": "Consultar contrato de antecipação", "responses": { "200": { "description": "Dados do contrato", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CashAdvanceDetailResponse" }, "example": { "cashAdvanceId": "11111111-1111-4111-8111-111111111111", "externalContractId": "contract-123", "status": "CREATED", "company": { "companyTaxId": "43151964000143", "companyName": "Empresa Teste" }, "financierTaxId": "12345678000190", "amounts": { "requestedAmount": 1500.0, "effectivelyEncumberedAmount": 1450.0 }, "bankingAddress": { "state": "PROVISIONED", "taxId": "43151964000143", "ispb": "13935893", "branch": "0001", "account": "12345-6", "bankName": "Banco Teste" }, "firstSettlementDate": "2036-04-20", "lastSettlementDate": "2036-04-25", "createdAt": "2036-04-23T18:45:00Z", "updatedAt": "2036-04-23T19:45:00Z", "cancellation": { "contractRegisterId": "REG-123", "cancelledAt": "2036-04-23T18:45:00Z", "receipt": "receipt-123" }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "404": { "description": "Contrato não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Antecipação" ], "description": "Consulta os detalhes de um contrato de antecipação específico, incluindo empresas, valores, status e dados operacionais. Use depois de criar ou localizar a antecipação na listagem. O token precisa incluir `read:contracts:cash-advances`." }, "delete": { "operationId": "contracts_cash_advances_v2_delete", "summary": "Baixar contrato de antecipação", "description": "Aplica o processo de baixa do contrato de antecipação. O processamento é assíncrono: o `202` indica que o pedido foi aceito e a confirmação no registrador externo acontece em segundo plano. Escopo: manage:contracts:cash-advances", "responses": { "202": { "description": "Deletion accepted, including an idempotent replay. The body is unchanged, `{\"cashAdvanceId\": \"...\"}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_DeleteCashAdvanceResponse" }, "example": { "cashAdvanceId": "11111111-1111-4111-8111-111111111111", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "409": { "description": "Nothing was changed: the registrar has not answered the creation of the cash advance yet (registration in progress), its status cannot be written off (FINISHED, EXPIRED, DELETION_FAILED...), or its automatic write-off (the canonical cycle decision of its receipts) is already under way. The body is `{\"message\": \"...\"}`." }, "401": { "description": "Trusted OAuth service identity context is missing or inconsistent." }, "403": { "description": "OAuth token does not grant the required scope." }, "404": { "description": "Cash advance not found for the authenticated client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Antecipação" ] } }, "/api/v2/cash-advances/{cashAdvanceId}/receivables": { "parameters": [ { "name": "cashAdvanceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_cash_advances_v2_receivables", "summary": "Consultar recebíveis vinculados ao contrato de antecipação", "responses": { "200": { "description": "Recebíveis do contrato", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CashAdvanceReceivablesResponse" }, "example": { "cashAdvanceId": "11111111-1111-4111-8111-111111111111", "receivables": [ { "receivableId": "1", "acquirerTaxId": "01027058000191", "paymentScheme": "MCC", "settlementDate": "2036-08-15", "requestedAmount": 1500.0, "effectivelyEncumberedAmount": 1450.0, "performedAmount": 1500.0 } ], "pagination": { "currentItem": "string", "limit": 30, "nextItem": "string", "totalItems": 150 }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "404": { "description": "Contrato não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Antecipação" ], "description": "Lista paginada dos recebíveis vinculados ao contrato. Cada item devolve `requestedAmount` (valor solicitado para o recebível no contrato), `effectivelyEncumberedAmount` (valor efetivamente onerado após confirmação do registrador; nulo até a confirmação ser recebida) e `performedAmount` (valor performado do recebível conforme registrado; nulo quando o recebível não está mais na agenda). O token precisa incluir `read:contracts:cash-advances:receivables`." } }, "/api/v2/collections/by-strategy": { "post": { "operationId": "contracts_collection_v2_create_by_strategy", "summary": "Criar cobrança por estratégia", "description": "Cria uma cobrança a partir de filtros de recebíveis e da estratégia informada. A resposta `202` indica que o pedido foi aceito e continuará sendo processado de forma assíncrona. O par `acquirerTaxIds` + `paymentSchemes` precisa existir na agenda da empresa. O token precisa incluir `create:contracts:collections`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Stable client-scoped creation identity. Exact accepted replay survives product deactivation; changed intent conflicts." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreateByStrategyRequest" } } } }, "responses": { "202": { "description": "Cobrança aceita para registro assíncrono.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CreateCollectionByStrategyResponse" }, "example": { "externalContractId": "contract-123", "collectionId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "400": { "description": "JSON inválido, campo desconhecido, tipo de campo inválido ou mais de um objeto JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsRequestBodyErrorResponse" }, "example": { "message": "Corpo da solicitação inválido", "errors": [ { "fieldName": "companies[0].companyTaxId", "code": "required", "message": "companyTaxId is required" } ] } } } }, "422": { "description": "Well-formed request body failed validation, COLLECTION_PRODUCT_INACTIVE or COLLECTION_PRICING_NOT_READY. No new creation is admitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsRequestBodyErrorResponse" }, "example": { "message": "Corpo da solicitação inválido", "errors": [ { "fieldName": "companies[0].companyTaxId", "code": "required", "message": "companyTaxId is required" } ] } } } }, "401": { "description": "Invalid or inconsistent trusted technical identity, including missing OAuth credential, owner client, or client_credentials grant." }, "403": { "description": "Required OAuth scope is absent, the client is not authorized for the company, or the owner client has no distinct canonical tenant." }, "409": { "description": "External collection ID already exists for the same client and company, or IDEMPOTENCY_KEY_REUSED for changed accepted intent." }, "424": { "description": "As contas obrigatórias de baixa da liquidação não estão configuradas para o financiador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteOffAccountReadinessErrorResponse" }, "example": { "code": "WRITE_OFF_ACCOUNTS_NOT_READY", "message": "Required write-off accounts are not configured.", "missingRoles": [ "PARENT" ] } } } }, "503": { "description": "COLLECTION_ADMISSION_UNAVAILABLE before admission, COLLECTION_CREATION_PENDING for an accepted creation with incomplete steps (retry the same Idempotency-Key and payload), or COLLECTION_CREATION_RECOVERY_UNAVAILABLE when durable recovery evidence is missing (contact support; do not create another identity)." } }, "tags": [ "Cobrança" ] } }, "/api/v2/collections": { "get": { "operationId": "contracts_collection_v2_list", "summary": "Listar contratos de cobrança", "responses": { "200": { "description": "Estado registral e resultado financeiro independente; FINISHED é terminal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionV2FinancialResult" } } } }, "example": { "collections": [ { "status": "string", "operationResult": "ACTIVE", "operationResultAt": "2036-04-23T18:45:00Z", "stage": "CONSULTING_AGENDA" } ] } } } }, "400": { "description": "Parâmetro de consulta inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "401": { "description": "Identificação do cliente ausente." } }, "tags": [ "Cobrança" ], "description": "Lista contratos de cobrança com paginação. Use os filtros disponíveis para acompanhar operações criadas por estratégia, status ou período, sem precisar abrir contrato por contrato. O token precisa incluir `read:contracts:collections`." } }, "/api/v2/collections/{collectionId}": { "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_collection_v2_detail", "summary": "Consultar contrato de cobrança", "parameters": [ { "$ref": "#/components/parameters/CollectionV2Id" } ], "responses": { "200": { "description": "Estado registral e resultado financeiro independente; FINISHED é terminal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionV2FinancialResult" }, "example": { "status": "string", "operationResult": "ACTIVE", "operationResultAt": "2036-04-23T18:45:00Z", "stage": "CONSULTING_AGENDA" } } } }, "400": { "description": "Identificador da cobrança inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "401": { "description": "Identificação do cliente ausente." }, "404": { "description": "Cobrança não encontrada para o cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Cobrança" ], "description": "Consulta os detalhes de um contrato de cobrança específico. Use para ver valores, empresas envolvidas, status e informações operacionais da cobrança. O token precisa incluir `read:contracts:collections`." } }, "/api/v2/collections/{collectionId}/events": { "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_collection_v2_events", "summary": "Consultar eventos da cobrança", "parameters": [ { "$ref": "#/components/parameters/CollectionV2Id" } ], "responses": { "200": { "description": "Eventos do contrato", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_ContractEventsResponse" }, "example": { "contractId": "ct-a1b2c3d4", "events": [ { "eventId": "evt-001", "eventType": "CONTRACT_CREATED", "description": "Contrato criado com sucesso", "createdAt": "2025-07-01T17:45:00Z" } ], "pagination": { "currentItem": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "limit": 30, "nextItem": "22222222-2222-4222-8222-222222222222", "totalItems": 150 }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "400": { "description": "Identificador da cobrança ou parâmetro de consulta inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "401": { "description": "Identificação do cliente ausente." }, "404": { "description": "Cobrança não encontrada para o cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Cobrança" ], "description": "Lista os eventos registrados para um contrato de cobrança. Use para acompanhar mudanças de status e marcos relevantes da operação ao longo do tempo. O token precisa incluir `read:contracts:collections:events`." } }, "/api/v2/collections/summary": { "get": { "operationId": "contracts_collection_v2_summary", "summary": "Consultar resumo agregado de cobranças (totais por status e estratégia)", "responses": { "200": { "description": "Resumo de cobranças", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CollectionSummaryResponse" }, "example": { "totalContracts": 55, "requestedAmount": 800000.0, "statuses": [ { "status": "CREATED", "contracts": 20, "requestedAmount": 2400.0 } ], "strategies": [ { "strategy": "TURBO", "contracts": 20, "requestedAmount": 2400.0 } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "400": { "description": "Parâmetro de consulta inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "401": { "description": "Identificação do cliente ausente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Cobrança" ], "description": "Devolve totalizadores monetários e quantidades agrupadas por status do contrato e por estratégia. Exposto apenas `requestedAmount` (sem `effectivelyEncumberedAmount`). O token precisa incluir `read:contracts:collections:summary`." } }, "/api/v2/collections/automatic-refund": { "patch": { "operationId": "contracts_collection_v2_automatic_refund_patch", "summary": "Configurar devolução automática", "responses": { "200": { "description": "A configuração de devolução automática foi atualizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_AutomaticRefundResponse" }, "example": { "companyTaxId": "43151964000143", "enabled": true, "updatedAt": "2025-07-01T17:45:00Z", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "400": { "description": "JSON inválido ou solicitação incompatível com o esquema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "401": { "description": "Identificação do cliente ausente." }, "404": { "description": "A projeção local da empresa do cliente não foi encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Cobrança" ], "description": "Habilita ou desabilita a devolução automática para uma empresa. Use esta configuração quando a cobrança precisar devolver valores automaticamente pela conta de devolução cadastrada. O token precisa incluir `manage:collections:automatic-refund`." } }, "/api/v2/collections/{collectionId}/receivables": { "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_collection_v2_receivables", "summary": "Consultar recebíveis vinculados ao contrato de cobrança", "parameters": [ { "$ref": "#/components/parameters/CollectionV2Id" } ], "responses": { "200": { "description": "Lista paginada dos recebíveis vinculados à cobrança.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionReceivablesV2Response" }, "example": { "collectionId": "11111111-1111-4111-8111-111111111111", "receivables": [ { "receivableId": "43151964000143|12345678000190|VCD|2036-04-23", "acquirerTaxId": "12345678000190", "paymentScheme": "VCD", "settlementDate": "2036-04-23", "amount": 47.62, "requestedAmount": 300.0, "status": "COMMITTED" } ], "pagination": { "cursor": "string", "limit": 30, "nextCursor": "string", "currentItem": 0, "nextItem": 0, "totalItems": 0 } } } } }, "400": { "description": "Identificador da cobrança ou parâmetro de consulta inválido." }, "401": { "description": "Identificação do cliente ausente." }, "404": { "description": "Cobrança não encontrada para o cliente." } }, "tags": [ "Cobrança" ] } }, "/api/v2/collateralized-credits/summary": { "get": { "operationId": "contracts_collateralized_credits_v2_summary", "summary": "Consultar resumo agregado de créditos com garantia (totais por status)", "responses": { "200": { "description": "Resumo de créditos com garantia", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CollateralizedCreditSummaryResponse" }, "example": { "totalContracts": 55, "requestedAmount": 800000.0, "effectivelyEncumberedAmount": 600000.0, "statuses": [ { "status": "CREATED", "contracts": 20, "requestedAmount": 2400.0, "effectivelyEncumberedAmount": 2100.0 } ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "400": { "description": "Parâmetro de consulta inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Crédito com Garantia" ], "description": "Devolve totalizadores monetários (`requestedAmount` + `effectivelyEncumberedAmount`) e quantidades agrupadas por status do contrato. Sem detalhamento por estratégia. O token precisa incluir `read:contracts:secured-credit:summary`." } }, "/api/v2/collateralized-credits/{creditId}/receivables": { "parameters": [ { "name": "creditId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "contracts_collateralized_credits_v2_receivables", "summary": "Consultar recebíveis do crédito", "responses": { "200": { "description": "Recebíveis do contrato", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CollateralizedCreditReceivablesResponse" }, "example": { "creditId": "11111111-1111-4111-8111-111111111111", "receivables": [ { "receivableId": "10", "acquirerTaxId": "01027058000191", "paymentScheme": "MCC", "settlementDate": "2025-08-15", "requestedAmount": 1500.0, "effectivelyEncumberedAmount": 1450.0 } ], "pagination": { "currentItem": "10", "limit": 30, "nextItem": "9", "totalItems": 150 }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "404": { "description": "Contrato não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Crédito com Garantia" ], "description": "Lista os recebíveis vinculados a um contrato de crédito com garantia. Use para entender quais recebíveis sustentam a operação e seus valores associados. O token precisa incluir `read:contracts:secured-credit:receivables`." } }, "/api/v2/accounts": { "get": { "operationId": "settlement_v2_accounts_list", "summary": "Listar contas bancárias do cliente", "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": "Página de contas operacionais.", "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" } } } } }, "example": { "accounts": [ { "accountId": "string", "category": "OPERATIONAL", "status": "string", "ownerTaxId": "string", "bankAccount": { "ispb": "string", "branch": "string", "accountNumber": "string", "accountVerificationDigit": "string" }, "balance": 0, "operation": { "operationId": "string", "onboardingId": "string", "contractId": "string", "contractType": "string" }, "createdAt": "2036-04-23T18:45:00Z" } ], "pagination": { "currentItem": "string", "limit": 0, "nextItem": "string", "totalItems": 0 } } } } }, "400": { "description": "Filtros ou parâmetros de paginação inválidos. Os filtros removidos `contractId` e `contractType` são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "401": { "description": "A identificação do cliente é obrigatória." }, "403": { "description": "O escopo obrigatório está ausente." } }, "tags": [ "Contas" ], "description": "Lista as contas do cliente autenticado. Use para obter o `accountId` que será passado às consultas de saldo e extrato. Cada conta traz a `category` (MOTHER, REFUND ou OPERATION). Todos os filtros são opcionais. O token precisa incluir `read:accounts`." } }, "/api/v2/accounts/{accountId}/balance": { "get": { "operationId": "settlement_v2_account_balance_get", "summary": "Consultar saldo de uma conta", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Posição do saldo da conta.", "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" } } }, "example": { "accountId": "string", "availableBalance": 0, "blockedBalance": 0, "totalBalance": 0, "updatedAt": "2036-04-23T18:45:00Z" } } } }, "401": { "description": "A identificação do cliente é obrigatória." }, "403": { "description": "O escopo obrigatório está ausente." }, "404": { "description": "Conta não encontrada para o cliente autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Contas" ], "description": "Consulta o saldo atual de uma conta bancária pelo `accountId`. Use depois de descobrir a conta em `/api/v2/accounts`. O token precisa incluir `read:accounts:balance`." } }, "/api/v2/accounts/{accountId}/transactions": { "get": { "operationId": "settlement_v2_account_transactions_list", "summary": "Consultar extrato da conta", "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": "Página de transações da conta com o contexto normalizado do provedor.", "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": "Contexto normalizado do provedor, sem `providerRawPayload`, na rota pública V2." } } } }, "totals": { "type": "object", "properties": { "transactionsAmount": { "type": "number" } } } } }, "example": { "meta": { "currentItem": "string", "limit": 0, "nextItem": "string", "totalItems": 0 }, "data": [ { "id": "string", "accountId": "string", "transactionAmount": 0, "createdAt": "string", "createdAtTimestamp": "string", "acquirerTaxId": "string", "acquirerName": "string", "providerContext": {} } ], "totals": { "transactionsAmount": 0 } } } } }, "400": { "description": "Parâmetros de paginação inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "401": { "description": "A identificação do cliente é obrigatória." }, "403": { "description": "O escopo obrigatório está ausente." }, "404": { "description": "Conta não encontrada para o cliente autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CustomErrorResponse" }, "example": { "timestamp": "2026-04-17T13:00:00Z", "error": "Requisição inválida", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Contas" ], "description": "Lista as transações de uma conta bancária pelo `accountId`. Quando `startDate` e `endDate` não são informados, a API consulta automaticamente os últimos 7 dias. O token precisa incluir `read:accounts:transactions`." } }, "/api/v2/webhook-subscriptions": { "get": { "operationId": "notifications_webhook_subscription_list", "summary": "Listar webhooks cadastrados", "description": "Lista os webhooks cadastrados para o cliente autenticado. Use para conferir URLs, eventos assinados, status e dados de autenticação antes de criar ou alterar subscriptions. O token precisa incluir `read:webhooks`.", "responses": { "200": { "description": "Webhook subscriptions owned by the authenticated client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionListResponse" }, "example": { "subscriptions": [ { "subscriptionId": "2w3Y2QeS0TtV3X9nZ5aBcD1eF6g", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "auth": { "type": "BEARER", "login": "X-Client-Webhook-Key", "configured": true }, "createdAt": "2036-04-23T18:45:00Z", "updatedAt": "2036-04-23T18:45:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] }, "post": { "operationId": "notifications_webhook_subscription_create", "summary": "Cadastrar webhook", "description": "Cadastra um webhook para receber eventos enviados pela Destrava. Informe uma URL pública e segura para onde as notificações devem ser entregues. O token precisa incluir `manage:webhooks`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateRequest" } } } }, "responses": { "201": { "description": "Webhook subscription created without plaintext secrets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "example": { "subscriptionId": "2w3Y2QeS0TtV3X9nZ5aBcD1eF6g", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "auth": { "type": "BEARER", "login": "X-Client-Webhook-Key", "configured": true }, "createdAt": "2036-04-23T18:45:00Z", "updatedAt": "2036-04-23T18:45:00Z" } } } }, "400": { "$ref": "#/components/responses/NotificationsRequestBodyBadRequest" }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "notifications_webhook_subscription_update", "summary": "Atualizar webhook", "description": "Atualiza uma subscription de webhook existente. Use para trocar URL, status, eventos assinados ou configuração de autenticação sem recriar a subscription. O token precisa incluir `manage:webhooks`.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Webhook subscription updated without plaintext secrets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "example": { "subscriptionId": "2w3Y2QeS0TtV3X9nZ5aBcD1eF6g", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "auth": { "type": "BEARER", "login": "X-Client-Webhook-Key", "configured": true }, "createdAt": "2036-04-23T18:45:00Z", "updatedAt": "2036-04-23T18:45:00Z" } } } }, "400": { "$ref": "#/components/responses/NotificationsRequestBodyBadRequest" }, "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": [ "Webhooks" ] }, "delete": { "operationId": "notifications_webhook_subscription_delete", "summary": "Desativar webhook", "description": "Desativa uma subscription de webhook e cancela entregas pendentes relacionadas a ela. Use quando a integração não deve mais receber eventos por aquela URL. O token precisa incluir `manage:webhooks`.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "204": { "description": "Webhook subscription deactivated without a response body." }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-deliveries/summary": { "get": { "operationId": "notifications_webhook_delivery_summary", "summary": "Ver resumo de entregas de webhook", "description": "Resume as entregas de webhook por subscription e status HTTP. Use para identificar rapidamente falhas, sucesso de envio e subscriptions que precisam de atenção. O token precisa incluir `read:webhooks`.", "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" }, "example": { "totalDeliveries": 12, "subscriptions": [ { "subscriptionId": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5", "eventType": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "totalDeliveries": 12, "statuses": [ { "status": "FAILED", "deliveries": 3 } ] } ] } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/deliveries": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "notifications_webhook_deliveries", "summary": "Ver detalhes de entregas de webhook", "description": "Lista as entregas e tentativas de uma subscription de webhook. Use para investigar uma notificação específica, entender respostas HTTP recebidas e acompanhar tentativas de reenvio. O token precisa incluir `read:webhooks`.", "parameters": [ { "$ref": "#/components/parameters/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" }, "example": { "deliveries": [ { "eventId": "99999999-9999-9999-9999-999999999999", "eventType": "COLLECTION_CONTRACT", "status": "FAILED", "eventStatus": "FAILED", "attempts": 3, "maxAttempts": 5, "lastHttpStatus": 500, "lastError": "upstream returned 500", "eventOccurredAt": "2026-06-17T12:00:00Z", "nextRetryAt": "2026-06-17T12:15:00Z", "deliveredAt": "2026-06-17T12:06:00Z", "createdAt": "2026-06-17T12:00:10Z", "updatedAt": "2026-06-17T12:05:00Z", "payload": "{\"eventId\":\"99999999-9999-9999-9999-999999999999\",\"payload\":{\"token\":\"[REDACTED]\"}}", "response": "{\"message\":\"temporary failure\"}", "attemptHistory": [ { "attemptNumber": 2, "webhookUrl": "https://example.com/destrava/webhooks", "payload": "{\"eventId\":\"99999999-9999-9999-9999-999999999999\",\"secret\":\"[REDACTED]\"}", "responseStatus": 500, "responseBody": "{\"message\":\"temporary failure\"}", "errorMessage": "timeout waiting for response", "durationMs": 842, "successful": false, "attemptedAt": "2026-06-17T12:05:00Z" } ] } ], "currentItem": "string", "nextItem": "string", "limit": 30, "totalItems": 42, "pagination": { "currentItem": "2026-06-17T12:00:00Z#DELIVERY#99999999-9999-9999-9999-999999999999", "nextItem": "2026-06-17T11:50:00Z#DELIVERY#88888888-8888-8888-8888-888888888888" } } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-delivery-replays": { "post": { "operationId": "notifications_webhook_delivery_replay", "summary": "Reenfileirar entregas com falha", "description": "Reenfileira entregas de webhook que chegaram a falha final, mantendo o mesmo `eventId`. Use para tentar novamente uma entrega depois de corrigir a URL ou o serviço consumidor. O token precisa incluir `manage:webhooks`.", "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" }, "example": { "requestedEvents": 3, "requeuedEvents": 1, "ignoredEvents": 2 } } } }, "400": { "$ref": "#/components/responses/NotificationsRequestBodyBadRequest" }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/pause": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "notifications_webhook_subscription_pause", "summary": "Pausar webhook", "description": "Pausa as próximas entregas de webhook sem remover a configuração. O token precisa incluir `manage:webhooks`.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "200": { "description": "Webhook subscription paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "example": { "subscriptionId": "2w3Y2QeS0TtV3X9nZ5aBcD1eF6g", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "auth": { "type": "BEARER", "login": "X-Client-Webhook-Key", "configured": true }, "createdAt": "2036-04-23T18:45:00Z", "updatedAt": "2036-04-23T18:45:00Z" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/reactivate": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "notifications_webhook_subscription_reactivate", "summary": "Reativar webhook", "description": "Reativa uma subscription pausada e retoma as próximas entregas conforme o contrato vigente da subscription. O token precisa incluir `manage:webhooks`.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "200": { "description": "Webhook subscription reactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "example": { "subscriptionId": "2w3Y2QeS0TtV3X9nZ5aBcD1eF6g", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "auth": { "type": "BEARER", "login": "X-Client-Webhook-Key", "configured": true }, "createdAt": "2036-04-23T18:45:00Z", "updatedAt": "2036-04-23T18:45:00Z" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/contracts/{contractId}/history": { "get": { "operationId": "contracts_traceability_history", "summary": "Listar alterações imutáveis de contratos, das mais recentes para as mais antigas.", "description": "Exige o escopo OAuth V2 `read:contracts:traceability`.", "parameters": [ { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owner-scoped contract history page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractHistoryResponse" }, "example": { "contractId": "string", "companyTaxId": "string", "historicalCompleteness": "COMPLETE_FROM_CREATION", "limit": 0, "nextCursor": "string", "changes": [ { "changeId": "string", "appliedAt": "2036-04-23T18:45:00Z", "changes": [ { "path": "string", "valueType": "DECIMAL", "before": "string", "after": "string" } ], "provenance": { "schemaVersion": 1, "aggregateType": "CONTRACT", "aggregateId": "string", "originType": "REGISTRAR", "originChannel": "TAG", "actorType": "PROVIDER", "actorId": "string", "actorRole": "string", "clientId": "string", "tenantId": "string", "companyTaxId": "string", "registrar": "TAG", "providerEventId": "string", "providerObjectId": "string", "providerVersion": "string", "providerSequence": "string", "orderBasis": "PROVIDER_SEQUENCE", "occurredAt": "2036-04-23T18:45:00Z", "effectiveAt": "2036-04-23T18:45:00Z", "receivedAt": "2036-04-23T18:45:00Z", "appliedAt": "2036-04-23T18:45:00Z", "correlationId": "string", "causationId": "string", "commandId": "string", "operationId": "string", "reasonCode": "string", "relatedObservationIds": [ "string" ], "version": 0, "historicalCompleteness": "COMPLETE_FROM_CREATION" } } ] } } } }, "400": { "description": "Invalid limit or cursor." }, "401": { "description": "Identificação do cliente ausente." }, "403": { "description": "Contract belongs to another client." }, "404": { "description": "Contract was not found." } }, "tags": [ "Contratos" ] } }, "/api/v2/contracts/{contractId}/registrar-observations": { "get": { "operationId": "contracts_traceability_registrar_observations", "summary": "Listar observações imutáveis do registrador para um contrato.", "description": "Exige o escopo OAuth V2 `read:contracts:traceability`.", "parameters": [ { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "registrar", "in": "query", "schema": { "type": "string", "enum": [ "TAG", "NUCLEA" ] } }, { "name": "decision", "in": "query", "schema": { "$ref": "#/components/schemas/TraceabilityObservationDecision" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Owner-scoped registrar observation page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractRegistrarObservationsResponse" }, "example": { "contractId": "string", "companyTaxId": "string", "historicalCompleteness": "COMPLETE_FROM_CREATION", "limit": 0, "nextCursor": "string", "observations": [ { "observationId": "string", "decision": "APPLIED", "values": {}, "provenance": { "schemaVersion": 1, "aggregateType": "CONTRACT", "aggregateId": "string", "originType": "REGISTRAR", "originChannel": "TAG", "actorType": "PROVIDER", "actorId": "string", "actorRole": "string", "clientId": "string", "tenantId": "string", "companyTaxId": "string", "registrar": "TAG", "providerEventId": "string", "providerObjectId": "string", "providerVersion": "string", "providerSequence": "string", "orderBasis": "PROVIDER_SEQUENCE", "occurredAt": "2036-04-23T18:45:00Z", "effectiveAt": "2036-04-23T18:45:00Z", "receivedAt": "2036-04-23T18:45:00Z", "appliedAt": "2036-04-23T18:45:00Z", "correlationId": "string", "causationId": "string", "commandId": "string", "operationId": "string", "reasonCode": "string", "relatedObservationIds": [ "string" ], "version": 0, "historicalCompleteness": "COMPLETE_FROM_CREATION" } } ] } } } }, "400": { "description": "Invalid filter, limit, or cursor." }, "401": { "description": "Identificação do cliente ausente." }, "403": { "description": "Contract belongs to another client." }, "404": { "description": "Contract was not found." } }, "tags": [ "Contratos" ] } }, "/api/v2/receivables/{receivableId}/history": { "parameters": [ { "name": "receivableId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "receivables_financier_receivable_history_v2", "summary": "Consultar histórico aplicado de uma UR", "description": "Retorna, da alteração mais recente para a mais antiga, apenas as mudanças efetivamente aplicadas à UR. O escopo OAuth necessário é `read:receivables`.", "parameters": [ { "$ref": "#/components/parameters/ReceivableId" }, { "$ref": "#/components/parameters/HistoryLimit" }, { "$ref": "#/components/parameters/HistoryCursor" } ], "responses": { "200": { "description": "Página do histórico aplicado da UR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableHistoryResponse" }, "example": { "receivableId": "string", "companyTaxId": "string", "historicalCompleteness": "COMPLETE_FROM_CREATION", "limit": 0, "nextCursor": "string", "changes": [ { "changeId": "string", "appliedAt": "2036-04-23T18:45:00Z", "changes": [ { "path": "string", "valueType": "DECIMAL", "before": "string", "after": "string" } ], "provenance": { "schemaVersion": 0, "aggregateType": "RECEIVABLE", "aggregateId": "string", "originType": "REGISTRAR", "originChannel": "TAG", "actorType": "PROVIDER", "actorId": "string", "actorRole": "string", "clientId": "string", "companyTaxId": "string", "registrar": "TAG", "providerEventId": "string", "providerObjectId": "string", "providerVersion": "string", "providerSequence": "string", "orderBasis": "PROVIDER_SEQUENCE", "occurredAt": "2036-04-23T18:45:00Z", "effectiveAt": "2036-04-23T18:45:00Z", "receivedAt": "2036-04-23T18:45:00Z", "correlationId": "string", "causationId": "string", "commandId": "string", "operationId": "string", "reasonCode": "string", "relatedObservationIds": [ "string" ], "stateHashBefore": "string", "stateHashAfter": "string", "version": 0, "historicalCompleteness": "COMPLETE_FROM_CREATION" } } ] } } } }, "400": { "description": "Limite ou cursor inválido." }, "403": { "description": "O cliente autenticado não possui acesso à empresa da UR." }, "404": { "description": "UR canônica não encontrada." } }, "tags": [ "Recebíveis" ] } }, "/api/v2/receivables/{receivableId}/registrar-observations": { "parameters": [ { "name": "receivableId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "receivables_financier_receivable_registrar_observations_v2", "summary": "Consultar observações de registradoras de uma UR", "description": "Retorna, da observação mais recente para a mais antiga, as evidências recebidas de TAG e NUCLEA, incluindo decisões que não alteraram o estado canônico. O escopo OAuth necessário é `read:receivables`.", "parameters": [ { "$ref": "#/components/parameters/ReceivableId" }, { "$ref": "#/components/parameters/HistoryLimit" }, { "$ref": "#/components/parameters/HistoryCursor" }, { "name": "registrar", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "TAG", "NUCLEA" ] } }, { "name": "decision", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "APPLIED", "NO_CHANGE", "IGNORED_DUPLICATE", "IGNORED_STALE", "CONFLICT", "REJECTED_INVALID" ] } } ], "responses": { "200": { "description": "Página de observações das registradoras.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableRegistrarObservationsResponse" }, "example": { "receivableId": "string", "companyTaxId": "string", "historicalCompleteness": "COMPLETE_FROM_CREATION", "limit": 0, "nextCursor": "string", "observations": [ { "observationId": "string", "decision": "APPLIED", "values": {}, "provenance": { "schemaVersion": 0, "aggregateType": "RECEIVABLE", "aggregateId": "string", "originType": "REGISTRAR", "originChannel": "TAG", "actorType": "PROVIDER", "actorId": "string", "actorRole": "string", "clientId": "string", "companyTaxId": "string", "registrar": "TAG", "providerEventId": "string", "providerObjectId": "string", "providerVersion": "string", "providerSequence": "string", "orderBasis": "PROVIDER_SEQUENCE", "occurredAt": "2036-04-23T18:45:00Z", "effectiveAt": "2036-04-23T18:45:00Z", "receivedAt": "2036-04-23T18:45:00Z", "correlationId": "string", "causationId": "string", "commandId": "string", "operationId": "string", "reasonCode": "string", "relatedObservationIds": [ "string" ], "stateHashBefore": "string", "stateHashAfter": "string", "version": 0, "historicalCompleteness": "COMPLETE_FROM_CREATION" } } ] } } } }, "400": { "description": "Filtro, limite ou cursor inválido." }, "403": { "description": "O cliente autenticado não possui acesso à empresa da UR." }, "404": { "description": "UR canônica não encontrada." } }, "tags": [ "Recebíveis" ] } }, "/api/v2/schedule-access-requests/{operationId}": { "get": { "operationId": "permission_v2_schedule_access_request_get", "summary": "Consultar processamento de acesso à agenda", "description": "Escopo OAuth necessário: `companies:read`. Retorna o estado agregado da operação, empresas e escopos sem transportar dados da agenda. Operações de outro cliente retornam 404.", "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Estado atual da operação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleAccessOperation" }, "example": { "operationId": "string", "optInExternalId": "string", "status": "SCHEDULED", "requestedAt": "2036-04-23T18:45:00Z", "scheduledFor": "2036-04-23T18:45:00Z", "companies": [ { "agendaScope": { "queryId": "string", "companyId": "string", "clientId": "string", "packageId": "string", "packageVersion": 0, "assignmentRevision": 0, "exceptionsRevision": 0, "migrationId": "string", "pairs": [ { "acquirerTaxId": "string", "paymentScheme": "string", "sources": [ "PACKAGE" ] } ], "resolvedAt": "2036-04-23T18:45:00Z", "legacy": true }, "companyTaxId": "string", "status": "PENDING", "scopes": [ { "externalRequests": [ { "agendaScope": { "version": 0, "queryId": "string", "clientId": "string", "companyId": "string", "snapshotHash": "string" }, "scheduleTrackingId": "string", "requestId": "string", "requestIds": [ "string" ], "processKey": "string", "provider": "string", "status": "string", "reason": "string", "occurredAt": "2036-04-23T18:45:00Z" } ], "scheduleTrackingId": "string", "acquirerTaxId": "string", "paymentScheme": "string", "resultStatus": "PENDING" } ] } ] } } } }, "404": { "description": "Operação não encontrada para o cliente autenticado." } }, "tags": [ "Opt-In" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/test": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "notifications_webhook_endpoint_test", "summary": "Enviar evento sintético de teste para um endpoint", "description": "Exige o escopo OAuth `manage:webhooks`. Envia de forma síncrona uma carga sintética usando o HMAC e a autenticação opcional configurados no endpoint. A solicitação não é persistida nem contabilizada como entrega de negócio. Os trechos da resposta são ocultados e truncados.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "200": { "description": "Resultado síncrono e sanitizado do evento de teste.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointTestResponse" }, "example": { "subscriptionId": "string", "eventType": "COLLECTION_CONTRACT", "request": { "method": "POST", "url": "https://integracao.exemplo.com.br/recurso", "payload": "string" }, "httpStatus": 100, "latencyMillis": 0, "response": "string", "error": "string", "successful": true } } } }, "400": { "$ref": "#/components/responses/WebhookBadRequest" }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } } }, "components": { "schemas": { "AgendaEncumbranceBreakdownStatus": { "type": "string", "enum": [ "AVAILABLE", "PARTIAL", "UNAVAILABLE" ], "description": "ENG-1235 whether the client split of a sum of URs is known: AVAILABLE when every counted UR (the unitCount ones) is known, including a sum without URs; PARTIAL when only some are (older photographs add nothing, the values cover the others); UNAVAILABLE when none is, as on every version consolidated before the frozen financier list (all split values null, never zero)." }, "AgendaVersionAcquirer": { "type": "object", "description": "ENG-1235 sum of the pairs of one acquirer, with the same fields and client split as a pair.", "required": [ "acquirerTaxId", "performed", "unitCount", "registered", "free", "encumbered", "notAllocated", "encumbranceBreakdownStatus", "encumberedByClient", "encumberedByOthers", "encumberedUnitCount", "clientEncumberedUnitCount", "clientFirstUnitCount" ], "properties": { "acquirerTaxId": { "type": "string" }, "performed": { "type": "boolean", "description": "Any pair of the acquirer performed." }, "unitCount": { "type": "integer", "minimum": 0 }, "registered": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "performedAmount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "ENG-1246 performed value of the acquirer's URs, the base (canonical performedAmount, or registered + cededAmount); session routes only." }, "cededAmount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "ENG-1246 value effective cessions took out of the acquirer's URs; session routes only." }, "free": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "encumbered": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "notAllocated": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "encumbranceBreakdownStatus": { "$ref": "#/components/schemas/AgendaEncumbranceBreakdownStatus" }, "encumberedByClient": { "type": "string", "nullable": true, "pattern": "^[0-9]+\\.[0-9]{2}$" }, "encumberedByOthers": { "type": "string", "nullable": true, "pattern": "^[0-9]+\\.[0-9]{2}$" }, "encumberedUnitCount": { "type": "integer", "nullable": true, "minimum": 0 }, "clientEncumberedUnitCount": { "type": "integer", "nullable": true, "minimum": 0 }, "clientFirstUnitCount": { "type": "integer", "nullable": true, "minimum": 0 } } }, "AgendaVersionMetadata": { "type": "object", "description": "ENG-1164 additive field, present only when the caller's client has an ACTIVE consolidated agenda version for the company. The listed receivables/encumbrances then come only from the snapshots of the version's DATA pairs (instead of the per-company active snapshots). The client x company authorization is still required (403). Absent (null) means the client has no ACTIVE version: agendas are read only from consolidated consults (ENG-1184), so the response carries no receivables/encumbrances. ENG-1246: on the session collateral read the values are on the base of each UR (unitCount counts the URs with a performed value above zero, ceded URs included; free, encumbered and the split on the base) and carry performedAmount and cededAmount; the external v2 schedule and encumbrances routes read the registry values of the same version, as before ENG-1246, without those two fields.", "required": [ "queryId", "sequence", "asOf", "closedBy", "totals", "pairs", "unavailablePairs", "acquirers" ], "properties": { "queryId": { "type": "string" }, "sequence": { "type": "integer", "minimum": 1 }, "openedAt": { "type": "string", "format": "date-time", "description": "When the consult of the active version was asked for. Omitted on versions consolidated before company started sending it." }, "asOf": { "type": "string", "format": "date-time", "description": "Consult date of the active version." }, "closedBy": { "type": "string", "enum": [ "ALL_TERMINAL", "TECHNICAL_DEADLINE" ] }, "totals": { "$ref": "#/components/schemas/AgendaVersionTotals" }, "acquirers": { "type": "array", "description": "ENG-1235 the pairs of each acquirer summed, sorted by acquirerTaxId; frozen at consolidation (derived from the pairs on versions consolidated before it).", "items": { "$ref": "#/components/schemas/AgendaVersionAcquirer" } }, "pairs": { "type": "array", "description": "Every acquirer x payment-scheme pair of the consolidated version, sorted by acquirerTaxId then paymentScheme. Values are version-wide (all dates, same scope as totals), independent of the requested window, filters and page. EMPTY, NO_ACTIVE_RELATIONSHIP and FAILED pairs carry zero values and keep their reason. See docs/contracts/agenda-version-read.md.", "items": { "$ref": "#/components/schemas/AgendaVersionPair" } }, "unavailablePairs": { "type": "array", "description": "Pairs that returned no agenda (FAILED or NO_ACTIVE_RELATIONSHIP) with their reason. Kept for compatibility; pairs[] carries the same pairs with their values.", "items": { "type": "object", "required": [ "acquirerTaxId", "paymentScheme", "result", "reason" ], "properties": { "acquirerTaxId": { "type": "string" }, "paymentScheme": { "type": "string" }, "result": { "type": "string", "enum": [ "FAILED", "NO_ACTIVE_RELATIONSHIP" ] }, "reason": { "type": "string" } } } } } }, "AgendaVersionPair": { "type": "object", "additionalProperties": false, "required": [ "acquirerTaxId", "paymentScheme", "result", "reason", "performed", "unitCount", "registered", "free", "encumbered", "notAllocated" ], "properties": { "acquirerTaxId": { "type": "string" }, "paymentScheme": { "type": "string" }, "result": { "type": "string", "enum": [ "DATA", "EMPTY", "NO_ACTIVE_RELATIONSHIP", "FAILED" ] }, "reason": { "type": "string" }, "performed": { "type": "boolean", "description": "Any unit of the pair performed (unit performed flag, fallback registered > 0)." }, "unitCount": { "type": "integer", "minimum": 0 }, "registered": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "performedAmount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "ENG-1246 performed value of the pair's URs, the base (canonical performedAmount, or registered + cededAmount). On the panel's session routes (collateral-management and the consult history); absent on the external v2 routes." }, "cededAmount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "ENG-1246 value effective cessions took out of the pair's URs; session routes only." }, "free": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "encumbered": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "notAllocated": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "sources": { "type": "array", "description": "ENG-1072 frozen origin of the pair when the consult opened — PACKAGE (contract package), ADDITIONAL (chosen in the company configuration) and CONTRACT (protected by an advance contract). A pair can have more than one; absent on versions consolidated before the freeze.", "items": { "type": "string", "enum": [ "PACKAGE", "ADDITIONAL", "CONTRACT" ] } }, "encumbranceBreakdownStatus": { "$ref": "#/components/schemas/AgendaEncumbranceBreakdownStatus" }, "encumberedByClient": { "type": "string", "nullable": true, "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "ENG-1235 committed by the client's financiers on the URs of the pair; null while UNAVAILABLE. Absent from the consult history pairs." }, "encumberedByOthers": { "type": "string", "nullable": true, "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "ENG-1235 committed by other institutions on the URs of the pair; null while UNAVAILABLE." }, "encumberedUnitCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "URs with an encumbrance (\"URs com oneração\"); null while UNAVAILABLE." }, "clientEncumberedUnitCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "URs with an encumbrance of the client's financiers (\"URs com a nossa oneração\"); null while UNAVAILABLE." }, "clientFirstUnitCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "URs where the client's financier is 1st in the queue (\"URs em que estamos em 1º\"); counts the URs with a queue, TAG and, since ENG-1313, Núclea with the canonical queue; null while UNAVAILABLE." } } }, "AgendaVersionTotals": { "type": "object", "description": "Totals of the whole consolidated version, independent of the requested window, filters and page. Since ENG-1235 they carry the client split (\"comprometido nosso\" × \"com outras instituições\") and its UR counts, frozen at consolidation with the client's ACTIVE financiers of that moment (docs/contracts/client-encumbrance-attribution.md).", "required": [ "registeredAmount", "freeAmount", "encumberedAmount", "notAllocatedAmount", "unitCount" ], "properties": { "registeredAmount": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "performedAmount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "ENG-1246 performed value of the company URs, the base (canonical performedAmount, or registeredAmount + cededAmount); freeAmount, encumberedAmount, unitCount and the split are on the same base. Session routes only (collateral-management and the consult history)." }, "cededAmount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "ENG-1246 value effective cessions took out of the company URs; session routes only." }, "freeAmount": { "allOf": [ { "$ref": "#/components/schemas/ReceivableDecimalAmount" } ], "description": "ENG-1355: the stored version keeps the free value before the acquirer's prepaid, so this total, the agenda.consolidated.v1 event and the external API v2 do not change; the Agenda summary, Onerações and the Excel read the prepaid out of the states and photographs and show the free value net of it." }, "encumberedAmount": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "notAllocatedAmount": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "unitCount": { "type": "integer", "minimum": 0 }, "encumbranceBreakdownStatus": { "$ref": "#/components/schemas/AgendaEncumbranceBreakdownStatus" }, "encumberedByClientAmount": { "type": "string", "nullable": true, "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "Committed by the client's financiers on the company URs; null while UNAVAILABLE." }, "encumberedByOthersAmount": { "type": "string", "nullable": true, "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "Committed by other institutions on the company URs; null while UNAVAILABLE." }, "encumberedUnitCount": { "type": "integer", "nullable": true, "minimum": 0 }, "clientEncumberedUnitCount": { "type": "integer", "nullable": true, "minimum": 0 }, "clientFirstUnitCount": { "type": "integer", "nullable": true, "minimum": 0 } } }, "CollectionCreateByStrategyRequest": { "type": "object", "required": [ "companyTaxId", "requestedAmount", "financierTaxId", "receivableFilter", "externalContractId", "strategy" ], "properties": { "companyTaxId": { "type": "string", "minLength": 11, "maxLength": 14 }, "requestedAmount": { "type": "number" }, "agingDays": { "type": "integer", "minimum": 0, "description": "Quantidade canônica de dias de atraso para faturamento da recuperação de COLLECTION." }, "financierTaxId": { "type": "string", "minLength": 11, "maxLength": 14 }, "receivableFilter": { "$ref": "#/components/schemas/CollectionReceivableFilter" }, "externalContractId": { "type": "string", "maxLength": 255 }, "externalId": { "type": "string", "maxLength": 255 }, "strategy": { "type": "string", "enum": [ "TURBO", "SELECTIVE", "SELECTIVE_WITH_DEBIT", "SNIPER", "DYNAMIC" ] } } }, "CollectionReceivableFilter": { "type": "object", "required": [ "firstSettlementDate", "lastSettlementDate" ], "properties": { "acquirerTaxIds": { "type": "array", "items": { "type": "string" } }, "paymentSchemes": { "type": "array", "items": { "type": "string" } }, "firstSettlementDate": { "type": "string", "format": "date", "description": "Não pode ser anterior ao dia corrente em São Paulo (hoje é aceito); uma data passada responde 400 (ENG-1555)." }, "lastSettlementDate": { "type": "string", "format": "date", "description": "Não pode ser anterior ao dia corrente em São Paulo (hoje é aceito); uma data passada responde 400 (ENG-1555)." } } }, "CollectionReceivableV2ResponseItem": { "type": "object", "description": "Recebível vinculado à cobrança.", "required": [ "receivableId", "amount", "status" ], "properties": { "receivableId": { "type": "string", "description": "Chave única do recebível dentro da cobrança.", "example": "43151964000143|12345678000190|VCD|2036-04-23" }, "acquirerTaxId": { "type": "string", "description": "CNPJ da adquirente.", "example": "12345678000190" }, "paymentScheme": { "type": "string", "description": "Código do arranjo de pagamento.", "example": "VCD" }, "settlementDate": { "type": "string", "format": "date", "description": "Data de liquidação do recebível. Na criação, não pode ser anterior ao dia útil corrente em São Paulo (hoje é aceito); uma data passada responde 400 (ENG-1555).", "example": "2036-04-23" }, "amount": { "type": "number", "format": "double", "description": "Valor onerado (efetivamente gravado pela registradora) considerado na cobrança. 0.00 numa UR a constituir.", "example": 47.62 }, "requestedAmount": { "type": "number", "format": "double", "description": "Valor solicitado à registradora para a UR, com duas casas (ENG-1653). Numa UR a constituir é o que ainda não virou onerado; 0.00 quando a cobrança não quer mais a UR. Igual para TAG e Núclea.", "example": 300.0 }, "status": { "type": "string", "description": "Situação do recebível dentro da cobrança. COMMITTED é a UR ativa (onerado acima de 0.00); TO_CONSTITUTE é a UR inativa que a registradora guarda com solicitado acima de 0.00 e onerado 0.00 (ENG-1653); INACTIVE é a UR que saiu da cobrança.", "enum": [ "COMMITTED", "TO_CONSTITUTE", "INACTIVE" ], "example": "COMMITTED" } } }, "CollectionReceivablesCursorPaginationV2Response": { "type": "object", "description": "Cursor pagination for collection receivables, backed by DynamoDB LastEvaluatedKey.", "required": [ "limit" ], "properties": { "cursor": { "type": "string", "description": "Opaque cursor used to load the current page." }, "limit": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "description": "Maximum number of receivables returned in the page.", "example": 30 }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page, omitted on the terminal page." }, "currentItem": { "type": "integer", "format": "int32", "description": "Legacy offset retained for backward-compatible callers using lastItem." }, "nextItem": { "type": "integer", "format": "int32", "description": "Legacy offset retained for backward-compatible callers using lastItem." }, "totalItems": { "type": "integer", "format": "int32", "description": "Total item count when the legacy offset compatibility path is used." } } }, "CollectionReceivablesV2Response": { "type": "object", "description": "Lista paginada dos recebíveis vinculados a uma cobrança.", "required": [ "collectionId", "receivables", "pagination" ], "properties": { "collectionId": { "type": "string", "format": "uuid", "description": "Identificador da cobrança.", "example": "11111111-1111-4111-8111-111111111111" }, "receivables": { "type": "array", "description": "Recebíveis materializados para a cobrança.", "items": { "$ref": "#/components/schemas/CollectionReceivableV2ResponseItem" } }, "pagination": { "$ref": "#/components/schemas/CollectionReceivablesCursorPaginationV2Response" } } }, "CollectionV2FinancialResult": { "type": "object", "description": "Campos aditivos de cobrança. Agregados de outros tipos não contêm resultado financeiro. Campo ausente em registros antigos equivale a ACTIVE.", "properties": { "status": { "type": "string", "description": "Estado registral; pode continuar REGISTERED após conclusão financeira." }, "operationResult": { "type": "string", "enum": [ "ACTIVE", "FINISHED" ] }, "operationResultAt": { "type": "string", "format": "date-time", "description": "Instante do recebimento de origem que cruzou o valor solicitado; imutável e omitido enquanto ACTIVE." }, "stage": { "type": "string", "enum": [ "CONSULTING_AGENDA", "CHECKING_ACQUIRERS", "OPENING_ACCOUNT", "SENT_TO_REGISTRAR", "REGISTERED" ], "description": "Stage of the collection before and during the registration (ENG-1405), derived from the status. The public API v2 keeps the codes and the order it had before ENG-1573 (a contract with external clients): CONSULTING_AGENDA (OPT_PENDING without a probe, with a FULL probe still without verdict, or, with the agenda closure of ENG-1574, waiting for the agenda of every kept pair); CHECKING_ACQUIRERS (OPT_PENDING with a PROBE probe, or a FULL one with its verdict waiting for the agenda); OPENING_ACCOUNT (REGISTRATION_PENDING without account); SENT_TO_REGISTRAR (REGISTRATION_PENDING with account); REGISTERED. Omitted in the other statuses. The panel stages of ENG-1573 (CHECKING_RELATIONSHIP before the agenda, WRITTEN_OFF) are never returned here." } } }, "CompanyV2": { "type": "object", "required": [ "companyId", "companyTaxId", "companyName", "status", "scheduleStatus", "createdAt" ], "properties": { "companyId": { "type": "string" }, "companyTaxId": { "type": "string" }, "companyName": { "type": "string" }, "nickname": { "type": "string", "nullable": true }, "status": { "type": "string" }, "scheduleStatus": { "type": "string", "enum": [ "INACTIVE", "ACTIVE", "PERFORMED", "NO_RELATIONSHIP_FOUND", "PENDING", "SENT" ] }, "scheduleStatusReasonCode": { "type": "string", "nullable": true }, "lastScheduleQueryAt": { "type": "string", "format": "date-time", "nullable": true }, "lastScheduleResultAt": { "type": "string", "format": "date-time", "nullable": true }, "queriedUnits": { "allOf": [ { "$ref": "#/components/schemas/ScheduleQueriedUnits" } ], "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "ContractFieldChange": { "type": "object", "required": [ "path", "valueType" ], "properties": { "path": { "type": "string" }, "valueType": { "type": "string", "enum": [ "DECIMAL", "STRING", "BOOLEAN", "DATE", "DATE_TIME", "JSON" ] }, "before": { "type": "string", "nullable": true }, "after": { "type": "string", "nullable": true } } }, "ContractHistoryChange": { "type": "object", "required": [ "changeId", "appliedAt", "changes", "provenance" ], "properties": { "changeId": { "type": "string" }, "appliedAt": { "type": "string", "format": "date-time" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ContractFieldChange" } }, "provenance": { "$ref": "#/components/schemas/ContractTraceabilityProvenance" } } }, "ContractHistoryResponse": { "type": "object", "required": [ "contractId", "companyTaxId", "historicalCompleteness", "limit", "changes" ], "properties": { "contractId": { "type": "string" }, "companyTaxId": { "type": "string" }, "historicalCompleteness": { "type": "string", "enum": [ "COMPLETE_FROM_CREATION", "FROM_BASELINE" ] }, "limit": { "type": "integer" }, "nextCursor": { "type": "string" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ContractHistoryChange" } } } }, "ContractRegistrarObservation": { "type": "object", "required": [ "observationId", "decision", "values", "provenance" ], "properties": { "observationId": { "type": "string" }, "decision": { "$ref": "#/components/schemas/TraceabilityObservationDecision" }, "values": { "type": "object", "additionalProperties": { "type": "string" } }, "provenance": { "$ref": "#/components/schemas/ContractTraceabilityProvenance" } } }, "ContractRegistrarObservationsResponse": { "type": "object", "required": [ "contractId", "companyTaxId", "historicalCompleteness", "limit", "observations" ], "properties": { "contractId": { "type": "string" }, "companyTaxId": { "type": "string" }, "historicalCompleteness": { "type": "string", "enum": [ "COMPLETE_FROM_CREATION", "FROM_BASELINE" ] }, "limit": { "type": "integer" }, "nextCursor": { "type": "string" }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/ContractRegistrarObservation" } } } }, "ContractTraceabilityProvenance": { "type": "object", "required": [ "schemaVersion", "aggregateType", "aggregateId", "originType", "originChannel", "actorType", "occurredAt", "receivedAt", "correlationId", "version", "historicalCompleteness" ], "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "aggregateType": { "type": "string", "enum": [ "CONTRACT" ] }, "aggregateId": { "type": "string" }, "originType": { "type": "string", "enum": [ "REGISTRAR", "CLIENT", "BACKOFFICE", "SYSTEM" ] }, "originChannel": { "type": "string", "enum": [ "TAG", "NUCLEA", "CONTROL_PANEL", "API_V2", "BACKOFFICE_API", "WORKER", "MIGRATION" ] }, "actorType": { "type": "string", "enum": [ "PROVIDER", "USER", "SERVICE" ] }, "actorId": { "type": "string" }, "actorRole": { "type": "string" }, "clientId": { "type": "string" }, "tenantId": { "type": "string", "description": "Canonical tenant associated with an API V2 service actor. Optional for historical provenance and actor types that predate this route-scoped requirement." }, "companyTaxId": { "type": "string" }, "registrar": { "type": "string", "enum": [ "TAG", "NUCLEA" ] }, "providerEventId": { "type": "string" }, "providerObjectId": { "type": "string" }, "providerVersion": { "type": "string" }, "providerSequence": { "type": "string" }, "orderBasis": { "type": "string", "enum": [ "PROVIDER_SEQUENCE", "PROVIDER_VERSION", "EFFECTIVE_AT", "RECEIVED_AT" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "appliedAt": { "type": "string", "format": "date-time" }, "correlationId": { "type": "string" }, "causationId": { "type": "string" }, "commandId": { "type": "string" }, "operationId": { "type": "string" }, "reasonCode": { "type": "string" }, "relatedObservationIds": { "type": "array", "maxItems": 20, "description": "Identificadores de observações imutáveis considerados em uma resolução de conflito do backoffice.", "items": { "type": "string" } }, "version": { "type": "integer", "format": "int64" }, "historicalCompleteness": { "type": "string", "enum": [ "COMPLETE_FROM_CREATION", "FROM_BASELINE" ] } } }, "ContractsRequestBodyErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "Corpo da solicitação inválido" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ContractsRequestBodyFieldError" } } } }, "ContractsRequestBodyFieldError": { "type": "object", "required": [ "fieldName", "code", "message" ], "properties": { "fieldName": { "type": "string", "description": "Caminho do campo JSON que falhou na leitura ou validação. Fica vazio quando o erro se refere ao corpo JSON inteiro.", "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" } } }, "HistoricalCompleteness": { "type": "string", "enum": [ "COMPLETE_FROM_CREATION", "FROM_BASELINE" ] }, "NotificationsRequestBodyErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "Corpo da solicitação inválido" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationsRequestBodyFieldError" } } } }, "NotificationsRequestBodyFieldError": { "type": "object", "required": [ "fieldName", "code", "message" ], "properties": { "fieldName": { "type": "string", "description": "Caminho do campo JSON que falhou na leitura ou validação. Fica vazio quando o erro se refere ao corpo JSON inteiro.", "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": "Código do erro OAuth.", "example": "invalid_request" }, "error_description": { "type": "string", "description": "Descrição do erro OAuth.", "example": "OAuth 2.0 Parameter: grant_type" } }, "description": "Resposta de erro OAuth 2.0." }, "OAuthRevokeRequest": { "type": "object", "required": [ "client_id", "client_secret", "token" ], "properties": { "client_id": { "type": "string", "description": "Identificador público do cliente OAuth fornecido pela Destrava.", "example": "preencher-com-client-id" }, "client_secret": { "type": "string", "description": "Segredo do cliente OAuth.", "example": "preencher-com-client-secret" }, "token": { "type": "string", "description": "Token de acesso retornado pelo endpoint de tokens OAuth.", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type_hint": { "type": "string", "description": "Indicação opcional do tipo de token OAuth. A API V2 aceita `access_token`.", "enum": [ "access_token" ], "example": "access_token" } }, "description": "Credenciais e token usados para revogar um token de acesso OAuth 2.0." }, "OAuthRevokeResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Status da revogação.", "enum": [ "REVOKED" ], "example": "REVOKED" }, "revokedToken": { "type": "string", "description": "Identificador mascarado do token revogado.", "example": "eyJh...abcd" } }, "description": "Resultado da revogação do token OAuth." }, "OAuthTokenRequest": { "type": "object", "required": [ "client_id", "client_secret", "grant_type" ], "properties": { "client_id": { "type": "string", "description": "Identificador público do cliente OAuth fornecido pela Destrava.", "example": "preencher-com-client-id" }, "client_secret": { "type": "string", "description": "Segredo do cliente OAuth. Não inclua esse valor no Git, em logs ou em ferramentas compartilhadas.", "example": "preencher-com-client-secret" }, "grant_type": { "type": "string", "description": "Tipo de concessão OAuth. Use `client_credentials` na API V2.", "enum": [ "client_credentials" ], "default": "client_credentials", "example": "client_credentials" }, "scope": { "type": "string", "description": "Lista opcional de escopos separados por espaços. Deixe em branco para usar os escopos cadastrados que continuam permitidos pela projeção atual `CLIENT_CONFIG` do cliente proprietário.", "example": "companies:read read:accounts read:accounts:balance" } }, "description": "Credenciais usadas para emitir um token de acesso OAuth 2.0 pelo fluxo de credenciais do cliente." }, "OAuthTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Token de acesso Bearer emitido.", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type": { "type": "string", "description": "Tipo do token.", "example": "Bearer" }, "expires_in": { "type": "integer", "format": "int32", "description": "Validade do token em segundos.", "example": 3600 }, "scope": { "type": "string", "description": "Escopos concedidos, separados por espaços.", "example": "read:companies:acquirers" } }, "description": "Resposta com token Bearer usada para autenticar chamadas protegidas da API V2." }, "PublicRefundAccount": { "type": "object", "additionalProperties": false, "required": [ "companyId", "version", "createdAt", "updatedAt", "account" ], "properties": { "companyId": { "type": "string", "minLength": 1, "maxLength": 256 }, "version": { "type": "integer", "format": "int64", "minimum": 0, "description": "Zero identifies a legacy-only record; canonical revisions start at one." }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "account": { "type": "object", "additionalProperties": false, "required": [ "holderTaxIdMasked", "holderName", "bankName", "ispb", "branch", "accountMasked", "accountDigit" ], "properties": { "holderTaxIdMasked": { "type": "string", "pattern": "^\\*+[A-Z0-9]{4}$" }, "holderName": { "type": "string", "minLength": 1, "maxLength": 160 }, "bankName": { "type": "string", "minLength": 1, "maxLength": 120 }, "ispb": { "type": "string", "pattern": "^\\d{8}$" }, "branch": { "type": "string", "pattern": "^\\d{1,5}$" }, "accountMasked": { "type": "string", "pattern": "^\\*+(?:\\d{2})?$" }, "accountDigit": { "type": "string", "pattern": "^[A-Z0-9]$" } } } }, "example": { "companyId": "company-123", "version": 1, "createdAt": "2026-09-11T12:00:00Z", "updatedAt": "2026-09-11T12:00:00Z", "account": { "holderTaxIdMasked": "**********0143", "holderName": "Empresa Exemplo", "bankName": "Banco Exemplo", "ispb": "12345678", "branch": "0001", "accountMasked": "*****67", "accountDigit": "8" } } }, "PublicRefundAccountReplace": { "type": "object", "additionalProperties": false, "description": "Complete unmasked replacement input. A masked GET response is not valid command input.", "required": [ "holderTaxId", "holderName", "bankName", "ispb", "branch", "account", "accountDigit" ], "properties": { "holderTaxId": { "type": "string", "pattern": "^(?:[0-9]{11}|[A-Z0-9]{12}[0-9]{2})$", "description": "Official CPF or numeric/alphanumeric CNPJ of the selected Company, with valid check digits." }, "holderName": { "type": "string", "minLength": 1, "maxLength": 160 }, "bankName": { "type": "string", "minLength": 1, "maxLength": 120 }, "ispb": { "type": "string", "pattern": "^\\d{8}$" }, "branch": { "type": "string", "pattern": "^\\d{1,5}$" }, "account": { "type": "string", "pattern": "^\\d{1,20}$" }, "accountDigit": { "type": "string", "pattern": "^[A-Z0-9]$" } }, "example": { "holderTaxId": "43151964000143", "holderName": "Empresa Exemplo", "bankName": "Banco Exemplo", "ispb": "12345678", "branch": "0001", "account": "1234567", "accountDigit": "8" } }, "ReadMe_AcquirerFinancierMetricsResponse": { "type": "object", "properties": { "taxId": { "type": "string", "description": "CNPJ do adquirente", "example": "01027058000191" }, "name": { "type": "string", "description": "Nome do adquirente", "example": "Adquirente Exemplo" }, "totalAmount": { "type": "number", "description": "Valor total considerado para o adquirente", "example": 10000 }, "priorities": { "type": "array", "description": "Prioridades por financiador", "items": { "$ref": "#/components/schemas/ReadMe_PriorityInfoFinancierResponse" } } }, "description": "Prioridades de oneração de um adquirente" }, "ReadMe_AcquirersResponse": { "type": "object", "properties": { "companyId": { "type": "string", "description": "ID da empresa", "example": "fe2cc560-036c-44cd-90e8-294d5a74cebc" }, "updatedAt": { "type": "string", "nullable": true, "description": "Data da última atualização dos adquirentes adicionais ativos. Fica nula quando a empresa não possui adicionais", "example": "2025-06-26T12:34:56.000Z" }, "acquirers": { "type": "array", "description": "Lista de adquirentes adicionais configurados", "items": { "$ref": "#/components/schemas/ReadMe_AcquirersResponse.AcquirerDetail" } }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Lista de adquirentes adicionais de uma empresa. Os adquirentes do pacote padrão não aparecem nesta resposta" }, "ReadMe_AcquirersResponse.AcquirerDetail": { "type": "object", "properties": { "taxId": { "type": "string", "description": "CNPJ do adquirente", "example": "43151964000143" }, "name": { "type": "string", "description": "Nome do adquirente", "nullable": true, "example": "ADQUIRENTE TESTE S.A." }, "nickname": { "type": "string", "description": "Apelido do adquirente", "nullable": true, "example": "Adquirente Teste" } }, "description": "Dados de um adquirente adicional" }, "ReadMe_ApiLink": { "type": "object", "description": "Link de navegação da API com o próximo passo sugerido", "properties": { "rel": { "type": "string", "description": "Relação do link com o recurso atual", "example": "self" }, "method": { "type": "string", "description": "Método HTTP do link", "example": "GET" }, "href": { "type": "string", "description": "Caminho relativo do recurso", "example": "/api/v2/companies" }, "description": { "type": "string", "description": "Explicação em português do que este link permite fazer", "example": "Cadastre a empresa para o cliente" } } }, "ReadMe_AutomaticRefundResponse": { "type": "object", "properties": { "companyTaxId": { "type": "string", "description": "CNPJ da empresa", "example": "43151964000143" }, "enabled": { "type": "boolean", "description": "Estado atual da devolução automática", "example": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data/hora da atualização", "example": "2025-07-01T17:45:00Z" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resposta de habilitação/desabilitação de devolução automática" }, "ReadMe_CashAdvanceAmountsResponse": { "type": "object", "description": "Valores monetários do contrato de antecipação", "properties": { "requestedAmount": { "type": "number", "description": "Valor solicitado", "format": "double", "example": 1500.0 }, "effectivelyEncumberedAmount": { "type": "number", "description": "Valor efetivamente onerado após confirmação do registrador", "format": "double", "nullable": true, "example": 1450.0 } } }, "ReadMe_CashAdvanceDetailBankingAddressResponse": { "type": "object", "description": "Dados bancários vinculados ao contrato. Enquanto a conta não foi provisionada, `state=PROCESSING` e os demais campos vêm `null`.", "properties": { "state": { "type": "string", "description": "Estado da provisão da conta de liquidação", "enum": [ "PROCESSING", "PROVISIONED" ], "example": "PROVISIONED" }, "taxId": { "type": "string", "description": "Documento vinculado à conta", "nullable": true, "example": "43151964000143" }, "ispb": { "type": "string", "description": "ISPB do banco", "nullable": true, "example": "13935893" }, "branch": { "type": "string", "description": "Agência", "nullable": true, "example": "0001" }, "account": { "type": "string", "description": "Conta com dígito", "nullable": true, "example": "12345-6" }, "bankName": { "type": "string", "description": "Nome do banco", "nullable": true, "example": "Banco Teste" } } }, "ReadMe_CashAdvanceDetailCancellationResponse": { "type": "object", "description": "Dados de cancelamento do contrato", "properties": { "contractRegisterId": { "type": "string", "description": "Identificador do contrato no registrador", "nullable": true, "example": "REG-123" }, "cancelledAt": { "type": "string", "format": "date-time", "description": "Data/hora de cancelamento em UTC", "nullable": true, "example": "2036-04-23T18:45:00Z" }, "receipt": { "type": "string", "description": "Comprovante de baixa do gravame", "nullable": true, "example": "receipt-123" } } }, "ReadMe_CashAdvanceDetailCompanyResponse": { "type": "object", "description": "Dados da empresa vinculada ao contrato", "properties": { "companyTaxId": { "type": "string", "description": "CNPJ/CPF da empresa", "example": "43151964000143" }, "companyName": { "type": "string", "description": "Nome da empresa", "example": "Empresa Teste" } } }, "ReadMe_CashAdvanceDetailResponse": { "type": "object", "description": "Detalhes de um contrato de antecipação. Recebíveis vinculados são consultados em /cash-advances/{id}/receivables", "properties": { "cashAdvanceId": { "type": "string", "format": "uuid", "description": "Identificador do contrato", "example": "11111111-1111-4111-8111-111111111111" }, "externalContractId": { "type": "string", "description": "Identificador externo do contrato", "example": "contract-123" }, "status": { "type": "string", "description": "Status do contrato", "enum": [ "CREATED", "CREATION_PENDING", "CREATION_FAILED", "DELETION_PENDING", "DELETION_FAILED", "DELETED" ], "example": "CREATED" }, "company": { "$ref": "#/components/schemas/ReadMe_CashAdvanceDetailCompanyResponse" }, "financierTaxId": { "type": "string", "description": "CNPJ do financiador", "example": "12345678000190" }, "amounts": { "$ref": "#/components/schemas/ReadMe_CashAdvanceAmountsResponse" }, "bankingAddress": { "$ref": "#/components/schemas/ReadMe_CashAdvanceDetailBankingAddressResponse" }, "firstSettlementDate": { "type": "string", "format": "date", "description": "Data inicial de liquidação dos recebíveis", "nullable": true, "example": "2036-04-20" }, "lastSettlementDate": { "type": "string", "format": "date", "description": "Data final de liquidação dos recebíveis", "nullable": true, "example": "2036-04-25" }, "createdAt": { "type": "string", "format": "date-time", "description": "Data/hora de criação em UTC", "nullable": true, "example": "2036-04-23T18:45:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data/hora da última atualização em UTC", "nullable": true, "example": "2036-04-23T19:45:00Z" }, "cancellation": { "$ref": "#/components/schemas/ReadMe_CashAdvanceDetailCancellationResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } } }, "ReadMe_CashAdvanceListResponse": { "type": "object", "description": "Lista paginada de contratos de antecipação", "properties": { "cashAdvances": { "type": "array", "items": { "$ref": "#/components/schemas/ReadMe_CashAdvanceResponse" } }, "pagination": { "$ref": "#/components/schemas/ReadMe_CashAdvancePaginationResponse" }, "totals": { "$ref": "#/components/schemas/ReadMe_CashAdvanceTotalsResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } } }, "ReadMe_CashAdvancePaginationResponse": { "type": "object", "description": "Metadados de paginação baseada em cursor", "properties": { "currentItem": { "type": "string", "description": "Cursor da página atual (id do último item da página anterior)", "nullable": true }, "limit": { "type": "integer", "format": "int32", "description": "Número de itens por página", "example": 30 }, "nextItem": { "type": "string", "description": "Cursor da próxima página, ou null se for a última", "nullable": true }, "totalItems": { "type": "integer", "format": "int64", "description": "Total de itens disponíveis para os filtros informados", "example": 150 } } }, "ReadMe_CashAdvanceReceivableDetailResponse": { "type": "object", "description": "Detalhes de um recebível vinculado ao contrato de antecipação", "properties": { "receivableId": { "type": "string", "description": "Identificador do recebível vinculado ao contrato", "example": "1" }, "acquirerTaxId": { "type": "string", "description": "CNPJ do adquirente", "example": "01027058000191" }, "paymentScheme": { "type": "string", "description": "Código do arranjo de pagamento", "example": "MCC" }, "settlementDate": { "type": "string", "format": "date", "description": "Data de liquidação", "example": "2036-08-15" }, "requestedAmount": { "type": "number", "format": "double", "description": "Valor solicitado para o recebível dentro do contrato", "example": 1500.0 }, "effectivelyEncumberedAmount": { "type": "number", "format": "double", "description": "Valor efetivamente onerado no recebível após confirmação do registrador. Vem nulo até a confirmação ser recebida.", "nullable": true, "example": 1450.0 }, "performedAmount": { "type": "number", "format": "double", "description": "Valor performado do recebível conforme registrado. Vem nulo quando o recebível não está mais na agenda.", "nullable": true, "example": 1500.0 } } }, "ReadMe_CashAdvanceReceivablesResponse": { "type": "object", "description": "Lista paginada dos recebíveis vinculados ao contrato de antecipação", "properties": { "cashAdvanceId": { "type": "string", "format": "uuid", "description": "Identificador do contrato" }, "receivables": { "type": "array", "items": { "$ref": "#/components/schemas/ReadMe_CashAdvanceReceivableDetailResponse" } }, "pagination": { "$ref": "#/components/schemas/ReadMe_CashAdvancePaginationResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } } }, "ReadMe_CashAdvanceResponse": { "type": "object", "description": "Dados de um contrato de antecipação", "properties": { "cashAdvanceId": { "type": "string", "format": "uuid", "description": "Identificador do contrato", "example": "11111111-1111-4111-8111-111111111111" }, "externalContractId": { "type": "string", "description": "Identificador externo do contrato", "example": "contract-123" }, "status": { "type": "string", "description": "Status do contrato", "enum": [ "CREATED", "CREATION_PENDING", "CREATION_FAILED", "DELETION_PENDING", "DELETION_FAILED", "DELETED" ], "example": "CREATED" }, "companyTaxId": { "type": "string", "description": "CNPJ/CPF da empresa", "nullable": true, "example": "43151964000143" }, "companyName": { "type": "string", "description": "Nome da empresa", "nullable": true, "example": "Empresa Teste" }, "financierTaxId": { "type": "string", "description": "CNPJ do financiador", "example": "12345678000190" }, "amounts": { "$ref": "#/components/schemas/ReadMe_CashAdvanceAmountsResponse" }, "firstSettlementDate": { "type": "string", "format": "date", "description": "Data inicial de liquidação dos recebíveis", "nullable": true, "example": "2036-04-01" }, "lastSettlementDate": { "type": "string", "format": "date", "description": "Data final de liquidação dos recebíveis", "nullable": true, "example": "2036-04-30" }, "createdAt": { "type": "string", "format": "date-time", "description": "Data/hora de criação em UTC", "nullable": true, "example": "2036-04-23T18:45:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data/hora da última atualização em UTC", "nullable": true, "example": "2036-04-23T19:45:00Z" } } }, "ReadMe_CashAdvanceTotalsResponse": { "type": "object", "description": "Totalizadores monetários do filtro", "properties": { "requestedAmount": { "type": "number", "description": "Valor solicitado total", "format": "double", "example": 15000.0 }, "effectivelyEncumberedAmount": { "type": "number", "description": "Valor efetivamente onerado total", "format": "double", "nullable": true, "example": 14500.0 } } }, "ReadMe_CollateralizedCreditReceivablesResponse": { "type": "object", "properties": { "creditId": { "type": "string", "format": "uuid", "description": "Identificador do contrato", "example": "11111111-1111-4111-8111-111111111111" }, "receivables": { "type": "array", "description": "Lista de recebíveis", "items": { "type": "object", "properties": { "receivableId": { "type": "string", "description": "Identificador do recebível", "example": "10" }, "acquirerTaxId": { "type": "string", "description": "CNPJ do adquirente", "example": "01027058000191" }, "paymentScheme": { "type": "string", "description": "Código do arranjo de pagamento", "example": "MCC" }, "settlementDate": { "type": "string", "format": "date", "description": "Data de liquidação", "example": "2025-08-15" }, "requestedAmount": { "type": "number", "format": "double", "description": "Valor solicitado para o recebível dentro do contrato", "example": 1500.0 }, "effectivelyEncumberedAmount": { "type": "number", "format": "double", "description": "Valor efetivamente onerado no recebível após confirmação do registrador. Vem nulo até a confirmação ser recebida.", "nullable": true, "example": 1450.0 } }, "description": "Detalhes de um recebível vinculado ao contrato de crédito com garantia", "title": "CollateralizedCreditReceivableDetailResponse" } }, "pagination": { "type": "object", "properties": { "currentItem": { "type": "string", "description": "ID do item atual (primeiro da página)", "example": "10" }, "limit": { "type": "integer", "description": "Número de itens por página", "format": "int32", "example": 30 }, "nextItem": { "type": "string", "description": "ID do proximo item (para paginação)", "nullable": true, "example": "9" }, "totalItems": { "type": "integer", "description": "Total de itens disponíveis", "format": "int64", "example": 150 } }, "description": "Metadados de paginação baseada em cursor", "title": "PaginationResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Recebíveis de um contrato de crédito com garantia" }, "ReadMe_CollateralizedCreditSummaryResponse": { "type": "object", "properties": { "totalContracts": { "type": "integer", "description": "Total de contratos no recorte", "format": "int32", "example": 55 }, "requestedAmount": { "type": "number", "description": "Valor solicitado total", "format": "double", "example": 800000.0 }, "effectivelyEncumberedAmount": { "type": "number", "description": "Valor efetivamente onerado total", "format": "double", "nullable": true, "example": 600000.0 }, "statuses": { "type": "array", "description": "Totais agrupados por status", "items": { "$ref": "#/components/schemas/ReadMe_CollateralizedCreditSummaryStatusResponse" } }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resumo consolidado de contratos de crédito com garantia", "title": "CollateralizedCreditSummaryResponse" }, "ReadMe_CollateralizedCreditSummaryStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Status do contrato", "enum": [ "CREATED", "CREATION_PENDING", "CREATION_FAILED", "DELETION_PENDING", "DELETION_FAILED", "DELETED" ], "example": "CREATED" }, "contracts": { "type": "integer", "description": "Quantidade de contratos no status", "format": "int32", "example": 20 }, "requestedAmount": { "type": "number", "description": "Valor solicitado", "format": "double", "example": 2400.0 }, "effectivelyEncumberedAmount": { "type": "number", "description": "Valor efetivamente onerado", "format": "double", "nullable": true, "example": 2100.0 } }, "description": "Totais de contratos de crédito com garantia por status", "title": "CollateralizedCreditSummaryStatusResponse" }, "ReadMe_CollectionSummaryResponse": { "type": "object", "properties": { "totalContracts": { "type": "integer", "description": "Total de contratos no recorte", "format": "int32", "example": 55 }, "requestedAmount": { "type": "number", "description": "Valor solicitado total", "format": "double", "example": 800000.0 }, "statuses": { "type": "array", "description": "Totais agrupados por status", "items": { "$ref": "#/components/schemas/ReadMe_CollectionSummaryStatusResponse" } }, "strategies": { "type": "array", "description": "Totais agrupados por estratégia de cobrança", "items": { "$ref": "#/components/schemas/ReadMe_CollectionSummaryStrategyResponse" } }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resumo consolidado de contratos de cobrança" }, "ReadMe_CollectionSummaryStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Status do contrato", "enum": [ "CREATED", "CREATION_PENDING", "CREATION_FAILED", "CREATION_FAILED_NO_RELATIONS", "DELETION_PENDING", "DELETION_FAILED", "DELETED" ], "example": "CREATED" }, "contracts": { "type": "integer", "description": "Quantidade de contratos no status", "format": "int32", "example": 20 }, "requestedAmount": { "type": "number", "description": "Valor solicitado", "format": "double", "example": 2400.0 } }, "description": "Totais de contratos de cobrança por status" }, "ReadMe_CollectionSummaryStrategyResponse": { "type": "object", "properties": { "strategy": { "type": "string", "description": "Estratégia de cobrança. Pode ser nula para contratos sem estratégia registrada.", "nullable": true, "enum": [ "TURBO", "SELECTIVE", "SELECTIVE_WITH_DEBIT", "SNIPER", "DYNAMIC" ], "example": "TURBO" }, "contracts": { "type": "integer", "description": "Quantidade de contratos na estratégia", "format": "int32", "example": 20 }, "requestedAmount": { "type": "number", "description": "Valor solicitado", "format": "double", "example": 2400.0 } }, "description": "Totais de contratos de cobrança por estratégia" }, "ReadMe_CompanyCreatedItem": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identificador da empresa criada", "example": "64091b0a-529d-48fc-9802-7b1600a07c8b" }, "companyTaxId": { "type": "string", "description": "CPF ou CNPJ da empresa", "example": "12345678000195" }, "status": { "type": "string", "description": "Status do processamento do item", "example": "CREATED" }, "error": { "type": "string", "nullable": true, "description": "Mensagem de erro quando o item falha", "example": "Empresa já cadastrada" } }, "description": "Resultado individual da criação de empresa" }, "ReadMe_CompanyGroupResponse": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo econômico", "example": "90c6c8a2-3a14-4600-a295-9cda95640fba" }, "groupName": { "type": "string", "description": "Nome do grupo", "example": "grupo-econômico-001" }, "externalGroupId": { "type": "string", "description": "ID externo do grupo", "example": "group-id-001" }, "createdAt": { "type": "string", "format": "date-time", "description": "Data de criação", "example": "2025-07-01T17:45:00Z" }, "associatedCompanies": { "type": "array", "description": "Empresas associadas ao grupo", "items": { "$ref": "#/components/schemas/ReadMe_CompanyGroupResponse.AssociatedCompany" } }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Dados de um grupo econômico" }, "ReadMe_CompanyGroupResponse.AssociatedCompany": { "type": "object", "properties": { "companyId": { "type": "string", "description": "ID da empresa", "example": "90c6c8a2-3a14-4600-a295-9cda95640fba" } }, "description": "Referência a uma empresa associada" }, "ReadMe_CompanyV2Response": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid", "description": "Identificador da empresa", "example": "64091b0a-529d-48fc-9802-7b1600a07c8b" }, "companyTaxId": { "type": "string", "description": "CPF ou CNPJ da empresa", "example": "12345678000195" }, "companyName": { "type": "string", "description": "Nome da empresa", "example": "Empresa Teste v2" }, "status": { "type": "string", "description": "Status da empresa", "example": "ACTIVE", "enum": [ "ACTIVE", "INACTIVE" ] }, "scheduleStatus": { "type": "string", "description": "Status da agenda da empresa", "example": "PENDING", "enum": [ "ACTIVE", "INACTIVE", "PERFORMED", "PENDING", "SENT" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Data de criação em UTC", "example": "2026-04-17T12:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de atualização em UTC", "example": "2026-04-17T13:45:00Z" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Empresa retornada pela API v2" }, "ReadMe_ContractEventsResponse": { "type": "object", "properties": { "contractId": { "type": "string", "description": "Identificador do contrato", "example": "ct-a1b2c3d4" }, "events": { "type": "array", "description": "Lista de eventos do contrato", "items": { "$ref": "#/components/schemas/ReadMe_ContractEventsResponse.ContractEvent" } }, "pagination": { "$ref": "#/components/schemas/ReadMe_PaginationResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Lista de eventos de um contrato" }, "ReadMe_ContractEventsResponse.ContractEvent": { "type": "object", "properties": { "eventId": { "type": "string", "description": "Identificador do evento", "example": "evt-001" }, "eventType": { "type": "string", "description": "Tipo do evento", "example": "CONTRACT_CREATED" }, "description": { "type": "string", "description": "Descrição do evento", "example": "Contrato criado com sucesso" }, "createdAt": { "type": "string", "format": "date-time", "description": "Data/hora do evento", "example": "2025-07-01T17:45:00Z" } }, "description": "Evento de um contrato" }, "ReadMe_CreateCashAdvanceResponse": { "type": "object", "description": "Resposta de aceite da criação do contrato de antecipação", "properties": { "cashAdvanceId": { "type": "string", "format": "uuid", "description": "Identificador do contrato", "example": "11111111-1111-4111-8111-111111111111" }, "externalContractId": { "type": "string", "description": "Identificador externo do contrato informado no body", "example": "contract-123" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } } }, "ReadMe_CreateCollectionByStrategyResponse": { "type": "object", "properties": { "externalContractId": { "type": "string", "description": "ID externo do contrato de cobrança", "example": "contract-123" }, "collectionId": { "type": "string", "format": "uuid", "description": "Identificador do contrato de cobrança criado para acompanhar o processamento.", "example": "fe2cc560-036c-44cd-90e8-294d5a74cebc" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resposta para criação assíncrona de cobrança por estratégia" }, "ReadMe_CreateCompaniesResponse": { "type": "object", "properties": { "companyGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identificador do grupo econômico associado", "example": "90c6c8a2-3a14-4600-a295-9cda95640fba" }, "companies": { "type": "array", "description": "Resultados por empresa processada", "items": { "$ref": "#/components/schemas/ReadMe_CompanyCreatedItem" } }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resultado da criação de empresas" }, "ReadMe_CustomErrorResponse": { "type": "object", "properties": { "timestamp": { "type": "string", "description": "Data/hora do erro em UTC", "example": "2026-04-17T13:00:00Z" }, "error": { "type": "string", "description": "Mensagem do erro", "example": "Requisição inválida" }, "links": { "type": "array", "description": "Ações sugeridas para resolver o erro. Presente apenas quando há ação corretiva", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resposta de erro" }, "ReadMe_DeleteCashAdvanceResponse": { "type": "object", "description": "Resposta de aceite da baixa do contrato de antecipação", "properties": { "cashAdvanceId": { "type": "string", "format": "uuid", "description": "Identificador do contrato em baixa", "example": "11111111-1111-4111-8111-111111111111" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } } }, "ReadMe_FieldMessageResponse": { "type": "object", "properties": { "fieldName": { "type": "string", "description": "Nome do campo inválido", "example": "companies[0].companyTaxId" }, "message": { "type": "string", "description": "Mensagem de validação", "example": "CPF ou CNPJ da empresa deve ser válido" } }, "description": "Mensagem de validação por campo" }, "ReadMe_GroupMembersResponse": { "type": "object", "properties": { "groupId": { "type": "string", "description": "ID do grupo econômico", "example": "90c6c8a2-3a14-4600-a295-9cda95640fba" }, "companies": { "type": "array", "description": "Empresas associadas/removidas", "items": { "$ref": "#/components/schemas/ReadMe_CompanyGroupResponse.AssociatedCompany" } }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resposta de associação/remocao de empresas em um grupo" }, "ReadMe_PaginationResponse": { "type": "object", "properties": { "currentItem": { "type": "string", "description": "ID do item atual (primeiro da página)", "example": "fe2cc560-036c-44cd-90e8-294d5a74cebc" }, "limit": { "type": "integer", "description": "Número de itens por página", "format": "int32", "example": 30 }, "nextItem": { "type": "string", "description": "ID do próximo item (cursor para a próxima página)", "nullable": true, "example": "22222222-2222-4222-8222-222222222222" }, "totalItems": { "type": "integer", "description": "Total de itens disponíveis", "format": "int64", "example": 150 } }, "description": "Metadados de paginação baseada em cursor" }, "ReadMe_PaymentSchemesResponse": { "type": "object", "properties": { "companyId": { "type": "string", "description": "ID da empresa", "example": "fe2cc560-036c-44cd-90e8-294d5a74cebc" }, "updatedAt": { "type": "string", "description": "Data da última atualização", "example": "2025-06-26T12:34:56.000Z" }, "paymentSchemes": { "type": "array", "description": "Lista de arranjos de pagamento ativos da empresa", "items": { "$ref": "#/components/schemas/ReadMe_PaymentSchemesResponse.PaymentSchemeDetail" } }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Lista de arranjos de pagamento ativos de uma empresa" }, "ReadMe_PaymentSchemesResponse.PaymentSchemeDetail": { "type": "object", "properties": { "code": { "type": "string", "description": "Código do arranjo", "example": "MCC" }, "name": { "type": "string", "description": "Nome do arranjo", "example": "Mastercard Cartão de Crédito" }, "type": { "type": "string", "description": "Tipo do arranjo", "example": "CREDIT" } }, "description": "Dados de um arranjo de pagamento" }, "ReadMe_PriorityInfoFinancierResponse": { "type": "object", "properties": { "financierTaxId": { "type": "string", "description": "CNPJ do financiador", "example": "12345678000190" }, "financierName": { "type": "string", "description": "Nome do financiador", "example": "Financiador Exemplo" }, "priority": { "type": "string", "description": "Prioridade calculada", "example": "1" }, "amount": { "type": "number", "description": "Valor solicitado pelo financiador", "example": 1500 }, "encumbranceType": { "type": "string", "description": "Tipo de oneração", "enum": [ "FIXED", "PERCENTAGE" ], "example": "FIXED" } }, "description": "Prioridade de um financiador" }, "ReadMe_PriorityMetricsResponse": { "type": "object", "properties": { "acquirers": { "type": "array", "description": "Lista de adquirentes com prioridades por financiador", "items": { "$ref": "#/components/schemas/ReadMe_AcquirerFinancierMetricsResponse" } }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Prioridades de oneração por adquirente e financiador" }, "ReadMe_ValidationErrorResponse": { "type": "object", "properties": { "timestamp": { "type": "string", "description": "Data/hora do erro em UTC", "example": "2026-04-17T13:00:00Z" }, "message": { "type": "string", "description": "Mensagem principal do erro", "example": "Dados inválidos" }, "errors": { "type": "array", "description": "Erros de validação por campo", "items": { "$ref": "#/components/schemas/ReadMe_FieldMessageResponse" } } }, "description": "Resposta de validação" }, "ReceivableCanonicalIdentity": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "ONLINE", "BATCH" ], "description": "Origin of the accepted snapshot; omitted for legacy observations without a recorded origin." }, "provider": { "type": "string", "enum": [ "TAG", "NUCLEA" ], "description": "Registrar of the accepted snapshot." }, "asOf": { "type": "string", "format": "date-time", "description": "Reference time of the accepted snapshot, never the retry processing time." }, "registeredAmount": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "receivableKey": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Canonical tuple hash. Legacy uniqueKey and receivableId remain valid during migration." }, "situation": { "$ref": "#/components/schemas/ReceivableSituation" } } }, "ReceivableDecimalAmount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "Exact non-negative reais with two decimals." }, "ReceivableEncumbranceBreakdown": { "type": "object", "description": "ENG-1235 client split of the provider committed total of the unit, computed on read with the financiers frozen on the caller's ACTIVE agenda version (docs/contracts/client-encumbrance-attribution.md). AVAILABLE carries encumberedByClient (\"comprometido nosso\": effects held by one of the client's financiers; Núclea totals: atInstitution when the consulting institution is one of them) and encumberedByOthers, which add up to encumberedTotal. UNAVAILABLE (a photograph taken before the registry queue, or a version consolidated before the frozen financier list) keeps both null, never zero. Provider totals are retained, including zero. ENG-1246: on the session collateral read the split and encumberedTotal are on the base of the unit (the canonical performedAmount, or registered + ceded) whenever the registry queue is known (TAG, or Núclea's canonical queue, ENG-1313), so they add up and a cession counts by its holder; the external schedule v2 keeps the split on the registered value and the registry encumberedTotal.", "required": [ "encumbranceBreakdownStatus", "encumberedTotal", "encumberedByClient", "encumberedByOthers" ], "properties": { "encumbranceBreakdownStatus": { "type": "string", "enum": [ "AVAILABLE", "UNAVAILABLE" ] }, "encumberedTotal": { "$ref": "#/components/schemas/ReceivableDecimalAmount" }, "encumberedByClient": { "type": "string", "nullable": true, "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "Committed on the unit by the client's financiers; null while encumbranceBreakdownStatus is UNAVAILABLE." }, "encumberedByOthers": { "type": "string", "nullable": true, "pattern": "^[0-9]+\\.[0-9]{2}$", "description": "Committed on the unit by other institutions; null while encumbranceBreakdownStatus is UNAVAILABLE." } } }, "ReceivableEncumbrancesResponse": { "type": "object", "required": [ "companyTaxId", "encumbrances", "pagination" ], "properties": { "companyTaxId": { "type": "string" }, "encumbrances": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "additionalProperties": true }, "agendaVersion": { "$ref": "#/components/schemas/AgendaVersionMetadata" } } }, "ReceivableFieldChange": { "type": "object", "required": [ "path", "valueType" ], "properties": { "path": { "type": "string" }, "valueType": { "type": "string", "enum": [ "DECIMAL", "STRING", "BOOLEAN", "DATE", "DATE_TIME", "JSON" ] }, "before": { "type": "string", "nullable": true }, "after": { "type": "string", "nullable": true } } }, "ReceivableHistoryChange": { "type": "object", "required": [ "changeId", "appliedAt", "changes", "provenance" ], "properties": { "changeId": { "type": "string" }, "appliedAt": { "type": "string", "format": "date-time" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivableFieldChange" } }, "provenance": { "$ref": "#/components/schemas/ReceivableTraceabilityProvenance" } } }, "ReceivableHistoryResponse": { "type": "object", "required": [ "receivableId", "companyTaxId", "historicalCompleteness", "limit", "changes" ], "properties": { "receivableId": { "type": "string" }, "companyTaxId": { "type": "string" }, "historicalCompleteness": { "$ref": "#/components/schemas/HistoricalCompleteness" }, "limit": { "type": "integer" }, "nextCursor": { "type": "string" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivableHistoryChange" } } } }, "ReceivableRegistrarObservation": { "type": "object", "required": [ "observationId", "decision", "values", "provenance" ], "properties": { "observationId": { "type": "string" }, "decision": { "type": "string", "enum": [ "APPLIED", "NO_CHANGE", "IGNORED_DUPLICATE", "IGNORED_STALE", "CONFLICT", "REJECTED_INVALID" ] }, "values": { "type": "object", "additionalProperties": { "type": "string" } }, "provenance": { "$ref": "#/components/schemas/ReceivableTraceabilityProvenance" } } }, "ReceivableRegistrarObservationsResponse": { "type": "object", "required": [ "receivableId", "companyTaxId", "historicalCompleteness", "limit", "observations" ], "properties": { "receivableId": { "type": "string" }, "companyTaxId": { "type": "string" }, "historicalCompleteness": { "$ref": "#/components/schemas/HistoricalCompleteness" }, "limit": { "type": "integer" }, "nextCursor": { "type": "string" }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivableRegistrarObservation" } } } }, "ReceivableScheduleMetadata": { "type": "object", "required": [ "status", "scopes" ], "properties": { "status": { "type": "string", "enum": [ "CURRENT", "PARTIAL", "EMPTY", "NO_ACTIVE_RELATIONSHIP", "STALE", "NOT_QUERIED" ] }, "lastSuccessfulAt": { "type": "string", "format": "date-time" }, "lastAttemptAt": { "type": "string", "format": "date-time" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivableScheduleScopeMetadata" } } } }, "ReceivableScheduleResponse": { "type": "object", "required": [ "receivables", "pagination", "totals", "scheduleMetadata" ], "properties": { "receivables": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ReceivableCanonicalIdentity" }, { "$ref": "#/components/schemas/ReceivableEncumbranceBreakdown" }, { "type": "object", "properties": { "paymentSchemeCode": { "type": "string", "description": "Canonical payment scheme code; equals the retained paymentScheme alias." }, "encumberedAmountByClient": { "type": "string", "nullable": true, "deprecated": true, "description": "Legacy alias of encumberedByClient. Null when client breakdown is unavailable." }, "encumberedAmountByOthers": { "type": "string", "nullable": true, "deprecated": true, "description": "Legacy alias of encumberedByOthers. Null when client breakdown is unavailable." }, "riskStatus": { "type": "string", "enum": [ "AVAILABLE", "HIGH_RISK" ], "description": "ENG-1313 the risk the calling client sees, by the single rule on its split of the registry queue, the same as the Agenda's: another holder 1st in the queue is HIGH_RISK; the client's financier 1st, or no effect, is AVAILABLE. `situation` is derived from it. The risk engine's decision is used only where the split is unknown (a photograph without evidence, a version without the frozen financiers), and the field is omitted then if the engine never evaluated the UR. A UR the engine never evaluated but whose split is known now answers a status; before ENG-1313 the field was always the engine's. A contract change for integrators. The split, encumberedTotal and freeAmount of the same item stay on the registry reading (ENG-1246), so one item mixes the two." }, "riskEvaluatedAt": { "type": "string", "format": "date-time", "description": "The engine's evaluation time or, when it has none, the as-of of the photograph; omitted when there is neither, even with `riskStatus` set." }, "riskBrokenRules": { "type": "string", "description": "`Q1` when the single rule decides HIGH_RISK (omitted when it decides AVAILABLE); the engine's rules (for example `Z8`, several joined by `_`) only when the split is unknown." } }, "additionalProperties": true } ] } }, "pagination": { "type": "object", "additionalProperties": true }, "totals": { "type": "object", "additionalProperties": true }, "scheduleMetadata": { "$ref": "#/components/schemas/ReceivableScheduleMetadata" }, "agendaVersion": { "$ref": "#/components/schemas/AgendaVersionMetadata" } } }, "ReceivableScheduleScopeMetadata": { "type": "object", "required": [ "acquirerTaxId", "paymentScheme", "snapshotId", "resultStatus", "asOf", "stale" ], "properties": { "acquirerTaxId": { "type": "string" }, "paymentScheme": { "type": "string" }, "snapshotId": { "type": "string" }, "resultStatus": { "type": "string", "enum": [ "DATA", "EMPTY", "NO_ACTIVE_RELATIONSHIP", "UNSUCCESSFUL", "FAILED" ] }, "asOf": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" } } }, "ReceivableSituation": { "type": "string", "enum": [ "AVAILABLE", "HIGH_RISK", "UNAVAILABLE", "SETTLING", "SETTLED" ], "description": "SETTLING starts on the scheduled settlement date in America/Sao_Paulo and remains after that date until confirmed settlement. SETTLED requires affirmative settlement evidence. Risk history remains separate. ENG-1355: UNAVAILABLE is an AVAILABLE or HIGH_RISK unit with `freeAmount` 0.00: nothing is left to the merchant. `unavailableReason` tells why: ACQUIRER_PREPAID when `acquirerPrepaidAmount` is above 0.00 (the acquirer prepaid what was free; it prevails when other institutions committed part of the unit too) or, since ENG-1612, OTHER_INSTITUTIONS when there is no prepaid and `encumberedByOthers` is above 0.00 (other institutions committed what was free; the client's financiers may hold the rest). A unit only the client's financiers committed keeps its situation, and so does one whose split is unknown. Settlement stays ahead of it (such a unit on its own settlement date reads SETTLING or SETTLED), so it means a unit with a future date. It is answered only by the session routes of the Agenda (collateral-management, summary and units) and its workbook; the external API v2 (`/api/v2/receivables/schedule`) never returns it and keeps the registry's `freeAmount`." }, "ReceivableTraceabilityProvenance": { "type": "object", "required": [ "schemaVersion", "aggregateType", "aggregateId", "originType", "originChannel", "actorType", "occurredAt", "receivedAt", "correlationId", "version", "historicalCompleteness" ], "properties": { "schemaVersion": { "type": "integer" }, "aggregateType": { "type": "string", "enum": [ "RECEIVABLE" ] }, "aggregateId": { "type": "string" }, "originType": { "type": "string", "enum": [ "REGISTRAR", "CLIENT", "BACKOFFICE", "SYSTEM" ] }, "originChannel": { "type": "string", "enum": [ "TAG", "NUCLEA", "CONTROL_PANEL", "BACKOFFICE_API", "WORKER", "MIGRATION" ] }, "actorType": { "type": "string", "enum": [ "PROVIDER", "USER", "SERVICE" ] }, "actorId": { "type": "string" }, "actorRole": { "type": "string" }, "clientId": { "type": "string" }, "companyTaxId": { "type": "string" }, "registrar": { "type": "string", "enum": [ "TAG", "NUCLEA" ] }, "providerEventId": { "type": "string" }, "providerObjectId": { "type": "string" }, "providerVersion": { "type": "string" }, "providerSequence": { "type": "string" }, "orderBasis": { "type": "string", "enum": [ "PROVIDER_SEQUENCE", "PROVIDER_VERSION", "EFFECTIVE_AT", "RECEIVED_AT" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "correlationId": { "type": "string" }, "causationId": { "type": "string" }, "commandId": { "type": "string" }, "operationId": { "type": "string" }, "reasonCode": { "type": "string" }, "relatedObservationIds": { "type": "array", "maxItems": 20, "description": "Identificadores de observações imutáveis considerados em uma resolução de conflito do backoffice.", "items": { "type": "string" } }, "stateHashBefore": { "type": "string" }, "stateHashAfter": { "type": "string" }, "version": { "type": "integer", "format": "int64" }, "historicalCompleteness": { "$ref": "#/components/schemas/HistoricalCompleteness" } } }, "ScheduleAccessCompany": { "type": "object", "required": [ "companyTaxId", "status", "scopes" ], "properties": { "agendaScope": { "type": "object", "required": [ "queryId", "companyId", "clientId", "pairs", "resolvedAt", "legacy" ], "properties": { "queryId": { "type": "string" }, "companyId": { "type": "string" }, "clientId": { "type": "string" }, "packageId": { "type": "string" }, "packageVersion": { "type": "integer" }, "assignmentRevision": { "type": "integer" }, "exceptionsRevision": { "type": "integer" }, "migrationId": { "type": "string" }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "acquirerTaxId": { "type": "string", "pattern": "^[A-Z0-9]{14}$" }, "paymentScheme": { "type": "string", "minLength": 1, "maxLength": 16 }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "PACKAGE", "ADDITIONAL", "CONTRACT", "LEGACY" ] }, "description": "ENG-1198: new scopes only carry PACKAGE and ADDITIONAL. CONTRACT (pairs kept by a contract protection) and LEGACY remain valid only in snapshots frozen before." } }, "required": [ "acquirerTaxId", "paymentScheme", "sources" ], "additionalProperties": false } }, "resolvedAt": { "type": "string", "format": "date-time" }, "legacy": { "type": "boolean" } }, "additionalProperties": false }, "companyTaxId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "FAILED" ] }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleAccessScope" } } } }, "ScheduleAccessOperation": { "type": "object", "required": [ "operationId", "status", "requestedAt", "companies" ], "properties": { "operationId": { "type": "string" }, "optInExternalId": { "type": "string" }, "status": { "type": "string", "enum": [ "SCHEDULED", "PENDING", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "FAILED" ] }, "requestedAt": { "type": "string", "format": "date-time" }, "scheduledFor": { "type": "string", "format": "date-time", "description": "Presente enquanto a operação está SCHEDULED; abertura da janela em que ela começa (ENG-1188)." }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleAccessCompany" } } } }, "ScheduleAccessScope": { "type": "object", "required": [ "scheduleTrackingId", "acquirerTaxId", "paymentScheme", "resultStatus" ], "properties": { "externalRequests": { "type": "array", "items": { "type": "object", "required": [ "agendaScope", "scheduleTrackingId", "requestId", "requestIds", "provider", "status", "occurredAt" ], "properties": { "agendaScope": { "type": "object", "additionalProperties": false, "required": [ "version", "queryId", "clientId", "companyId", "snapshotHash" ], "properties": { "version": { "type": "integer", "const": 1 }, "queryId": { "type": "string", "minLength": 1, "maxLength": 128 }, "clientId": { "type": "string", "minLength": 1, "maxLength": 128 }, "companyId": { "type": "string", "minLength": 1, "maxLength": 128 }, "snapshotHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "scheduleTrackingId": { "type": "string" }, "requestId": { "type": "string" }, "requestIds": { "type": "array", "items": { "type": "string" } }, "processKey": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "scheduleTrackingId": { "type": "string", "description": "Empty while a frozen scope is awaiting consent or registration; its result remains PENDING." }, "acquirerTaxId": { "type": "string" }, "paymentScheme": { "type": "string" }, "resultStatus": { "type": "string", "enum": [ "PENDING", "PROCESSING", "DATA", "EMPTY", "NO_ACTIVE_RELATIONSHIP", "UNSUCCESSFUL", "FAILED", "CONSENTED" ], "description": "CONSENTED only on the operation of a contracts relationship probe (ENG-1403) whose pair ended on the consent, without a read." } } }, "ScheduleQueriedUnits": { "type": "object", "description": "The set queried by the last schedule request (acquirers × payment schemes, package plus additionals). packageVersion is filled once the package is versioned (ENG-981).", "properties": { "acquirers": { "type": "integer" }, "paymentSchemes": { "type": "integer" }, "packageVersion": { "type": "string", "nullable": true } } }, "ScheduleQueryPricingError": { "type": "object", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "Stable admission code, including AGENDA_QUERY_PRICING_NOT_CONFIGURED, AGENDA_QUERY_PRICING_INVALID or AGENDA_QUERY_PRICING_UNAVAILABLE." }, "message": { "type": "string" } } }, "TraceabilityObservationDecision": { "type": "string", "enum": [ "APPLIED", "NO_CHANGE", "IGNORED_DUPLICATE", "IGNORED_STALE", "CONFLICT", "REJECTED_INVALID" ] }, "WebhookAuthRequest": { "type": "object", "additionalProperties": false, "required": [ "type", "pwd" ], "properties": { "type": { "$ref": "#/components/schemas/WebhookAuthType" }, "login": { "type": "string", "description": "Header name for API_KEY or username for BASIC.", "minLength": 1, "example": "X-Client-Webhook-Key" }, "pwd": { "type": "string", "format": "password", "minLength": 1, "writeOnly": true, "example": "secret-value" } } }, "WebhookAuthType": { "type": "string", "enum": [ "BASIC", "BEARER", "API_KEY" ], "example": "BEARER" }, "WebhookAuthView": { "type": "object", "required": [ "type", "configured" ], "properties": { "type": { "$ref": "#/components/schemas/WebhookAuthType" }, "login": { "type": "string", "example": "X-Client-Webhook-Key" }, "configured": { "type": "boolean", "description": "Whether an encrypted authentication 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": "Identificador estável da entrega ou do evento. O reprocessamento preserva esse identificador.", "example": "99999999-9999-9999-9999-999999999999" }, "eventType": { "$ref": "#/components/schemas/WebhookEntity" }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "eventStatus": { "type": "string", "description": "Status de negócio associado ao evento de origem, quando disponível.", "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": "Trecho do último erro ocultado e truncado.", "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": "Trecho do payload ocultado e truncado para exibição na interface.", "example": "{\"eventId\":\"99999999-9999-9999-9999-999999999999\",\"payload\":{\"token\":\"[REDACTED]\"}}" }, "response": { "type": "string", "description": "Trecho da resposta final ocultado e truncado.", "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": "Trecho do corpo da solicitação ocultado e truncado. Chaves sensíveis são substituídas por `[REDACTED]`.", "example": "{\"eventId\":\"99999999-9999-9999-9999-999999999999\",\"secret\":\"[REDACTED]\"}" }, "responseStatus": { "type": "integer", "example": 500 }, "responseBody": { "type": "string", "description": "Trecho da resposta do provedor ocultado e truncado.", "example": "{\"message\":\"temporary failure\"}" }, "errorMessage": { "type": "string", "description": "Trecho do erro ocultado e truncado.", "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": "Identificadores de entrega ou evento que serão reprocessados. Apenas entregas finais com status FAILED pertencentes ao cliente são recolocadas na fila.", "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": "Inscrição cujas entregas finais com falha devem ser recolocadas na fila.", "example": "whsub_01HZX000000000000000000000" }, "status": { "type": "string", "enum": [ "FAILED" ], "description": "Deve ser `FAILED`; o reprocessamento do endpoint não recoloca na fila entregas pendentes, concluídas ou canceladas." } } } ] }, "WebhookDeliveryReplayResponse": { "type": "object", "required": [ "requestedEvents", "requeuedEvents", "ignoredEvents" ], "properties": { "requestedEvents": { "type": "integer", "minimum": 0, "example": 3 }, "requeuedEvents": { "type": "integer", "minimum": 0, "description": "Quantidade de entregas finais com status FAILED recolocadas na fila.", "example": 1 }, "ignoredEvents": { "type": "integer", "minimum": 0, "description": "Quantidade de entregas ignoradas por não existirem, não pertencerem ao cliente, não serem finais ou não estarem com status FAILED.", "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" } } } }, "WebhookEndpointTestResponse": { "type": "object", "required": [ "subscriptionId", "eventType", "request", "latencyMillis", "successful" ], "properties": { "subscriptionId": { "type": "string" }, "eventType": { "$ref": "#/components/schemas/WebhookEntity" }, "request": { "type": "object", "required": [ "method", "url", "payload" ], "properties": { "method": { "type": "string", "enum": [ "POST" ] }, "url": { "type": "string", "format": "uri" }, "payload": { "type": "string", "description": "Apenas carga sintética; os segredos HMAC e de autenticação são omitidos." } } }, "httpStatus": { "type": "integer", "minimum": 100, "maximum": 599 }, "latencyMillis": { "type": "integer", "minimum": 0 }, "response": { "type": "string", "description": "Trecho ocultado da resposta, truncado após 4096 bytes." }, "error": { "type": "string", "description": "Erro de transporte ocultado quando a solicitação não recebeu resposta HTTP." }, "successful": { "type": "boolean" } } }, "WebhookEntity": { "type": "string", "enum": [ "SCHEDULE_ACCESS_REQUEST", "COLLECTION_CONTRACT_CREATION", "COLLECTION_CONTRACT", "COLLATERALIZED_CREDIT_CONTRACT", "COLLATERALIZED_CREDIT_ESCROW_ACCOUNT", "AGENDA_CONSOLIDATED", "NUCLEA_CONTRACT", "NUCLEA_SCHEDULE_QUERY" ], "example": "COLLECTION_CONTRACT" }, "WebhookErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "status": { "type": "string", "description": "Status de erro opcional para leitura por sistemas.", "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", "additionalProperties": false, "required": [ "entity", "webhookUrl", "signatureSecret" ], "properties": { "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Public HTTPS receiver URL. Private, loopback, localhost, and link-local targets are rejected.", "example": "https://example.com/destrava/webhooks" }, "signatureSecret": { "type": "string", "format": "password", "minLength": 32, "maxLength": 256, "writeOnly": true, "example": "0123456789abcdef0123456789abcdef" }, "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/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", "minLength": 1, "example": "2w3Y2QeS0TtV3X9nZ5aBcD1eF6g" }, "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "example": "https://example.com/destrava/webhooks" }, "active": { "type": "boolean", "example": true }, "status": { "$ref": "#/components/schemas/WebhookSubscriptionStatus" }, "signatureSecretConfigured": { "type": "boolean", "description": "Whether a signature secret is stored encrypted.", "example": true }, "auth": { "$ref": "#/components/schemas/WebhookAuthView" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookSubscriptionStatus": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DEACTIVATED" ], "example": "ACTIVE" }, "WebhookSubscriptionUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Replacement public HTTPS receiver URL.", "example": "https://example.com/destrava/webhooks/v2" }, "signatureSecret": { "type": "string", "format": "password", "minLength": 32, "maxLength": 256, "writeOnly": true, "example": "fedcba9876543210fedcba9876543210" }, "auth": { "$ref": "#/components/schemas/WebhookAuthRequest" } } }, "WriteOffAccountReadinessErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "missingRoles" ], "properties": { "code": { "type": "string", "enum": [ "WRITE_OFF_ACCOUNTS_NOT_READY" ] }, "message": { "type": "string", "example": "Required write-off accounts are not configured." }, "missingRoles": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "PARENT", "DEVOLUTION" ] } } } } }, "responses": { "NotificationsRequestBodyBadRequest": { "description": "JSON inválido, campo desconhecido, tipo de campo inválido ou mais de um objeto JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsRequestBodyErrorResponse" } } } }, "WebhookBadRequest": { "description": "Corpo ou caminho da solicitação inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookForbidden": { "description": "O solicitante autenticado não possui o escopo OAuth público exigido.", "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 autenticado.", "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": "Consulta, payload, inscrição ou elegibilidade de entrega inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } } }, "parameters": { "CollectionV2Id": { "name": "collectionId", "in": "path", "required": true, "description": "A KSUID, a UUID, 32 hexadecimal characters, or an identifier Contracts derived for the collection: \"collection-<32 lowercase hex>\" for a creation with an Idempotency-Key and \"contract-<32 lowercase hex>\" for a batch import row. Any other value is answered with 400.", "schema": { "type": "string", "minLength": 1 } }, "HistoryCursor": { "name": "cursor", "in": "query", "required": false, "description": "Cursor opaco retornado pela página anterior.", "schema": { "type": "string" } }, "HistoryLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, "PublicRefundCompanyId": { "name": "companyId", "in": "path", "required": true, "description": "Opaque Company ID owned by the authenticated Client; never the Client ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, "PublicRefundCorrelationId": { "name": "X-Correlation-Id", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } }, "PublicRefundIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, "ReceivableId": { "name": "receivableId", "in": "path", "required": true, "description": "Identificador canônico da UR, independente da registradora.", "schema": { "type": "string" } }, "WebhookDeliveryStatusQuery": { "name": "status", "in": "query", "required": false, "description": "Filtro opcional pelo status da entrega.", "schema": { "$ref": "#/components/schemas/WebhookDeliveryStatus" } }, "WebhookEndDateQuery": { "name": "endDate", "in": "query", "required": false, "description": "Filtro inclusivo de data UTC no formato `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-17" }, "WebhookEventTypeQuery": { "name": "eventType", "in": "query", "required": false, "description": "Filtro opcional pelo tipo canônico do evento de webhook.", "schema": { "$ref": "#/components/schemas/WebhookEntity" } }, "WebhookLastItemQuery": { "name": "lastItem", "in": "query", "required": false, "description": "Cursor de paginação retornado como `nextItem` pela resposta anterior.", "schema": { "type": "string" }, "example": "2026-06-17T12:00:00Z#DELIVERY#99999999-9999-9999-9999-999999999999" }, "WebhookLimitQuery": { "name": "limit", "in": "query", "required": false, "description": "Tamanho da página do histórico de entregas. O padrão é 30 e o máximo é 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "example": 30 }, "WebhookStartDateQuery": { "name": "startDate", "in": "query", "required": false, "description": "Filtro inclusivo de data UTC no formato `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-01" }, "WebhookSubscriptionId": { "name": "subscriptionId", "in": "path", "required": true, "description": "Webhook subscription identifier returned by notifications subscription APIs.", "schema": { "type": "string", "minLength": 1 }, "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" }, "WebhookSubscriptionIdQuery": { "name": "subscriptionId", "in": "query", "required": false, "description": "Filtro opcional por inscrição.", "schema": { "type": "string", "minLength": 1 }, "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Token de acesso Bearer OAuth V2 emitido por `/v2/oauth/token`." } } } }