API Pagamento de Serviços de Terceiro

Contexto Geral

API de consulta a pagamentos de serviços (prestadores/terceiros) para uso em portais, integrações e relatórios. Retorna uma lista paginável com informações financeiras, operacionais e de referência (contrato, centro de custos, município, fornecedor, transportador etc.).

Base URL: ip:porta/api/query/v1/pagtoServicoTerceiro
Método: GET
Conteúdo: application/json
Paginação: campo hasNext no retorno indica se há mais páginas.
Autenticação: conforme seu padrão (ex.: OAuth2 do API-Hub TOTVS).

Estruturas:

Principais campos
Campo	Tipo	Exemplo	Descrição
instancia	string	1	Identificador da Instância.
dtIniSint	datetime	2016-03-01T00:00:00	Data/hora inicial da síntese/período do pagamento.
dtFimSint	datetime	2016-03-31T00:00:00	Data/hora final da síntese/período do pagamento.
cdEmprErp	string	10	Código da empresa no ERP.
cdUnegErp	string	100	Código da unidade de negócio no ERP.
cdEvtoErp	string	18	Código do evento no ERP.
cdEvtoFat	number	18	Código do evento de faturamento.
cdProcesso	number	1	Código do Processo
fgExpErp	string	N	Flag indicando exportação ao ERP.
qtMat	number	1	Quantidade de materiais/itens vinculados.
cdTranspErp	string	85340	Código do transportador no ERP.
vlBruto	number	4824.07	Valor bruto do pagamento.
vlDesconto	number	0	Total de descontos aplicados.
vlLiquido	number	4824.07	Valor líquido após descontos.
cdCcustoErp	string	1_01010802	Centro de custo no ERP.
cdUniEvto	string	HR	Unidade do evento.
cdMunicIbge	string	3501004	Código do município (IBGE).
cdContratoErp	string	2478	Código do contrato no ERP.
cdContrato	string	1000000002478	Código do contrato (negócio).
deEvtoFat	string	CARREG.MECÂNICO (HM)	Descrição do evento de faturamento.
fgEvtoMunic	string	N	Flag se o evento municipal.
cdCcusto	number	101010802	Centro de custo.
cdMunic	number	5	Código do município.
cdFornec	number	319	Código do fornecedor.
dtPagto	string	2016-04-11T03:00:00.000+00:00	Data do Pagamento.

Campos internos
Estrutura	Campos Internos	Exemplo	Descrição
cdTransp	cdTransp (number), deTransp (string)	[{'cdTransp': 85340, 'deTransp': 'MAURICIO ...'}]	Dados do prestador.
cdUpnivel1	fazenda (string), cdFornec (number), deUpnivel1 (string), tpPessoa (string), cdIntErp (string)	[{'fazenda':'10455','cdFornec':319,...}]	Unidade produtiva (nível 1) vinculada ao serviço.
cdOperacao	cdOperacao (number), deOperacao (string), cdIntErp (string)	[{'cdOperacao':18,'deOperacao':'CARREG. MECÂNICO',...}]	Operação executada (código e descrição).
cCusto	cdCcusto (number), deCcustos (string), cdIntErp (string)	[{'cdCcusto':101010802,'deCcustos':'APLIC. TORTA ...'}]	Detalhes do centro de custos.
municipio	cdMunic (number), deMunic (string)	[{'cdMunic':5,'deMunic':'ALTINÓPOLIS'}]	Informações do município.
Fornecedor	cdFornec (number), deFornec (string), cdIntErp (string), fgTpFornecs (string), cdTrans (number\|null), fgAtivo (string), noCgcCpf (string)	[{'cdFornec':319,'deFornec':'FORNECEDOR TOTVS 2',...}]	Dados do fornecedor.

Método GET:

http:127.0.0.1:8080/api/query/v1/pagtoServicoTerceiro

Estrutura de dados:

Pagamento de Serviço de Terceiro

 {
    "hasNext": false,
    "items": [
        {
            "instancia": "1",
            "dtIniSint": "2016-03-01T00:00:00",
            "dtFimSint": "2016-03-31T00:00:00",
            "cdEmprErp": "10",
            "cdUnegErp": "100",
            "cdEvtoErp": "18",
            "cdEvtoFat": 18,
		    "cdProcesso": 1,
            "fgExpErp": "N",
            "qtMat": 1,
            "cdTranspErp": "85340",
            "cdTransp": [
                {
                    "cdTransp": 85340,
                    "deTransp": "TOTVS - SA"
                }
            ],
            "vlBruto": 4824.07,
            "vlDesconto": 0,
            "vlLiquido": 4824.07,
            "cdCcustoErp": "1_01010802",
            "cdUniEvto": "HR",
            "cdMunicIbge": "3501004",
            "cdUpnivel1": [
                {
                    "fazenda": " 10455",
                    "cdFornec": 319,
                    "deUpnivel1": "FAZENDA TOTVS  10455",
                    "tpPessoa": "J",
                    "cdIntErp": "1_600_455"
                }
            ],
            "cdContratoErp": "2478",
            "cdContrato": "1000000002478",
            "deEvtoFat": "CARREG.MECÂNICO (HM)",
            "fgEvtoMunic": "N",
            "cdOperacao": [
                {
                    "cdOperacao": 18,
                    "deOperacao": "CARREG. MECÂNICO",
                    "cdIntErp": "18"
                }
            ],
            "cdCcusto": 101010802,
            "cdMunic": 5,
            "cdFornec": 319,
			"dtPagto": "2016-04-11T03:00:00.000+00:00",         
			"cCusto": [
                {
                    "cdCcusto": 101010802,
                    "deCcustos": "APLIC. TORTA F. PLAN MEC.",
                    "cdIntErp": "1_01010802"
                }
            ],
            "municipio": [
                {
                    "cdMunic": 5,
                    "deMunic": "ALTINÓPOLIS"
                }
            ],
            "Fornecedor": [
                {
                    "cdFornec": 319,
                    "deFornec": "FORNECEDOR TOTVS 2",
                    "cdIntErp": "319",
                    "fgTpFornecs": "4",
                    "cdTrans": null,
                    "fgAtivo": "S",
                    "noCgcCpf": "87.870.952/0014-69"
                 }
            ]
        },
        
    ]
}

Parâmetros de consulta

Obrigatórios

instancia (string) – Identifica ambiente.
dtPagto (date/datetime) – Data de pagamento para filtro (2016-03-01T00:00:00).

Opcionais

cdContrato (string) – Código do contrato.
cdFornec (number) – Código do fornecedor.
cdTransp (number) – Código do transportador (prestador).
cdProcesso (number) – Código do Processo.
fgStatusIntegracao (string) – Flag de busca das integrações. O valor "nulo" refere-se a registros nunca integrados. Exemplo: 1;2;3;nulo;5

Atualizar status de integração - Pagamento de Serviços (Prestadores/Terceiros)

Disponibilizado endpoint para atualização do status de integração dos registros de Pagamento de Serviços (Prestadores/Terceiros), considerando o retorno do processamento de integração e as regras de bloqueio de reversões definidas no módulo Bioenergia.

Estrutura:

Campo	Tipo	Obrigatório	Descrição
fgStatusIntegracao	String(1)	Sim	Flag do status de integração.
instancia	String	Sim	Identificador da instância
cdProcesso	Integer	Sim	Código do processo de integração vinculado ao pagamento.
dataIniSintet	DateTime	Sim	Data inicial do período sintético do pagamento.
dataFimSintet	DateTime	Sim	Data final do período sintético do pagamento.
dataPagto	DateTime	Opcional	Data de efetivação do pagamento.
dataRetencaoMensal	DateTime	Opcional	Data de retenção mensal do pagamento (quando aplicável).
dataRetencaoAnual	DateTime	Opcional	Data de retenção anual do pagamento (quando aplicável).

Método PUT:

http:127.0.0.1:8080/api/entity/v1/pagamentoServico

Request

 {              
 	fgStatusIntegracao": "1",
  	"instancia": "1",
  	"cdProcesso": 1,
  	"dataIniSintet": "2016-06-01T00:00:00",
  	"dataFimSintet": "2016-06-30T00:00:00",
  	"dataPagto": "2016-07-11T00:00:00",
  	"dataRetencaoMensal": "2016-07-11T00:00:00",
  	"dataRetencaoAnual": "2016-07-11T00:00:00"
}

Bloqueio da Reversão de Processamentos que apresentem registros já integrados com outros sistemas

Com o objetivo de assegurar a consistência das informações integradas com outros sistemas, foi desenvolvido uma nova funcionalidade dentro da aplicação Configuração Central (CFGCEN/ TOTVS Agro Bioenergia), onde será possível realizar o cadastro de rotinas executadas pelo TOTVS Agro Bioenergia e indicar os possíveis "status de integração" vindos de sistemas externos (que estejam integrados ao TOTVS Agro Bioenergia).

Para cada status indicado, será possível apontar se será permitido ou não a reversão do processo em questão.

Visando possibilitar a indicação de diferentes cadastros para diferentes processamentos disponíveis em nosso sistema, foram criados parâmetros específicos para cada rotina,
onde o usuário deverá determinar qual cadastro deverá ser consultado no momento de realizar a reversão do processamento.

Importante frisar que, caso um ou mais registros apresentem um status onde esteja apontado o impedimento para reversão, o processamento será interrompido, impedindo a execução da reversão para todos os registros envolvidos.

Parâmetro "Código do cadastro de controle de status para Pagamento de Serviços de Terceiro":

Seção: CBSVCOSA;
Entrada: CD_CAD_STATUS_INT_PGSERV;

Para mais detalhes sobre a funcionalidade citada acima, acesse a página Cadastro de Bloqueio de Movimentações via API.

Páginas filhas