ERP senior X > Integrações via API > Integração títulos de contas a pagar via API

Integração de títulos de contas a pagar via API

A geração de títulos de contas a pagar no ambiente do Senior X pode ser realizada por meio de chamadas às APIs públicas. Esse recurso oferece maior flexibilidade, permitindo automatizar processos financeiros e integrar soluções externas ao ERP.

Este documento é direcionado a parceiros e usuários técnicos interessados em integrar-se ao ERP da Senior, com foco específico no módulo Financeiro para a criação e reprocessamento de títulos de contas a pagar.

Antes de iniciar o processo de integração, recomenda-se a leitura dos tutoriais básicos sobre consumo de APIs da Senior.

Autenticação

Assim como as demais APIs da Senior, a integração de títulos de contas a pagar exige autenticação por meio da primitiva loginWithKey. Esse processo gera o token necessário para acessar os serviços da plataforma Senior X.

Geração de títulos de contas a pagar

A criação ou reprocessamento de títulos de contas a pagar ocorre de forma assíncrona. Isso significa que, após a requisição, o sistema valida a estrutura básica e retorna imediatamente um ticket para acompanhamento. O processamento real acontece em segundo plano e o resultado é publicado por meio de eventos de sucesso ou erro.

A criação de título de contas a pagar é iniciada por meio de uma requisição POST:

https://api.senior.com.br/erpx_fin_int/facade/apis/saveAccountsPayableTitles

Para utilizar essa funcionalidade, é fundamental que todos os pré-requisitos estejam devidamente configurados.

Header: No cabeçalho da requisição, é obrigatório incluir dois parâmetros: authorization e client_id.

O client_id é utilizado para identificar a aplicação que está se conectando. Caso ainda não tenha sido cadastrado conforme especificado nos pré-requisitos, realize o processo seguindo as instruções do tutorial do artigo Criando uma Aplicação, disponível no portal de APIs da Senior;

Body: No corpo da requisição, é possível enviar diversos parâmetros, alguns obrigatórios e outros opcionais. Um exemplo completo, incluindo o uso e a descrição dos campos das APIs, pode ser consultado no portal de APIs da Senior.

Parâmetros

Os parâmetros são organizados em categorias para facilitar a configuração:

Estrutura

Propriedade	Tipo	Obrigatório	Descrição
id	string (UUID)	Não	Identificador de controle opcional da requisição.
financialBatchReprocessingId	string	Não	Identificador de um lote financeiro existente para fins de reprocessamento.
titles	array de objetos	Sim	Lista contendo as definições dos títulos de contas a pagar a serem criados.

Dados de identificação

Campo	Tipo do Objeto	Obrigatório	Campos Internos Aceitos
company	companyIdentifier	Sim	id (string - UUID) code (integer, mínimo 0 e máximo 9999) Pelo menos um deve ser informado.
branch	branchIdentifier	Sim	id (string - UUID) code (integer, mínimo 0 e máximo 9999) documentNumber (string - CNPJ/CPF com 14 caracteres) nifNumber (string - Identificação Fiscal com até 40 caracteres) Pelo menos um deve ser informado.
supplier	personIdentifier	Sim	Fornecedor do título. id (string - UUID) code (integer) documentNumber (CNPJ/CPF) ou nifNumber. Pelo menos um deve ser informado.
titleType	titleTypeIdentifier	Sim	Tipo de Título id (string - UUID) code (string) Ex: NFC (Nota Fiscal de Compra), IMP (Impostos), OUT (Outros Tipos), ADF (Adiantamento a Fornecedor), ADV (Adiantamento Viagem).
transaction	genericIdCode	Sim	Transação. id (string - UUID) code (string) Ex: 90500.
bearer	genericIdCode	Sim	Portador do título. id (string - UUID) code (string) Ex: 999 (Portador Empresa).
beneficiary	personIdentifier	Não	Favorecido do título. id (string - UUID) code (integer) documentNumber (string - CNPJ/CPF) nifNumber (string) Aceita os mesmos campos de supplier.
financialAccount	genericIdCode	Não	Conta Financeira. id (string - UUID) code (string)
costCenter	genericIdCode	Não	Centro de Custo. id (string - UUID) code (string)
accountsPayableGroup	genericIdCode	Não	Grupo de Contas a Pagarid (string - UUID) code (string)
baseCurrency	genericIdCode	Não	Moeda Base. id (string - UUID) code (string)
extensionReason	genericIdCode	Não	Motivo de Prorrogação. id (string - UUID) code (string)
paymentMethod	genericIdCode	Não	Forma de Pagamento. id (string - UUID) code (string)
wallet	genericIdCode	Não	Carteira. id (string - UUID) code (string)
previousBearer	genericIdCode	Não	Portador Anterior. id (string - UUID) code (string)
previousWallet	genericIdCode	Não	Carteira Anterior. id (string - UUID) code (string)
forecastTransaction	genericIdCode	Não	Transação de Previsão. id (string - UUID) code (string)

Informações gerais do título

Propriedade	Tipo	Obrigatório	Validações/Limites	Descrição
id	string	Não	Deve ser um UUID válido.	ID da entidade para atualização ou controle.
titleNumber	string	Sim	Máximo de 15 caracteres.	Número identificador do título.
financialFact	string	Não	Livre.	Identificador do fato financeiro do título.
observation	string	Não	Máximo de 250 caracteres.	Observações adicionais do título.
situation	string	Sim	Livre.	Situação do título. Ex.: VAB (Aberto Normal).
taxationCode	string	Não	Máximo de 5 caracteres.	Código de tributação para DARF.
bankTitleNumber	string	Não	Máximo de 20 caracteres.	Número do título gerado ou registrado no banco.
titlePaymentPriority	integer	Não	Mínimo: 0. Máximo: 999999999.	Nível de prioridade para pagamento do título.
situationResponsibleUser	integer	Não	Mínimo: 0.	Código do usuário responsável pela situação atual.
previousSituation	string	Não	Livre.	Situação anterior do título.
adjustmentFormula	string	Não	Livre.	Fórmula para reajuste do título.
negotiatedValuesUser	integer	Não	Mínimo: 0.	Usuário que negociou os valores.
effectuationType	string	Não	Livre.	Tipo de efetivação do título.
bankFileNumber	integer	Não	Mínimo: 0. Máximo: 999999999.	Número do arquivo bancário de remessa ou retorno.
taxType	string	Não	Livre.	Tipo de imposto associado.
generatedPaymentReversalTitle	boolean	Não	`true` ou `false`.	Indica se foi gerado título de estorno de pagamento.
generatedEntryTax	boolean	Não	`true` ou `false`.	Indica se foi gerado imposto na entrada.

Datas

Todos os campos de data devem seguir o formato internacional YYYY-MM-DD.

Propriedade	Tipo	Obrigatório	Descrição
issueDate	date	Sim	Data de emissão do título.
entryDate	date	Sim	Data de entrada do título no sistema.
originalDueDate	date	Sim	Data de vencimento original.
extendedDueDate	date	Não	Data de vencimento prorrogado.
probablePaymentDate	date	Sim	Data provável em que o pagamento será efetuado.
negotiatedValuesDate	date	Não	Data em que os valores foram renegociados.
discountDate	date	Não	Data limite para obtenção de desconto.
lastInterestCalculationDate	date	Não	Data do último cálculo de juros realizado.
lastPaymentDate	date	Não	Data do último pagamento efetuado.
lastValuatedQuotationDate	date	Não	Data da última cotação valorizada.
forecastEntryDate	date	Não	Data de entrada da previsão do título.

Valores financeiros e cotações

Propriedade	Tipo	Obrigatório	Validações / Limites	Descrição
originalValue	decimal	Sim	Mínimo: 0.00. Máximo: 9999999999999.99.	Valor original do título.
openValue	decimal	Não	Mínimo: 0.00. Máximo: 9999999999999.99.	Valor que permanece em aberto.
negotiatedInterestValue	decimal	Não	Mínimo: 0.00. Máximo: 9999999999999.99.	Valor de juros negociado.
negotiatedFineValue	decimal	Não	Mínimo: 0.00. Máximo: 9999999999999.99.	Valor de multa negociado.
negotiatedDiscountValue	decimal	Não	Mínimo: 0.00. Máximo: 9999999999999.99.	Valor de desconto negociado.
otherNegotiated	decimal	Não	Mínimo: 0.00. Máximo: 9999999999999.99.	Outros valores negociados.
negotiatedCurrencyQuotation	double	Não	Mínimo: 0.00. Máximo: 999999999.9999999999.	Taxa de cotação da moeda negociada.
issueCurrencyQuotation	decimal	Não	Mínimo: 0.00. Máximo: 999999999.9999999999.	Taxa de cotação da moeda na data de emissão.
correctionsControl	double	Não	Mínimo: 0.00. Máximo: 9999999999999.99.	Valor de controle de correções monetárias.
lastValuationQuotation	double	Não	Mínimo: 0.00. Máximo: 999999999.9999999999.	Cotação na última valorização.
forecastValue	decimal	Não	Mínimo: 0.00. Máximo: 9999999999999.99.	Valor previsto do título.

Multa, juros e descontos

Propriedade	Tipo	Obrigatório	Validações / Limites	Descrição
extensionWithInterest	boolean	Sim	`true` ou `false`.	Define se a prorrogação do título será realizada com juros.
calculateAdvanceDiscount	boolean	Não	`true` ou `false`.	Indica se calcula desconto por antecipação.
discountTolerance	integer	Não	Mínimo: -9999. Máximo: 9999.	Dias de tolerância para aplicação do desconto.
discountPercentage	double	Não	Mínimo: 0.00. Máximo: 999.99.	Percentual de desconto a ser aplicado.
discountValue	decimal	Não	Mínimo: 0.00. Máximo: 9999999999999.99.	Valor absoluto de desconto.
finePercentage	double	Não	Mínimo: 0.00. Máximo: 999.99.	Percentual de multa por atraso.
fineToleranceDays	integer	Não	Mínimo: 0. Máximo: 9999.	Dias de carência ou tolerância para aplicação da multa.
dailyInterestValue	double	Não	Mínimo: 0.00. Máximo: 9999999.99.	Valor diário de juros de mora em valor absoluto.
interestPercentage	double	Não	Mínimo: 0.00. Máximo: 999.99.	Percentual de juros de mora.
interestType	string	Não	Livre. Exemplos: `SIMPLE_INTEREST`, `COMPOUND_INTEREST`.	Tipo de cálculo de juros.
interestToleranceDays	integer	Não	Mínimo: 0. Máximo: 9999.	Dias de carência ou tolerância antes da cobrança de juros.

Exemplo prático de request

Veja abaixo um exemplo simplificado de requisição para criação de título de contas a pagar:

{
		"id": "a7b7c251-1d54-4bb5-86d3-9fa7e1cc26c0",	
		"titles":[
		{
		"company":{
			"code": 1
		},

		"branch":{
			"code": 1
		},
		"titleNumber": "TIT-998823",
		"titleType":{
			"code": "NFC"
		},
		"supplier":{
			"documentNumber": "82951229000176"
		},
		"beneficiary":{
			"documentNumber":"87934675000196"
		},
		"transaction":{
		"code": "90500"
 		},
		"bearer":{
			"code": "999"
		},

		"situation": "VAB",
		"issueDate": "2026-05-28",
		"entryDate": "2026-05-28",
		"originalDueDate": "2026-06-30",
		"probablePaymentDate": "2026-06-30",
		"originalValue": 1500.50,
		"extensionWithInterest": false,
		"observation": "Título de teste via API pública"
		}
	]
}

Respostas da API

Sucesso - 201 Created: Retorna quando a requisição passa pelas validações básicas de formato e os registros são encaminhados para a fila de processamento assíncrono.

{
	"ticket": "85ef27b2-84fc-4876-8051-fb1bf482ea7c"
}

Inválida - 400 Bad Request: Ocorre quando algum campo obrigatório não é fornecido ou viola as regras (Exemplo: UUID inválido, valor menor que zero, strings muito longas).

{
	"reason":"BAD_REQUEST", 
	"message":"Identificador da empresa é obrigatório"

}

Importante

O retorno imediato não confirma o registro do título, mas apenas o início do processo de integração. O resultado final será informado por meio de eventos assíncronos.

Processamento assíncrono

O processo de geração de títulos de contas a pagar ocorre de forma assíncrona. Isso significa que, após a requisição, o sistema retorna imediatamente um ticket para acompanhamento. O processamento real acontece em segundo plano e o resultado é publicado por meio de eventos específicos.

Importante

O ticket é apenas um identificador do processo de integração. O título só será efetivamente registrado após a conclusão do processamento assíncrono.

Eventos de retorno

Após o envio da requisição, o sistema publica eventos que informam o resultado do processamento:

Resumo de fluxo completo

O fluxo de integração pode ser resumido em três etapas principais:

Envio da requisição: O usuário envia os dados do título via API.
Retorno imediato: O sistema valida a estrutura e retorna um ticket.
Processamento assíncrono: O sistema publica eventos de sucesso ou erro, informando o resultado final.

Cadastros necessários

Para que a integração funcione corretamente, é necessário que alguns cadastros básicos já estejam realizados no ERP Senior X:

Cadastro de fornecedor: Utilizado para vincular o título ao responsável pelo pagamento.
Cadastro de transação financeira: Necessário para identificar o tipo de operação.
Cadastro de portador: Define a entidade responsável pelo título.

Esses cadastros podem ser realizados diretamente no ERP ou via APIs disponíveis no portal de APIs da Senior.

Consulte também a documentação de outras APIs financeiras para ampliar a integração com o ERP Senior X.

PORTAL DE DOCUMENTAÇÃO
Gestão Empresarial \| ERP senior X