API Recibo de Pagamento de Cana por Fazenda

Contexto

A API de Recibo de Pagamento de Cana por Fazenda tem como objetivo disponibilizar a consulta das informações consolidadas de pagamento de cana, organizadas por fazenda e período de referência.
Por meio dessa API, é possível acessar dados como valores pagos, descontos, deduções e totais processados, assegurando transparência e rastreabilidade nas operações de pagamento.

Integrada ao TOTVS Agro API-Hub, a API garante padronização, segurança e atualização em tempo real, facilitando a integração com sistemas parceiros e o acompanhamento detalhado das movimentações por fazenda.

Estruturas:

Atributos	Descrição	Tipo	Observação
instancia	Identificador da instância	String
fgTpFolha	Tipo da folha	String	F - FOLHA MENSAL DE FORNECEDOR P - FOLHA MENSAL DE PARCERIA T - FOLHA MENSAL DE TERCEIROS A - FOLHA ANUAL DE FORNECEDOR B - FOLHA ANUAL DE PARCERIA G - FOLHA ANUAL DE TERCEIROS C - FOLHA FINAL DE FORNECEDOR D - FOLHA FINAL DE PARCERIA H - FOLHA FINAL DE TERCEIROS
tipoFolha	Descrição do tipo de folha	String	Ex: "FOLHA ANUAL DE FORNECEDOR"
dataFornecimento	Data de fornecimento	DateTime	Formato ISO "YYYY-MM-DDTHH:MM:SS"
dataEmissao	Data de emissão	DateTime	Formato ISO
safra	Ano da safra	Integer	Ex: 2018
vlToneladaCana	Valor por tonelada de cana	Decimal	Ex: 78.2908998
qtCanaEntregue	Quantidade de cana entregue	Integer	Ex: 16532711
vlBrutoRecibo	Valor bruto do recibo	Decimal
vlAcumTaxasContrib	Valor acumulado de taxas de contribuição	Decimal	Pode ser zero
vlAcumDeducoes	Valor acumulado de deduções	Decimal	Pode ser zero
vlAcumNFPromissorias	Valor acumulado de NFs promissórias	Decimal	Pode ser zero
vlLiquidoRecibo	Valor líquido do recibo	Decimal
cdTpPropriedade	Código do tipo de propriedade	Integer
fgProcIndividual	Flag de processamento individual	String	Pode ser null
instanciaCompraDeCana	Instância de compra de cana	String
cdEmpresaCompraDeCana	Código da empresa de compra de cana	String
noContratoCana	Número do contrato de cana	Integer
pcPagamento	Percentual de pagamento	Decimal	Pode ser null
fgTipoSuspensaoPagamento	Flag tipo de suspensão	String	Pode ser null
cdUsuarioInclusao	Usuário de inclusão	String	Ex: "TOTVS"
dtHrInclusao	Data/hora inclusão	DateTime	Formato ISO
cdUsuarioAlteracao	Usuário de alteração	String	Pode ser null
dtHtAlteracao	Data/hora alteração	DateTime	Pode ser null
fgStatusIntegracao	Status de integração	String	Pode ser null
fluxoCaixa	Fluxo de caixa associado	String	Parâmetro: Seção: RCMP_PGTCP - Entrada: CD_TP_FLXCX_REC_DS

Seção historicoTaxas

Atributos	Descrição	Tipo	Observação
dtFimPeriodo	Fim do período da taxa	DateTime
safra	Ano da safra	Integer
fgLiminarSuspCobrancaICMS	Suspensão ICMS	String	Pode ser null
vlBaseTaxa	Base de cálculo da taxa	Decimal
dtInicioPeriodo	Início do período	DateTime
cdTaxa	Código da taxa	Integer
detalheCdTaxa	Detalhe da contribuição	Array/Object	Contém `cdTaxaContribuicao`, `fgAcertoAno`, etc.
grupoTaxaContribuicao	Grupo da taxa de contribuição	Integer
fornecedor	Código do fornecedor	Integer
upnivel1	Código do upnivel1	String
vlTaxaContribuicao	Valor da taxa de contribuição	Decimal
vlSubsidio	Valor do subsídio	Decimal	Pode ser zero
cdUsuarioAlteracao	Usuário de alteração	String	Pode ser null

Seção detalheCdTaxa (dentro de historicoTaxas)

Atributos	Descrição	Tipo	Observação
cdTaxaContribuicao	Código da taxa de contribuição	Integer
fgAcertoAno	Flag acerto anual	String	"S" ou "N"
codigoEspecie	Código da espécie	String	Ex: "ESPECIE 1"
percentualReducaoBase	Percentual redução base	Decimal	Pode ser null
cdIndiceBase	Código do índice base	Integer
dtValidadeInicial	Data de validade inicial	DateTime	Formato ISO
codigoClassificacao	Código de classificação	String	Ex: "CLAS 1"
deTaxaContribuicao	Descrição da taxa	String	Ex: "INSS"
percentualTaxaContribuicao	Percentual da taxa	Decimal	Ex: 1.3

Seção historicoDeducoesGtm

Atributos	Descrição	Tipo	Observação
cdGrupoEvento	Código do grupo do evento	Integer
dtFimPeriodo	Fim do período	DateTime
cdEvento	Código do evento	Integer
noCtaContb	Numero da Conta Contábil	Integer
fgTpFolha	Tipo de folha	String	Ex: "A"
vlDeducao	Valor da dedução	Decimal
dtInicioPeriodo	Início do período	DateTime
dtEvento	Data do evento	DateTime
cdUsuarioInclusao	Usuário de inclusão	String
cdUpnivel1	Código do upnivel1	String
cdFornecedor	Código do fornecedor	Integer
fgDedAdiant	Flag indicativa para dedução de Adiantamento	String	Ex: "S" ou "N"

Seção infoUpnivel1

Atributos	Descrição	Tipo	Observação
cdUpnivel1	Código upnivel1	String
deUpnivel1	Descrição upnivel1	String
cdFornec	Código do fornecedor	Integer
fgTpPess	Tipo de pessoa	String	"J" ou "F"
cdIntErp	Código ERP	String

Seção infoFornecs

Atributos	Descrição	Tipo	Observação
cdFornec	Código do fornecedor	Integer
deFornec	Descrição do fornecedor	String
fgTpFornec	Tipo de fornecedor	String	1 - ACIONISTA 2 - FORNECEDOR 3 - EVENTUAL 4 - PROPRIO 5 - PARCEIRO
deTpFornec	Descrição tipo fornecedor	String	Ex: "PROPRIO"
fgTpPess	Tipo de pessoa	String	"J" ou "F"
cdIntErp	Código ERP	String

Seção notasFiscais

Atributos	Descrição	Tipo	Observação
cdSerieNf	Código da série NF	String
noNf	Número da Nota Fiscal	Integer

Método GET:

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

Estrutura de dados:

Recibo de Pagamento de Cana por Fazenda

{
   "hasNext":true,
   "items":[
      {
         "instancia":"1",
         "fgTpFolha":"A",
         "tipoFolha":"FOLHA ANUAL DE FORNECEDOR",
         "dataFornecimento":"2018-08-01T00:00:00",
         "dataEmissao":"2018-08-10T00:00:00",
         "safra":2018,
         "vlToneladaCana":78.2908998,
         "qtCanaEntregue":16532711,
         "vlBrutoRecibo":1294360.82,
         "vlAcumTaxasContrib":0,
         "vlAcumDeducoes":0,
         "vlAcumNFPromissorias":0,
         "vlLiquidoRecibo":1294360.82,
         "cdTpPropriedade":2,
         "fgProcIndividual":null,
         "instanciaCompraDeCana":"1",
         "cdEmpresaCompraDeCana":"1",
         "noContratoCana":2861,
         "pcPagamento":null,
         "fgTipoSuspensaoPagamento":null,
         "cdUsuarioInclusao":"TOTVS",
         "dtHrInclusao":"2025-09-24T12:55:50",
         "cdUsuarioAlteracao":null,
         "dtHtAlteracao":null,
         "fgStatusIntegracao":null,
         "fluxoCaixa":"RCMP - FLXCX - REC",
         "historicoTaxas":[
            {
               "dtFimPeriodo":"2018-08-31T00:00:00",
               "safra":2016,
               "fgLiminarSuspCobrancaICMS":null,
               "vlBaseTaxa":944.86,
               "dtInicioPeriodo":"2018-08-01T00:00:00",
               "dtHtAlteracao":null,
               "cdTaxa":1,
               "cdUsuarioInclusao":null,
               "instancia":"1",
               "dtHrInclusao":null,
               "detalheCdTaxa":[
                  {
                     "cdTaxaContribuicao":1,
                     "fgAcertoAno":"S",
                     "codigoEspecie":"ESPECIE 1",
                     "percentualReducaoBase":null,
                     "cdIndiceBase":950,
                     "cdTxErp":null,
                     "dtValidadeInicial":"2015-10-01T00:00:00",
                     "codigoClassificacao":"CLAS 1",
                     "deTaxaContribuicao":"INSS",
                     "percentualTaxaContribuicao":1.3
                  }
               ],
               "grupoTaxaContribuicao":1,
               "fgAcertoAnual":null,
               "fornecedor":319,
               "upnivel1":" 10094",
               "vlTaxaContribuicao":19.84,
               "vlSubsidio":0,
               "cdUsuarioAlteracao":null
            },
            {
               "dtFimPeriodo":"2018-08-31T00:00:00",
               "safra":2016,
               "fgLiminarSuspCobrancaICMS":null,
               "vlBaseTaxa":944.86,
               "dtInicioPeriodo":"2018-08-01T00:00:00",
               "dtHtAlteracao":null,
               "cdTaxa":2,
               "cdUsuarioInclusao":null,
               "instancia":"1",
               "dtHrInclusao":null,
               "detalheCdTaxa":[
                  {
                     "cdTaxaContribuicao":2,
                     "fgAcertoAno":"S",
                     "codigoEspecie":"ESPECIE 2",
                     "percentualReducaoBase":null,
                     "cdIndiceBase":950,
                     "cdTxErp":null,
                     "dtValidadeInicial":"2015-10-01T00:00:00",
                     "codigoClassificacao":"CLAS 2",
                     "deTaxaContribuicao":"SENAR",
                     "percentualTaxaContribuicao":0.2
                  }
               ],
               "grupoTaxaContribuicao":1,
               "fgAcertoAnual":null,
               "fornecedor":319,
               "upnivel1":" 10094",
               "vlTaxaContribuicao":1.87,
               "vlSubsidio":0,
               "cdUsuarioAlteracao":null
            }
         ],
         "historicoDeducoesGtm":[
            {
               "cdGrupoEvento":1,
               "dtFimPeriodo":"2018-08-31T00:00:00",
               "cdEvento":101,
               "noCtaContb":"110",
               "fgTpFolha":"A",
               "vlDeducao":132,
               "dtInicioPeriodo":"2018-08-01T00:00:00",
               "dtHtAlteracao":null,
               "dtEvento":"2016-05-29T00:00:00",
               "cdUsuarioInclusao":"TOTVS",
               "fgProcessaIndividual":null,
               "instancia":"1",
               "dtHrInclusao":"2025-08-05T14:34:34",
               "cdUpnivel1":" 10094",
               "cdUsuarioAlteracao":null,
               "cdFornecedor":319,
               "fgDedAdiant":"N"
            }
         ],
         "infoUpnivel1":[
            {
               "cdUpnivel1":" 10094",
               "deUpnivel1":"FAZENDA TOTVS  10094",
               "cdFornec":319,
               "fgTpPess":"J",
               "cdIntErp":"1_600_94"
            }
         ],
         "infoFornecs":[
            {
               "cdFornec":319,
               "deFornec":"FORNECEDOR TOTVS 2",
               "fgTpFornec":"4",
               "deTpFornec":"PROPRIO",
               "fgTpPess":"J",
               "cdIntErp":"319"
            }
         ],
         "notasFiscais":[
            {
               "cdSerieNf":"UN",
               "noNf":50001
            }
         ]
      }
   ]
}

Parâmetros Obrigatórios

instancia: Código da Instância.
dtFornecimentoInicial: Data de Fornecimento Inicial (atributo AM_FORNEC).
dtFornecimentoFinal: Data de Fornecimento Final (atributo AM_FORNEC).

Parâmetros Opcionais

fgTpProc: Flag Controlador de Tipo de Processo.
cdFornecedor: Código do Fornecedor.
cdUpnivel1: Código do Upnivel1 (Fazenda, por exemplo).

Atualizar status de integração - Recibos de Pagamento de Cana por Fazenda

Disponibilizado endpoint para atualizar status de integração dos registros relacionados aos Recibos de Pagamento de Cana por Fazenda.

Método PUT:

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

Body da Requisição - Recibo de Pagamento de Cana por Fazenda

{
  "fgStatusIntegracao":"S",
  "instancia": "1",
  "fgTpProc": "F",
  "cdFornecedor": 96096,
  "cdUpnivel1":" 20402",
  "dataFornecimento": "2016-07-01T00: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 Folha por Fundo Agrícola":

Seção: RCMP_PGTCP
Entrada: CD_CAD_STATUS_INT_FFAZ

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

Páginas filhas

API Recibo de Pagamento de Cana por Fazenda

Contexto

Parâmetros Obrigatórios

Parâmetros Opcionais

Atualizar status de integração - Recibos de Pagamento de Cana por Fazenda