{ "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://decwk785irlh8.cloudfront.net", "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" } ], "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": { "$ref": "#/components/schemas/ReadMe_GetCompaniesResponse" }, "example": { "companies": [ { "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" } ] } ], "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" } ] } } } } }, "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.", "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." }, "409": { "description": "Empresa possui opt-in ativo." } }, "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" } ] } } } } }, "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" } ] } } } } }, "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", "responses": { "200": { "description": "Conta de devolução encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_RefundAccountResponse" }, "example": { "companyId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "createdAt": "2025-06-26T13:20:00.000Z", "updatedAt": "2025-06-26T13:20:00.000Z", "account": { "holderTaxId": "12345678000190", "holderName": "EMPRESA EXEMPLO LTDA", "ispb": "00000000", "branch": "1234", "account": "56789-1" }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ], "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`." }, "post": { "operationId": "settlement_v2_refund_account_create", "summary": "Cadastrar conta de devolução", "responses": { "201": { "description": "Conta de devolução criada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_RefundAccountResponse" }, "example": { "companyId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "createdAt": "2025-06-26T13:20:00.000Z", "updatedAt": "2025-06-26T13:20:00.000Z", "account": { "holderTaxId": "12345678000190", "holderName": "EMPRESA EXEMPLO LTDA", "ispb": "00000000", "branch": "1234", "account": "56789-1" }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ], "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`." }, "put": { "operationId": "settlement_v2_refund_account_update", "summary": "Atualizar conta de devolução", "responses": { "200": { "description": "Conta de devolução atualizada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_RefundAccountResponse" }, "example": { "companyId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "createdAt": "2025-06-26T13:20:00.000Z", "updatedAt": "2025-06-26T13:20:00.000Z", "account": { "holderTaxId": "12345678000190", "holderName": "EMPRESA EXEMPLO LTDA", "ispb": "00000000", "branch": "1234", "account": "56789-1" }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Empresas" ], "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`." } }, "/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": "Stable retry identity. Reusing it with the same request returns the original operation without creating new billing usage; reusing it with different content returns 409.", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "202": { "description": "Solicitação de acesso à agenda aceita para processamento assíncrono.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_ScheduleAccessAcceptedResponse" }, "example": { "operationId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "receivedAt": "2026-04-17T13:00:00Z", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "409": { "description": "Idempotency-Key was already used for different request content." }, "422": { "description": "The request contains the same normalized company tax ID more than once.", "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" } ] } } } } }, "tags": [ "Opt-In" ] } }, "/api/v2/opt-ins": { "get": { "operationId": "permission_v2_opt_ins_list", "summary": "Listar opt-ins", "description": "Lista os opt-ins do cliente autenticado com filtros opcionais e paginação por cursor. Use para acompanhar quais empresas autorizaram o acesso e em que situação a autorização se encontra. O token precisa incluir `companies:read`.", "responses": { "200": { "description": "Página de opt-ins.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_OptInListV2Response" }, "example": { "opts": [ { "optInId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "companyTaxId": "12345678000195", "status": "CREATED", "scheduleEnabled": true, "createdAt": "2026-04-17T12:30:00Z", "updatedAt": "2026-04-17T13:00:00Z", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } ], "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" } ] } } } } }, "tags": [ "Opt-In" ] }, "post": { "operationId": "permission_v2_opt_ins_create", "summary": "Realizar opt-in", "description": "Cria opt-ins para as empresas informadas e habilita a recorrência conforme o payload. Use esta operação para iniciar a autorização de acesso à agenda de recebíveis. O token precisa incluir `companies:write`.", "responses": { "202": { "description": "Opt-ins aceitos para processamento assíncrono.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_OptInBatchV2Response" }, "example": { "optInIds": [ "fe2cc560-036c-44cd-90e8-294d5a74cebc" ], "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Opt-In" ] }, "patch": { "operationId": "permission_v2_opt_in_recurrence_update", "summary": "Alterar recorrência do opt-in", "description": "Altera a recorrência de opt-ins já existentes para as empresas informadas. Use quando a autorização deve continuar ativa ou deixar de ser recorrente sem recriar o opt-in. O token precisa incluir `companies:write`.", "responses": { "200": { "description": "Recorrência de opt-in atualizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_OptInModifyV2Response" }, "example": { "updatedAt": "2026-04-17T13:00:00Z", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "tags": [ "Opt-In" ] } }, "/api/v2/opt-ins/{optId}": { "parameters": [ { "name": "optId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "permission_v2_opt_in_get", "summary": "Consultar um opt-in", "description": "Consulta os detalhes de um opt-in específico do cliente autenticado. Use para verificar status, empresa relacionada e dados de controle depois da criação ou atualização. O token precisa incluir `companies:read`.", "responses": { "200": { "description": "Detalhes do opt-in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_OptInV2Response" }, "example": { "optInId": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "companyTaxId": "12345678000195", "status": "CREATED", "scheduleEnabled": true, "createdAt": "2026-04-17T12:30:00Z", "updatedAt": "2026-04-17T13:00:00Z", "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } } }, "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": "Optional OR filter for the business origin of an encumbrance.", "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/ReadMe_EncumbrancesResponse" }, "example": { "companyTaxId": "43151964000143", "encumbrances": [ { "encumbranceId": "9bd85955-20b5-4a01-9f18-51e118bd9ec5", "receivableUnitKey": "01027058000191_MCC_43151964000143_2026-04-30", "financierTaxId": "12345678000190", "acquirerTaxId": "01027058000191", "paymentScheme": "MCC", "amount": 1500, "encumbranceType": "FIXED", "priority": "1", "settlementDate": "2026-04-30", "registeredAmount": 10000, "availableAmount": 8500, "effectivelyEncumberedAmount": 1500 } ], "pagination": { "currentItem": "9bd85955-20b5-4a01-9f18-51e118bd9ec5", "limit": 30, "nextItem": "31f29c39-cd87-49ac-b14e-e2ad9e21e3c4", "totalItems": 150 }, "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": "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", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "scheduleType", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "PERFORMED", "TO_PERFORM" ] } }, { "name": "relativePriority", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "paymentScheme", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "acquirerTaxId", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "encumbranceType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "FIXED", "PERCENTAGE" ] } }, { "name": "encumbranceCategories", "in": "query", "description": "Optional OR filter for the business origin of an encumbrance.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "CASH_ADVANCE", "COLLATERALIZED_CREDIT", "JUDICIAL_BLOCK" ] } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Prioridade dos gravames de recebíveis.", "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": "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/schedule/{companyTaxId}": { "get": { "operationId": "receivables_financier_receivable_schedule_v2_empty_window", "summary": "Consultar agenda de recebíveis da empresa", "description": "Lista os recebíveis disponíveis na agenda de uma empresa, respeitando o opt-in vigente. 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/ReadMe_ReceivableScheduleResponse" }, "example": { "receivables": [ { "uniqueKey": "string", "acquirerTaxId": "string", "acquirerName": "string", "paymentScheme": "string", "paymentSchemeName": "string", "settlementDate": "2036-04-23", "registeredAmount": 0, "encumberedAmountByClient": 0, "encumberedAmountByOthers": 0, "freeAmount": 0, "risk": { "status": "AVAILABLE", "evaluatedAt": "2036-04-23T18:45:00Z", "brokenRules": "REGRA_001" }, "lastUpdate": "2036-04-23T18:45:00Z" } ], "pagination": { "currentItem": "string", "limit": 30, "nextItem": "string", "totalItems": 150 }, "totals": { "totalRegisteredAmount": 15000.0, "pageRegisteredAmount": 3000.0 }, "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": "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", "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." } }, "tags": [ "Antecipação" ], "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`." }, "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", "responses": { "202": { "description": "Solicitação de baixa aceita", "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" } ] } } } }, "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": "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" } }, "/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", "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": "Invalid request body", "errors": [ { "fieldName": "companies[0].companyTaxId", "code": "required", "message": "companyTaxId is required" } ] } } } }, "422": { "description": "O corpo bem-formado da solicitação falhou na validação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsRequestBodyErrorResponse" }, "example": { "message": "Invalid request body", "errors": [ { "fieldName": "companies[0].companyTaxId", "code": "required", "message": "companyTaxId is required" } ] } } } }, "401": { "description": "Identificação do cliente ausente." }, "403": { "description": "O cliente não está autorizado a operar a empresa." }, "409": { "description": "O identificador externo da cobrança já existe para o mesmo cliente e empresa." }, "424": { "description": "As contas obrigatórias de baixa da liquidação não estão configuradas para o financiador." } }, "tags": [ "Cobrança" ], "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`." } }, "/api/v2/collections": { "get": { "operationId": "contracts_collection_v2_list", "summary": "Listar contratos de cobrança", "responses": { "200": { "description": "Lista de contratos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CollectionListResponse" }, "example": { "collections": [ { "collectionId": "11111111-1111-4111-8111-111111111111", "externalContractId": "ext-col-001", "externalId": "ext-op-001", "status": "CREATED", "companyTaxId": "43151964000143", "companyName": "Empresa Teste", "financierTaxId": "12345678000190", "amounts": { "requestedAmount": 1500.0, "effectivelyEncumberedAmount": 1450.0 }, "strategy": "TURBO", "firstSettlementDate": "2026-04-01", "lastSettlementDate": "2026-04-30", "createdAt": "2026-04-23T18:45:00Z", "updatedAt": "2026-04-23T19:45:00Z" } ], "pagination": { "currentItem": "fe2cc560-036c-44cd-90e8-294d5a74cebc", "limit": 30, "nextItem": "22222222-2222-4222-8222-222222222222", "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" } ] } } } }, "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", "responses": { "200": { "description": "Dados do contrato", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMe_CollectionDetailResponse" }, "example": { "collectionId": "22222222-2222-4222-8222-222222222222", "externalContractId": "ext-col-001", "externalId": "ext-op-001", "status": "CREATED", "company": { "companyTaxId": "43151964000143", "companyName": "Empresa Teste" }, "financierTaxId": "12345678000190", "amounts": { "requestedAmount": 1500.0, "effectivelyEncumberedAmount": 1450.0 }, "acquirerTaxIds": [ "01027058000191" ], "paymentSchemes": [ "MCC" ], "bankingAddress": { "state": "PROVISIONED", "taxId": "43151964000143", "ispb": "12345678", "branch": "0001", "account": "12345-6", "bankName": "Banco Teste" }, "strategy": "SELECTIVE", "firstSettlementDate": "2026-04-20", "lastSettlementDate": "2026-04-25", "createdAt": "2026-04-23T18:45:00Z", "updatedAt": "2026-04-23T19:45:00Z", "cancellation": { "contractRegisterId": "REG-123", "cancelledAt": "2026-04-23T20:00:00Z", "receipt": "receipt-123" }, "links": [ { "rel": "self", "method": "GET", "href": "/api/v2/companies", "description": "Cadastre a empresa para o cliente" } ] } } } }, "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", "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", "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": 1500, "status": "COMMITTED" } ], "pagination": { "currentItem": 0, "limit": 30, "nextItem": 30, "totalItems": 1 } } } } }, "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": "identity_profile_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": "Inscrições de webhook do cliente autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionListResponse" }, "example": { "subscriptions": [ { "subscriptionId": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "createdAt": "2026-06-17T12:00:00Z", "updatedAt": "2026-06-17T12:10:00Z", "auth": { "type": "API_KEY", "login": "X-Webhook-Key", "configured": true } } ] } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] }, "post": { "operationId": "identity_profile_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": "Inscrição de webhook criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "example": { "subscriptionId": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "createdAt": "2026-06-17T12:00:00Z", "updatedAt": "2026-06-17T12:10:00Z", "auth": { "type": "API_KEY", "login": "X-Webhook-Key", "configured": true } } } } }, "400": { "$ref": "#/components/responses/IdentityProfileRequestBodyBadRequest" }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "identity_profile_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": "Inscrição de webhook atualizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "example": { "subscriptionId": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "createdAt": "2026-06-17T12:00:00Z", "updatedAt": "2026-06-17T12:10:00Z", "auth": { "type": "API_KEY", "login": "X-Webhook-Key", "configured": true } } } } }, "400": { "$ref": "#/components/responses/IdentityProfileRequestBodyBadRequest" }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "Webhooks" ] }, "delete": { "operationId": "identity_profile_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": "Inscrição de webhook desativada sem corpo de resposta." }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/WebhookForbidden" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "500": { "$ref": "#/components/responses/WebhookInternalError" } }, "tags": [ "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/notifications_WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/notifications_WebhookForbidden" }, "422": { "$ref": "#/components/responses/notifications_WebhookValidationError" }, "500": { "$ref": "#/components/responses/notifications_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/notifications_WebhookSubscriptionId" }, { "$ref": "#/components/parameters/WebhookDeliveryStatusQuery" }, { "$ref": "#/components/parameters/WebhookEventTypeQuery" }, { "$ref": "#/components/parameters/WebhookStartDateQuery" }, { "$ref": "#/components/parameters/WebhookEndDateQuery" }, { "$ref": "#/components/parameters/WebhookLastItemQuery" }, { "$ref": "#/components/parameters/WebhookLimitQuery" } ], "responses": { "200": { "description": "Histórico de entregas e tentativas de uma inscrição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveriesResponse" }, "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/notifications_WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/notifications_WebhookForbidden" }, "422": { "$ref": "#/components/responses/notifications_WebhookValidationError" }, "500": { "$ref": "#/components/responses/notifications_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/notifications_WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/notifications_WebhookForbidden" }, "422": { "$ref": "#/components/responses/notifications_WebhookValidationError" }, "500": { "$ref": "#/components/responses/notifications_WebhookInternalError" } }, "tags": [ "Webhooks" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/pause": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "identity_profile_webhook_subscription_pause", "summary": "Pausar webhook", "description": "Escopo OAuth necessário: `manage:webhooks`. Pausa uma inscrição de webhook sem remover a configuração.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "200": { "description": "Inscrição de webhook pausada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "example": { "subscriptionId": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "createdAt": "2026-06-17T12:00:00Z", "updatedAt": "2026-06-17T12:10:00Z", "auth": { "type": "API_KEY", "login": "X-Webhook-Key", "configured": true } } } } }, "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" ] } }, "/api/v2/webhook-subscriptions/{subscriptionId}/reactivate": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "identity_profile_webhook_subscription_reactivate", "summary": "Reativar webhook", "description": "Escopo OAuth necessário: `manage:webhooks`. Reativa uma inscrição de webhook pausada e retoma entregas futuras elegíveis.", "parameters": [ { "$ref": "#/components/parameters/WebhookSubscriptionId" } ], "responses": { "200": { "description": "Inscrição de webhook reativada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "example": { "subscriptionId": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5", "entity": "COLLECTION_CONTRACT", "webhookUrl": "https://example.com/destrava/webhooks", "active": true, "status": "ACTIVE", "signatureSecretConfigured": true, "createdAt": "2026-06-17T12:00:00Z", "updatedAt": "2026-06-17T12:10:00Z", "auth": { "type": "API_KEY", "login": "X-Webhook-Key", "configured": true } } } } }, "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" ] } }, "/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": "Requires OAuth scope `manage:webhooks`. Sends one synchronous, synthetic payload through the endpoint's configured HMAC and optional authentication. The request is never persisted or counted as a business delivery. Response excerpts are redacted and truncated.", "parameters": [ { "$ref": "#/components/parameters/notifications_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/notifications_WebhookUnauthorized" }, "403": { "$ref": "#/components/responses/notifications_WebhookForbidden" }, "404": { "$ref": "#/components/responses/notifications_WebhookNotFound" }, "500": { "$ref": "#/components/responses/notifications_WebhookInternalError" } }, "tags": [ "Webhooks" ] } } }, "components": { "schemas": { "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": "Canonical aging days for COLLECTION recovery billing." }, "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" ] } } }, "CollectionOffsetPaginationV2Response": { "type": "object", "description": "Paginação por posição usada nas consultas de cobrança.", "required": [ "currentItem", "limit", "totalItems" ], "properties": { "currentItem": { "type": "integer", "format": "int32", "description": "Posição inicial da página atual.", "example": 0 }, "limit": { "type": "integer", "format": "int32", "description": "Quantidade máxima de itens por página.", "example": 30 }, "nextItem": { "type": "integer", "format": "int32", "description": "Posição inicial da próxima página.", "example": 30 }, "totalItems": { "type": "integer", "format": "int32", "description": "Total de recebíveis vinculados à cobrança.", "example": 1 } } }, "CollectionReceivableFilter": { "type": "object", "required": [ "firstSettlementDate", "lastSettlementDate" ], "properties": { "acquirerTaxIds": { "type": "array", "items": { "type": "string" } }, "paymentSchemes": { "type": "array", "items": { "type": "string" } }, "firstSettlementDate": { "type": "string", "format": "date" }, "lastSettlementDate": { "type": "string", "format": "date" } } }, "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.", "example": "2036-04-23" }, "amount": { "type": "number", "format": "double", "description": "Valor corrente considerado na cobrança.", "example": 1500 }, "status": { "type": "string", "description": "Situação do recebível dentro da cobrança.", "enum": [ "COMMITTED", "INACTIVE" ], "example": "COMMITTED" } } }, "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/CollectionOffsetPaginationV2Response" } } }, "ContractsRequestBodyErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "Invalid request body" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ContractsRequestBodyFieldError" } } } }, "ContractsRequestBodyFieldError": { "type": "object", "required": [ "fieldName", "code", "message" ], "properties": { "fieldName": { "type": "string", "description": "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" } } }, "IdentityProfileRequestBodyErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "Invalid request body" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityProfileRequestBodyFieldError" } } } }, "IdentityProfileRequestBodyFieldError": { "type": "object", "required": [ "fieldName", "code", "message" ], "properties": { "fieldName": { "type": "string", "description": "Caminho do campo JSON que falhou na leitura ou validação. Fica vazio quando o erro se refere ao corpo JSON inteiro.", "example": "auth.type" }, "code": { "type": "string", "enum": [ "unknown_field", "invalid_type", "invalid_json" ], "example": "unknown_field" }, "message": { "type": "string", "example": "auth.type has an invalid type" } } }, "NotificationsRequestBodyErrorResponse": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string", "example": "Invalid request body" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationsRequestBodyFieldError" } } } }, "NotificationsRequestBodyFieldError": { "type": "object", "required": [ "fieldName", "code", "message" ], "properties": { "fieldName": { "type": "string", "description": "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." }, "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_CollectionAmountsResponse": { "type": "object", "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 } }, "description": "Valores monetários de contratos de cobrança" }, "ReadMe_CollectionDetailAmountsResponse": { "type": "object", "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 } }, "description": "Valores monetários do contrato de cobrança" }, "ReadMe_CollectionDetailBankingAddressResponse": { "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": "12345678" }, "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_CollectionDetailCancellationResponse": { "type": "object", "properties": { "contractRegisterId": { "type": "string", "description": "Identificador do contrato no registrador", "nullable": true, "example": "REG-123" }, "cancelledAt": { "type": "string", "description": "Data/hora de cancelamento em UTC", "format": "date-time", "nullable": true, "example": "2026-04-23T20:00:00Z" }, "receipt": { "type": "string", "description": "Comprovante de baixa do gravame", "nullable": true, "example": "receipt-123" } }, "description": "Dados de cancelamento do contrato" }, "ReadMe_CollectionDetailCompanyResponse": { "type": "object", "properties": { "companyTaxId": { "type": "string", "description": "CNPJ/CPF da empresa", "example": "43151964000143" }, "companyName": { "type": "string", "description": "Nome da empresa", "example": "Empresa Teste" } }, "description": "Dados da empresa vinculada ao contrato" }, "ReadMe_CollectionDetailResponse": { "type": "object", "properties": { "collectionId": { "type": "string", "format": "uuid", "description": "Identificador do contrato", "example": "22222222-2222-4222-8222-222222222222" }, "externalContractId": { "type": "string", "description": "Identificador externo do contrato", "example": "ext-col-001" }, "externalId": { "type": "string", "description": "Identificador externo individual da operação de cobrança", "example": "ext-op-001" }, "status": { "type": "string", "description": "Status do contrato", "example": "CREATED", "enum": [ "CREATED", "CREATION_PENDING", "CREATION_FAILED", "CREATION_FAILED_NO_RELATIONS", "DELETION_PENDING", "DELETION_FAILED", "DELETED" ] }, "company": { "$ref": "#/components/schemas/ReadMe_CollectionDetailCompanyResponse" }, "financierTaxId": { "type": "string", "description": "CNPJ do financiador", "example": "12345678000190" }, "amounts": { "$ref": "#/components/schemas/ReadMe_CollectionDetailAmountsResponse" }, "acquirerTaxIds": { "type": "array", "description": "CNPJs de adquirentes relacionados ao contrato", "items": { "type": "string", "example": "01027058000191" } }, "paymentSchemes": { "type": "array", "description": "Filtros de arranjo de pagamento relacionados ao contrato", "items": { "type": "string", "example": "MCC" } }, "bankingAddress": { "$ref": "#/components/schemas/ReadMe_CollectionDetailBankingAddressResponse" }, "strategy": { "type": "string", "description": "Estratégia de cobrança", "example": "SELECTIVE", "enum": [ "TURBO", "SELECTIVE", "SELECTIVE_WITH_DEBIT", "SNIPER", "DYNAMIC" ] }, "firstSettlementDate": { "type": "string", "description": "Data inicial de liquidação dos recebíveis", "format": "date", "example": "2026-04-20" }, "lastSettlementDate": { "type": "string", "description": "Data final de liquidação dos recebíveis", "format": "date", "example": "2026-04-25" }, "createdAt": { "type": "string", "description": "Data/hora de criação em UTC", "format": "date-time", "example": "2026-04-23T18:45:00Z" }, "updatedAt": { "type": "string", "description": "Data/hora da última atualização em UTC", "format": "date-time", "nullable": true, "example": "2026-04-23T19:45:00Z" }, "cancellation": { "$ref": "#/components/schemas/ReadMe_CollectionDetailCancellationResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Detalhes de um contrato de cobrança" }, "ReadMe_CollectionListResponse": { "type": "object", "properties": { "collections": { "type": "array", "description": "Lista de contratos de cobrança", "items": { "$ref": "#/components/schemas/ReadMe_CollectionResponse" } }, "pagination": { "$ref": "#/components/schemas/ReadMe_PaginationResponse" }, "totals": { "$ref": "#/components/schemas/ReadMe_CollectionTotalsResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Lista paginada de contratos de cobrança" }, "ReadMe_CollectionResponse": { "type": "object", "properties": { "collectionId": { "type": "string", "format": "uuid", "description": "Identificador do contrato", "example": "11111111-1111-4111-8111-111111111111" }, "externalContractId": { "type": "string", "description": "Identificador externo do contrato", "example": "ext-col-001" }, "externalId": { "type": "string", "description": "Identificador externo individual da operação de cobrança", "example": "ext-op-001" }, "status": { "type": "string", "description": "Status do contrato", "example": "CREATED", "enum": [ "CREATED", "CREATION_PENDING", "CREATION_FAILED", "CREATION_FAILED_NO_RELATIONS", "DELETION_PENDING", "DELETION_FAILED", "DELETED" ] }, "companyTaxId": { "type": "string", "description": "CNPJ/CPF da empresa", "example": "43151964000143" }, "companyName": { "type": "string", "description": "Nome da empresa", "example": "Empresa Teste" }, "financierTaxId": { "type": "string", "description": "CNPJ do financiador", "example": "12345678000190" }, "amounts": { "$ref": "#/components/schemas/ReadMe_CollectionAmountsResponse" }, "strategy": { "type": "string", "description": "Estratégia de cobrança", "example": "TURBO", "enum": [ "TURBO", "SELECTIVE", "SNIPER", "SELECTIVE_WITH_DEBIT", "DYNAMIC" ] }, "firstSettlementDate": { "type": "string", "format": "date", "description": "Data inicial de liquidação dos recebíveis", "example": "2026-04-01" }, "lastSettlementDate": { "type": "string", "format": "date", "description": "Data final de liquidação dos recebíveis", "example": "2026-04-30" }, "createdAt": { "type": "string", "format": "date-time", "description": "Data/hora de criação em UTC", "example": "2026-04-23T18:45:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Data/hora da última atualização em UTC", "nullable": true, "example": "2026-04-23T19:45:00Z" } }, "description": "Dados de um contrato de cobrança" }, "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_CollectionTotalsResponse": { "type": "object", "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 } }, "description": "Totalizadores monetários do filtro" }, "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_EncumbranceItemResponse": { "type": "object", "properties": { "encumbranceId": { "type": "string", "description": "Identificador da oneração", "example": "9bd85955-20b5-4a01-9f18-51e118bd9ec5" }, "receivableUnitKey": { "type": "string", "description": "Chave da unidade recebível", "example": "01027058000191_MCC_43151964000143_2026-04-30" }, "financierTaxId": { "type": "string", "description": "CNPJ do financiador", "example": "12345678000190" }, "acquirerTaxId": { "type": "string", "description": "CNPJ do adquirente", "example": "01027058000191" }, "paymentScheme": { "type": "string", "description": "Código do arranjo", "example": "MCC" }, "amount": { "type": "number", "description": "Valor configurado para a oneração. Quando encumbranceType for FIXED, representa valor monetário; quando for PERCENTAGE, representa percentual.", "example": 1500 }, "encumbranceType": { "type": "string", "description": "Tipo de oneração", "enum": [ "FIXED", "PERCENTAGE" ], "example": "FIXED" }, "priority": { "type": "string", "description": "Prioridade absoluta registrada para a oneração", "example": "1" }, "settlementDate": { "type": "string", "format": "date", "description": "Data de liquidação", "example": "2026-04-30" }, "registeredAmount": { "type": "number", "description": "Valor registrado da unidade recebível", "example": 10000 }, "availableAmount": { "type": "number", "description": "Valor disponível registrado para a unidade recebível", "example": 8500 }, "effectivelyEncumberedAmount": { "type": "number", "description": "Valor efetivamente onerado registrado para a unidade recebível", "example": 1500 } }, "description": "Detalhes de uma oneração sobre recebível" }, "ReadMe_EncumbrancePaginationResponse": { "type": "object", "properties": { "currentItem": { "type": "string", "nullable": true, "description": "Cursor usado na página atual", "example": "9bd85955-20b5-4a01-9f18-51e118bd9ec5" }, "limit": { "type": "integer", "format": "int32", "description": "Número máximo de itens na página", "example": 30 }, "nextItem": { "type": "string", "nullable": true, "description": "Cursor da próxima página", "example": "31f29c39-cd87-49ac-b14e-e2ad9e21e3c4" }, "totalItems": { "type": "integer", "format": "int32", "description": "Total de onerações disponíveis para os filtros informados", "example": 150 } }, "description": "Metadados de paginação baseada em cursor" }, "ReadMe_EncumbrancesResponse": { "type": "object", "properties": { "companyTaxId": { "type": "string", "description": "CNPJ da empresa", "example": "43151964000143" }, "encumbrances": { "type": "array", "description": "Lista de onerações", "items": { "$ref": "#/components/schemas/ReadMe_EncumbranceItemResponse" } }, "pagination": { "$ref": "#/components/schemas/ReadMe_EncumbrancePaginationResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Lista de onerações sobre recebíveis de uma empresa" }, "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_GetCompaniesResponse": { "type": "object", "properties": { "companies": { "type": "array", "description": "Empresas retornadas na página atual", "items": { "$ref": "#/components/schemas/ReadMe_CompanyV2Response" } }, "pagination": { "$ref": "#/components/schemas/ReadMe_PaginationResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Página de empresas da API v2" }, "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_OptInBatchV2Response": { "type": "object", "properties": { "optInIds": { "type": "array", "description": "Identificadores dos opt-ins criados", "items": { "type": "string", "format": "uuid" }, "example": [ "fe2cc560-036c-44cd-90e8-294d5a74cebc" ] }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resultado do enfileiramento do opt-in em lote" }, "ReadMe_OptInListV2Response": { "type": "object", "properties": { "opts": { "type": "array", "description": "Opt-ins encontrados", "items": { "$ref": "#/components/schemas/ReadMe_OptInV2Response" } }, "pagination": { "$ref": "#/components/schemas/ReadMe_PaginationResponse" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Lista paginada de opt-ins" }, "ReadMe_OptInModifyV2Response": { "type": "object", "properties": { "updatedAt": { "type": "string", "format": "date-time", "description": "Data da atualização em UTC", "example": "2026-04-17T13:00:00Z" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Data da última atualização da recorrência" }, "ReadMe_OptInV2Response": { "type": "object", "properties": { "optInId": { "type": "string", "format": "uuid", "description": "Identificador único do opt-in", "example": "fe2cc560-036c-44cd-90e8-294d5a74cebc" }, "companyTaxId": { "type": "string", "description": "CPF ou CNPJ da empresa", "example": "12345678000195" }, "status": { "type": "string", "description": "Status do opt-in", "example": "CREATED", "enum": [ "CREATION_PENDING", "REGISTRATION_REQUESTED", "RETRY_CREATION", "CREATION_FAILED", "CREATION_TIMEOUT", "CANCELLED", "CREATED", "DELETION_PENDING", "DELETION_FAILED", "DELETED", "DELETED_INACTIVE", "DELETION_INACTIVE_PENDING", "DELETION_INACTIVE_FAILED" ] }, "scheduleEnabled": { "type": "boolean", "description": "Indica se a recorrência está habilitada", "example": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de criação do opt-in em UTC", "example": "2026-04-17T12:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Data da última atualização do opt-in em UTC", "example": "2026-04-17T13:00:00Z" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Dados públicos do opt-in" }, "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_ReceivableScheduleItem": { "type": "object", "description": "Recebível disponível na agenda da empresa", "properties": { "uniqueKey": { "type": "string" }, "acquirerTaxId": { "type": "string" }, "acquirerName": { "type": "string", "nullable": true }, "paymentScheme": { "type": "string" }, "paymentSchemeName": { "type": "string", "nullable": true }, "settlementDate": { "type": "string", "format": "date" }, "registeredAmount": { "type": "number", "format": "double" }, "encumberedAmountByClient": { "type": "number", "format": "double" }, "encumberedAmountByOthers": { "type": "number", "format": "double" }, "freeAmount": { "type": "number", "format": "double", "nullable": true }, "risk": { "$ref": "#/components/schemas/ReadMe_ReceivableScheduleRisk" }, "lastUpdate": { "type": "string", "format": "date-time", "nullable": true } } }, "ReadMe_ReceivableSchedulePagination": { "type": "object", "description": "Metadados de paginação baseada em cursor", "properties": { "currentItem": { "type": "string", "nullable": true }, "limit": { "type": "integer", "format": "int32", "example": 30 }, "nextItem": { "type": "string", "nullable": true }, "totalItems": { "type": "integer", "format": "int64", "example": 150 } } }, "ReadMe_ReceivableScheduleResponse": { "type": "object", "description": "Agenda paginada de recebíveis disponíveis para operação", "properties": { "receivables": { "type": "array", "items": { "$ref": "#/components/schemas/ReadMe_ReceivableScheduleItem" } }, "pagination": { "$ref": "#/components/schemas/ReadMe_ReceivableSchedulePagination" }, "totals": { "$ref": "#/components/schemas/ReadMe_ReceivableScheduleTotals" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } } }, "ReadMe_ReceivableScheduleRisk": { "type": "object", "description": "Resultado da avaliação de risco do recebível", "properties": { "status": { "type": "string", "nullable": true, "example": "AVAILABLE" }, "evaluatedAt": { "type": "string", "format": "date-time", "nullable": true }, "brokenRules": { "type": "string", "nullable": true, "example": "REGRA_001" } } }, "ReadMe_ReceivableScheduleTotals": { "type": "object", "description": "Totalizadores monetários do recorte", "properties": { "totalRegisteredAmount": { "type": "number", "format": "double", "example": 15000.0 }, "pageRegisteredAmount": { "type": "number", "format": "double", "example": 3000.0 } } }, "ReadMe_RefundAccountResponse": { "type": "object", "properties": { "companyId": { "type": "string", "description": "ID da empresa", "example": "fe2cc560-036c-44cd-90e8-294d5a74cebc" }, "createdAt": { "type": "string", "description": "Data de criação em UTC", "example": "2025-06-26T13:20:00.000Z" }, "updatedAt": { "type": "string", "description": "Data de atualização em UTC", "example": "2025-06-26T13:20:00.000Z" }, "account": { "$ref": "#/components/schemas/ReadMe_RefundAccountResponse.AccountDetail" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resposta com dados da conta bancária de devolução" }, "ReadMe_RefundAccountResponse.AccountDetail": { "type": "object", "properties": { "holderTaxId": { "type": "string", "description": "CPF/CNPJ do titular", "example": "12345678000190" }, "holderName": { "type": "string", "description": "Nome do titular", "example": "EMPRESA EXEMPLO LTDA" }, "ispb": { "type": "string", "description": "Código ISPB da instituição", "example": "00000000" }, "branch": { "type": "string", "description": "Agência bancária", "example": "1234" }, "account": { "type": "string", "description": "Número da conta", "example": "56789-1" } }, "description": "Detalhes da conta bancária de devolução" }, "ReadMe_ScheduleAccessAcceptedResponse": { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid", "description": "Identificador da operação", "example": "fe2cc560-036c-44cd-90e8-294d5a74cebc" }, "receivedAt": { "type": "string", "format": "date-time", "description": "Data/hora de recebimento em UTC", "example": "2026-04-17T13:00:00Z" }, "links": { "type": "array", "description": "Links de navegação da API", "items": { "$ref": "#/components/schemas/ReadMe_ApiLink" } } }, "description": "Resposta assíncrona para solicitação de acesso à agenda" }, "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" }, "WebhookAuthRequest": { "type": "object", "required": [ "type", "pwd" ], "properties": { "type": { "$ref": "#/components/schemas/WebhookAuthType" }, "login": { "type": "string", "description": "Username for BASIC or API-key header name. Required for BASIC and API_KEY. API-key header names must be valid HTTP field names and cannot replace Authorization, transport headers, or Destrava signature headers.", "example": "X-Webhook-Key" }, "pwd": { "type": "string", "description": "Valor secreto usado na autenticação de saída do webhook. É armazenado de forma criptografada e nunca é retornado.", "minLength": 1, "writeOnly": true, "example": "client-webhook-api-key" } }, "description": "Configuração opcional de autenticação de saída enviada nas entregas de webhook." }, "WebhookAuthType": { "type": "string", "enum": [ "BASIC", "BEARER", "API_KEY" ], "example": "API_KEY" }, "WebhookAuthView": { "type": "object", "required": [ "type", "configured" ], "properties": { "type": { "$ref": "#/components/schemas/WebhookAuthType" }, "login": { "type": "string", "description": "Identificador público de autenticação. O valor secreto nunca é retornado.", "example": "X-Webhook-Key" }, "configured": { "type": "boolean", "description": "Verdadeiro quando há um segredo de autenticação de saída configurado.", "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/notifications_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/notifications_WebhookEntity" }, "request": { "type": "object", "required": [ "method", "url", "payload" ], "properties": { "method": { "type": "string", "enum": [ "POST" ] }, "url": { "type": "string", "format": "uri" }, "payload": { "type": "string", "description": "Synthetic payload only; HMAC and authentication secrets are omitted." } } }, "httpStatus": { "type": "integer", "minimum": 100, "maximum": 599 }, "latencyMillis": { "type": "integer", "minimum": 0 }, "response": { "type": "string", "description": "Redacted response excerpt, truncated after 4096 bytes." }, "error": { "type": "string", "description": "Redacted transport error when the request had no HTTP response." }, "successful": { "type": "boolean" } } }, "WebhookEntity": { "type": "string", "enum": [ "OPT_IN_CREATED", "OPT_IN_RECURRENCE_UPDATED", "SCHEDULE_ACCESS_REQUEST", "COLLECTION_CONTRACT_CREATION", "COLLECTION_CONTRACT", "COLLATERALIZED_CREDIT_CONTRACT", "COLLATERALIZED_CREDIT_ESCROW_ACCOUNT" ], "example": "COLLECTION_CONTRACT" }, "WebhookErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "status": { "type": "string", "description": "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", "required": [ "entity", "webhookUrl", "signatureSecret" ], "properties": { "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Public HTTPS callback URL. Localhost, private, link-local, metadata and ambiguous IP targets, as well as URLs with embedded credentials, are rejected for SSRF protection.", "example": "https://example.com/destrava/webhooks" }, "signatureSecret": { "type": "string", "minLength": 32, "maxLength": 256, "writeOnly": true, "description": "Segredo de assinatura HMAC. É armazenado de forma criptografada e nunca é retornado depois da criação ou atualização.", "example": "destrava-webhook-signature-secret-123456" }, "auth": { "$ref": "#/components/schemas/WebhookAuthRequest" } } }, "WebhookSubscriptionDeliverySummary": { "type": "object", "required": [ "subscriptionId", "eventType", "webhookUrl", "totalDeliveries", "statuses" ], "properties": { "subscriptionId": { "type": "string", "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" }, "eventType": { "$ref": "#/components/schemas/notifications_WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "example": "https://example.com/destrava/webhooks" }, "totalDeliveries": { "type": "integer", "minimum": 0, "example": 12 }, "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryStatusSummary" } } } }, "WebhookSubscriptionListResponse": { "type": "object", "required": [ "subscriptions" ], "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "WebhookSubscriptionResponse": { "type": "object", "required": [ "subscriptionId", "entity", "webhookUrl", "active", "status", "signatureSecretConfigured", "createdAt", "updatedAt" ], "properties": { "subscriptionId": { "type": "string", "example": "sub_01HZY7E6R4G7Z2M6D3T0Q9X4K5" }, "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "example": "https://example.com/destrava/webhooks" }, "active": { "type": "boolean", "description": "Indicador de compatibilidade para elegibilidade da entrega. Prefira `status` para representar o estado na interface.", "example": true }, "status": { "$ref": "#/components/schemas/WebhookSubscriptionStatus" }, "signatureSecretConfigured": { "type": "boolean", "description": "Verdadeiro quando há um segredo de assinatura HMAC configurado; o segredo original nunca é retornado.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-06-17T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-06-17T12:10:00Z" }, "auth": { "$ref": "#/components/schemas/WebhookAuthView" } } }, "WebhookSubscriptionStatus": { "type": "string", "description": "Entregas ACTIVE são elegíveis, PAUSED mantém a configuração sem novas entregas e DEACTIVATED representa a remoção lógica com o histórico preservado.", "enum": [ "ACTIVE", "PAUSED", "DEACTIVATED" ], "example": "ACTIVE" }, "WebhookSubscriptionUpdateRequest": { "type": "object", "minProperties": 1, "properties": { "entity": { "$ref": "#/components/schemas/WebhookEntity" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Nova URL HTTPS pública de retorno para entregas futuras.", "example": "https://example.com/destrava/webhooks/updated" }, "signatureSecret": { "type": "string", "minLength": 32, "maxLength": 256, "writeOnly": true, "description": "Novo segredo de assinatura HMAC para entregas futuras. Nunca é retornado pela API.", "example": "destrava-webhook-signature-secret-rotated-123456" }, "auth": { "$ref": "#/components/schemas/WebhookAuthRequest" } } }, "notifications_WebhookEntity": { "type": "string", "enum": [ "OPT_IN_CREATED", "OPT_IN_RECURRENCE_UPDATED", "SCHEDULE_ACCESS_REQUEST", "COLLECTION_CONTRACT_CREATION", "COLLECTION_CONTRACT", "COLLATERALIZED_CREDIT_CONTRACT", "COLLATERALIZED_CREDIT_ESCROW_ACCOUNT" ], "example": "COLLECTION_CONTRACT" }, "notifications_WebhookErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "status": { "type": "string", "description": "Status de erro opcional para leitura por sistemas.", "example": "forbidden" }, "message": { "type": "string", "example": "missing required OAuth scope" } } } }, "responses": { "IdentityProfileRequestBodyBadRequest": { "description": "JSON inválido, campo desconhecido, tipo de campo inválido ou mais de um objeto JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityProfileRequestBodyErrorResponse" } } } }, "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/notifications_WebhookErrorResponse" } } } }, "WebhookForbidden": { "description": "Permissões insuficientes para o escopo OAuth ou para a entidade de webhook solicitada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookInternalError": { "description": "Erro interno inesperado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookNotFound": { "description": "Inscrição de webhook não encontrada para o cliente ou já desativada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookUnauthorized": { "description": "Token Bearer ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "WebhookValidationError": { "description": "URL, entidade, segredo de assinatura, autenticação ou estado da inscrição inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookErrorResponse" } } } }, "notifications_WebhookForbidden": { "description": "O solicitante autenticado não possui o escopo OAuth público exigido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } }, "notifications_WebhookInternalError": { "description": "Erro interno inesperado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } }, "notifications_WebhookNotFound": { "description": "Webhook subscription was not found for the authenticated client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } }, "notifications_WebhookUnauthorized": { "description": "Token Bearer ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } }, "notifications_WebhookValidationError": { "description": "Consulta, payload, inscrição ou elegibilidade de entrega inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notifications_WebhookErrorResponse" } } } } }, "parameters": { "WebhookDeliveryStatusQuery": { "name": "status", "in": "query", "required": false, "description": "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/notifications_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": "Identificador da inscrição de webhook retornado pelas operações de criação e listagem.", "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" }, "notifications_WebhookSubscriptionId": { "name": "subscriptionId", "in": "path", "required": true, "description": "Identificador da inscrição de webhook retornado pelas APIs de inscrição de identidade e perfil.", "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`." } } } }