Guia de Integração Paggo × SAP

1. Introdução

A Paggo é a camada financeira sobre o ERP do cliente. Lemos os títulos a pagar e a receber, executamos os pagamentos e a emissão de cobranças, e devolvemos as confirmações para o ERP escriturar a movimentação. Este guia descreve, por fluxo, quais dados precisamos consumir e em quais momentos a Paggo escreve de volta no ERP.

Este documento é uma orientação geral, não uma especificação rígida. Os endpoints listados aqui descrevem o modelo de referência que usamos com outros ERPs. O SAP não precisa replicar nome de rota, formato de payload ou estrutura de campo idênticos. O que importa é que existam endpoints análogos, capazes de cobrir os mesmos dados e operações. Se a forma como o SAP expõe esses dados divergir estruturalmente do que está aqui, conseguimos adaptar o lado da Paggo.

A integração cobre dois fluxos:

Contas a Pagar: a Paggo lê os fornecedores e títulos a pagar do ERP, executa o pagamento (via PIX, TED ou boleto) e devolve a confirmação da baixa para o ERP escriturar.
Contas a Receber: a Paggo lê os contratos de venda, clientes e parcelas a receber, emite boleto/PIX para o pagador final, e devolve a baixa quando o pagamento é recebido.

As listagens de dados-mestre e de títulos devem ser paginadas e suportar sincronização incremental por data de alteração, para que a Paggo não precise reler todo o histórico em cada ciclo. A forma como o ERP expõe paginação e filtros pode seguir o padrão natural do SAP.

Os blocos a seguir estão organizados em três seções: Configuração reúne os dados-mestre comuns aos dois fluxos (empresas, obras, contas-correntes, plano financeiro); Contas a Pagar e Contas a Receber trazem os dados e operações específicos de cada fluxo. Cada endpoint pode ser expandido para ver a tabela de campos esperada na resposta.

2. Configuração

Endpoints somente-leitura usados nos dois fluxos. A Paggo consome estes recursos para descobrir as estruturas (empresa, obra, conta corrente, plano financeiro) e classificar corretamente os lançamentos.

Endpoint	Recurso
`GET /companies`	Empresas
`GET /enterprises`	Empreendimentos (Obras)
`GET /cost-centers`	Centros de Custo
`GET /checking-accounts`	Contas-correntes
`GET /payment-categories`	Planos Financeiros
`GET /payment-types`	Formas de pagamento
`GET /document-types`	Tipos de documento

GET/companiesEmpresas

Lista todas as empresas (entidades legais com CNPJ próprio). É o ponto de partida do onboarding; cada empresa é referenciada por todos os demais recursos.

Query params

Parâmetro	Descrição
`page`	Número da página (default `1`).
`pageSize`	Quantidade de itens por página.
`updatedSince`	ISO-8601. Retorna apenas registros alterados a partir da data informada.
`includeInactive`	Quando `true`, inclui empresas inativas. Default `false`.

Resposta esperada

Campo	Descrição
`id`	Identificador único da empresa no ERP.
`code`	Código curto da empresa (filial).
`taxId`	CNPJ formatado `XX.XXX.XXX/XXXX-XX`.
`legalName`	Razão social.
`tradeName`	Nome fantasia (pode ser vazio).
`address.street`	Logradouro da sede.
`address.number`	Número.
`address.city`	Cidade.
`address.state`	UF (sigla de 2 letras).
`address.zipCode`	CEP no formato `XXXXX-XXX`.
`active`	Indica se a empresa está ativa.
`updatedAt`	Timestamp ISO-8601 da última alteração.

GET/enterprisesEmpreendimentos (Obras)

Estrutura operacional sob cada empresa. No contexto de construtoras, equivale à obra. Cada empreendimento agrupa unidades (apartamentos, salas, lotes) e tem ciclo financeiro próprio.

Query params

Parâmetro	Descrição
`companyId`	Filtra empreendimentos por empresa proprietária.
`page`	Número da página.
`pageSize`	Quantidade de itens por página.
`updatedSince`	ISO-8601 para sync incremental.

Resposta esperada

Campo	Descrição
`id`	Identificador único do empreendimento.
`code`	Código do empreendimento.
`name`	Nome do empreendimento.
`companyId`	Empresa proprietária (referência a `/companies`).
`type`	Tipo (`RESIDENTIAL`, `COMMERCIAL`, etc.).
`startDate`	Data de início no formato `YYYY-MM-DD`.
`expectedDeliveryDate`	Data prevista de entrega.
`address.city`	Cidade.
`address.state`	UF.
`totalUnits`	Total de unidades vendáveis no empreendimento.
`active`	Empreendimento ativo.
`updatedAt`	Timestamp ISO-8601 da última alteração.

GET/cost-centersCentros de Custo

Unidade de apropriação de despesa. Pode estar vinculada a um empreendimento ou ser corporativa. Toda confirmação de pagamento referencia um centro de custo.

Resposta esperada

Campo	Descrição
`id`	Identificador único do centro de custo.
`code`	Código numérico ou alfanumérico.
`name`	Nome descritivo.
`enterpriseId`	Empreendimento vinculado, quando aplicável.
`companyId`	Empresa proprietária.
`active`	Centro de custo ativo.
`updatedAt`	Última atualização (ISO-8601).

GET/checking-accountsContas-correntes

Contas bancárias da empresa, usadas como origem de pagamentos (Contas a Pagar) e destino de recebimentos (Contas a Receber). Também é a chave para conciliação por extrato bancário.

Resposta esperada

Campo	Descrição
`id`	Identificador único da conta corrente.
`code`	Código interno da conta.
`companyId`	Empresa titular.
`bankCode`	Código FEBRABAN do banco (3 dígitos).
`bankName`	Nome do banco.
`agency`	Agência (com dígito quando aplicável).
`accountNumber`	Número da conta com dígito.
`holderTaxId`	CNPJ do titular (deve corresponder ao da empresa).
`linkedEnterpriseIds`	Lista de empreendimentos com permissão de uso da conta.
`currency`	Código ISO da moeda (default `BRL`).
`active`	Conta ativa.
`updatedAt`	Última atualização.

O campo holderTaxId é validado contra o CNPJ da empresa antes de qualquer movimentação financeira.

GET/payment-categoriesPlanos Financeiros

Plano de contas e classificação contábil. Cada lançamento financeiro é associado a uma categoria. Estrutura hierárquica (pai/filho).

Resposta esperada

Campo	Descrição
`id`	Identificador único.
`code`	Código hierárquico (ex.: `3.1.01`).
`name`	Nome da categoria.
`parentCode`	Código da categoria-pai (raiz se vazio).
`type`	`EXPENSE` (despesa) ou `REVENUE` (receita).
`active`	Categoria ativa.

GET/payment-typesFormas de pagamento

Códigos que o SAP reconhece como meio de pagamento (PIX, TED, Boleto, Dinheiro). A Paggo informa o código correto a cada baixa.

Resposta esperada

Campo	Descrição
`id`	Identificador único.
`code`	Código curto reconhecido pelo ERP (ex.: `PIX`, `TED`, `BOL`).
`name`	Nome legível.
`active`	Tipo ativo.

GET/document-typesTipos de documento

Classificação do documento financeiro (NF, NFS-e, Recibo, Boleto, Contrato). A Paggo encaminha o tipo correspondente a cada baixa.

Resposta esperada

Campo	Descrição
`id`	Identificador único.
`code`	Código (ex.: `NF`, `BOL`, `REC`).
`name`	Nome legível.
`active`	Tipo ativo.

3. Contas a Pagar

Endpoints exclusivos do fluxo de Contas a Pagar. A Paggo lê fornecedores e títulos abertos do SAP, executa o pagamento, e devolve a confirmação de baixa para o ERP escriturar a movimentação.

Endpoint	Propósito
`GET /suppliers`	Cadastro de fornecedores
`GET /suppliers/{id}`	Detalhe e dados bancários
`GET /bills`	Listagem de títulos a pagar
`GET /bills/{id}`	Detalhe do título e parcelas
`GET /bills/{id}/attachments`	NF, boleto, comprovantes
`POST /bills/{id}/installments/{n}/payments`	Confirmação de baixa
`PATCH /bills/{id}/installments/{n}/payments/{paymentId}/notes`	Atualização de observações
`DELETE /bills/{id}/installments/{n}/payments/{paymentId}`	Estorno

GET/suppliersFornecedores

Cadastro de fornecedores cuja relação financeira a Paggo vai operar. Inclui pessoa física e jurídica.

Query params

Parâmetro	Descrição
`page`	Número da página.
`pageSize`	Quantidade de itens por página.
`updatedSince`	ISO-8601 para sync incremental.
`taxId`	Busca pontual por CPF ou CNPJ.

Resposta esperada

Campo	Descrição
`id`	Identificador único do fornecedor.
`code`	Código interno.
`personType`	`PF` (pessoa física) ou `PJ` (jurídica).
`taxId`	CPF ou CNPJ formatado.
`legalName`	Razão social ou nome completo.
`tradeName`	Nome fantasia.
`active`	Fornecedor ativo.
`updatedAt`	Última atualização.

GET/suppliers/{id}Detalhe do fornecedor

Detalhe completo do fornecedor com endereço, contatos e contas bancárias para crédito de pagamentos.

Resposta esperada

Campo	Descrição
`id`	Identificador único.
`code`	Código interno.
`personType`	`PF` ou `PJ`.
`taxId`	CPF ou CNPJ.
`legalName`	Razão social.
`tradeName`	Nome fantasia.
`address.street`	Logradouro.
`address.number`	Número.
`address.city`	Cidade.
`address.state`	UF.
`address.zipCode`	CEP.
`contacts.type`	Tipo do contato (`EMAIL` ou `PHONE`).
`contacts.value`	Valor do contato.
`bankAccounts.id`	Identificador da conta bancária do fornecedor.
`bankAccounts.bankCode`	Código FEBRABAN do banco.
`bankAccounts.agency`	Agência.
`bankAccounts.accountNumber`	Conta com dígito.
`bankAccounts.type`	`CHECKING` ou `SAVINGS`.
`bankAccounts.pixKey`	Chave PIX para crédito.
`bankAccounts.pixKeyType`	`CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `EVP`.
`active`	Fornecedor ativo.
`updatedAt`	Última atualização.

GET/billsTítulos a pagar

Títulos e faturas registrados no ERP. A Paggo consome este endpoint periodicamente para identificar contas a pagar e gerar pacotes de pagamento.

Query params

Parâmetro	Descrição
`status`	`open`, `partially_paid`, `paid`, `cancelled` (default `open`).
`dueDateFrom`	Vencimento mínimo (ISO-8601).
`dueDateTo`	Vencimento máximo (ISO-8601).
`supplierId`	Filtra por fornecedor.
`companyId`	Filtra por empresa devedora.
`enterpriseId`	Filtra por empreendimento.
`updatedSince`	ISO-8601 para sync incremental.
`page`	Número da página.
`pageSize`	Quantidade de itens por página.

Resposta esperada

Campo	Descrição
`id`	Identificador único do título.
`code`	Código interno.
`companyId`	Empresa devedora.
`supplierId`	Fornecedor (referência a `/suppliers`).
`enterpriseId`	Empreendimento associado.
`costCenterId`	Centro de custo.
`paymentCategoryId`	Categoria financeira (despesa).
`documentTypeCode`	Código do tipo de documento (ex.: `NF`).
`documentNumber`	Número do documento (ex.: número da NF).
`issueDate`	Data de emissão.
`totalAmount`	Valor total bruto do título.
`currency`	Moeda (default `BRL`).
`status`	`open`, `partially_paid`, `paid`, `cancelled`.
`notes`	Observações livres.
`installmentsCount`	Quantidade de parcelas.
`updatedAt`	Última atualização.

GET/bills/{id}Detalhe do título

Retorna o título com todas as parcelas. A baixa é feita parcela a parcela.

Resposta esperada

Campo	Descrição
`id`	Identificador do título.
`code`	Código interno.
`supplierId`	Fornecedor.
`totalAmount`	Valor total.
`status`	Status atual do título.
`installments.number`	Número da parcela (1, 2, 3...).
`installments.dueDate`	Vencimento da parcela.
`installments.amount`	Valor da parcela.
`installments.status`	`open`, `paid`, `cancelled`.

GET/bills/{id}/attachmentsAnexos do título

Recupera arquivos anexados ao título (NF em PDF, boleto, comprovantes). Devolver URLs presigned (expirando em ≥ 30 minutos) para download direto, sem proxy.

Resposta esperada

Campo	Descrição
`id`	Identificador do anexo.
`fileName`	Nome do arquivo.
`mimeType`	MIME type (ex.: `application/pdf`).
`sizeBytes`	Tamanho do arquivo em bytes.
`downloadUrl`	URL presigned para download direto.
`expiresAt`	Quando a URL expira (ISO-8601).

POST/bills/{id}/installments/{installmentNumber}/paymentsConfirmação de baixa

Endpoint crítico do fluxo. Após a Paggo executar o pagamento (PIX, TED, boleto), envia ao SAP a confirmação para que o ERP escriture a movimentação financeira.

Headers

Idempotency-Key: {uuid}. Repetições com a mesma chave devem retornar a mesma resposta sem duplicar lançamento.

Request body

Campo	Descrição
`paymentDate`	Data efetiva do pagamento (`YYYY-MM-DD`).
`paidAmount`	Valor líquido pago.
`interestAmount`	Juros aplicados, quando houver.
`fineAmount`	Multa aplicada, quando houver.
`discountAmount`	Desconto concedido, quando houver.
`checkingAccountId`	Conta corrente de origem do pagamento.
`paymentTypeCode`	Código da forma de pagamento (`PIX`, `TED`, etc.).
`documentTypeCode`	Tipo de documento (`NF`, `BOL`, `REC`).
`transactionEntryNumber`	Número de lançamento no ERP, se exigido pelo modelo de escrituração.
`transactionSequenceNumber`	Sequência do lançamento, se aplicável.
`notes`	Observações livres. A Paggo inclui o link do comprovante.

Resposta

Campo	Descrição
`paymentId`	Identificador único da baixa criada.
`billId`	Identificador do título.
`installmentNumber`	Número da parcela liquidada.
`settledAt`	Timestamp da baixa.
`remainingBalance`	Saldo remanescente do título.
`newBillStatus`	Novo status do título (`partially_paid`, `paid`).

PATCH/bills/{id}/installments/{installmentNumber}/payments/{paymentId}/notesAtualização de observações

Após a baixa, eventualmente a Paggo precisa atualizar as observações da movimentação (por exemplo, novo número de comprovante ou retificação).

Request body

Campo	Descrição
`notes`	Texto atualizado das observações.

Resposta

Campo	Descrição
`paymentId`	Identificador da baixa.
`updatedAt`	Timestamp da atualização.

DELETE/bills/{id}/installments/{installmentNumber}/payments/{paymentId}Estorno

Reverte uma baixa. A parcela retorna ao status anterior.

Request body

Campo	Descrição
`reason`	Motivo do estorno (campo livre).

Resposta

Campo	Descrição
`paymentId`	Identificador da baixa estornada.
`reversedAt`	Timestamp do estorno.
`newInstallmentStatus`	Novo status da parcela (`open`).

4. Contas a Receber

Endpoints exclusivos do fluxo de Contas a Receber. A Paggo lê do ERP os contratos de venda, parcelas a receber e clientes finais; emite boletos ou PIX para os pagadores; e devolve a baixa quando a parcela é liquidada.

Endpoint	Propósito
`GET /customers`	Pagadores (compradores)
`GET /units`	Unidades vendáveis
`GET /sales-contracts`	Contratos de venda
`GET /sales-contracts/{id}/installments`	Parcelas a receber
`GET /sales-contracts/{id}/installments/{n}/attachments`	Boleto ou 2ª via
`GET /indexers`	Tabelas de correção (INCC, IPCA, IGP-M)
`POST /sales-contracts/{id}/installments/{n}/receipts`	Confirmação de recebimento
`DELETE /sales-contracts/{id}/installments/{n}/receipts/{receiptId}`	Estorno de recebimento

GET/customersClientes

Pessoas físicas ou jurídicas que assinaram contrato com a empresa, ou seja, os compradores de unidade. Necessário para emissão de boletos no nome correto.

Resposta esperada

Campo	Descrição
`id`	Identificador único.
`code`	Código interno.
`personType`	`PF` ou `PJ`.
`taxId`	CPF ou CNPJ formatado.
`name`	Nome completo ou razão social.
`email`	E-mail principal.
`phone`	Telefone principal.
`address.street`	Logradouro.
`address.number`	Número.
`address.city`	Cidade.
`address.state`	UF.
`address.zipCode`	CEP.
`active`	Cliente ativo.
`updatedAt`	Última atualização.

GET/unitsUnidades

Unidades vendáveis (apartamentos, salas, lotes), vinculadas a um empreendimento. Necessárias para resolver o contexto de cada contrato.

Query params

Parâmetro	Descrição
`enterpriseId`	Filtra unidades de um empreendimento específico.
`status`	`available`, `reserved`, `sold`.
`updatedSince`	ISO-8601 para sync incremental.

Resposta esperada

Campo	Descrição
`id`	Identificador único.
`code`	Código da unidade.
`enterpriseId`	Empreendimento ao qual pertence.
`blockCode`	Bloco ou torre.
`phaseCode`	Etapa ou fase.
`areaSqm`	Área em m².
`bedrooms`	Número de dormitórios.
`status`	`available`, `reserved`, `sold`.
`active`	Unidade ativa.
`updatedAt`	Última atualização.

GET/sales-contractsContratos de venda

Contrato firmado entre cliente final e a empresa. É a origem das parcelas a receber e inclui referência ao empreendimento, à unidade e ao cliente.

Query params

Parâmetro	Descrição
`customerId`	Filtra contratos de um cliente.
`enterpriseId`	Filtra contratos de um empreendimento.
`unitId`	Filtra contratos de uma unidade.
`status`	Status do contrato (ex.: `ATIVO`, `DISTRATADO`).
`updatedSince`	ISO-8601 para sync incremental.
`page`	Número da página.
`pageSize`	Quantidade de itens por página.

Resposta esperada

Campo	Descrição
`id`	Identificador único do contrato.
`contractCode`	Código numérico do contrato.
`proposalCode`	Código da proposta originária.
`companyId`	Empresa vendedora.
`branchCode`	Código da filial.
`branchName`	Nome da filial.
`customerId`	Cliente comprador.
`customerCode`	Código do cliente no ERP.
`customerName`	Nome do cliente.
`personType`	`PF` ou `PJ`.
`cpfCnpj`	Documento do cliente.
`enterpriseId`	Empreendimento.
`enterpriseCode`	Código numérico do empreendimento.
`enterpriseName`	Nome do empreendimento.
`unitId`	Unidade vendida.
`unitCode`	Código numérico da unidade.
`unitName`	Descrição da unidade.
`blockCode`	Bloco ou torre.
`phaseCode`	Etapa.
`contractType`	Tipo (`VENDA`, `LOCACAO`, etc.).
`contractStatus`	Status (`ATIVO`, `DISTRATADO`, etc.).
`contractValue`	Valor total do contrato.
`registrationDate`	Data de cadastro.
`signatureDate`	Data de assinatura.
`deliveryDate`	Data prevista de entrega.
`keysDeliveryDate`	Data efetiva de entrega das chaves.
`finePercentage`	Percentual de multa por atraso.
`lateInterestPercentage`	Percentual de juros de mora ao mês.
`classification`	Classificação interna do contrato.
`updatedAt`	Última atualização.

GET/sales-contracts/{id}/installmentsParcelas do contrato

Parcelas a receber, com vencimento, valor original, valor corrigido pelo indexador e juros ou multa quando em atraso. É a base para emissão de boleto ou PIX.

Resposta esperada

Campo	Descrição
`contractId`	Identificador do contrato.
`installmentNumber`	Número da parcela.
`conditionCode`	Código da condição comercial.
`seriesCode`	Código da série da parcela.
`installmentType`	Periodicidade (`MENSAL`, `ANUAL`, etc.).
`installmentStatus`	`ABERTA`, `QUITADA`, `PARCIAL` ou `CANCELADA`.
`statusDate`	Data da última mudança de status.
`sequence`	Sequência amigável (`012/240`).
`dueDate`	Vencimento.
`movementDate`	Data do último movimento financeiro.
`originalAmount`	Valor original da parcela.
`correctedAmount`	Valor corrigido pelo indexador.
`fineAmount`	Multa acumulada.
`interestAmount`	Juros acumulados.
`discountAmount`	Desconto aplicado.
`feesAmount`	Tarifas.
`delayAmount`	Acréscimo total por atraso.
`paidAmount`	Valor já pago em pagamentos parciais.
`settlementDate`	Data da baixa total, se ocorreu.
`presentValue`	Valor presente líquido.
`ourNumber`	Nosso número do boleto.
`boletoDueDate`	Vencimento do boleto.
`bankName`	Banco emissor do boleto.
`agency`	Agência.
`checkingAccount`	Conta corrente do boleto.
`indexerCode`	Código do indexador (`INCC`, `IPCA`, `IGPM`).
`monetaryCorrectionAmount`	Valor de correção monetária acumulado.

GET/sales-contracts/{id}/installments/{installmentNumber}/attachmentsAnexos da parcela

Boleto, comprovante de recebimento ou outros arquivos vinculados à parcela. URLs presigned com expiração mínima de 30 minutos.

Resposta esperada

Campo	Descrição
`id`	Identificador do anexo.
`fileName`	Nome do arquivo.
`mimeType`	MIME type.
`downloadUrl`	URL presigned para download direto.
`expiresAt`	Quando a URL expira (ISO-8601).

GET/indexersIndexadores

Tabelas de correção monetária (INCC, IPCA, IGP-M) com valores mensais, usadas para conferir o cálculo de correção das parcelas.

Resposta esperada

Campo	Descrição
`code`	Código do indexador (`INCC`, `IPCA`, `IGPM`).
`name`	Nome completo do indexador.
`monthlyValues.month`	Mês de referência no formato `YYYY-MM`.
`monthlyValues.value`	Fator de correção do mês.

POST/sales-contracts/{id}/installments/{installmentNumber}/receiptsConfirmação de recebimento

Endpoint crítico do fluxo. Quando o pagador quita a parcela (boleto pago, PIX recebido), a Paggo envia ao ERP a baixa para liquidar o título a receber.

Headers

Idempotency-Key: {uuid}. Repetições com a mesma chave devem retornar a mesma resposta sem duplicar lançamento.

Request body

Campo	Descrição
`paymentDate`	Data do recebimento (`YYYY-MM-DD`).
`paidAmount`	Valor recebido.
`interestAmount`	Juros recebidos, quando houver.
`fineAmount`	Multa recebida, quando houver.
`discountAmount`	Desconto concedido, quando houver.
`feesAmount`	Tarifas, quando houver.
`checkingAccountId`	Conta corrente destino.
`paymentTypeCode`	Forma do recebimento (`PIX`, `TED`, `BOL`).
`ourNumber`	Nosso número conciliado, quando boleto.
`notes`	Observações. A Paggo inclui o link do comprovante.

Resposta

Campo	Descrição
`receiptId`	Identificador único da baixa criada.
`contractId`	Identificador do contrato.
`installmentNumber`	Parcela liquidada.
`settledAt`	Timestamp da baixa.
`remainingBalance`	Saldo remanescente da parcela.
`newInstallmentStatus`	`QUITADA` ou `PARCIAL`.

DELETE/sales-contracts/{id}/installments/{installmentNumber}/receipts/{receiptId}Estorno de recebimento

Reverte a baixa de uma parcela (boleto cancelado, devolução PIX, retorno bancário negativo).

Request body

Campo	Descrição
`reason`	Motivo do estorno (campo livre).

Resposta

Campo	Descrição
`receiptId`	Identificador estornado.
`reversedAt`	Timestamp do estorno.
`newInstallmentStatus`	Novo status da parcela (`ABERTA`).