Pular para o conteúdo

Pagadoria e certidões

Contrato curto para um sistema externo usar o Garagem como backoffice de pós-venda. A negociação e as pessoas continuam na API de negociações. Esta página não cria cobrança nem dispara repasse: isso fica na interface, porque o payload leva CPF e dados bancários.

Autenticação: a mesma API key de Configurações → Desenvolvedor.

Janela do terminal
Authorization: Bearer sua_api_key

A chave age com o perfil de quem a criou.

  • Ler pagamentos exige Pagamentos → Visualizar.
  • Montar o carrinho de certidões e emitir exige perfil proprietário ou administrador.

Valores de certidão e de pagamento vêm em centavos (amountMinor), moeda BRL. Não mande CPF, banco ou chave PIX nestes endpoints. A resposta também não devolve esses campos.


POST /api/mcp com a mesma API key (ou OAuth) já expõe estas ferramentas. Elas não estão no catálogo certidoes.* da interface. O catálogo público é o conjunto com expose: mcp.

FerramentaO que faz
payments.list_paymentsLista cobranças sem documento, banco ou PIX
payments.get_paymentUma cobrança, mesmo recorte
payments.list_rental_invoicesFaturas de aluguel
subscription.get_distribution_statusStatus do repasse, destino mascarado
subscription.preview_distribution_splitPrévia do split, sem disparar transferência
certificate.browse_catalogCatálogo com preço do servidor e aplicabilidade
certificate.resolve_partiesPartes do negócio, só nome e papel
certificate.get_cartCarrinho com total e versionToken
certificate.get_order_statusStatus por item
certificate.add_cart_itemInclui item no rascunho
certificate.remove_cart_itemRemove item (exige versionToken)
certificate.submit_orderEmite e gasta o total. Reenvio não pede de novo
certificate.retry_itemReemite um item com correção, também pago
certificate.list_deal_ordersLista pedidos de um negócio, só id e status
transaction.get_diligence_loopLeitura da diligência
transaction.list_diligencesLista diligências
transaction.start_diligence_processAbre o processo de diligência
transaction.resolve_diligence_findingResolve um apontamento tipado
transaction.contest_diligence_findingContesta um apontamento
transaction.retry_diligence_processingReprocessa coleta ou análise que falhou

Incluir item, emitir e retentar são recusados quando a conexão MCP está vinculada a um agente. Com API key de proprietário ou administrador, a chamada passa. Soltar o repasse para a conta do recebedor não está no MCP.

A API REST é esse mesmo procedimento. HTTP e MCP executam a operação portátil.


Não há POST /payments. Criar a cobrança e liberar o repasse continuam na interface.

GET /api/v1/payments
ParâmetroTipoDescrição
dealIdstringFiltra pela negociação
listingIduuidFiltra pelo anúncio
statusstringpending, processing, paid, partial, failed, cancelled, refunded
paymentTypestringsale ou rent
limitnumberDefault 50, máximo 100
Janela do terminal
curl "https://app.garagem.ai/api/v1/payments?dealId=DEAL_ID&status=paid" \
-H "Authorization: Bearer sua_api_key"

Cada item traz id, status, paymentType, paymentMethod, totais (totalAmount, serviceFee, netAmount, paidAmount), parcelas, e a referência de negociação e anúncio (id e code).

GET /api/v1/payments/{id}

found: false quando o id não existe ou está fora do alcance. Não é um 404.


A pessoa, a empresa e o imóvel já precisam estar na negociação. Estes endpoints não recebem CPF, endereço nem nome da mãe. Eles usam o que já está gravado.

POST /api/v1/certificates/parties
{ "dealId": "uuid-da-negociacao" }

roster[].partyId é o entityId do passo 3. displayName é nome de exibição. Documento, contato e endereço não vêm.

POST /api/v1/certificates/catalog
{
"dealId": "uuid-da-negociacao",
"region": "SP",
"certificateKeys": ["rf_pessoa_fisica"]
}

region e certificateKeys são opcionais. Use certificates[].key como certificateType. applicability[].applicable diz se aquela parte pode pedir aquela certidão. price.amountMinor é o preço do servidor, em centavos.

POST /api/v1/certificates/cart/items
{
"dealId": "uuid-da-negociacao",
"certificateType": "rf_pessoa_fisica",
"entityId": "party-id"
}

A resposta traz orderId, itemId e o carrinho. outcome: "not_applicable" significa que a certidão não cabe naquela parte. O primeiro item cria o rascunho.

Para tirar um item do rascunho:

POST /api/v1/certificates/cart/items/remove
{
"orderId": "id-do-pedido",
"itemId": "id-do-item",
"versionToken": "token-lido-no-carrinho"
}

version_conflict pede para reler o carrinho e tentar de novo.

GET /api/v1/certificates/cart/{orderId}

cart.total.amountMinor é o valor que a emissão vai cobrar. cart.readiness.submittable precisa ser true. cart.versionToken é o token da remoção.

POST /api/v1/certificates/orders/{orderId}/submit
{
"approval": {
"confirmed": true,
"acknowledgedAmountMinor": 15000
}
}

acknowledgedAmountMinor tem de ser exatamente cart.total.amountMinor. Outro valor volta outcome: "refused" e refusalReason: "amount_mismatch", sem pedido no provedor.

Um segundo POST com o mesmo pedido volta already_in_progress e não emite de novo.

GET /api/v1/certificates/orders?dealId=uuid-da-negociacao
GET /api/v1/certificates/orders/{orderId}

A lista traz orderId e status. O detalhe traz status por item: pending, awaiting_webhook, processing, completed, failed. Documento pronto volta como id de entidade, não como URL de download. O PDF continua na interface e na área do cliente.

Correção paga de um item com falha:

POST /api/v1/certificates/orders/{orderId}/items/{itemId}/retry

O corpo repete orderId, itemId, fieldPatches e o mesmo approval da emissão. É a ferramenta certificate.retry_item.


O Garagem avisa a URL do tenant com o mesmo recorte desta página. Assine estes nomes, ou use todos os eventos:

EventoQuandoCorpo em data
payment.updatedO status da cobrança mudapayment, o DTO de GET /payments/{id}. Fatura de aluguel é outro registro e não entra neste evento
payment.distribution_updatedO status de um repasse mudadistributionId, paymentId, installmentNumber, status. Sem CPF, banco ou PIX
certificate.order.updatedO pedido ou um item muda de statusorderId, status, rollup, items do GET do pedido

diligence.updated e diligenceResult.* continuam sendo a linha interna da diligência. Não use esses corpos.

O bloco “Webhooks de Pagamento” em 08 - Webhooks e Eventos é o que o provedor manda para o Garagem. Os três eventos acima saem do Garagem para a sua URL.

Não há evento com o PDF nem com banco/PIX. Se o POST não chegar, leia GET /api/v1/payments/{id} ou GET /api/v1/certificates/orders/{orderId}.