Integração DDA para Parceiros via API

    {
        //Obrigatório: Chave da aplicação
        accessKey: string
        //Obrigatório: Segredo da chave informada
        secret: string
        //Obrigatório: Nome do tenant em que se deseja efetuar o login
        tenantName: string
        //Opcional: Escopo do token da autenticação. Se não for informado será usado o valor padrão 'desktop'
        scope : string
    }

Detalhes dos parâmetros:

• accessKey: Chave de aplicação gerada no momento da criação da aplicação, disponível no caminho: Tecnologia > Administração > Gerenciamento de aplicações. A chave se encontra no campo Chave de acesso das propriedades da aplicação;
• secret: Chave única gerada no momento da criação da aplicação, disponível no caminho: Tecnologia > Administração > Gerenciamento de aplicações. A chave se encontra no campo Secret das propriedades da aplicação, e deve ser copiada logo após a sua criação.
• Tanto o secret como o accessKey são valores únicos responsáveis pela identificação da aplicação que está tentando conectar com o ERP;
• tenantName: Identificação do cliente (tenant) que o parceiro representa e utiliza a base de dados.

• Cadastrar uma aplicação no Senior X: Para mais detalhes, consulte o tópico Utilizando a aplicação do artigo Consumindo uma API, disponível no portal de APIs da Senior;
• Registrar a aplicação no portal de API: Para realizar o cadastro, siga o tutorial do artigo Criando uma Aplicação, disponível no portal de APIs da Senior;
• Associar a aplicação a um papel: Para conceder permissões de uso das primitivas DDA, associe a aplicação a um papel que possua a task ERPX Banking Registro DDA em: Tecnologia > Administração > Autorização > Gestão de papéis;
• Verificar CNPJ da filial: O CNPJ da filial deve estar cadastrado no módulo Banking, tabela e070fil (coluna numCgc). Esse identificador é obrigatório para todas as requisições;
• Onboarding DDA: A filial deve ter sido previamente onboardada com o parceiro bancário (BTG) através do fluxo de Ativação de Parceiros, disponível em: Banking > Ativação de Parceiros > Onboarding.

• processId (string, uuid): Identificador único do lote de processamento. Deve ser um UUID válido, utilizado para acompanhamento e auditoria do envio. Campo obrigatório.
• company (object): Identificação da empresa, contendo id ou code. Se omitido, o sistema assume a empresa padrão do contexto. Campo opcional.
• branch (object): Identificação da filial, contendo o CNPJ (14 dígitos) no campo documentNumber. Campo obrigatório.
• accountsPayable (array): Lista de títulos a serem registrados. Máximo de 100 títulos por requisição. A lista não pode ser vazia. Campo obrigatório.

• accountPayableId (string, uuid): Identificador único do título no ERP origem, utilizado para rastreamento e auditoria. Deve ser um UUID válido e não pode haver duplicatas na mesma requisição. Campo obrigatório.
• accountPayableNumber (string): Número identificador do título no ERP, como número da nota fiscal ou duplicata (ex.: "NF-001234"). Campo obrigatório.
• accountPayableType (string): Tipo ou classificação do título para o DDA. Valores aceitos: DUP (Duplicata), IMP (Imposto), NF (Nota Fiscal). Outros tipos podem ser aceitos conforme configuração do cliente. Campo obrigatório.
• favored.documentNumber (string): CPF (11 dígitos) ou CNPJ (14 dígitos) do beneficiário do título, utilizado para validação e associação com boletos. Deve passar na validação de dígito verificador. Campo obrigatório.
• favored.name (string): Nome do beneficiário do título. Campo obrigatório.
• dueDate (date): Data de vencimento do título, no formato ISO (YYYY-MM-DD). Utilizada para matching automático com boletos DDA. Campo obrigatório.
• value (decimal): Valor original do título, utilizado para matching com o valor do boleto DDA (com tolerância configurável). Valor mínimo de 0.00, sem limite máximo especificado. Campo obrigatório.

Veja abaixo um exemplo completo do payload de requisição para registro de títulos DDA:

POST https://api.senior.com.br/erpx_bnk_pag/facade/apis/registerAccountsPayableDebits
Body:
{
	"processId": "a7b7c251-1d54-4bb5-86d3-9fa7e1cc26c0",
	"company": { "code": 1 },
	"branch": { 
		"documentNumber": "82951229000176" 
	},
	"accountsPayable": [
		{
			"accountPayableId": "550e8400-e29b-41d4-a716-446655440000",
			"accountPayableNumber": "NF-001234",
			"accountPayableType": "NF",
			"favored": {
				"documentNumber": "82951229000176",
				"name": "Fornecedor LTDA"
			},
			"dueDate": "2026-06-30",
			"value": 1500.50				
			}
		]
	}

Em caso de sucesso, a API retorna um objeto vazio, indicando que a requisição foi validada e aceita para processamento assíncrono:

Response 200:{}

Em caso de requisição inválida, quando algum campo obrigatório não é fornecido ou viola as regras de negócio:

Response 400:{
		"reason": "BAD_REQUEST",
		"message": "A lista de títulos é obrigatória"
		}

• processId (string, uuid): Identificador único do lote de exclusão. Deve ser um UUID válido e diferente do processId do registro original. Campo obrigatório.
• accountsPayableDebit (array de strings): Lista contendo os UUIDs dos títulos a serem removidos. Máximo de 100 identificadores por requisição. A lista não pode ser vazia e não pode conter duplicatas. Campo obrigatório.

Em caso de sucesso, a API retorna um objeto vazio, indicando a aceitação da requisição para processamento assíncrono:

Response 200:{}

Em caso de requisição inválida, quando parâmetros obrigatórios não são fornecidos ou violam as regras:

Response 400:{
		"reason": "BAD_REQUEST",
		"message": "O identificador do processo não é um UUID válido"
		}

• company (object): Empresa relacionada ao evento, identificada pelo id.
• branch (object): Filial relacionada ao evento, identificada pelo id.
• associatedDebts (array): Lista de títulos associados, contendo accountPayableId, accountPayableNumber, accountPayableType, expirationDate, digitableLine (linha digitável do boleto), dueDate, value, debitSituation (EM_ABERTO ou LIQUIDADO), favored (documentNumber, name e bank), statusAssociation e dateTimeAssociation.

{
	"company": { "id": "UUID empresa" },
	"branch": { "id": "UUID filial" },
	"associatedDebts": [
		{
			"accountPayableId": "UUID do título",
			"accountPayableNumber": "número do título",
			"accountPayableType": "tipo",
			"expirationDate": "date (YYYY-MM-DD)",
			"digitableLine": "string (LINHA DIGITÁVEL DO BOLETO)",
			"dueDate": "date (YYYY-MM-DD)",
			"value": "decimal",
			"debitSituation": "EM_ABERTO | LIQUIDADO",
			"favored": {
				"documentNumber": "CPF/CNPJ",
				"name": "nome",
				"bank": {"code": "código banco","name": "nome banco"}
			},
			"statusAssociation": "tipo de associação",
			"dateTimeAssociation": "ISO datetime"
		}
	]
}

• AUTOMATICA_SEM_TOLERANCIA: Correspondência exata entre valor e vencimento do título e do boleto..
• AUTOMATICA_POR_TOLERANCIA_VALOR: Valor do boleto dentro da faixa de tolerância configurada.
• AUTOMATICA_POR_TOLERANCIA_VENCIMENTO: Data de vencimento do boleto dentro da faixa de tolerância configurada.
• AUTOMATICA_POR_TOLERANCIA_VALOR_E_VENCIMENTO: Ambas as tolerâncias (valor e vencimento) foram aplicadas na conciliação.
• AUTOMATICA_POR_OUTRA_FILIAL: Boleto foi associado a título de outra filial pelo CNPJ.
• AUTOMATICA_POR_RAIZ_CNPJ: Associação realizada pela raiz do CNPJ do fornecedor.
• ASSOCIADO_MANUALMENTE: Usuário realizou a associação manualmente através da tela de Gestão DDA.
• NAO_ASSOCIADO: Título foi enviado mas não encontrou boleto correspondente.
• IGNORADO: Título foi marcado como ignorado no fluxo de associação.
• DESASSOCIADO: Título que teve a associação desfeita após ter sido previamente associado.

• company (object): Empresa relacionada ao evento, identificada pelo id. Campo opcional (pode ser nulo).
• branch (object): Filial relacionada ao evento, identificada pelo id. Campo opcional (pode ser nulo).
• disassociatedDebts (array): Lista de títulos desassociados, contendo apenas accountPayableId, accountPayableNumber e accountPayableType, utilizados para localizar o título.

{
	"company": { "id": "UUID empresa (opcional)" },
	"branch": { "id": "UUID filial (opcional)" },
	"disassociatedDebts": [
		{
			"accountPayableId": "UUID do título",
			"accountPayableNumber": "número do título",
			"accountPayableType": "tipo do título"
		}
	]
}

• "A lista de títulos é obrigatória": o campo accountsPayable está vazio, nulo ou não foi informado. Envie pelo menos um título no array;
• "Não é permitido informar mais de 100 títulos por requisição": o array accountsPayable contém mais de 100 itens. Divida a requisição em múltiplos envios, cada um com até 100 títulos;
• "Existem títulos com o mesmo identificador na requisição: {id}": há duplicata de accountPayableId na mesma requisição. Remova os IDs duplicados do array;
• "O identificador do título {id} não é um UUID válido": o campo accountPayableId não segue o formato UUID. Gere um UUID válido (ex.: 550e8400-e29b-41d4-a716-446655440000);
• "O número do documento do favorecido do título {id} é inválido": o CPF/CNPJ possui dígitos incorretos ou formato inválido. Valide o CPF (11 dígitos) ou CNPJ (14 dígitos) com dígito verificador correto;
• "O documento da filial (CNPJ) é obrigatório": o campo branch.documentNumber não foi informado. Informe o CNPJ da filial com 14 dígitos;
• "O documento da filial (CPF/CNPJ) é inválido": o CNPJ possui dígitos incorretos ou formato inválido. Valide o CNPJ com dígito verificador correto;
• "Filial não encontrada para o documento informado": o CNPJ não está cadastrado na tabela e070fil do Banking. Verifique se a filial foi registrada no módulo Banking com o CNPJ correto;
• "O identificador do processo não é um UUID válido": o campo processId não segue o formato UUID ou está ausente. Gere ou informe um UUID válido para o processId.